security/nss/lib/pki/pkim.h

   1 /* ***** BEGIN LICENSE BLOCK *****
   2  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   3  *
   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/
   8  *
   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
  12  * License.
  13  *
  14  * The Original Code is the Netscape security libraries.
  15  *
  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.
  20  *
  21  * Contributor(s):
  22  *
  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.
  34  *
  35  * ***** END LICENSE BLOCK ***** */
  36
  37 #ifndef PKIM_H
  38 #define PKIM_H
  39
  40 #ifdef DEBUG
  41 static const char PKIM_CVS_ID[] = "@(#) $RCSfile: pkim.h,v $ $Revision: 1.28 $ $Date: 2006/08/22 22:54:11 $";
  42 #endif /* DEBUG */
  43
  44 #ifndef BASE_H
  45 #include "base.h"
  46 #endif /* BASE_H */
  47
  48 #ifndef PKI_H
  49 #include "pki.h"
  50 #endif /* PKI_H */
  51
  52 #ifndef PKITM_H
  53 #include "pkitm.h"
  54 #endif /* PKITM_H */
  55
  56 PR_BEGIN_EXTERN_C
  57
  58 /* nssPKIObject
  59  *
  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.
  63  *
  64  * nssPKIObject_Create
  65  * nssPKIObject_Destroy
  66  * nssPKIObject_AddRef
  67  * nssPKIObject_AddInstance
  68  * nssPKIObject_HasInstance
  69  * nssPKIObject_GetTokens
  70  * nssPKIObject_GetNicknameForToken
  71  * nssPKIObject_RemoveInstanceForToken
  72  * nssPKIObject_DeleteStoredObject
  73  */
  74
  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);
  80
  81 /* nssPKIObject_Create
  82  *
  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.
  85  */
  86 NSS_EXTERN nssPKIObject *
  87 nssPKIObject_Create
  88 (
  89   NSSArena *arenaOpt,
  90   nssCryptokiObject *instanceOpt,
  91   NSSTrustDomain *td,
  92   NSSCryptoContext *ccOpt,
  93   nssPKILockType lockType
  94 );
  95
  96 /* nssPKIObject_AddRef
  97  */
  98 NSS_EXTERN nssPKIObject *
  99 nssPKIObject_AddRef
 100 (
 101   nssPKIObject *object
 102 );
 103
 104 /* nssPKIObject_Destroy
 105  *
 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.
 108  */
 109 NSS_EXTERN PRBool
 110 nssPKIObject_Destroy
 111 (
 112   nssPKIObject *object
 113 );
 114
 115 /* nssPKIObject_AddInstance
 116  *
 117  * Add a token instance to the object, if it does not have it already.
 118  */
 119 NSS_EXTERN PRStatus
 120 nssPKIObject_AddInstance
 121 (
 122   nssPKIObject *object,
 123   nssCryptokiObject *instance
 124 );
 125
 126 /* nssPKIObject_HasInstance
 127  *
 128  * Query the object for a token instance.
 129  */
 130 NSS_EXTERN PRBool
 131 nssPKIObject_HasInstance
 132 (
 133   nssPKIObject *object,
 134   nssCryptokiObject *instance
 135 );
 136
 137 /* nssPKIObject_GetTokens
 138  *
 139  * Get all tokens which have an instance of the object.
 140  */
 141 NSS_EXTERN NSSToken **
 142 nssPKIObject_GetTokens
 143 (
 144   nssPKIObject *object,
 145   PRStatus *statusOpt
 146 );
 147
 148 /* nssPKIObject_GetNicknameForToken
 149  *
 150  * tokenOpt == NULL means take the first available, otherwise return the
 151  * nickname for the specified token.
 152  */
 153 NSS_EXTERN NSSUTF8 *
 154 nssPKIObject_GetNicknameForToken
 155 (
 156   nssPKIObject *object,
 157   NSSToken *tokenOpt
 158 );
 159
 160 /* nssPKIObject_RemoveInstanceForToken
 161  *
 162  * Remove the instance of the object on the specified token.
 163  */
 164 NSS_EXTERN PRStatus
 165 nssPKIObject_RemoveInstanceForToken
 166 (
 167   nssPKIObject *object,
 168   NSSToken *token
 169 );
 170
 171 /* nssPKIObject_DeleteStoredObject
 172  *
 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'.
 180  */
 181 NSS_EXTERN PRStatus
 182 nssPKIObject_DeleteStoredObject
 183 (
 184   nssPKIObject *object,
 185   NSSCallback *uhh,
 186   PRBool isFriendly
 187 );
 188
 189 #ifdef NSS_3_4_CODE
 190 NSS_EXTERN nssCryptokiObject **
 191 nssPKIObject_GetInstances
 192 (
 193   nssPKIObject *object
 194 );
 195 #endif
 196
 197 NSS_EXTERN NSSCertificate **
 198 nssTrustDomain_FindCertificatesByID
 199 (
 200   NSSTrustDomain *td,
 201   NSSItem *id,
 202   NSSCertificate **rvOpt,
 203   PRUint32 maximumOpt,
 204   NSSArena *arenaOpt
 205 );
 206
 207 NSS_EXTERN NSSCRL **
 208 nssTrustDomain_FindCRLsBySubject
 209 (
 210   NSSTrustDomain *td,
 211   NSSDER *subject
 212 );
 213
 214 /* module-private nsspki methods */
 215
 216 NSS_EXTERN NSSCryptoContext *
 217 nssCryptoContext_Create
 218 (
 219   NSSTrustDomain *td,
 220   NSSCallback *uhhOpt
 221 );
 222
 223 /* XXX for the collection */
 224 NSS_EXTERN NSSCertificate *
 225 nssCertificate_Create
 226 (
 227   nssPKIObject *object
 228 );
 229
 230 NSS_EXTERN PRStatus
 231 nssCertificate_SetCertTrust
 232 (
 233   NSSCertificate *c,
 234   NSSTrust *trust
 235 );
 236
 237 NSS_EXTERN nssDecodedCert *
 238 nssCertificate_GetDecoding
 239 (
 240   NSSCertificate *c
 241 );
 242
 243 extern PRIntn
 244 nssCertificate_SubjectListSort
 245 (
 246   void *v1,
 247   void *v2
 248 );
 249
 250 NSS_EXTERN nssDecodedCert *
 251 nssDecodedCert_Create
 252 (
 253   NSSArena *arenaOpt,
 254   NSSDER *encoding,
 255   NSSCertificateType type
 256 );
 257
 258 NSS_EXTERN PRStatus
 259 nssDecodedCert_Destroy
 260 (
 261   nssDecodedCert *dc
 262 );
 263
 264 NSS_EXTERN NSSTrust *
 265 nssTrust_Create
 266 (
 267   nssPKIObject *object,
 268   NSSItem *certData
 269 );
 270
 271 NSS_EXTERN NSSCRL *
 272 nssCRL_Create
 273 (
 274   nssPKIObject *object
 275 );
 276
 277 NSS_EXTERN NSSCRL *
 278 nssCRL_AddRef
 279 (
 280   NSSCRL *crl
 281 );
 282
 283 NSS_EXTERN PRStatus
 284 nssCRL_Destroy
 285 (
 286   NSSCRL *crl
 287 );
 288
 289 NSS_EXTERN PRStatus
 290 nssCRL_DeleteStoredObject
 291 (
 292   NSSCRL *crl,
 293   NSSCallback *uhh
 294 );
 295
 296 NSS_EXTERN NSSPrivateKey *
 297 nssPrivateKey_Create
 298 (
 299   nssPKIObject *o
 300 );
 301
 302 NSS_EXTERN NSSDER *
 303 nssCRL_GetEncoding
 304 (
 305   NSSCRL *crl
 306 );
 307
 308 NSS_EXTERN NSSPublicKey *
 309 nssPublicKey_Create
 310 (
 311   nssPKIObject *object
 312 );
 313
 314 /* nssCertificateArray
 315  *
 316  * These are being thrown around a lot, might as well group together some
 317  * functionality.
 318  *
 319  * nssCertificateArray_Destroy
 320  * nssCertificateArray_Join
 321  * nssCertificateArray_FindBestCertificate
 322  * nssCertificateArray_Traverse
 323  */
 324
 325 /* nssCertificateArray_Destroy
 326  *
 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.
 330  */
 331 NSS_EXTERN void
 332 nssCertificateArray_Destroy
 333 (
 334   NSSCertificate **certs
 335 );
 336
 337 /* nssCertificateArray_Join
 338  *
 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
 343  * arena.
 344  */
 345 NSS_EXTERN NSSCertificate **
 346 nssCertificateArray_Join
 347 (
 348   NSSCertificate **certs1,
 349   NSSCertificate **certs2
 350 );
 351
 352 /* nssCertificateArray_FindBestCertificate
 353  *
 354  * Use the usual { time, usage, policies } to find the best cert in the
 355  * array.
 356  */
 357 NSS_EXTERN NSSCertificate *
 358 nssCertificateArray_FindBestCertificate
 359 (
 360   NSSCertificate **certs,
 361   NSSTime *timeOpt,
 362   const NSSUsage *usage,
 363   NSSPolicies *policiesOpt
 364 );
 365
 366 /* nssCertificateArray_Traverse
 367  *
 368  * Do the callback for each cert, terminate the traversal if the callback
 369  * fails.
 370  */
 371 NSS_EXTERN PRStatus
 372 nssCertificateArray_Traverse
 373 (
 374   NSSCertificate **certs,
 375   PRStatus (* callback)(NSSCertificate *c, void *arg),
 376   void *arg
 377 );
 378
 379 NSS_EXTERN void
 380 nssCRLArray_Destroy
 381 (
 382   NSSCRL **crls
 383 );
 384
 385 /* nssPKIObjectCollection
 386  *
 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
 390  * been formed yet.
 391  *
 392  * nssCertificateCollection_Create
 393  * nssPrivateKeyCollection_Create
 394  * nssPublicKeyCollection_Create
 395  *
 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.
 403  *
 404  * nssPKIObjectCollection_Destroy
 405  * nssPKIObjectCollection_Count
 406  * nssPKIObjectCollection_AddObject
 407  * nssPKIObjectCollection_AddInstances
 408  * nssPKIObjectCollection_Traverse
 409  *
 410  * Back to type-specific methods.
 411  *
 412  * nssPKIObjectCollection_GetCertificates
 413  * nssPKIObjectCollection_GetCRLs
 414  * nssPKIObjectCollection_GetPrivateKeys
 415  * nssPKIObjectCollection_GetPublicKeys
 416  */
 417
 418 /* nssCertificateCollection_Create
 419  *
 420  * Create a collection of certificates in the specified trust domain.
 421  * Optionally provide a starting set of certs.
 422  */
 423 NSS_EXTERN nssPKIObjectCollection *
 424 nssCertificateCollection_Create
 425 (
 426   NSSTrustDomain *td,
 427   NSSCertificate **certsOpt
 428 );
 429
 430 /* nssCRLCollection_Create
 431  *
 432  * Create a collection of CRLs/KRLs in the specified trust domain.
 433  * Optionally provide a starting set of CRLs.
 434  */
 435 NSS_EXTERN nssPKIObjectCollection *
 436 nssCRLCollection_Create
 437 (
 438   NSSTrustDomain *td,
 439   NSSCRL **crlsOpt
 440 );
 441
 442 /* nssPrivateKeyCollection_Create
 443  *
 444  * Create a collection of private keys in the specified trust domain.
 445  * Optionally provide a starting set of keys.
 446  */
 447 NSS_EXTERN nssPKIObjectCollection *
 448 nssPrivateKeyCollection_Create
 449 (
 450   NSSTrustDomain *td,
 451   NSSPrivateKey **pvkOpt
 452 );
 453
 454 /* nssPublicKeyCollection_Create
 455  *
 456  * Create a collection of public keys in the specified trust domain.
 457  * Optionally provide a starting set of keys.
 458  */
 459 NSS_EXTERN nssPKIObjectCollection *
 460 nssPublicKeyCollection_Create
 461 (
 462   NSSTrustDomain *td,
 463   NSSPublicKey **pvkOpt
 464 );
 465
 466 /* nssPKIObjectCollection_Destroy
 467  */
 468 NSS_EXTERN void
 469 nssPKIObjectCollection_Destroy
 470 (
 471   nssPKIObjectCollection *collection
 472 );
 473
 474 /* nssPKIObjectCollection_Count
 475  */
 476 NSS_EXTERN PRUint32
 477 nssPKIObjectCollection_Count
 478 (
 479   nssPKIObjectCollection *collection
 480 );
 481
 482 NSS_EXTERN PRStatus
 483 nssPKIObjectCollection_AddObject
 484 (
 485   nssPKIObjectCollection *collection,
 486   nssPKIObject *object
 487 );
 488
 489 /* nssPKIObjectCollection_AddInstances
 490  *
 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).
 495  *
 496  * Failure means the collection is in an invalid state.
 497  *
 498  * numInstances = 0 means the array is NULL-terminated
 499  */
 500 NSS_EXTERN PRStatus
 501 nssPKIObjectCollection_AddInstances
 502 (
 503   nssPKIObjectCollection *collection,
 504   nssCryptokiObject **instances,
 505   PRUint32 numInstances
 506 );
 507
 508 /* nssPKIObjectCollection_Traverse
 509  */
 510 NSS_EXTERN PRStatus
 511 nssPKIObjectCollection_Traverse
 512 (
 513   nssPKIObjectCollection *collection,
 514   nssPKIObjectCallback *callback
 515 );
 516
 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.
 521  */
 522 NSS_EXTERN PRStatus
 523 nssPKIObjectCollection_AddInstanceAsObject
 524 (
 525   nssPKIObjectCollection *collection,
 526   nssCryptokiObject *instance
 527 );
 528
 529 /* nssPKIObjectCollection_GetCertificates
 530  *
 531  * Get all of the certificates in the collection.
 532  */
 533 NSS_EXTERN NSSCertificate **
 534 nssPKIObjectCollection_GetCertificates
 535 (
 536   nssPKIObjectCollection *collection,
 537   NSSCertificate **rvOpt,
 538   PRUint32 maximumOpt,
 539   NSSArena *arenaOpt
 540 );
 541
 542 NSS_EXTERN NSSCRL **
 543 nssPKIObjectCollection_GetCRLs
 544 (
 545   nssPKIObjectCollection *collection,
 546   NSSCRL **rvOpt,
 547   PRUint32 maximumOpt,
 548   NSSArena *arenaOpt
 549 );
 550
 551 NSS_EXTERN NSSPrivateKey **
 552 nssPKIObjectCollection_GetPrivateKeys
 553 (
 554   nssPKIObjectCollection *collection,
 555   NSSPrivateKey **rvOpt,
 556   PRUint32 maximumOpt,
 557   NSSArena *arenaOpt
 558 );
 559
 560 NSS_EXTERN NSSPublicKey **
 561 nssPKIObjectCollection_GetPublicKeys
 562 (
 563   nssPKIObjectCollection *collection,
 564   NSSPublicKey **rvOpt,
 565   PRUint32 maximumOpt,
 566   NSSArena *arenaOpt
 567 );
 568
 569 NSS_EXTERN NSSTime *
 570 NSSTime_Now
 571 (
 572   NSSTime *timeOpt
 573 );
 574
 575 NSS_EXTERN NSSTime *
 576 NSSTime_SetPRTime
 577 (
 578   NSSTime *timeOpt,
 579   PRTime prTime
 580 );
 581
 582 NSS_EXTERN PRTime
 583 NSSTime_GetPRTime
 584 (
 585   NSSTime *time
 586 );
 587
 588 NSS_EXTERN nssHash *
 589 nssHash_CreateCertificate
 590 (
 591   NSSArena *arenaOpt,
 592   PRUint32 numBuckets
 593 );
 594
 595 /* 3.4 Certificate cache routines */
 596
 597 NSS_EXTERN PRStatus
 598 nssTrustDomain_InitializeCache
 599 (
 600   NSSTrustDomain *td,
 601   PRUint32 cacheSize
 602 );
 603
 604 NSS_EXTERN PRStatus
 605 nssTrustDomain_AddCertsToCache
 606 (
 607   NSSTrustDomain *td,
 608   NSSCertificate **certs,
 609   PRUint32 numCerts
 610 );
 611
 612 NSS_EXTERN void
 613 nssTrustDomain_RemoveCertFromCacheLOCKED (
 614   NSSTrustDomain *td,
 615   NSSCertificate *cert
 616 );
 617
 618 NSS_EXTERN void
 619 nssTrustDomain_LockCertCache (
 620   NSSTrustDomain *td
 621 );
 622
 623 NSS_EXTERN void
 624 nssTrustDomain_UnlockCertCache (
 625   NSSTrustDomain *td
 626 );
 627
 628 NSS_IMPLEMENT PRStatus
 629 nssTrustDomain_DestroyCache
 630 (
 631   NSSTrustDomain *td
 632 );
 633
 634 /*
 635  * Remove all certs for the given token from the cache.  This is
 636  * needed if the token is removed.
 637  */
 638 NSS_EXTERN PRStatus
 639 nssTrustDomain_RemoveTokenCertsFromCache
 640 (
 641   NSSTrustDomain *td,
 642   NSSToken *token
 643 );
 644
 645 NSS_EXTERN PRStatus
 646 nssTrustDomain_UpdateCachedTokenCerts
 647 (
 648   NSSTrustDomain *td,
 649   NSSToken *token
 650 );
 651
 652 /*
 653  * Find all cached certs with this nickname (label).
 654  */
 655 NSS_EXTERN NSSCertificate **
 656 nssTrustDomain_GetCertsForNicknameFromCache
 657 (
 658   NSSTrustDomain *td,
 659   NSSUTF8 *nickname,
 660   nssList *certListOpt
 661 );
 662
 663 /*
 664  * Find all cached certs with this email address.
 665  */
 666 NSS_EXTERN NSSCertificate **
 667 nssTrustDomain_GetCertsForEmailAddressFromCache
 668 (
 669   NSSTrustDomain *td,
 670   NSSASCII7 *email,
 671   nssList *certListOpt
 672 );
 673
 674 /*
 675  * Find all cached certs with this subject.
 676  */
 677 NSS_EXTERN NSSCertificate **
 678 nssTrustDomain_GetCertsForSubjectFromCache
 679 (
 680   NSSTrustDomain *td,
 681   NSSDER *subject,
 682   nssList *certListOpt
 683 );
 684
 685 /*
 686  * Look for a specific cert in the cache.
 687  */
 688 NSS_EXTERN NSSCertificate *
 689 nssTrustDomain_GetCertForIssuerAndSNFromCache
 690 (
 691   NSSTrustDomain *td,
 692   NSSDER *issuer,
 693   NSSDER *serialNum
 694 );
 695
 696 /*
 697  * Look for a specific cert in the cache.
 698  */
 699 NSS_EXTERN NSSCertificate *
 700 nssTrustDomain_GetCertByDERFromCache
 701 (
 702   NSSTrustDomain *td,
 703   NSSDER *der
 704 );
 705
 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
 709  */
 710 NSS_EXTERN NSSCertificate **
 711 nssTrustDomain_GetCertsFromCache
 712 (
 713   NSSTrustDomain *td,
 714   nssList *certListOpt
 715 );
 716
 717 NSS_EXTERN void
 718 nssTrustDomain_DumpCacheInfo
 719 (
 720   NSSTrustDomain *td,
 721   void (* cert_dump_iter)(const void *, void *, void *),
 722   void *arg
 723 );
 724
 725 NSS_EXTERN void
 726 nssCertificateList_AddReferences
 727 (
 728   nssList *certList
 729 );
 730
 731 PR_END_EXTERN_C
 732
 733 #endif /* PKIM_H */