Back to index

lightning-sunbird  0.9+nobinonly
pkim.h
Go to the documentation of this file.
00001 /* ***** BEGIN LICENSE BLOCK *****
00002  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00003  *
00004  * The contents of this file are subject to the Mozilla Public License Version
00005  * 1.1 (the "License"); you may not use this file except in compliance with
00006  * the License. You may obtain a copy of the License at
00007  * http://www.mozilla.org/MPL/
00008  *
00009  * Software distributed under the License is distributed on an "AS IS" basis,
00010  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00011  * for the specific language governing rights and limitations under the
00012  * License.
00013  *
00014  * The Original Code is the Netscape security libraries.
00015  *
00016  * The Initial Developer of the Original Code is
00017  * Netscape Communications Corporation.
00018  * Portions created by the Initial Developer are Copyright (C) 1994-2000
00019  * the Initial Developer. All Rights Reserved.
00020  *
00021  * Contributor(s):
00022  *
00023  * Alternatively, the contents of this file may be used under the terms of
00024  * either the GNU General Public License Version 2 or later (the "GPL"), or
00025  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00026  * in which case the provisions of the GPL or the LGPL are applicable instead
00027  * of those above. If you wish to allow use of your version of this file only
00028  * under the terms of either the GPL or the LGPL, and not to allow others to
00029  * use your version of this file under the terms of the MPL, indicate your
00030  * decision by deleting the provisions above and replace them with the notice
00031  * and other provisions required by the GPL or the LGPL. If you do not delete
00032  * the provisions above, a recipient may use your version of this file under
00033  * the terms of any one of the MPL, the GPL or the LGPL.
00034  *
00035  * ***** END LICENSE BLOCK ***** */
00036 
00037 #ifndef PKIM_H
00038 #define PKIM_H
00039 
00040 #ifdef DEBUG
00041 static const char PKIM_CVS_ID[] = "@(#) $RCSfile: pkim.h,v $ $Revision: 1.27.2.1 $ $Date: 2006/08/23 01:36:31 $";
00042 #endif /* DEBUG */
00043 
00044 #ifndef BASE_H
00045 #include "base.h"
00046 #endif /* BASE_H */
00047 
00048 #ifndef PKI_H
00049 #include "pki.h"
00050 #endif /* PKI_H */
00051 
00052 #ifndef PKITM_H
00053 #include "pkitm.h"
00054 #endif /* PKITM_H */
00055 
00056 PR_BEGIN_EXTERN_C
00057 
00058 /* nssPKIObject
00059  *
00060  * This is the base object class, common to all PKI objects defined in
00061  * in this module.  Each object can be safely 'casted' to an nssPKIObject,
00062  * then passed to these methods.
00063  *
00064  * nssPKIObject_Create
00065  * nssPKIObject_Destroy
00066  * nssPKIObject_AddRef
00067  * nssPKIObject_AddInstance
00068  * nssPKIObject_HasInstance
00069  * nssPKIObject_GetTokens
00070  * nssPKIObject_GetNicknameForToken
00071  * nssPKIObject_RemoveInstanceForToken
00072  * nssPKIObject_DeleteStoredObject
00073  */
00074 
00075 NSS_EXTERN void     nssPKIObject_Lock       (nssPKIObject * object);
00076 NSS_EXTERN void     nssPKIObject_Unlock     (nssPKIObject * object);
00077 NSS_EXTERN PRStatus nssPKIObject_NewLock    (nssPKIObject * object,
00078                                              nssPKILockType lockType);
00079 NSS_EXTERN void     nssPKIObject_DestroyLock(nssPKIObject * object);
00080 
00081 /* nssPKIObject_Create
00082  *
00083  * A generic PKI object.  It must live in a trust domain.  It may be
00084  * initialized with a token instance, or alternatively in a crypto context.
00085  */
00086 NSS_EXTERN nssPKIObject *
00087 nssPKIObject_Create
00088 (
00089   NSSArena *arenaOpt,
00090   nssCryptokiObject *instanceOpt,
00091   NSSTrustDomain *td,
00092   NSSCryptoContext *ccOpt,
00093   nssPKILockType lockType
00094 );
00095 
00096 /* nssPKIObject_AddRef
00097  */
00098 NSS_EXTERN nssPKIObject *
00099 nssPKIObject_AddRef
00100 (
00101   nssPKIObject *object
00102 );
00103 
00104 /* nssPKIObject_Destroy
00105  *
00106  * Returns true if object was destroyed.  This notifies the subclass that
00107  * all references are gone and it should delete any members it owns.
00108  */
00109 NSS_EXTERN PRBool
00110 nssPKIObject_Destroy
00111 (
00112   nssPKIObject *object
00113 );
00114 
00115 /* nssPKIObject_AddInstance
00116  *
00117  * Add a token instance to the object, if it does not have it already.
00118  */
00119 NSS_EXTERN PRStatus
00120 nssPKIObject_AddInstance
00121 (
00122   nssPKIObject *object,
00123   nssCryptokiObject *instance
00124 );
00125 
00126 /* nssPKIObject_HasInstance
00127  *
00128  * Query the object for a token instance.
00129  */
00130 NSS_EXTERN PRBool
00131 nssPKIObject_HasInstance
00132 (
00133   nssPKIObject *object,
00134   nssCryptokiObject *instance
00135 );
00136 
00137 /* nssPKIObject_GetTokens
00138  *
00139  * Get all tokens which have an instance of the object.
00140  */
00141 NSS_EXTERN NSSToken **
00142 nssPKIObject_GetTokens
00143 (
00144   nssPKIObject *object,
00145   PRStatus *statusOpt
00146 );
00147 
00148 /* nssPKIObject_GetNicknameForToken
00149  *
00150  * tokenOpt == NULL means take the first available, otherwise return the
00151  * nickname for the specified token.
00152  */
00153 NSS_EXTERN NSSUTF8 *
00154 nssPKIObject_GetNicknameForToken
00155 (
00156   nssPKIObject *object,
00157   NSSToken *tokenOpt
00158 );
00159 
00160 /* nssPKIObject_RemoveInstanceForToken
00161  *
00162  * Remove the instance of the object on the specified token.
00163  */
00164 NSS_EXTERN PRStatus
00165 nssPKIObject_RemoveInstanceForToken
00166 (
00167   nssPKIObject *object,
00168   NSSToken *token
00169 );
00170 
00171 /* nssPKIObject_DeleteStoredObject
00172  *
00173  * Delete all token instances of the object, as well as any crypto context
00174  * instances (TODO).  If any of the instances are read-only, or if the
00175  * removal fails, the object will keep those instances.  'isFriendly' refers
00176  * to the object -- can this object be removed from a friendly token without
00177  * login?  For example, certificates are friendly, private keys are not.
00178  * Note that if the token is not friendly, authentication will be required
00179  * regardless of the value of 'isFriendly'.
00180  */
00181 NSS_EXTERN PRStatus
00182 nssPKIObject_DeleteStoredObject
00183 (
00184   nssPKIObject *object,
00185   NSSCallback *uhh,
00186   PRBool isFriendly
00187 );
00188 
00189 #ifdef NSS_3_4_CODE
00190 NSS_EXTERN nssCryptokiObject **
00191 nssPKIObject_GetInstances
00192 (
00193   nssPKIObject *object
00194 );
00195 #endif
00196 
00197 NSS_EXTERN NSSCertificate **
00198 nssTrustDomain_FindCertificatesByID
00199 (
00200   NSSTrustDomain *td,
00201   NSSItem *id,
00202   NSSCertificate **rvOpt,
00203   PRUint32 maximumOpt,
00204   NSSArena *arenaOpt
00205 );
00206 
00207 NSS_EXTERN NSSCRL **
00208 nssTrustDomain_FindCRLsBySubject
00209 (
00210   NSSTrustDomain *td,
00211   NSSDER *subject
00212 );
00213 
00214 /* module-private nsspki methods */
00215 
00216 NSS_EXTERN NSSCryptoContext *
00217 nssCryptoContext_Create
00218 (
00219   NSSTrustDomain *td,
00220   NSSCallback *uhhOpt
00221 );
00222 
00223 /* XXX for the collection */
00224 NSS_EXTERN NSSCertificate *
00225 nssCertificate_Create
00226 (
00227   nssPKIObject *object
00228 );
00229 
00230 NSS_EXTERN PRStatus
00231 nssCertificate_SetCertTrust
00232 (
00233   NSSCertificate *c,
00234   NSSTrust *trust
00235 );
00236 
00237 NSS_EXTERN nssDecodedCert *
00238 nssCertificate_GetDecoding
00239 (
00240   NSSCertificate *c
00241 );
00242 
00243 extern PRIntn
00244 nssCertificate_SubjectListSort
00245 (
00246   void *v1,
00247   void *v2
00248 );
00249 
00250 NSS_EXTERN nssDecodedCert *
00251 nssDecodedCert_Create
00252 (
00253   NSSArena *arenaOpt,
00254   NSSDER *encoding,
00255   NSSCertificateType type
00256 );
00257 
00258 NSS_EXTERN PRStatus
00259 nssDecodedCert_Destroy
00260 (
00261   nssDecodedCert *dc
00262 );
00263 
00264 NSS_EXTERN NSSTrust *
00265 nssTrust_Create
00266 (
00267   nssPKIObject *object,
00268   NSSItem *certData
00269 );
00270 
00271 NSS_EXTERN NSSCRL *
00272 nssCRL_Create
00273 (
00274   nssPKIObject *object
00275 );
00276 
00277 NSS_EXTERN NSSCRL *
00278 nssCRL_AddRef
00279 (
00280   NSSCRL *crl
00281 );
00282 
00283 NSS_EXTERN PRStatus
00284 nssCRL_Destroy
00285 (
00286   NSSCRL *crl
00287 );
00288 
00289 NSS_EXTERN PRStatus
00290 nssCRL_DeleteStoredObject
00291 (
00292   NSSCRL *crl,
00293   NSSCallback *uhh
00294 );
00295 
00296 NSS_EXTERN NSSPrivateKey *
00297 nssPrivateKey_Create
00298 (
00299   nssPKIObject *o
00300 );
00301 
00302 NSS_EXTERN NSSDER *
00303 nssCRL_GetEncoding
00304 (
00305   NSSCRL *crl
00306 );
00307 
00308 NSS_EXTERN NSSPublicKey *
00309 nssPublicKey_Create
00310 (
00311   nssPKIObject *object
00312 );
00313 
00314 /* nssCertificateArray
00315  *
00316  * These are being thrown around a lot, might as well group together some
00317  * functionality.
00318  *
00319  * nssCertificateArray_Destroy
00320  * nssCertificateArray_Join
00321  * nssCertificateArray_FindBestCertificate
00322  * nssCertificateArray_Traverse
00323  */
00324 
00325 /* nssCertificateArray_Destroy
00326  *
00327  * Will destroy the array and the certs within it.  If the array was created
00328  * in an arena, will *not* (of course) destroy the arena.  However, is safe
00329  * to call this method on an arena-allocated array.
00330  */
00331 NSS_EXTERN void
00332 nssCertificateArray_Destroy
00333 (
00334   NSSCertificate **certs
00335 );
00336 
00337 /* nssCertificateArray_Join
00338  *
00339  * Join two arrays into one.  The two arrays, certs1 and certs2, should
00340  * be considered invalid after a call to this function (they may be destroyed
00341  * as part of the join).  certs1 and/or certs2 may be NULL.  Safe to
00342  * call with arrays allocated in an arena, the result will also be in the
00343  * arena.
00344  */
00345 NSS_EXTERN NSSCertificate **
00346 nssCertificateArray_Join
00347 (
00348   NSSCertificate **certs1,
00349   NSSCertificate **certs2
00350 );
00351 
00352 /* nssCertificateArray_FindBestCertificate
00353  *
00354  * Use the usual { time, usage, policies } to find the best cert in the
00355  * array.
00356  */
00357 NSS_EXTERN NSSCertificate * 
00358 nssCertificateArray_FindBestCertificate
00359 (
00360   NSSCertificate **certs, 
00361   NSSTime *timeOpt,
00362   const NSSUsage *usage,
00363   NSSPolicies *policiesOpt
00364 );
00365 
00366 /* nssCertificateArray_Traverse
00367  *
00368  * Do the callback for each cert, terminate the traversal if the callback
00369  * fails.
00370  */
00371 NSS_EXTERN PRStatus
00372 nssCertificateArray_Traverse
00373 (
00374   NSSCertificate **certs,
00375   PRStatus (* callback)(NSSCertificate *c, void *arg),
00376   void *arg
00377 );
00378 
00379 NSS_EXTERN void
00380 nssCRLArray_Destroy
00381 (
00382   NSSCRL **crls
00383 );
00384 
00385 /* nssPKIObjectCollection
00386  *
00387  * This is a handy way to group objects together and perform operations
00388  * on them.  It can also handle "proto-objects"-- references to
00389  * objects instances on tokens, where the actual object hasn't 
00390  * been formed yet.
00391  *
00392  * nssCertificateCollection_Create
00393  * nssPrivateKeyCollection_Create
00394  * nssPublicKeyCollection_Create
00395  *
00396  * If this was a language that provided for inheritance, each type would
00397  * inherit all of the following methods.  Instead, there is only one
00398  * type (nssPKIObjectCollection), shared among all.  This may cause
00399  * confusion; an alternative would be to define all of the methods
00400  * for each subtype (nssCertificateCollection_Destroy, ...), but that doesn't
00401  * seem worth the code bloat..  It is left up to the caller to remember 
00402  * what type of collection he/she is dealing with.
00403  *
00404  * nssPKIObjectCollection_Destroy
00405  * nssPKIObjectCollection_Count
00406  * nssPKIObjectCollection_AddObject
00407  * nssPKIObjectCollection_AddInstances
00408  * nssPKIObjectCollection_Traverse
00409  *
00410  * Back to type-specific methods.
00411  *
00412  * nssPKIObjectCollection_GetCertificates
00413  * nssPKIObjectCollection_GetCRLs
00414  * nssPKIObjectCollection_GetPrivateKeys
00415  * nssPKIObjectCollection_GetPublicKeys
00416  */
00417 
00418 /* nssCertificateCollection_Create
00419  *
00420  * Create a collection of certificates in the specified trust domain.
00421  * Optionally provide a starting set of certs.
00422  */
00423 NSS_EXTERN nssPKIObjectCollection *
00424 nssCertificateCollection_Create
00425 (
00426   NSSTrustDomain *td,
00427   NSSCertificate **certsOpt
00428 );
00429 
00430 /* nssCRLCollection_Create
00431  *
00432  * Create a collection of CRLs/KRLs in the specified trust domain.
00433  * Optionally provide a starting set of CRLs.
00434  */
00435 NSS_EXTERN nssPKIObjectCollection *
00436 nssCRLCollection_Create
00437 (
00438   NSSTrustDomain *td,
00439   NSSCRL **crlsOpt
00440 );
00441 
00442 /* nssPrivateKeyCollection_Create
00443  *
00444  * Create a collection of private keys in the specified trust domain.
00445  * Optionally provide a starting set of keys.
00446  */
00447 NSS_EXTERN nssPKIObjectCollection *
00448 nssPrivateKeyCollection_Create
00449 (
00450   NSSTrustDomain *td,
00451   NSSPrivateKey **pvkOpt
00452 );
00453 
00454 /* nssPublicKeyCollection_Create
00455  *
00456  * Create a collection of public keys in the specified trust domain.
00457  * Optionally provide a starting set of keys.
00458  */
00459 NSS_EXTERN nssPKIObjectCollection *
00460 nssPublicKeyCollection_Create
00461 (
00462   NSSTrustDomain *td,
00463   NSSPublicKey **pvkOpt
00464 );
00465 
00466 /* nssPKIObjectCollection_Destroy
00467  */
00468 NSS_EXTERN void
00469 nssPKIObjectCollection_Destroy
00470 (
00471   nssPKIObjectCollection *collection
00472 );
00473 
00474 /* nssPKIObjectCollection_Count
00475  */
00476 NSS_EXTERN PRUint32
00477 nssPKIObjectCollection_Count
00478 (
00479   nssPKIObjectCollection *collection
00480 );
00481 
00482 NSS_EXTERN PRStatus
00483 nssPKIObjectCollection_AddObject
00484 (
00485   nssPKIObjectCollection *collection,
00486   nssPKIObject *object
00487 );
00488 
00489 /* nssPKIObjectCollection_AddInstances
00490  *
00491  * Add a set of object instances to the collection.  The instances
00492  * will be sorted into any existing certs/proto-certs that may be in
00493  * the collection.  The instances will be absorbed by the collection,
00494  * the array should not be used after this call (except to free it).
00495  *
00496  * Failure means the collection is in an invalid state.
00497  *
00498  * numInstances = 0 means the array is NULL-terminated
00499  */
00500 NSS_EXTERN PRStatus
00501 nssPKIObjectCollection_AddInstances
00502 (
00503   nssPKIObjectCollection *collection,
00504   nssCryptokiObject **instances,
00505   PRUint32 numInstances
00506 );
00507 
00508 /* nssPKIObjectCollection_Traverse
00509  */
00510 NSS_EXTERN PRStatus
00511 nssPKIObjectCollection_Traverse
00512 (
00513   nssPKIObjectCollection *collection,
00514   nssPKIObjectCallback *callback
00515 );
00516 
00517 /* This function is being added for NSS 3.5.  It corresponds to the function
00518  * nssToken_TraverseCertificates.  The idea is to use the collection during
00519  * a traversal, creating certs each time a new instance is added for which
00520  * a cert does not already exist.
00521  */
00522 NSS_EXTERN PRStatus
00523 nssPKIObjectCollection_AddInstanceAsObject
00524 (
00525   nssPKIObjectCollection *collection,
00526   nssCryptokiObject *instance
00527 );
00528 
00529 /* nssPKIObjectCollection_GetCertificates
00530  *
00531  * Get all of the certificates in the collection. 
00532  */
00533 NSS_EXTERN NSSCertificate **
00534 nssPKIObjectCollection_GetCertificates
00535 (
00536   nssPKIObjectCollection *collection,
00537   NSSCertificate **rvOpt,
00538   PRUint32 maximumOpt,
00539   NSSArena *arenaOpt
00540 );
00541 
00542 NSS_EXTERN NSSCRL **
00543 nssPKIObjectCollection_GetCRLs
00544 (
00545   nssPKIObjectCollection *collection,
00546   NSSCRL **rvOpt,
00547   PRUint32 maximumOpt,
00548   NSSArena *arenaOpt
00549 );
00550 
00551 NSS_EXTERN NSSPrivateKey **
00552 nssPKIObjectCollection_GetPrivateKeys
00553 (
00554   nssPKIObjectCollection *collection,
00555   NSSPrivateKey **rvOpt,
00556   PRUint32 maximumOpt,
00557   NSSArena *arenaOpt
00558 );
00559 
00560 NSS_EXTERN NSSPublicKey **
00561 nssPKIObjectCollection_GetPublicKeys
00562 (
00563   nssPKIObjectCollection *collection,
00564   NSSPublicKey **rvOpt,
00565   PRUint32 maximumOpt,
00566   NSSArena *arenaOpt
00567 );
00568 
00569 NSS_EXTERN NSSTime *
00570 NSSTime_Now
00571 (
00572   NSSTime *timeOpt
00573 );
00574 
00575 NSS_EXTERN NSSTime *
00576 NSSTime_SetPRTime
00577 (
00578   NSSTime *timeOpt,
00579   PRTime prTime
00580 );
00581 
00582 NSS_EXTERN PRTime
00583 NSSTime_GetPRTime
00584 (
00585   NSSTime *time
00586 );
00587 
00588 NSS_EXTERN nssHash *
00589 nssHash_CreateCertificate
00590 (
00591   NSSArena *arenaOpt,
00592   PRUint32 numBuckets
00593 );
00594 
00595 /* 3.4 Certificate cache routines */
00596 
00597 NSS_EXTERN PRStatus
00598 nssTrustDomain_InitializeCache
00599 (
00600   NSSTrustDomain *td,
00601   PRUint32 cacheSize
00602 );
00603 
00604 NSS_EXTERN PRStatus
00605 nssTrustDomain_AddCertsToCache
00606 (
00607   NSSTrustDomain *td,
00608   NSSCertificate **certs,
00609   PRUint32 numCerts
00610 );
00611 
00612 NSS_EXTERN void
00613 nssTrustDomain_RemoveCertFromCacheLOCKED (
00614   NSSTrustDomain *td,
00615   NSSCertificate *cert
00616 );
00617 
00618 NSS_EXTERN void
00619 nssTrustDomain_LockCertCache (
00620   NSSTrustDomain *td
00621 );
00622 
00623 NSS_EXTERN void
00624 nssTrustDomain_UnlockCertCache (
00625   NSSTrustDomain *td
00626 );
00627 
00628 NSS_IMPLEMENT PRStatus
00629 nssTrustDomain_DestroyCache
00630 (
00631   NSSTrustDomain *td
00632 );
00633 
00634 /* 
00635  * Remove all certs for the given token from the cache.  This is
00636  * needed if the token is removed.
00637  */
00638 NSS_EXTERN PRStatus
00639 nssTrustDomain_RemoveTokenCertsFromCache
00640 (
00641   NSSTrustDomain *td,
00642   NSSToken *token
00643 );
00644 
00645 NSS_EXTERN PRStatus
00646 nssTrustDomain_UpdateCachedTokenCerts
00647 (
00648   NSSTrustDomain *td,
00649   NSSToken *token
00650 );
00651 
00652 /*
00653  * Find all cached certs with this nickname (label).
00654  */
00655 NSS_EXTERN NSSCertificate **
00656 nssTrustDomain_GetCertsForNicknameFromCache
00657 (
00658   NSSTrustDomain *td,
00659   NSSUTF8 *nickname,
00660   nssList *certListOpt
00661 );
00662 
00663 /*
00664  * Find all cached certs with this email address.
00665  */
00666 NSS_EXTERN NSSCertificate **
00667 nssTrustDomain_GetCertsForEmailAddressFromCache
00668 (
00669   NSSTrustDomain *td,
00670   NSSASCII7 *email,
00671   nssList *certListOpt
00672 );
00673 
00674 /*
00675  * Find all cached certs with this subject.
00676  */
00677 NSS_EXTERN NSSCertificate **
00678 nssTrustDomain_GetCertsForSubjectFromCache
00679 (
00680   NSSTrustDomain *td,
00681   NSSDER *subject,
00682   nssList *certListOpt
00683 );
00684 
00685 /*
00686  * Look for a specific cert in the cache.
00687  */
00688 NSS_EXTERN NSSCertificate *
00689 nssTrustDomain_GetCertForIssuerAndSNFromCache
00690 (
00691   NSSTrustDomain *td,
00692   NSSDER *issuer,
00693   NSSDER *serialNum
00694 );
00695 
00696 /*
00697  * Look for a specific cert in the cache.
00698  */
00699 NSS_EXTERN NSSCertificate *
00700 nssTrustDomain_GetCertByDERFromCache
00701 (
00702   NSSTrustDomain *td,
00703   NSSDER *der
00704 );
00705 
00706 /* Get all certs from the cache */
00707 /* XXX this is being included to make some old-style calls word, not to
00708  *     say we should keep it
00709  */
00710 NSS_EXTERN NSSCertificate **
00711 nssTrustDomain_GetCertsFromCache
00712 (
00713   NSSTrustDomain *td,
00714   nssList *certListOpt
00715 );
00716 
00717 NSS_EXTERN void
00718 nssTrustDomain_DumpCacheInfo
00719 (
00720   NSSTrustDomain *td,
00721   void (* cert_dump_iter)(const void *, void *, void *),
00722   void *arg
00723 );
00724 
00725 NSS_EXTERN void
00726 nssCertificateList_AddReferences
00727 (
00728   nssList *certList
00729 );
00730 
00731 PR_END_EXTERN_C
00732 
00733 #endif /* PKIM_H */