1
/* ***** BEGIN LICENSE BLOCK *****
2
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
4
* The contents of this file are subject to the Mozilla Public License Version
5
* 1.1 (the "License"); you may not use this file except in compliance with
6
* the License. You may obtain a copy of the License at
7
* http://www.mozilla.org/MPL/
9
* Software distributed under the License is distributed on an "AS IS" basis,
10
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
11
* for the specific language governing rights and limitations under the
14
* The Original Code is the Netscape security libraries.
16
* The Initial Developer of the Original Code is
17
* Netscape Communications Corporation.
18
* Portions created by the Initial Developer are Copyright (C) 1994-2000
19
* the Initial Developer. All Rights Reserved.
23
* Alternatively, the contents of this file may be used under the terms of
24
* either the GNU General Public License Version 2 or later (the "GPL"), or
25
* the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
26
* in which case the provisions of the GPL or the LGPL are applicable instead
27
* of those above. If you wish to allow use of your version of this file only
28
* under the terms of either the GPL or the LGPL, and not to allow others to
29
* use your version of this file under the terms of the MPL, indicate your
30
* decision by deleting the provisions above and replace them with the notice
31
* and other provisions required by the GPL or the LGPL. If you do not delete
32
* the provisions above, a recipient may use your version of this file under
33
* the terms of any one of the MPL, the GPL or the LGPL.
35
* ***** END LICENSE BLOCK ***** */
41
static const char PKIM_CVS_ID[] = "@(#) $RCSfile: pkim.h,v $ $Revision: 1.27.2.1 $ $Date: 2006/08/23 01:36:31 $";
60
* This is the base object class, common to all PKI objects defined in
61
* in this module. Each object can be safely 'casted' to an nssPKIObject,
62
* then passed to these methods.
65
* nssPKIObject_Destroy
67
* nssPKIObject_AddInstance
68
* nssPKIObject_HasInstance
69
* nssPKIObject_GetTokens
70
* nssPKIObject_GetNicknameForToken
71
* nssPKIObject_RemoveInstanceForToken
72
* nssPKIObject_DeleteStoredObject
75
NSS_EXTERN void nssPKIObject_Lock (nssPKIObject * object);
76
NSS_EXTERN void nssPKIObject_Unlock (nssPKIObject * object);
77
NSS_EXTERN PRStatus nssPKIObject_NewLock (nssPKIObject * object,
78
nssPKILockType lockType);
79
NSS_EXTERN void nssPKIObject_DestroyLock(nssPKIObject * object);
81
/* nssPKIObject_Create
83
* A generic PKI object. It must live in a trust domain. It may be
84
* initialized with a token instance, or alternatively in a crypto context.
86
NSS_EXTERN nssPKIObject *
90
nssCryptokiObject *instanceOpt,
92
NSSCryptoContext *ccOpt,
93
nssPKILockType lockType
96
/* nssPKIObject_AddRef
98
NSS_EXTERN nssPKIObject *
104
/* nssPKIObject_Destroy
106
* Returns true if object was destroyed. This notifies the subclass that
107
* all references are gone and it should delete any members it owns.
115
/* nssPKIObject_AddInstance
117
* Add a token instance to the object, if it does not have it already.
120
nssPKIObject_AddInstance
122
nssPKIObject *object,
123
nssCryptokiObject *instance
126
/* nssPKIObject_HasInstance
128
* Query the object for a token instance.
131
nssPKIObject_HasInstance
133
nssPKIObject *object,
134
nssCryptokiObject *instance
137
/* nssPKIObject_GetTokens
139
* Get all tokens which have an instance of the object.
141
NSS_EXTERN NSSToken **
142
nssPKIObject_GetTokens
144
nssPKIObject *object,
148
/* nssPKIObject_GetNicknameForToken
150
* tokenOpt == NULL means take the first available, otherwise return the
151
* nickname for the specified token.
154
nssPKIObject_GetNicknameForToken
156
nssPKIObject *object,
160
/* nssPKIObject_RemoveInstanceForToken
162
* Remove the instance of the object on the specified token.
165
nssPKIObject_RemoveInstanceForToken
167
nssPKIObject *object,
171
/* nssPKIObject_DeleteStoredObject
173
* Delete all token instances of the object, as well as any crypto context
174
* instances (TODO). If any of the instances are read-only, or if the
175
* removal fails, the object will keep those instances. 'isFriendly' refers
176
* to the object -- can this object be removed from a friendly token without
177
* login? For example, certificates are friendly, private keys are not.
178
* Note that if the token is not friendly, authentication will be required
179
* regardless of the value of 'isFriendly'.
182
nssPKIObject_DeleteStoredObject
184
nssPKIObject *object,
190
NSS_EXTERN nssCryptokiObject **
191
nssPKIObject_GetInstances
197
NSS_EXTERN NSSCertificate **
198
nssTrustDomain_FindCertificatesByID
202
NSSCertificate **rvOpt,
208
nssTrustDomain_FindCRLsBySubject
214
/* module-private nsspki methods */
216
NSS_EXTERN NSSCryptoContext *
217
nssCryptoContext_Create
223
/* XXX for the collection */
224
NSS_EXTERN NSSCertificate *
225
nssCertificate_Create
231
nssCertificate_SetCertTrust
237
NSS_EXTERN nssDecodedCert *
238
nssCertificate_GetDecoding
244
nssCertificate_SubjectListSort
250
NSS_EXTERN nssDecodedCert *
251
nssDecodedCert_Create
255
NSSCertificateType type
259
nssDecodedCert_Destroy
264
NSS_EXTERN NSSTrust *
267
nssPKIObject *object,
290
nssCRL_DeleteStoredObject
296
NSS_EXTERN NSSPrivateKey *
308
NSS_EXTERN NSSPublicKey *
314
/* nssCertificateArray
316
* These are being thrown around a lot, might as well group together some
319
* nssCertificateArray_Destroy
320
* nssCertificateArray_Join
321
* nssCertificateArray_FindBestCertificate
322
* nssCertificateArray_Traverse
325
/* nssCertificateArray_Destroy
327
* Will destroy the array and the certs within it. If the array was created
328
* in an arena, will *not* (of course) destroy the arena. However, is safe
329
* to call this method on an arena-allocated array.
332
nssCertificateArray_Destroy
334
NSSCertificate **certs
337
/* nssCertificateArray_Join
339
* Join two arrays into one. The two arrays, certs1 and certs2, should
340
* be considered invalid after a call to this function (they may be destroyed
341
* as part of the join). certs1 and/or certs2 may be NULL. Safe to
342
* call with arrays allocated in an arena, the result will also be in the
345
NSS_EXTERN NSSCertificate **
346
nssCertificateArray_Join
348
NSSCertificate **certs1,
349
NSSCertificate **certs2
352
/* nssCertificateArray_FindBestCertificate
354
* Use the usual { time, usage, policies } to find the best cert in the
357
NSS_EXTERN NSSCertificate *
358
nssCertificateArray_FindBestCertificate
360
NSSCertificate **certs,
362
const NSSUsage *usage,
363
NSSPolicies *policiesOpt
366
/* nssCertificateArray_Traverse
368
* Do the callback for each cert, terminate the traversal if the callback
372
nssCertificateArray_Traverse
374
NSSCertificate **certs,
375
PRStatus (* callback)(NSSCertificate *c, void *arg),
385
/* nssPKIObjectCollection
387
* This is a handy way to group objects together and perform operations
388
* on them. It can also handle "proto-objects"-- references to
389
* objects instances on tokens, where the actual object hasn't
392
* nssCertificateCollection_Create
393
* nssPrivateKeyCollection_Create
394
* nssPublicKeyCollection_Create
396
* If this was a language that provided for inheritance, each type would
397
* inherit all of the following methods. Instead, there is only one
398
* type (nssPKIObjectCollection), shared among all. This may cause
399
* confusion; an alternative would be to define all of the methods
400
* for each subtype (nssCertificateCollection_Destroy, ...), but that doesn't
401
* seem worth the code bloat.. It is left up to the caller to remember
402
* what type of collection he/she is dealing with.
404
* nssPKIObjectCollection_Destroy
405
* nssPKIObjectCollection_Count
406
* nssPKIObjectCollection_AddObject
407
* nssPKIObjectCollection_AddInstances
408
* nssPKIObjectCollection_Traverse
410
* Back to type-specific methods.
412
* nssPKIObjectCollection_GetCertificates
413
* nssPKIObjectCollection_GetCRLs
414
* nssPKIObjectCollection_GetPrivateKeys
415
* nssPKIObjectCollection_GetPublicKeys
418
/* nssCertificateCollection_Create
420
* Create a collection of certificates in the specified trust domain.
421
* Optionally provide a starting set of certs.
423
NSS_EXTERN nssPKIObjectCollection *
424
nssCertificateCollection_Create
427
NSSCertificate **certsOpt
430
/* nssCRLCollection_Create
432
* Create a collection of CRLs/KRLs in the specified trust domain.
433
* Optionally provide a starting set of CRLs.
435
NSS_EXTERN nssPKIObjectCollection *
436
nssCRLCollection_Create
442
/* nssPrivateKeyCollection_Create
444
* Create a collection of private keys in the specified trust domain.
445
* Optionally provide a starting set of keys.
447
NSS_EXTERN nssPKIObjectCollection *
448
nssPrivateKeyCollection_Create
451
NSSPrivateKey **pvkOpt
454
/* nssPublicKeyCollection_Create
456
* Create a collection of public keys in the specified trust domain.
457
* Optionally provide a starting set of keys.
459
NSS_EXTERN nssPKIObjectCollection *
460
nssPublicKeyCollection_Create
463
NSSPublicKey **pvkOpt
466
/* nssPKIObjectCollection_Destroy
469
nssPKIObjectCollection_Destroy
471
nssPKIObjectCollection *collection
474
/* nssPKIObjectCollection_Count
477
nssPKIObjectCollection_Count
479
nssPKIObjectCollection *collection
483
nssPKIObjectCollection_AddObject
485
nssPKIObjectCollection *collection,
489
/* nssPKIObjectCollection_AddInstances
491
* Add a set of object instances to the collection. The instances
492
* will be sorted into any existing certs/proto-certs that may be in
493
* the collection. The instances will be absorbed by the collection,
494
* the array should not be used after this call (except to free it).
496
* Failure means the collection is in an invalid state.
498
* numInstances = 0 means the array is NULL-terminated
501
nssPKIObjectCollection_AddInstances
503
nssPKIObjectCollection *collection,
504
nssCryptokiObject **instances,
505
PRUint32 numInstances
508
/* nssPKIObjectCollection_Traverse
511
nssPKIObjectCollection_Traverse
513
nssPKIObjectCollection *collection,
514
nssPKIObjectCallback *callback
517
/* This function is being added for NSS 3.5. It corresponds to the function
518
* nssToken_TraverseCertificates. The idea is to use the collection during
519
* a traversal, creating certs each time a new instance is added for which
520
* a cert does not already exist.
523
nssPKIObjectCollection_AddInstanceAsObject
525
nssPKIObjectCollection *collection,
526
nssCryptokiObject *instance
529
/* nssPKIObjectCollection_GetCertificates
531
* Get all of the certificates in the collection.
533
NSS_EXTERN NSSCertificate **
534
nssPKIObjectCollection_GetCertificates
536
nssPKIObjectCollection *collection,
537
NSSCertificate **rvOpt,
543
nssPKIObjectCollection_GetCRLs
545
nssPKIObjectCollection *collection,
551
NSS_EXTERN NSSPrivateKey **
552
nssPKIObjectCollection_GetPrivateKeys
554
nssPKIObjectCollection *collection,
555
NSSPrivateKey **rvOpt,
560
NSS_EXTERN NSSPublicKey **
561
nssPKIObjectCollection_GetPublicKeys
563
nssPKIObjectCollection *collection,
564
NSSPublicKey **rvOpt,
589
nssHash_CreateCertificate
595
/* 3.4 Certificate cache routines */
598
nssTrustDomain_InitializeCache
605
nssTrustDomain_AddCertsToCache
608
NSSCertificate **certs,
613
nssTrustDomain_RemoveCertFromCacheLOCKED (
619
nssTrustDomain_LockCertCache (
624
nssTrustDomain_UnlockCertCache (
628
NSS_IMPLEMENT PRStatus
629
nssTrustDomain_DestroyCache
635
* Remove all certs for the given token from the cache. This is
636
* needed if the token is removed.
639
nssTrustDomain_RemoveTokenCertsFromCache
646
nssTrustDomain_UpdateCachedTokenCerts
653
* Find all cached certs with this nickname (label).
655
NSS_EXTERN NSSCertificate **
656
nssTrustDomain_GetCertsForNicknameFromCache
664
* Find all cached certs with this email address.
666
NSS_EXTERN NSSCertificate **
667
nssTrustDomain_GetCertsForEmailAddressFromCache
675
* Find all cached certs with this subject.
677
NSS_EXTERN NSSCertificate **
678
nssTrustDomain_GetCertsForSubjectFromCache
686
* Look for a specific cert in the cache.
688
NSS_EXTERN NSSCertificate *
689
nssTrustDomain_GetCertForIssuerAndSNFromCache
697
* Look for a specific cert in the cache.
699
NSS_EXTERN NSSCertificate *
700
nssTrustDomain_GetCertByDERFromCache
706
/* Get all certs from the cache */
707
/* XXX this is being included to make some old-style calls word, not to
708
* say we should keep it
710
NSS_EXTERN NSSCertificate **
711
nssTrustDomain_GetCertsFromCache
718
nssTrustDomain_DumpCacheInfo
721
void (* cert_dump_iter)(const void *, void *, void *),
726
nssCertificateList_AddReferences