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.2 $ $Date: 2007/11/16 05:25:08 $";
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 NSS_EXTERN nssCryptokiObject **
00190 nssPKIObject_GetInstances
00191 (
00192   nssPKIObject *object
00193 );
00194 
00195 NSS_EXTERN NSSCertificate **
00196 nssTrustDomain_FindCertificatesByID
00197 (
00198   NSSTrustDomain *td,
00199   NSSItem *id,
00200   NSSCertificate **rvOpt,
00201   PRUint32 maximumOpt,
00202   NSSArena *arenaOpt
00203 );
00204 
00205 NSS_EXTERN NSSCRL **
00206 nssTrustDomain_FindCRLsBySubject
00207 (
00208   NSSTrustDomain *td,
00209   NSSDER *subject
00210 );
00211 
00212 /* module-private nsspki methods */
00213 
00214 NSS_EXTERN NSSCryptoContext *
00215 nssCryptoContext_Create
00216 (
00217   NSSTrustDomain *td,
00218   NSSCallback *uhhOpt
00219 );
00220 
00221 /* XXX for the collection */
00222 NSS_EXTERN NSSCertificate *
00223 nssCertificate_Create
00224 (
00225   nssPKIObject *object
00226 );
00227 
00228 NSS_EXTERN PRStatus
00229 nssCertificate_SetCertTrust
00230 (
00231   NSSCertificate *c,
00232   NSSTrust *trust
00233 );
00234 
00235 NSS_EXTERN nssDecodedCert *
00236 nssCertificate_GetDecoding
00237 (
00238   NSSCertificate *c
00239 );
00240 
00241 extern PRIntn
00242 nssCertificate_SubjectListSort
00243 (
00244   void *v1,
00245   void *v2
00246 );
00247 
00248 NSS_EXTERN nssDecodedCert *
00249 nssDecodedCert_Create
00250 (
00251   NSSArena *arenaOpt,
00252   NSSDER *encoding,
00253   NSSCertificateType type
00254 );
00255 
00256 NSS_EXTERN PRStatus
00257 nssDecodedCert_Destroy
00258 (
00259   nssDecodedCert *dc
00260 );
00261 
00262 NSS_EXTERN NSSTrust *
00263 nssTrust_Create
00264 (
00265   nssPKIObject *object,
00266   NSSItem *certData
00267 );
00268 
00269 NSS_EXTERN NSSCRL *
00270 nssCRL_Create
00271 (
00272   nssPKIObject *object
00273 );
00274 
00275 NSS_EXTERN NSSCRL *
00276 nssCRL_AddRef
00277 (
00278   NSSCRL *crl
00279 );
00280 
00281 NSS_EXTERN PRStatus
00282 nssCRL_Destroy
00283 (
00284   NSSCRL *crl
00285 );
00286 
00287 NSS_EXTERN PRStatus
00288 nssCRL_DeleteStoredObject
00289 (
00290   NSSCRL *crl,
00291   NSSCallback *uhh
00292 );
00293 
00294 NSS_EXTERN NSSPrivateKey *
00295 nssPrivateKey_Create
00296 (
00297   nssPKIObject *o
00298 );
00299 
00300 NSS_EXTERN NSSDER *
00301 nssCRL_GetEncoding
00302 (
00303   NSSCRL *crl
00304 );
00305 
00306 NSS_EXTERN NSSPublicKey *
00307 nssPublicKey_Create
00308 (
00309   nssPKIObject *object
00310 );
00311 
00312 /* nssCertificateArray
00313  *
00314  * These are being thrown around a lot, might as well group together some
00315  * functionality.
00316  *
00317  * nssCertificateArray_Destroy
00318  * nssCertificateArray_Join
00319  * nssCertificateArray_FindBestCertificate
00320  * nssCertificateArray_Traverse
00321  */
00322 
00323 /* nssCertificateArray_Destroy
00324  *
00325  * Will destroy the array and the certs within it.  If the array was created
00326  * in an arena, will *not* (of course) destroy the arena.  However, is safe
00327  * to call this method on an arena-allocated array.
00328  */
00329 NSS_EXTERN void
00330 nssCertificateArray_Destroy
00331 (
00332   NSSCertificate **certs
00333 );
00334 
00335 /* nssCertificateArray_Join
00336  *
00337  * Join two arrays into one.  The two arrays, certs1 and certs2, should
00338  * be considered invalid after a call to this function (they may be destroyed
00339  * as part of the join).  certs1 and/or certs2 may be NULL.  Safe to
00340  * call with arrays allocated in an arena, the result will also be in the
00341  * arena.
00342  */
00343 NSS_EXTERN NSSCertificate **
00344 nssCertificateArray_Join
00345 (
00346   NSSCertificate **certs1,
00347   NSSCertificate **certs2
00348 );
00349 
00350 /* nssCertificateArray_FindBestCertificate
00351  *
00352  * Use the usual { time, usage, policies } to find the best cert in the
00353  * array.
00354  */
00355 NSS_EXTERN NSSCertificate * 
00356 nssCertificateArray_FindBestCertificate
00357 (
00358   NSSCertificate **certs, 
00359   NSSTime *timeOpt,
00360   const NSSUsage *usage,
00361   NSSPolicies *policiesOpt
00362 );
00363 
00364 /* nssCertificateArray_Traverse
00365  *
00366  * Do the callback for each cert, terminate the traversal if the callback
00367  * fails.
00368  */
00369 NSS_EXTERN PRStatus
00370 nssCertificateArray_Traverse
00371 (
00372   NSSCertificate **certs,
00373   PRStatus (* callback)(NSSCertificate *c, void *arg),
00374   void *arg
00375 );
00376 
00377 NSS_EXTERN void
00378 nssCRLArray_Destroy
00379 (
00380   NSSCRL **crls
00381 );
00382 
00383 /* nssPKIObjectCollection
00384  *
00385  * This is a handy way to group objects together and perform operations
00386  * on them.  It can also handle "proto-objects"-- references to
00387  * objects instances on tokens, where the actual object hasn't 
00388  * been formed yet.
00389  *
00390  * nssCertificateCollection_Create
00391  * nssPrivateKeyCollection_Create
00392  * nssPublicKeyCollection_Create
00393  *
00394  * If this was a language that provided for inheritance, each type would
00395  * inherit all of the following methods.  Instead, there is only one
00396  * type (nssPKIObjectCollection), shared among all.  This may cause
00397  * confusion; an alternative would be to define all of the methods
00398  * for each subtype (nssCertificateCollection_Destroy, ...), but that doesn't
00399  * seem worth the code bloat..  It is left up to the caller to remember 
00400  * what type of collection he/she is dealing with.
00401  *
00402  * nssPKIObjectCollection_Destroy
00403  * nssPKIObjectCollection_Count
00404  * nssPKIObjectCollection_AddObject
00405  * nssPKIObjectCollection_AddInstances
00406  * nssPKIObjectCollection_Traverse
00407  *
00408  * Back to type-specific methods.
00409  *
00410  * nssPKIObjectCollection_GetCertificates
00411  * nssPKIObjectCollection_GetCRLs
00412  * nssPKIObjectCollection_GetPrivateKeys
00413  * nssPKIObjectCollection_GetPublicKeys
00414  */
00415 
00416 /* nssCertificateCollection_Create
00417  *
00418  * Create a collection of certificates in the specified trust domain.
00419  * Optionally provide a starting set of certs.
00420  */
00421 NSS_EXTERN nssPKIObjectCollection *
00422 nssCertificateCollection_Create
00423 (
00424   NSSTrustDomain *td,
00425   NSSCertificate **certsOpt
00426 );
00427 
00428 /* nssCRLCollection_Create
00429  *
00430  * Create a collection of CRLs/KRLs in the specified trust domain.
00431  * Optionally provide a starting set of CRLs.
00432  */
00433 NSS_EXTERN nssPKIObjectCollection *
00434 nssCRLCollection_Create
00435 (
00436   NSSTrustDomain *td,
00437   NSSCRL **crlsOpt
00438 );
00439 
00440 /* nssPrivateKeyCollection_Create
00441  *
00442  * Create a collection of private keys in the specified trust domain.
00443  * Optionally provide a starting set of keys.
00444  */
00445 NSS_EXTERN nssPKIObjectCollection *
00446 nssPrivateKeyCollection_Create
00447 (
00448   NSSTrustDomain *td,
00449   NSSPrivateKey **pvkOpt
00450 );
00451 
00452 /* nssPublicKeyCollection_Create
00453  *
00454  * Create a collection of public keys in the specified trust domain.
00455  * Optionally provide a starting set of keys.
00456  */
00457 NSS_EXTERN nssPKIObjectCollection *
00458 nssPublicKeyCollection_Create
00459 (
00460   NSSTrustDomain *td,
00461   NSSPublicKey **pvkOpt
00462 );
00463 
00464 /* nssPKIObjectCollection_Destroy
00465  */
00466 NSS_EXTERN void
00467 nssPKIObjectCollection_Destroy
00468 (
00469   nssPKIObjectCollection *collection
00470 );
00471 
00472 /* nssPKIObjectCollection_Count
00473  */
00474 NSS_EXTERN PRUint32
00475 nssPKIObjectCollection_Count
00476 (
00477   nssPKIObjectCollection *collection
00478 );
00479 
00480 NSS_EXTERN PRStatus
00481 nssPKIObjectCollection_AddObject
00482 (
00483   nssPKIObjectCollection *collection,
00484   nssPKIObject *object
00485 );
00486 
00487 /* nssPKIObjectCollection_AddInstances
00488  *
00489  * Add a set of object instances to the collection.  The instances
00490  * will be sorted into any existing certs/proto-certs that may be in
00491  * the collection.  The instances will be absorbed by the collection,
00492  * the array should not be used after this call (except to free it).
00493  *
00494  * Failure means the collection is in an invalid state.
00495  *
00496  * numInstances = 0 means the array is NULL-terminated
00497  */
00498 NSS_EXTERN PRStatus
00499 nssPKIObjectCollection_AddInstances
00500 (
00501   nssPKIObjectCollection *collection,
00502   nssCryptokiObject **instances,
00503   PRUint32 numInstances
00504 );
00505 
00506 /* nssPKIObjectCollection_Traverse
00507  */
00508 NSS_EXTERN PRStatus
00509 nssPKIObjectCollection_Traverse
00510 (
00511   nssPKIObjectCollection *collection,
00512   nssPKIObjectCallback *callback
00513 );
00514 
00515 /* This function is being added for NSS 3.5.  It corresponds to the function
00516  * nssToken_TraverseCertificates.  The idea is to use the collection during
00517  * a traversal, creating certs each time a new instance is added for which
00518  * a cert does not already exist.
00519  */
00520 NSS_EXTERN PRStatus
00521 nssPKIObjectCollection_AddInstanceAsObject
00522 (
00523   nssPKIObjectCollection *collection,
00524   nssCryptokiObject *instance
00525 );
00526 
00527 /* nssPKIObjectCollection_GetCertificates
00528  *
00529  * Get all of the certificates in the collection. 
00530  */
00531 NSS_EXTERN NSSCertificate **
00532 nssPKIObjectCollection_GetCertificates
00533 (
00534   nssPKIObjectCollection *collection,
00535   NSSCertificate **rvOpt,
00536   PRUint32 maximumOpt,
00537   NSSArena *arenaOpt
00538 );
00539 
00540 NSS_EXTERN NSSCRL **
00541 nssPKIObjectCollection_GetCRLs
00542 (
00543   nssPKIObjectCollection *collection,
00544   NSSCRL **rvOpt,
00545   PRUint32 maximumOpt,
00546   NSSArena *arenaOpt
00547 );
00548 
00549 NSS_EXTERN NSSPrivateKey **
00550 nssPKIObjectCollection_GetPrivateKeys
00551 (
00552   nssPKIObjectCollection *collection,
00553   NSSPrivateKey **rvOpt,
00554   PRUint32 maximumOpt,
00555   NSSArena *arenaOpt
00556 );
00557 
00558 NSS_EXTERN NSSPublicKey **
00559 nssPKIObjectCollection_GetPublicKeys
00560 (
00561   nssPKIObjectCollection *collection,
00562   NSSPublicKey **rvOpt,
00563   PRUint32 maximumOpt,
00564   NSSArena *arenaOpt
00565 );
00566 
00567 NSS_EXTERN NSSTime *
00568 NSSTime_Now
00569 (
00570   NSSTime *timeOpt
00571 );
00572 
00573 NSS_EXTERN NSSTime *
00574 NSSTime_SetPRTime
00575 (
00576   NSSTime *timeOpt,
00577   PRTime prTime
00578 );
00579 
00580 NSS_EXTERN PRTime
00581 NSSTime_GetPRTime
00582 (
00583   NSSTime *time
00584 );
00585 
00586 NSS_EXTERN nssHash *
00587 nssHash_CreateCertificate
00588 (
00589   NSSArena *arenaOpt,
00590   PRUint32 numBuckets
00591 );
00592 
00593 /* 3.4 Certificate cache routines */
00594 
00595 NSS_EXTERN PRStatus
00596 nssTrustDomain_InitializeCache
00597 (
00598   NSSTrustDomain *td,
00599   PRUint32 cacheSize
00600 );
00601 
00602 NSS_EXTERN PRStatus
00603 nssTrustDomain_AddCertsToCache
00604 (
00605   NSSTrustDomain *td,
00606   NSSCertificate **certs,
00607   PRUint32 numCerts
00608 );
00609 
00610 NSS_EXTERN void
00611 nssTrustDomain_RemoveCertFromCacheLOCKED (
00612   NSSTrustDomain *td,
00613   NSSCertificate *cert
00614 );
00615 
00616 NSS_EXTERN void
00617 nssTrustDomain_LockCertCache (
00618   NSSTrustDomain *td
00619 );
00620 
00621 NSS_EXTERN void
00622 nssTrustDomain_UnlockCertCache (
00623   NSSTrustDomain *td
00624 );
00625 
00626 NSS_IMPLEMENT PRStatus
00627 nssTrustDomain_DestroyCache
00628 (
00629   NSSTrustDomain *td
00630 );
00631 
00632 /* 
00633  * Remove all certs for the given token from the cache.  This is
00634  * needed if the token is removed.
00635  */
00636 NSS_EXTERN PRStatus
00637 nssTrustDomain_RemoveTokenCertsFromCache
00638 (
00639   NSSTrustDomain *td,
00640   NSSToken *token
00641 );
00642 
00643 NSS_EXTERN PRStatus
00644 nssTrustDomain_UpdateCachedTokenCerts
00645 (
00646   NSSTrustDomain *td,
00647   NSSToken *token
00648 );
00649 
00650 /*
00651  * Find all cached certs with this nickname (label).
00652  */
00653 NSS_EXTERN NSSCertificate **
00654 nssTrustDomain_GetCertsForNicknameFromCache
00655 (
00656   NSSTrustDomain *td,
00657   NSSUTF8 *nickname,
00658   nssList *certListOpt
00659 );
00660 
00661 /*
00662  * Find all cached certs with this email address.
00663  */
00664 NSS_EXTERN NSSCertificate **
00665 nssTrustDomain_GetCertsForEmailAddressFromCache
00666 (
00667   NSSTrustDomain *td,
00668   NSSASCII7 *email,
00669   nssList *certListOpt
00670 );
00671 
00672 /*
00673  * Find all cached certs with this subject.
00674  */
00675 NSS_EXTERN NSSCertificate **
00676 nssTrustDomain_GetCertsForSubjectFromCache
00677 (
00678   NSSTrustDomain *td,
00679   NSSDER *subject,
00680   nssList *certListOpt
00681 );
00682 
00683 /*
00684  * Look for a specific cert in the cache.
00685  */
00686 NSS_EXTERN NSSCertificate *
00687 nssTrustDomain_GetCertForIssuerAndSNFromCache
00688 (
00689   NSSTrustDomain *td,
00690   NSSDER *issuer,
00691   NSSDER *serialNum
00692 );
00693 
00694 /*
00695  * Look for a specific cert in the cache.
00696  */
00697 NSS_EXTERN NSSCertificate *
00698 nssTrustDomain_GetCertByDERFromCache
00699 (
00700   NSSTrustDomain *td,
00701   NSSDER *der
00702 );
00703 
00704 /* Get all certs from the cache */
00705 /* XXX this is being included to make some old-style calls word, not to
00706  *     say we should keep it
00707  */
00708 NSS_EXTERN NSSCertificate **
00709 nssTrustDomain_GetCertsFromCache
00710 (
00711   NSSTrustDomain *td,
00712   nssList *certListOpt
00713 );
00714 
00715 NSS_EXTERN void
00716 nssTrustDomain_DumpCacheInfo
00717 (
00718   NSSTrustDomain *td,
00719   void (* cert_dump_iter)(const void *, void *, void *),
00720   void *arg
00721 );
00722 
00723 NSS_EXTERN void
00724 nssCertificateList_AddReferences
00725 (
00726   nssList *certList
00727 );
00728 
00729 PR_END_EXTERN_C
00730 
00731 #endif /* PKIM_H */