The Tor Browser: security/nss/lib/pki/pkim.h@6474c204b198

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

     1 /* This Source Code Form is subject to the terms of the Mozilla Public

     2  * License, v. 2.0. If a copy of the MPL was not distributed with this

     3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

     5 #ifndef PKIM_H

     6 #define PKIM_H

     8 #ifndef BASE_H

     9 #include "base.h"

    10 #endif /* BASE_H */

    12 #ifndef PKI_H

    13 #include "pki.h"

    14 #endif /* PKI_H */

    16 #ifndef PKITM_H

    17 #include "pkitm.h"

    18 #endif /* PKITM_H */

    20 PR_BEGIN_EXTERN_C

    22 /* nssPKIObject

    23  *

    24  * This is the base object class, common to all PKI objects defined in

    25  * in this module.  Each object can be safely 'casted' to an nssPKIObject,

    26  * then passed to these methods.

    27  *

    28  * nssPKIObject_Create

    29  * nssPKIObject_Destroy

    30  * nssPKIObject_AddRef

    31  * nssPKIObject_AddInstance

    32  * nssPKIObject_HasInstance

    33  * nssPKIObject_GetTokens

    34  * nssPKIObject_GetNicknameForToken

    35  * nssPKIObject_RemoveInstanceForToken

    36  * nssPKIObject_DeleteStoredObject

    37  */

    39 NSS_EXTERN void     nssPKIObject_Lock       (nssPKIObject * object);

    40 NSS_EXTERN void     nssPKIObject_Unlock     (nssPKIObject * object);

    41 NSS_EXTERN PRStatus nssPKIObject_NewLock    (nssPKIObject * object,

    42                                              nssPKILockType lockType);

    43 NSS_EXTERN void     nssPKIObject_DestroyLock(nssPKIObject * object);

    45 /* nssPKIObject_Create

    46  *

    47  * A generic PKI object.  It must live in a trust domain.  It may be

    48  * initialized with a token instance, or alternatively in a crypto context.

    49  */

    50 NSS_EXTERN nssPKIObject *

    51 nssPKIObject_Create

    52 (

    53   NSSArena *arenaOpt,

    54   nssCryptokiObject *instanceOpt,

    55   NSSTrustDomain *td,

    56   NSSCryptoContext *ccOpt,

    57   nssPKILockType lockType

    58 );

    60 /* nssPKIObject_AddRef

    61  */

    62 NSS_EXTERN nssPKIObject *

    63 nssPKIObject_AddRef

    64 (

    65   nssPKIObject *object

    66 );

    68 /* nssPKIObject_Destroy

    69  *

    70  * Returns true if object was destroyed.  This notifies the subclass that

    71  * all references are gone and it should delete any members it owns.

    72  */

    73 NSS_EXTERN PRBool

    74 nssPKIObject_Destroy

    75 (

    76   nssPKIObject *object

    77 );

    79 /* nssPKIObject_AddInstance

    80  *

    81  * Add a token instance to the object, if it does not have it already.

    82  */

    83 NSS_EXTERN PRStatus

    84 nssPKIObject_AddInstance

    85 (

    86   nssPKIObject *object,

    87   nssCryptokiObject *instance

    88 );

    90 /* nssPKIObject_HasInstance

    91  *

    92  * Query the object for a token instance.

    93  */

    94 NSS_EXTERN PRBool

    95 nssPKIObject_HasInstance

    96 (

    97   nssPKIObject *object,

    98   nssCryptokiObject *instance

    99 );

   101 /* nssPKIObject_GetTokens

   102  *

   103  * Get all tokens which have an instance of the object.

   104  */

   105 NSS_EXTERN NSSToken **

   106 nssPKIObject_GetTokens

   107 (

   108   nssPKIObject *object,

   109   PRStatus *statusOpt

   110 );

   112 /* nssPKIObject_GetNicknameForToken

   113  *

   114  * tokenOpt == NULL means take the first available, otherwise return the

   115  * nickname for the specified token.

   116  */

   117 NSS_EXTERN NSSUTF8 *

   118 nssPKIObject_GetNicknameForToken

   119 (

   120   nssPKIObject *object,

   121   NSSToken *tokenOpt

   122 );

   124 /* nssPKIObject_RemoveInstanceForToken

   125  *

   126  * Remove the instance of the object on the specified token.

   127  */

   128 NSS_EXTERN PRStatus

   129 nssPKIObject_RemoveInstanceForToken

   130 (

   131   nssPKIObject *object,

   132   NSSToken *token

   133 );

   135 /* nssPKIObject_DeleteStoredObject

   136  *

   137  * Delete all token instances of the object, as well as any crypto context

   138  * instances (TODO).  If any of the instances are read-only, or if the

   139  * removal fails, the object will keep those instances.  'isFriendly' refers

   140  * to the object -- can this object be removed from a friendly token without

   141  * login?  For example, certificates are friendly, private keys are not.

   142  * Note that if the token is not friendly, authentication will be required

   143  * regardless of the value of 'isFriendly'.

   144  */

   145 NSS_EXTERN PRStatus

   146 nssPKIObject_DeleteStoredObject

   147 (

   148   nssPKIObject *object,

   149   NSSCallback *uhh,

   150   PRBool isFriendly

   151 );

   153 NSS_EXTERN nssCryptokiObject **

   154 nssPKIObject_GetInstances

   155 (

   156   nssPKIObject *object

   157 );

   159 NSS_EXTERN NSSCertificate **

   160 nssTrustDomain_FindCertificatesByID

   161 (

   162   NSSTrustDomain *td,

   163   NSSItem *id,

   164   NSSCertificate **rvOpt,

   165   PRUint32 maximumOpt,

   166   NSSArena *arenaOpt

   167 );

   169 NSS_EXTERN NSSCRL **

   170 nssTrustDomain_FindCRLsBySubject

   171 (

   172   NSSTrustDomain *td,

   173   NSSDER *subject

   174 );

   176 /* module-private nsspki methods */

   178 NSS_EXTERN NSSCryptoContext *

   179 nssCryptoContext_Create

   180 (

   181   NSSTrustDomain *td,

   182   NSSCallback *uhhOpt

   183 );

   185 /* XXX for the collection */

   186 NSS_EXTERN NSSCertificate *

   187 nssCertificate_Create

   188 (

   189   nssPKIObject *object

   190 );

   192 NSS_EXTERN PRStatus

   193 nssCertificate_SetCertTrust

   194 (

   195   NSSCertificate *c,

   196   NSSTrust *trust

   197 );

   199 NSS_EXTERN nssDecodedCert *

   200 nssCertificate_GetDecoding

   201 (

   202   NSSCertificate *c

   203 );

   205 extern PRIntn

   206 nssCertificate_SubjectListSort

   207 (

   208   void *v1,

   209   void *v2

   210 );

   212 NSS_EXTERN nssDecodedCert *

   213 nssDecodedCert_Create

   214 (

   215   NSSArena *arenaOpt,

   216   NSSDER *encoding,

   217   NSSCertificateType type

   218 );

   220 NSS_EXTERN PRStatus

   221 nssDecodedCert_Destroy

   222 (

   223   nssDecodedCert *dc

   224 );

   226 NSS_EXTERN NSSTrust *

   227 nssTrust_Create

   228 (

   229   nssPKIObject *object,

   230   NSSItem *certData

   231 );

   233 NSS_EXTERN NSSCRL *

   234 nssCRL_Create

   235 (

   236   nssPKIObject *object

   237 );

   239 NSS_EXTERN NSSCRL *

   240 nssCRL_AddRef

   241 (

   242   NSSCRL *crl

   243 );

   245 NSS_EXTERN PRStatus

   246 nssCRL_Destroy

   247 (

   248   NSSCRL *crl

   249 );

   251 NSS_EXTERN PRStatus

   252 nssCRL_DeleteStoredObject

   253 (

   254   NSSCRL *crl,

   255   NSSCallback *uhh

   256 );

   258 NSS_EXTERN NSSPrivateKey *

   259 nssPrivateKey_Create

   260 (

   261   nssPKIObject *o

   262 );

   264 NSS_EXTERN NSSDER *

   265 nssCRL_GetEncoding

   266 (

   267   NSSCRL *crl

   268 );

   270 NSS_EXTERN NSSPublicKey *

   271 nssPublicKey_Create

   272 (

   273   nssPKIObject *object

   274 );

   276 /* nssCertificateArray

   277  *

   278  * These are being thrown around a lot, might as well group together some

   279  * functionality.

   280  *

   281  * nssCertificateArray_Destroy

   282  * nssCertificateArray_Join

   283  * nssCertificateArray_FindBestCertificate

   284  * nssCertificateArray_Traverse

   285  */

   287 /* nssCertificateArray_Destroy

   288  *

   289  * Will destroy the array and the certs within it.  If the array was created

   290  * in an arena, will *not* (of course) destroy the arena.  However, is safe

   291  * to call this method on an arena-allocated array.

   292  */

   293 NSS_EXTERN void

   294 nssCertificateArray_Destroy

   295 (

   296   NSSCertificate **certs

   297 );

   299 /* nssCertificateArray_Join

   300  *

   301  * Join two arrays into one.  The two arrays, certs1 and certs2, should

   302  * be considered invalid after a call to this function (they may be destroyed

   303  * as part of the join).  certs1 and/or certs2 may be NULL.  Safe to

   304  * call with arrays allocated in an arena, the result will also be in the

   305  * arena.

   306  */

   307 NSS_EXTERN NSSCertificate **

   308 nssCertificateArray_Join

   309 (

   310   NSSCertificate **certs1,

   311   NSSCertificate **certs2

   312 );

   314 /* nssCertificateArray_FindBestCertificate

   315  *

   316  * Use the usual { time, usage, policies } to find the best cert in the

   317  * array.

   318  */

   319 NSS_EXTERN NSSCertificate *

   320 nssCertificateArray_FindBestCertificate

   321 (

   322   NSSCertificate **certs,

   323   NSSTime *timeOpt,

   324   const NSSUsage *usage,

   325   NSSPolicies *policiesOpt

   326 );

   328 /* nssCertificateArray_Traverse

   329  *

   330  * Do the callback for each cert, terminate the traversal if the callback

   331  * fails.

   332  */

   333 NSS_EXTERN PRStatus

   334 nssCertificateArray_Traverse

   335 (

   336   NSSCertificate **certs,

   337   PRStatus (* callback)(NSSCertificate *c, void *arg),

   338   void *arg

   339 );

   341 NSS_EXTERN void

   342 nssCRLArray_Destroy

   343 (

   344   NSSCRL **crls

   345 );

   347 /* nssPKIObjectCollection

   348  *

   349  * This is a handy way to group objects together and perform operations

   350  * on them.  It can also handle "proto-objects"-- references to

   351  * objects instances on tokens, where the actual object hasn't

   352  * been formed yet.

   353  *

   354  * nssCertificateCollection_Create

   355  * nssPrivateKeyCollection_Create

   356  * nssPublicKeyCollection_Create

   357  *

   358  * If this was a language that provided for inheritance, each type would

   359  * inherit all of the following methods.  Instead, there is only one

   360  * type (nssPKIObjectCollection), shared among all.  This may cause

   361  * confusion; an alternative would be to define all of the methods

   362  * for each subtype (nssCertificateCollection_Destroy, ...), but that doesn't

   363  * seem worth the code bloat..  It is left up to the caller to remember

   364  * what type of collection he/she is dealing with.

   365  *

   366  * nssPKIObjectCollection_Destroy

   367  * nssPKIObjectCollection_Count

   368  * nssPKIObjectCollection_AddObject

   369  * nssPKIObjectCollection_AddInstances

   370  * nssPKIObjectCollection_Traverse

   371  *

   372  * Back to type-specific methods.

   373  *

   374  * nssPKIObjectCollection_GetCertificates

   375  * nssPKIObjectCollection_GetCRLs

   376  * nssPKIObjectCollection_GetPrivateKeys

   377  * nssPKIObjectCollection_GetPublicKeys

   378  */

   380 /* nssCertificateCollection_Create

   381  *

   382  * Create a collection of certificates in the specified trust domain.

   383  * Optionally provide a starting set of certs.

   384  */

   385 NSS_EXTERN nssPKIObjectCollection *

   386 nssCertificateCollection_Create

   387 (

   388   NSSTrustDomain *td,

   389   NSSCertificate **certsOpt

   390 );

   392 /* nssCRLCollection_Create

   393  *

   394  * Create a collection of CRLs/KRLs in the specified trust domain.

   395  * Optionally provide a starting set of CRLs.

   396  */

   397 NSS_EXTERN nssPKIObjectCollection *

   398 nssCRLCollection_Create

   399 (

   400   NSSTrustDomain *td,

   401   NSSCRL **crlsOpt

   402 );

   404 /* nssPrivateKeyCollection_Create

   405  *

   406  * Create a collection of private keys in the specified trust domain.

   407  * Optionally provide a starting set of keys.

   408  */

   409 NSS_EXTERN nssPKIObjectCollection *

   410 nssPrivateKeyCollection_Create

   411 (

   412   NSSTrustDomain *td,

   413   NSSPrivateKey **pvkOpt

   414 );

   416 /* nssPublicKeyCollection_Create

   417  *

   418  * Create a collection of public keys in the specified trust domain.

   419  * Optionally provide a starting set of keys.

   420  */

   421 NSS_EXTERN nssPKIObjectCollection *

   422 nssPublicKeyCollection_Create

   423 (

   424   NSSTrustDomain *td,

   425   NSSPublicKey **pvkOpt

   426 );

   428 /* nssPKIObjectCollection_Destroy

   429  */

   430 NSS_EXTERN void

   431 nssPKIObjectCollection_Destroy

   432 (

   433   nssPKIObjectCollection *collection

   434 );

   436 /* nssPKIObjectCollection_Count

   437  */

   438 NSS_EXTERN PRUint32

   439 nssPKIObjectCollection_Count

   440 (

   441   nssPKIObjectCollection *collection

   442 );

   444 NSS_EXTERN PRStatus

   445 nssPKIObjectCollection_AddObject

   446 (

   447   nssPKIObjectCollection *collection,

   448   nssPKIObject *object

   449 );

   451 /* nssPKIObjectCollection_AddInstances

   452  *

   453  * Add a set of object instances to the collection.  The instances

   454  * will be sorted into any existing certs/proto-certs that may be in

   455  * the collection.  The instances will be absorbed by the collection,

   456  * the array should not be used after this call (except to free it).

   457  *

   458  * Failure means the collection is in an invalid state.

   459  *

   460  * numInstances = 0 means the array is NULL-terminated

   461  */

   462 NSS_EXTERN PRStatus

   463 nssPKIObjectCollection_AddInstances

   464 (

   465   nssPKIObjectCollection *collection,

   466   nssCryptokiObject **instances,

   467   PRUint32 numInstances

   468 );

   470 /* nssPKIObjectCollection_Traverse

   471  */

   472 NSS_EXTERN PRStatus

   473 nssPKIObjectCollection_Traverse

   474 (

   475   nssPKIObjectCollection *collection,

   476   nssPKIObjectCallback *callback

   477 );

   479 /* This function is being added for NSS 3.5.  It corresponds to the function

   480  * nssToken_TraverseCertificates.  The idea is to use the collection during

   481  * a traversal, creating certs each time a new instance is added for which

   482  * a cert does not already exist.

   483  */

   484 NSS_EXTERN PRStatus

   485 nssPKIObjectCollection_AddInstanceAsObject

   486 (

   487   nssPKIObjectCollection *collection,

   488   nssCryptokiObject *instance

   489 );

   491 /* nssPKIObjectCollection_GetCertificates

   492  *

   493  * Get all of the certificates in the collection.

   494  */

   495 NSS_EXTERN NSSCertificate **

   496 nssPKIObjectCollection_GetCertificates

   497 (

   498   nssPKIObjectCollection *collection,

   499   NSSCertificate **rvOpt,

   500   PRUint32 maximumOpt,

   501   NSSArena *arenaOpt

   502 );

   504 NSS_EXTERN NSSCRL **

   505 nssPKIObjectCollection_GetCRLs

   506 (

   507   nssPKIObjectCollection *collection,

   508   NSSCRL **rvOpt,

   509   PRUint32 maximumOpt,

   510   NSSArena *arenaOpt

   511 );

   513 NSS_EXTERN NSSPrivateKey **

   514 nssPKIObjectCollection_GetPrivateKeys

   515 (

   516   nssPKIObjectCollection *collection,

   517   NSSPrivateKey **rvOpt,

   518   PRUint32 maximumOpt,

   519   NSSArena *arenaOpt

   520 );

   522 NSS_EXTERN NSSPublicKey **

   523 nssPKIObjectCollection_GetPublicKeys

   524 (

   525   nssPKIObjectCollection *collection,

   526   NSSPublicKey **rvOpt,

   527   PRUint32 maximumOpt,

   528   NSSArena *arenaOpt

   529 );

   531 NSS_EXTERN NSSTime *

   532 NSSTime_Now

   533 (

   534   NSSTime *timeOpt

   535 );

   537 NSS_EXTERN NSSTime *

   538 NSSTime_SetPRTime

   539 (

   540   NSSTime *timeOpt,

   541   PRTime prTime

   542 );

   544 NSS_EXTERN PRTime

   545 NSSTime_GetPRTime

   546 (

   547   NSSTime *time

   548 );

   550 NSS_EXTERN nssHash *

   551 nssHash_CreateCertificate

   552 (

   553   NSSArena *arenaOpt,

   554   PRUint32 numBuckets

   555 );

   557 /* 3.4 Certificate cache routines */

   559 NSS_EXTERN PRStatus

   560 nssTrustDomain_InitializeCache

   561 (

   562   NSSTrustDomain *td,

   563   PRUint32 cacheSize

   564 );

   566 NSS_EXTERN PRStatus

   567 nssTrustDomain_AddCertsToCache

   568 (

   569   NSSTrustDomain *td,

   570   NSSCertificate **certs,

   571   PRUint32 numCerts

   572 );

   574 NSS_EXTERN void

   575 nssTrustDomain_RemoveCertFromCacheLOCKED (

   576   NSSTrustDomain *td,

   577   NSSCertificate *cert

   578 );

   580 NSS_EXTERN void

   581 nssTrustDomain_LockCertCache (

   582   NSSTrustDomain *td

   583 );

   585 NSS_EXTERN void

   586 nssTrustDomain_UnlockCertCache (

   587   NSSTrustDomain *td

   588 );

   590 NSS_IMPLEMENT PRStatus

   591 nssTrustDomain_DestroyCache

   592 (

   593   NSSTrustDomain *td

   594 );

   596 /*

   597  * Remove all certs for the given token from the cache.  This is

   598  * needed if the token is removed.

   599  */

   600 NSS_EXTERN PRStatus

   601 nssTrustDomain_RemoveTokenCertsFromCache

   602 (

   603   NSSTrustDomain *td,

   604   NSSToken *token

   605 );

   607 NSS_EXTERN PRStatus

   608 nssTrustDomain_UpdateCachedTokenCerts

   609 (

   610   NSSTrustDomain *td,

   611   NSSToken *token

   612 );

   614 /*

   615  * Find all cached certs with this nickname (label).

   616  */

   617 NSS_EXTERN NSSCertificate **

   618 nssTrustDomain_GetCertsForNicknameFromCache

   619 (

   620   NSSTrustDomain *td,

   621   const NSSUTF8 *nickname,

   622   nssList *certListOpt

   623 );

   625 /*

   626  * Find all cached certs with this email address.

   627  */

   628 NSS_EXTERN NSSCertificate **

   629 nssTrustDomain_GetCertsForEmailAddressFromCache

   630 (

   631   NSSTrustDomain *td,

   632   NSSASCII7 *email,

   633   nssList *certListOpt

   634 );

   636 /*

   637  * Find all cached certs with this subject.

   638  */

   639 NSS_EXTERN NSSCertificate **

   640 nssTrustDomain_GetCertsForSubjectFromCache

   641 (

   642   NSSTrustDomain *td,

   643   NSSDER *subject,

   644   nssList *certListOpt

   645 );

   647 /*

   648  * Look for a specific cert in the cache.

   649  */

   650 NSS_EXTERN NSSCertificate *

   651 nssTrustDomain_GetCertForIssuerAndSNFromCache

   652 (

   653   NSSTrustDomain *td,

   654   NSSDER *issuer,

   655   NSSDER *serialNum

   656 );

   658 /*

   659  * Look for a specific cert in the cache.

   660  */

   661 NSS_EXTERN NSSCertificate *

   662 nssTrustDomain_GetCertByDERFromCache

   663 (

   664   NSSTrustDomain *td,

   665   NSSDER *der

   666 );

   668 /* Get all certs from the cache */

   669 /* XXX this is being included to make some old-style calls word, not to

   670  *     say we should keep it

   671  */

   672 NSS_EXTERN NSSCertificate **

   673 nssTrustDomain_GetCertsFromCache

   674 (

   675   NSSTrustDomain *td,

   676   nssList *certListOpt

   677 );

   679 NSS_EXTERN void

   680 nssTrustDomain_DumpCacheInfo

   681 (

   682   NSSTrustDomain *td,

   683   void (* cert_dump_iter)(const void *, void *, void *),

   684   void *arg

   685 );

   687 NSS_EXTERN void

   688 nssCertificateList_AddReferences

   689 (

   690   nssList *certList

   691 );

   693 PR_END_EXTERN_C

   695 #endif /* PKIM_H */

The Tor Browser / file revision

security/nss/lib/pki/pkim.h@6474c204b198

security/nss/lib/pki/pkim.h