pkim.h (14221B)
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/. */ 4 5 #ifndef PKIM_H 6 #define PKIM_H 7 8 #ifndef BASE_H 9 #include "base.h" 10 #endif /* BASE_H */ 11 12 #ifndef PKI_H 13 #include "pki.h" 14 #endif /* PKI_H */ 15 16 #ifndef PKITM_H 17 #include "pkitm.h" 18 #endif /* PKITM_H */ 19 20 PR_BEGIN_EXTERN_C 21 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 */ 38 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); 44 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 NSSArena *arenaOpt, 53 nssCryptokiObject *instanceOpt, 54 NSSTrustDomain *td, 55 NSSCryptoContext *ccOpt, 56 nssPKILockType lockType); 57 58 /* nssPKIObject_AddRef 59 */ 60 NSS_EXTERN nssPKIObject * 61 nssPKIObject_AddRef(nssPKIObject *object); 62 63 /* nssPKIObject_Destroy 64 * 65 * Returns true if object was destroyed. This notifies the subclass that 66 * all references are gone and it should delete any members it owns. 67 */ 68 NSS_EXTERN PRBool 69 nssPKIObject_Destroy(nssPKIObject *object); 70 71 /* nssPKIObject_AddInstance 72 * 73 * Add a token instance to the object, if it does not have it already. 74 */ 75 NSS_EXTERN PRStatus 76 nssPKIObject_AddInstance( 77 nssPKIObject *object, 78 nssCryptokiObject *instance); 79 80 /* nssPKIObject_HasInstance 81 * 82 * Query the object for a token instance. 83 */ 84 NSS_EXTERN PRBool 85 nssPKIObject_HasInstance( 86 nssPKIObject *object, 87 nssCryptokiObject *instance); 88 89 /* nssPKIObject_GetTokens 90 * 91 * Get all tokens which have an instance of the object. 92 */ 93 NSS_EXTERN NSSToken ** 94 nssPKIObject_GetTokens( 95 nssPKIObject *object, 96 PRStatus *statusOpt); 97 98 /* nssPKIObject_GetNicknameForToken 99 * 100 * tokenOpt == NULL means take the first available, otherwise return the 101 * nickname for the specified token. 102 */ 103 NSS_EXTERN NSSUTF8 * 104 nssPKIObject_GetNicknameForToken( 105 nssPKIObject *object, 106 NSSToken *tokenOpt); 107 108 /* nssPKIObject_RemoveInstanceForToken 109 * 110 * Remove the instance of the object on the specified token. 111 */ 112 NSS_EXTERN PRStatus 113 nssPKIObject_RemoveInstanceForToken( 114 nssPKIObject *object, 115 NSSToken *token); 116 117 /* nssPKIObject_DeleteStoredObject 118 * 119 * Delete all token instances of the object, as well as any crypto context 120 * instances (TODO). If any of the instances are read-only, or if the 121 * removal fails, the object will keep those instances. 'isFriendly' refers 122 * to the object -- can this object be removed from a friendly token without 123 * login? For example, certificates are friendly, private keys are not. 124 * Note that if the token is not friendly, authentication will be required 125 * regardless of the value of 'isFriendly'. 126 */ 127 NSS_EXTERN PRStatus 128 nssPKIObject_DeleteStoredObject( 129 nssPKIObject *object, 130 NSSCallback *uhh, 131 PRBool isFriendly); 132 133 NSS_EXTERN nssCryptokiObject ** 134 nssPKIObject_GetInstances( 135 nssPKIObject *object); 136 137 NSS_EXTERN NSSCertificate ** 138 nssTrustDomain_FindCertificatesByID( 139 NSSTrustDomain *td, 140 NSSItem *id, 141 NSSCertificate **rvOpt, 142 PRUint32 maximumOpt, 143 NSSArena *arenaOpt); 144 145 NSS_EXTERN NSSCRL ** 146 nssTrustDomain_FindCRLsBySubject( 147 NSSTrustDomain *td, 148 NSSDER *subject); 149 150 /* module-private nsspki methods */ 151 152 NSS_EXTERN NSSCryptoContext * 153 nssCryptoContext_Create( 154 NSSTrustDomain *td, 155 NSSCallback *uhhOpt); 156 157 /* XXX for the collection */ 158 NSS_EXTERN NSSCertificate * 159 nssCertificate_Create(nssPKIObject *object); 160 161 NSS_EXTERN PRStatus 162 nssCertificate_SetCertTrust( 163 NSSCertificate *c, 164 NSSTrust *trust); 165 166 NSS_EXTERN nssDecodedCert * 167 nssCertificate_GetDecoding(NSSCertificate *c); 168 169 extern PRIntn 170 nssCertificate_SubjectListSort( 171 void *v1, 172 void *v2); 173 174 NSS_EXTERN nssDecodedCert * 175 nssDecodedCert_Create( 176 NSSArena *arenaOpt, 177 NSSDER *encoding, 178 NSSCertificateType type); 179 180 NSS_EXTERN PRStatus 181 nssDecodedCert_Destroy(nssDecodedCert *dc); 182 183 NSS_EXTERN NSSTrust * 184 nssTrust_Create( 185 nssPKIObject *object, 186 NSSItem *certData); 187 188 NSS_EXTERN NSSCRL * 189 nssCRL_Create(nssPKIObject *object); 190 191 NSS_EXTERN NSSCRL * 192 nssCRL_AddRef(NSSCRL *crl); 193 194 NSS_EXTERN PRStatus 195 nssCRL_Destroy(NSSCRL *crl); 196 197 NSS_EXTERN PRStatus 198 nssCRL_DeleteStoredObject( 199 NSSCRL *crl, 200 NSSCallback *uhh); 201 202 NSS_EXTERN NSSPrivateKey * 203 nssPrivateKey_Create(nssPKIObject *o); 204 205 NSS_EXTERN NSSDER * 206 nssCRL_GetEncoding(NSSCRL *crl); 207 208 NSS_EXTERN NSSPublicKey * 209 nssPublicKey_Create(nssPKIObject *object); 210 211 /* nssCertificateArray 212 * 213 * These are being thrown around a lot, might as well group together some 214 * functionality. 215 * 216 * nssCertificateArray_Destroy 217 * nssCertificateArray_Join 218 * nssCertificateArray_FindBestCertificate 219 * nssCertificateArray_Traverse 220 */ 221 222 /* nssCertificateArray_Destroy 223 * 224 * Will destroy the array and the certs within it. If the array was created 225 * in an arena, will *not* (of course) destroy the arena. However, is safe 226 * to call this method on an arena-allocated array. 227 */ 228 NSS_EXTERN void 229 nssCertificateArray_Destroy(NSSCertificate **certs); 230 231 /* nssCertificateArray_Join 232 * 233 * Join two arrays into one. The two arrays, certs1 and certs2, should 234 * be considered invalid after a call to this function (they may be destroyed 235 * as part of the join). certs1 and/or certs2 may be NULL. Safe to 236 * call with arrays allocated in an arena, the result will also be in the 237 * arena. 238 */ 239 NSS_EXTERN NSSCertificate ** 240 nssCertificateArray_Join( 241 NSSCertificate **certs1, 242 NSSCertificate **certs2); 243 244 /* nssCertificateArray_FindBestCertificate 245 * 246 * Use the usual { time, usage, policies } to find the best cert in the 247 * array. 248 */ 249 NSS_EXTERN NSSCertificate * 250 nssCertificateArray_FindBestCertificate( 251 NSSCertificate **certs, 252 NSSTime *timeOpt, 253 const NSSUsage *usage, 254 NSSPolicies *policiesOpt); 255 256 /* nssCertificateArray_Traverse 257 * 258 * Do the callback for each cert, terminate the traversal if the callback 259 * fails. 260 */ 261 NSS_EXTERN PRStatus 262 nssCertificateArray_Traverse( 263 NSSCertificate **certs, 264 PRStatus (*callback)(NSSCertificate *c, void *arg), 265 void *arg); 266 267 NSS_EXTERN void 268 nssCRLArray_Destroy(NSSCRL **crls); 269 270 /* nssPKIObjectCollection 271 * 272 * This is a handy way to group objects together and perform operations 273 * on them. It can also handle "proto-objects"-- references to 274 * objects instances on tokens, where the actual object hasn't 275 * been formed yet. 276 * 277 * nssCertificateCollection_Create 278 * nssPrivateKeyCollection_Create 279 * nssPublicKeyCollection_Create 280 * 281 * If this was a language that provided for inheritance, each type would 282 * inherit all of the following methods. Instead, there is only one 283 * type (nssPKIObjectCollection), shared among all. This may cause 284 * confusion; an alternative would be to define all of the methods 285 * for each subtype (nssCertificateCollection_Destroy, ...), but that doesn't 286 * seem worth the code bloat.. It is left up to the caller to remember 287 * what type of collection he/she is dealing with. 288 * 289 * nssPKIObjectCollection_Destroy 290 * nssPKIObjectCollection_Count 291 * nssPKIObjectCollection_AddObject 292 * nssPKIObjectCollection_AddInstances 293 * nssPKIObjectCollection_Traverse 294 * 295 * Back to type-specific methods. 296 * 297 * nssPKIObjectCollection_GetCertificates 298 * nssPKIObjectCollection_GetCRLs 299 * nssPKIObjectCollection_GetPrivateKeys 300 * nssPKIObjectCollection_GetPublicKeys 301 */ 302 303 /* nssCertificateCollection_Create 304 * 305 * Create a collection of certificates in the specified trust domain. 306 * Optionally provide a starting set of certs. 307 */ 308 NSS_EXTERN nssPKIObjectCollection * 309 nssCertificateCollection_Create( 310 NSSTrustDomain *td, 311 NSSCertificate **certsOpt); 312 313 /* nssCRLCollection_Create 314 * 315 * Create a collection of CRLs/KRLs in the specified trust domain. 316 * Optionally provide a starting set of CRLs. 317 */ 318 NSS_EXTERN nssPKIObjectCollection * 319 nssCRLCollection_Create( 320 NSSTrustDomain *td, 321 NSSCRL **crlsOpt); 322 323 /* nssPrivateKeyCollection_Create 324 * 325 * Create a collection of private keys in the specified trust domain. 326 * Optionally provide a starting set of keys. 327 */ 328 NSS_EXTERN nssPKIObjectCollection * 329 nssPrivateKeyCollection_Create( 330 NSSTrustDomain *td, 331 NSSPrivateKey **pvkOpt); 332 333 /* nssPublicKeyCollection_Create 334 * 335 * Create a collection of public keys in the specified trust domain. 336 * Optionally provide a starting set of keys. 337 */ 338 NSS_EXTERN nssPKIObjectCollection * 339 nssPublicKeyCollection_Create( 340 NSSTrustDomain *td, 341 NSSPublicKey **pvkOpt); 342 343 /* nssPKIObjectCollection_Destroy 344 */ 345 NSS_EXTERN void 346 nssPKIObjectCollection_Destroy(nssPKIObjectCollection *collection); 347 348 /* nssPKIObjectCollection_Count 349 */ 350 NSS_EXTERN PRUint32 351 nssPKIObjectCollection_Count(nssPKIObjectCollection *collection); 352 353 NSS_EXTERN PRStatus 354 nssPKIObjectCollection_AddObject( 355 nssPKIObjectCollection *collection, 356 nssPKIObject *object); 357 358 /* nssPKIObjectCollection_AddInstances 359 * 360 * Add a set of object instances to the collection. The instances 361 * will be sorted into any existing certs/proto-certs that may be in 362 * the collection. The instances will be absorbed by the collection, 363 * the array should not be used after this call (except to free it). 364 * 365 * Failure means the collection is in an invalid state. 366 * 367 * numInstances = 0 means the array is NULL-terminated 368 */ 369 NSS_EXTERN PRStatus 370 nssPKIObjectCollection_AddInstances( 371 nssPKIObjectCollection *collection, 372 nssCryptokiObject **instances, 373 PRUint32 numInstances); 374 375 /* nssPKIObjectCollection_Traverse 376 */ 377 NSS_EXTERN PRStatus 378 nssPKIObjectCollection_Traverse( 379 nssPKIObjectCollection *collection, 380 nssPKIObjectCallback *callback); 381 382 /* This function is being added for NSS 3.5. It corresponds to the function 383 * nssToken_TraverseCertificates. The idea is to use the collection during 384 * a traversal, creating certs each time a new instance is added for which 385 * a cert does not already exist. 386 */ 387 NSS_EXTERN PRStatus 388 nssPKIObjectCollection_AddInstanceAsObject( 389 nssPKIObjectCollection *collection, 390 nssCryptokiObject *instance); 391 392 /* nssPKIObjectCollection_GetCertificates 393 * 394 * Get all of the certificates in the collection. 395 */ 396 NSS_EXTERN NSSCertificate ** 397 nssPKIObjectCollection_GetCertificates( 398 nssPKIObjectCollection *collection, 399 NSSCertificate **rvOpt, 400 PRUint32 maximumOpt, 401 NSSArena *arenaOpt); 402 403 NSS_EXTERN NSSCRL ** 404 nssPKIObjectCollection_GetCRLs( 405 nssPKIObjectCollection *collection, 406 NSSCRL **rvOpt, 407 PRUint32 maximumOpt, 408 NSSArena *arenaOpt); 409 410 NSS_EXTERN NSSPrivateKey ** 411 nssPKIObjectCollection_GetPrivateKeys( 412 nssPKIObjectCollection *collection, 413 NSSPrivateKey **rvOpt, 414 PRUint32 maximumOpt, 415 NSSArena *arenaOpt); 416 417 NSS_EXTERN NSSPublicKey ** 418 nssPKIObjectCollection_GetPublicKeys( 419 nssPKIObjectCollection *collection, 420 NSSPublicKey **rvOpt, 421 PRUint32 maximumOpt, 422 NSSArena *arenaOpt); 423 424 NSS_EXTERN NSSTime * 425 NSSTime_Now(NSSTime *timeOpt); 426 427 NSS_EXTERN NSSTime * 428 NSSTime_SetPRTime( 429 NSSTime *timeOpt, 430 PRTime prTime); 431 432 NSS_EXTERN PRTime 433 NSSTime_GetPRTime( 434 NSSTime *time); 435 436 NSS_EXTERN nssHash * 437 nssHash_CreateCertificate( 438 NSSArena *arenaOpt, 439 PRUint32 numBuckets); 440 441 /* 3.4 Certificate cache routines */ 442 443 NSS_EXTERN PRStatus 444 nssTrustDomain_InitializeCache( 445 NSSTrustDomain *td, 446 PRUint32 cacheSize); 447 448 NSS_EXTERN PRStatus 449 nssTrustDomain_AddCertsToCache( 450 NSSTrustDomain *td, 451 NSSCertificate **certs, 452 PRUint32 numCerts); 453 454 NSS_EXTERN void 455 nssTrustDomain_RemoveCertFromCacheLOCKED( 456 NSSTrustDomain *td, 457 NSSCertificate *cert); 458 459 NSS_EXTERN void 460 nssTrustDomain_LockCertCache(NSSTrustDomain *td); 461 462 NSS_EXTERN void 463 nssTrustDomain_UnlockCertCache(NSSTrustDomain *td); 464 465 NSS_IMPLEMENT PRStatus 466 nssTrustDomain_DestroyCache(NSSTrustDomain *td); 467 468 /* 469 * Remove all certs for the given token from the cache. This is 470 * needed if the token is removed. 471 */ 472 NSS_EXTERN PRStatus 473 nssTrustDomain_RemoveTokenCertsFromCache( 474 NSSTrustDomain *td, 475 NSSToken *token); 476 477 NSS_EXTERN PRStatus 478 nssTrustDomain_UpdateCachedTokenCerts( 479 NSSTrustDomain *td, 480 NSSToken *token); 481 482 /* 483 * Find all cached certs with this nickname (label). 484 */ 485 NSS_EXTERN NSSCertificate ** 486 nssTrustDomain_GetCertsForNicknameFromCache( 487 NSSTrustDomain *td, 488 const NSSUTF8 *nickname, 489 nssList *certListOpt); 490 491 /* 492 * Find all cached certs with this email address. 493 */ 494 NSS_EXTERN NSSCertificate ** 495 nssTrustDomain_GetCertsForEmailAddressFromCache( 496 NSSTrustDomain *td, 497 NSSASCII7 *email, 498 nssList *certListOpt); 499 500 /* 501 * Find all cached certs with this subject. 502 */ 503 NSS_EXTERN NSSCertificate ** 504 nssTrustDomain_GetCertsForSubjectFromCache( 505 NSSTrustDomain *td, 506 NSSDER *subject, 507 nssList *certListOpt); 508 509 /* 510 * Look for a specific cert in the cache. 511 */ 512 NSS_EXTERN NSSCertificate * 513 nssTrustDomain_GetCertForIssuerAndSNFromCache( 514 NSSTrustDomain *td, 515 NSSDER *issuer, 516 NSSDER *serialNum); 517 518 /* 519 * Look for a specific cert in the cache. 520 */ 521 NSS_EXTERN NSSCertificate * 522 nssTrustDomain_GetCertByDERFromCache( 523 NSSTrustDomain *td, 524 NSSDER *der); 525 526 /* Get all certs from the cache */ 527 /* XXX this is being included to make some old-style calls word, not to 528 * say we should keep it 529 */ 530 NSS_EXTERN NSSCertificate ** 531 nssTrustDomain_GetCertsFromCache( 532 NSSTrustDomain *td, 533 nssList *certListOpt); 534 535 NSS_EXTERN void 536 nssTrustDomain_DumpCacheInfo( 537 NSSTrustDomain *td, 538 void (*cert_dump_iter)(const void *, void *, void *), 539 void *arg); 540 541 NSS_EXTERN void 542 nssCertificateList_AddReferences( 543 nssList *certList); 544 545 PR_END_EXTERN_C 546 547 #endif /* PKIM_H */