security/nss/lib/pki/nsspki.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 NSSPKI_H
  38 #define NSSPKI_H
  39
  40 #ifdef DEBUG
  41 static const char NSSPKI_CVS_ID[] = "@(#) $RCSfile: nsspki.h,v $ $Revision: 1.12 $ $Date: 2007/07/11 04:47:42 $";
  42 #endif /* DEBUG */
  43
  44 /*
  45  * nsspki.h
  46  *
  47  * This file prototypes the methods of the top-level PKI objects.
  48  */
  49
  50 #ifndef NSSDEVT_H
  51 #include "nssdevt.h"
  52 #endif /* NSSDEVT_H */
  53
  54 #ifndef NSSPKIT_H
  55 #include "nsspkit.h"
  56 #endif /* NSSPKIT_H */
  57
  58 #ifndef NSSPKI1_H
  59 #include "nsspki1.h"
  60 #endif /* NSSPKI1_H */
  61
  62 #ifndef BASE_H
  63 #include "base.h"
  64 #endif /* BASE_H */
  65
  66 PR_BEGIN_EXTERN_C
  67
  68 /*
  69  * A note about interfaces
  70  *
  71  * Although these APIs are specified in C, a language which does
  72  * not have fancy support for abstract interfaces, this library
  73  * was designed from an object-oriented perspective.  It may be
  74  * useful to consider the standard interfaces which went into
  75  * the writing of these APIs.
  76  *
  77  * Basic operations on all objects:
  78  *  Destroy -- free a pointer to an object
  79  *  DeleteStoredObject -- delete an object permanently
  80  *
  81  * Public Key cryptographic operations:
  82  *  Encrypt
  83  *  Verify
  84  *  VerifyRecover
  85  *  Wrap
  86  *  Derive
  87  *
  88  * Private Key cryptographic operations:
  89  *  IsStillPresent
  90  *  Decrypt
  91  *  Sign
  92  *  SignRecover
  93  *  Unwrap
  94  *  Derive
  95  *
  96  * Symmetric Key cryptographic operations:
  97  *  IsStillPresent
  98  *  Encrypt
  99  *  Decrypt
 100  *  Sign
 101  *  SignRecover
 102  *  Verify
 103  *  VerifyRecover
 104  *  Wrap
 105  *  Unwrap
 106  *  Derive
 107  *
 108  */
 109
 110 /*
 111  * NSSCertificate
 112  *
 113  * These things can do crypto ops like public keys, except that the trust,
 114  * usage, and other constraints are checked.  These objects are "high-level,"
 115  * so trust, usages, etc. are in the form we throw around (client auth,
 116  * email signing, etc.).  Remember that theoretically another implementation
 117  * (think PGP) could be beneath this object.
 118  */
 119
 120 /*
 121  * NSSCertificate_Destroy
 122  *
 123  * Free a pointer to a certificate object.
 124  */
 125
 126 NSS_EXTERN PRStatus
 127 NSSCertificate_Destroy
 128 (
 129   NSSCertificate *c
 130 );
 131
 132 /*
 133  * NSSCertificate_DeleteStoredObject
 134  *
 135  * Permanently remove this certificate from storage.  If this is the
 136  * only (remaining) certificate corresponding to a private key,
 137  * public key, and/or other object; then that object (those objects)
 138  * are deleted too.
 139  */
 140
 141 NSS_EXTERN PRStatus
 142 NSSCertificate_DeleteStoredObject
 143 (
 144   NSSCertificate *c,
 145   NSSCallback *uhh
 146 );
 147
 148 /*
 149  * NSSCertificate_Validate
 150  *
 151  * Verify that this certificate is trusted, for the specified usage(s),
 152  * at the specified time, {word word} the specified policies.
 153  */
 154
 155 NSS_EXTERN PRStatus
 156 NSSCertificate_Validate
 157 (
 158   NSSCertificate *c,
 159   NSSTime *timeOpt, /* NULL for "now" */
 160   NSSUsage *usage,
 161   NSSPolicies *policiesOpt /* NULL for none */
 162 );
 163
 164 /*
 165  * NSSCertificate_ValidateCompletely
 166  *
 167  * Verify that this certificate is trusted.  The difference between
 168  * this and the previous call is that NSSCertificate_Validate merely
 169  * returns success or failure with an appropriate error stack.
 170  * However, there may be (and often are) multiple problems with a
 171  * certificate.  This routine returns an array of errors, specifying
 172  * every problem.
 173  */
 174
 175 /*
 176  * Return value must be an array of objects, each of which has
 177  * an NSSError, and any corresponding certificate (in the chain)
 178  * and/or policy.
 179  */
 180
 181 NSS_EXTERN void ** /* void *[] */
 182 NSSCertificate_ValidateCompletely
 183 (
 184   NSSCertificate *c,
 185   NSSTime *timeOpt, /* NULL for "now" */
 186   NSSUsage *usage,
 187   NSSPolicies *policiesOpt, /* NULL for none */
 188   void **rvOpt, /* NULL for allocate */
 189   PRUint32 rvLimit, /* zero for no limit */
 190   NSSArena *arenaOpt /* NULL for heap */
 191 );
 192
 193 /*
 194  * NSSCertificate_ValidateAndDiscoverUsagesAndPolicies
 195  *
 196  * Returns PR_SUCCESS if the certificate is valid for at least something.
 197  */
 198
 199 NSS_EXTERN PRStatus
 200 NSSCertificate_ValidateAndDiscoverUsagesAndPolicies
 201 (
 202   NSSCertificate *c,
 203   NSSTime **notBeforeOutOpt,
 204   NSSTime **notAfterOutOpt,
 205   void *allowedUsages,
 206   void *disallowedUsages,
 207   void *allowedPolicies,
 208   void *disallowedPolicies,
 209   /* more args.. work on this fgmr */
 210   NSSArena *arenaOpt
 211 );
 212
 213 /*
 214  * NSSCertificate_Encode
 215  *
 216  */
 217
 218 NSS_EXTERN NSSDER *
 219 NSSCertificate_Encode
 220 (
 221   NSSCertificate *c,
 222   NSSDER *rvOpt,
 223   NSSArena *arenaOpt
 224 );
 225
 226 /*
 227  * NSSCertificate_BuildChain
 228  *
 229  * This routine returns NSSCertificate *'s for each certificate
 230  * in the "chain" starting from the specified one up to and
 231  * including the root.  The zeroth element in the array is the
 232  * specified ("leaf") certificate.
 233  *
 234  * If statusOpt is supplied, and is returned as PR_FAILURE, possible
 235  * error values are:
 236  *
 237  * NSS_ERROR_CERTIFICATE_ISSUER_NOT_FOUND - the chain is incomplete
 238  *
 239  */
 240
 241 extern const NSSError NSS_ERROR_CERTIFICATE_ISSUER_NOT_FOUND;
 242
 243 NSS_EXTERN NSSCertificate **
 244 NSSCertificate_BuildChain
 245 (
 246   NSSCertificate *c,
 247   NSSTime *timeOpt,
 248   NSSUsage *usage,
 249   NSSPolicies *policiesOpt,
 250   NSSCertificate **rvOpt,
 251   PRUint32 rvLimit, /* zero for no limit */
 252   NSSArena *arenaOpt,
 253   PRStatus *statusOpt,
 254   NSSTrustDomain *td,
 255   NSSCryptoContext *cc
 256 );
 257
 258 /*
 259  * NSSCertificate_GetTrustDomain
 260  *
 261  */
 262
 263 NSS_EXTERN NSSTrustDomain *
 264 NSSCertificate_GetTrustDomain
 265 (
 266   NSSCertificate *c
 267 );
 268
 269 /*
 270  * NSSCertificate_GetToken
 271  *
 272  * There doesn't have to be one.
 273  */
 274
 275 NSS_EXTERN NSSToken *
 276 NSSCertificate_GetToken
 277 (
 278   NSSCertificate *c,
 279   PRStatus *statusOpt
 280 );
 281
 282 /*
 283  * NSSCertificate_GetSlot
 284  *
 285  * There doesn't have to be one.
 286  */
 287
 288 NSS_EXTERN NSSSlot *
 289 NSSCertificate_GetSlot
 290 (
 291   NSSCertificate *c,
 292   PRStatus *statusOpt
 293 );
 294
 295 /*
 296  * NSSCertificate_GetModule
 297  *
 298  * There doesn't have to be one.
 299  */
 300
 301 NSS_EXTERN NSSModule *
 302 NSSCertificate_GetModule
 303 (
 304   NSSCertificate *c,
 305   PRStatus *statusOpt
 306 );
 307
 308 /*
 309  * NSSCertificate_Encrypt
 310  *
 311  * Encrypt a single chunk of data with the public key corresponding to
 312  * this certificate.
 313  */
 314
 315 NSS_EXTERN NSSItem *
 316 NSSCertificate_Encrypt
 317 (
 318   NSSCertificate *c,
 319   NSSAlgorithmAndParameters *apOpt,
 320   NSSItem *data,
 321   NSSTime *timeOpt,
 322   NSSUsage *usage,
 323   NSSPolicies *policiesOpt,
 324   NSSCallback *uhh,
 325   NSSItem *rvOpt,
 326   NSSArena *arenaOpt
 327 );
 328
 329 /*
 330  * NSSCertificate_Verify
 331  *
 332  */
 333
 334 NSS_EXTERN PRStatus
 335 NSSCertificate_Verify
 336 (
 337   NSSCertificate *c,
 338   NSSAlgorithmAndParameters *apOpt,
 339   NSSItem *data,
 340   NSSItem *signature,
 341   NSSTime *timeOpt,
 342   NSSUsage *usage,
 343   NSSPolicies *policiesOpt,
 344   NSSCallback *uhh
 345 );
 346
 347 /*
 348  * NSSCertificate_VerifyRecover
 349  *
 350  */
 351
 352 NSS_EXTERN NSSItem *
 353 NSSCertificate_VerifyRecover
 354 (
 355   NSSCertificate *c,
 356   NSSAlgorithmAndParameters *apOpt,
 357   NSSItem *signature,
 358   NSSTime *timeOpt,
 359   NSSUsage *usage,
 360   NSSPolicies *policiesOpt,
 361   NSSCallback *uhh,
 362   NSSItem *rvOpt,
 363   NSSArena *arenaOpt
 364 );
 365
 366 /*
 367  * NSSCertificate_WrapSymmetricKey
 368  *
 369  * This method tries very hard to to succeed, even in situations
 370  * involving sensitive keys and multiple modules.
 371  * { relyea: want to add verbiage? }
 372  */
 373
 374 NSS_EXTERN NSSItem *
 375 NSSCertificate_WrapSymmetricKey
 376 (
 377   NSSCertificate *c,
 378   NSSAlgorithmAndParameters *apOpt,
 379   NSSSymmetricKey *keyToWrap,
 380   NSSTime *timeOpt,
 381   NSSUsage *usage,
 382   NSSPolicies *policiesOpt,
 383   NSSCallback *uhh,
 384   NSSItem *rvOpt,
 385   NSSArena *arenaOpt
 386 );
 387
 388 /*
 389  * NSSCertificate_CreateCryptoContext
 390  *
 391  * Create a crypto context, in this certificate's trust domain, with this
 392  * as the distinguished certificate.
 393  */
 394
 395 NSS_EXTERN NSSCryptoContext *
 396 NSSCertificate_CreateCryptoContext
 397 (
 398   NSSCertificate *c,
 399   NSSAlgorithmAndParameters *apOpt,
 400   NSSTime *timeOpt,
 401   NSSUsage *usage,
 402   NSSPolicies *policiesOpt,
 403   NSSCallback *uhh
 404 );
 405
 406 /*
 407  * NSSCertificate_GetPublicKey
 408  *
 409  * Returns the public key corresponding to this certificate.
 410  */
 411
 412 NSS_EXTERN NSSPublicKey *
 413 NSSCertificate_GetPublicKey
 414 (
 415   NSSCertificate *c
 416 );
 417
 418 /*
 419  * NSSCertificate_FindPrivateKey
 420  *
 421  * Finds and returns the private key corresponding to this certificate,
 422  * if it is available.
 423  *
 424  * { Should this hang off of NSSUserCertificate? }
 425  */
 426
 427 NSS_EXTERN NSSPrivateKey *
 428 NSSCertificate_FindPrivateKey
 429 (
 430   NSSCertificate *c,
 431   NSSCallback *uhh
 432 );
 433
 434 /*
 435  * NSSCertificate_IsPrivateKeyAvailable
 436  *
 437  * Returns success if the private key corresponding to this certificate
 438  * is available to be used.
 439  *
 440  * { Should *this* hang off of NSSUserCertificate?? }
 441  */
 442
 443 NSS_EXTERN PRBool
 444 NSSCertificate_IsPrivateKeyAvailable
 445 (
 446   NSSCertificate *c,
 447   NSSCallback *uhh,
 448   PRStatus *statusOpt
 449 );
 450
 451 /*
 452  * If we make NSSUserCertificate not a typedef of NSSCertificate,
 453  * then we'll need implementations of the following:
 454  *
 455  *  NSSUserCertificate_Destroy
 456  *  NSSUserCertificate_DeleteStoredObject
 457  *  NSSUserCertificate_Validate
 458  *  NSSUserCertificate_ValidateCompletely
 459  *  NSSUserCertificate_ValidateAndDiscoverUsagesAndPolicies
 460  *  NSSUserCertificate_Encode
 461  *  NSSUserCertificate_BuildChain
 462  *  NSSUserCertificate_GetTrustDomain
 463  *  NSSUserCertificate_GetToken
 464  *  NSSUserCertificate_GetSlot
 465  *  NSSUserCertificate_GetModule
 466  *  NSSUserCertificate_GetCryptoContext
 467  *  NSSUserCertificate_GetPublicKey
 468  */
 469
 470 /*
 471  * NSSUserCertificate_IsStillPresent
 472  *
 473  * Verify that if this certificate lives on a token, that the token
 474  * is still present and the certificate still exists.  This is a
 475  * lightweight call which should be used whenever it should be
 476  * verified that the user hasn't perhaps popped out his or her
 477  * token and strolled away.
 478  */
 479
 480 NSS_EXTERN PRBool
 481 NSSUserCertificate_IsStillPresent
 482 (
 483   NSSUserCertificate *uc,
 484   PRStatus *statusOpt
 485 );
 486
 487 /*
 488  * NSSUserCertificate_Decrypt
 489  *
 490  * Decrypt a single chunk of data with the private key corresponding
 491  * to this certificate.
 492  */
 493
 494 NSS_EXTERN NSSItem *
 495 NSSUserCertificate_Decrypt
 496 (
 497   NSSUserCertificate *uc,
 498   NSSAlgorithmAndParameters *apOpt,
 499   NSSItem *data,
 500   NSSTime *timeOpt,
 501   NSSUsage *usage,
 502   NSSPolicies *policiesOpt,
 503   NSSCallback *uhh,
 504   NSSItem *rvOpt,
 505   NSSArena *arenaOpt
 506 );
 507
 508 /*
 509  * NSSUserCertificate_Sign
 510  *
 511  */
 512
 513 NSS_EXTERN NSSItem *
 514 NSSUserCertificate_Sign
 515 (
 516   NSSUserCertificate *uc,
 517   NSSAlgorithmAndParameters *apOpt,
 518   NSSItem *data,
 519   NSSTime *timeOpt,
 520   NSSUsage *usage,
 521   NSSPolicies *policiesOpt,
 522   NSSCallback *uhh,
 523   NSSItem *rvOpt,
 524   NSSArena *arenaOpt
 525 );
 526
 527 /*
 528  * NSSUserCertificate_SignRecover
 529  *
 530  */
 531
 532 NSS_EXTERN NSSItem *
 533 NSSUserCertificate_SignRecover
 534 (
 535   NSSUserCertificate *uc,
 536   NSSAlgorithmAndParameters *apOpt,
 537   NSSItem *data,
 538   NSSTime *timeOpt,
 539   NSSUsage *usage,
 540   NSSPolicies *policiesOpt,
 541   NSSCallback *uhh,
 542   NSSItem *rvOpt,
 543   NSSArena *arenaOpt
 544 );
 545
 546 /*
 547  * NSSUserCertificate_UnwrapSymmetricKey
 548  *
 549  */
 550
 551 NSS_EXTERN NSSSymmetricKey *
 552 NSSUserCertificate_UnwrapSymmetricKey
 553 (
 554   NSSUserCertificate *uc,
 555   NSSAlgorithmAndParameters *apOpt,
 556   NSSItem *wrappedKey,
 557   NSSTime *timeOpt,
 558   NSSUsage *usage,
 559   NSSPolicies *policiesOpt,
 560   NSSCallback *uhh,
 561   NSSItem *rvOpt,
 562   NSSArena *arenaOpt
 563 );
 564
 565 /*
 566  * NSSUserCertificate_DeriveSymmetricKey
 567  *
 568  */
 569
 570 NSS_EXTERN NSSSymmetricKey *
 571 NSSUserCertificate_DeriveSymmetricKey
 572 (
 573   NSSUserCertificate *uc, /* provides private key */
 574   NSSCertificate *c, /* provides public key */
 575   NSSAlgorithmAndParameters *apOpt,
 576   NSSOID *target,
 577   PRUint32 keySizeOpt, /* zero for best allowed */
 578   NSSOperations operations,
 579   NSSCallback *uhh
 580 );
 581
 582 /* filter-certs function(s) */
 583
 584 /**
 585  ** fgmr -- trust objects
 586  **/
 587
 588 /*
 589  * NSSPrivateKey
 590  *
 591  */
 592
 593 /*
 594  * NSSPrivateKey_Destroy
 595  *
 596  * Free a pointer to a private key object.
 597  */
 598
 599 NSS_EXTERN PRStatus
 600 NSSPrivateKey_Destroy
 601 (
 602   NSSPrivateKey *vk
 603 );
 604
 605 /*
 606  * NSSPrivateKey_DeleteStoredObject
 607  *
 608  * Permanently remove this object, and any related objects (such as the
 609  * certificates corresponding to this key).
 610  */
 611
 612 NSS_EXTERN PRStatus
 613 NSSPrivateKey_DeleteStoredObject
 614 (
 615   NSSPrivateKey *vk,
 616   NSSCallback *uhh
 617 );
 618
 619 /*
 620  * NSSPrivateKey_GetSignatureLength
 621  *
 622  */
 623
 624 NSS_EXTERN PRUint32
 625 NSSPrivateKey_GetSignatureLength
 626 (
 627   NSSPrivateKey *vk
 628 );
 629
 630 /*
 631  * NSSPrivateKey_GetPrivateModulusLength
 632  *
 633  */
 634
 635 NSS_EXTERN PRUint32
 636 NSSPrivateKey_GetPrivateModulusLength
 637 (
 638   NSSPrivateKey *vk
 639 );
 640
 641 /*
 642  * NSSPrivateKey_IsStillPresent
 643  *
 644  */
 645
 646 NSS_EXTERN PRBool
 647 NSSPrivateKey_IsStillPresent
 648 (
 649   NSSPrivateKey *vk,
 650   PRStatus *statusOpt
 651 );
 652
 653 /*
 654  * NSSPrivateKey_Encode
 655  *
 656  */
 657
 658 NSS_EXTERN NSSItem *
 659 NSSPrivateKey_Encode
 660 (
 661   NSSPrivateKey *vk,
 662   NSSAlgorithmAndParameters *ap,
 663   NSSItem *passwordOpt, /* NULL will cause a callback; "" for no password */
 664   NSSCallback *uhhOpt,
 665   NSSItem *rvOpt,
 666   NSSArena *arenaOpt
 667 );
 668
 669 /*
 670  * NSSPrivateKey_GetTrustDomain
 671  *
 672  * There doesn't have to be one.
 673  */
 674
 675 NSS_EXTERN NSSTrustDomain *
 676 NSSPrivateKey_GetTrustDomain
 677 (
 678   NSSPrivateKey *vk,
 679   PRStatus *statusOpt
 680 );
 681
 682 /*
 683  * NSSPrivateKey_GetToken
 684  *
 685  */
 686
 687 NSS_EXTERN NSSToken *
 688 NSSPrivateKey_GetToken
 689 (
 690   NSSPrivateKey *vk
 691 );
 692
 693 /*
 694  * NSSPrivateKey_GetSlot
 695  *
 696  */
 697
 698 NSS_EXTERN NSSSlot *
 699 NSSPrivateKey_GetSlot
 700 (
 701   NSSPrivateKey *vk
 702 );
 703
 704 /*
 705  * NSSPrivateKey_GetModule
 706  *
 707  */
 708
 709 NSS_EXTERN NSSModule *
 710 NSSPrivateKey_GetModule
 711 (
 712   NSSPrivateKey *vk
 713 );
 714
 715 /*
 716  * NSSPrivateKey_Decrypt
 717  *
 718  */
 719
 720 NSS_EXTERN NSSItem *
 721 NSSPrivateKey_Decrypt
 722 (
 723   NSSPrivateKey *vk,
 724   NSSAlgorithmAndParameters *apOpt,
 725   NSSItem *encryptedData,
 726   NSSCallback *uhh,
 727   NSSItem *rvOpt,
 728   NSSArena *arenaOpt
 729 );
 730
 731 /*
 732  * NSSPrivateKey_Sign
 733  *
 734  */
 735
 736 NSS_EXTERN NSSItem *
 737 NSSPrivateKey_Sign
 738 (
 739   NSSPrivateKey *vk,
 740   NSSAlgorithmAndParameters *apOpt,
 741   NSSItem *data,
 742   NSSCallback *uhh,
 743   NSSItem *rvOpt,
 744   NSSArena *arenaOpt
 745 );
 746
 747 /*
 748  * NSSPrivateKey_SignRecover
 749  *
 750  */
 751
 752 NSS_EXTERN NSSItem *
 753 NSSPrivateKey_SignRecover
 754 (
 755   NSSPrivateKey *vk,
 756   NSSAlgorithmAndParameters *apOpt,
 757   NSSItem *data,
 758   NSSCallback *uhh,
 759   NSSItem *rvOpt,
 760   NSSArena *arenaOpt
 761 );
 762
 763 /*
 764  * NSSPrivateKey_UnwrapSymmetricKey
 765  *
 766  */
 767
 768 NSS_EXTERN NSSSymmetricKey *
 769 NSSPrivateKey_UnwrapSymmetricKey
 770 (
 771   NSSPrivateKey *vk,
 772   NSSAlgorithmAndParameters *apOpt,
 773   NSSItem *wrappedKey,
 774   NSSCallback *uhh
 775 );
 776
 777 /*
 778  * NSSPrivateKey_DeriveSymmetricKey
 779  *
 780  */
 781
 782 NSS_EXTERN NSSSymmetricKey *
 783 NSSPrivateKey_DeriveSymmetricKey
 784 (
 785   NSSPrivateKey *vk,
 786   NSSPublicKey *bk,
 787   NSSAlgorithmAndParameters *apOpt,
 788   NSSOID *target,
 789   PRUint32 keySizeOpt, /* zero for best allowed */
 790   NSSOperations operations,
 791   NSSCallback *uhh
 792 );
 793
 794 /*
 795  * NSSPrivateKey_FindPublicKey
 796  *
 797  */
 798
 799 NSS_EXTERN NSSPublicKey *
 800 NSSPrivateKey_FindPublicKey
 801 (
 802   NSSPrivateKey *vk
 803   /* { don't need the callback here, right? } */
 804 );
 805
 806 /*
 807  * NSSPrivateKey_CreateCryptoContext
 808  *
 809  * Create a crypto context, in this key's trust domain,
 810  * with this as the distinguished private key.
 811  */
 812
 813 NSS_EXTERN NSSCryptoContext *
 814 NSSPrivateKey_CreateCryptoContext
 815 (
 816   NSSPrivateKey *vk,
 817   NSSAlgorithmAndParameters *apOpt,
 818   NSSCallback *uhh
 819 );
 820
 821 /*
 822  * NSSPrivateKey_FindCertificates
 823  *
 824  * Note that there may be more than one certificate for this
 825  * private key.  { FilterCertificates function to further
 826  * reduce the list. }
 827  */
 828
 829 NSS_EXTERN NSSCertificate **
 830 NSSPrivateKey_FindCertificates
 831 (
 832   NSSPrivateKey *vk,
 833   NSSCertificate *rvOpt[],
 834   PRUint32 maximumOpt, /* 0 for no max */
 835   NSSArena *arenaOpt
 836 );
 837
 838 /*
 839  * NSSPrivateKey_FindBestCertificate
 840  *
 841  * The parameters for this function will depend on what the users
 842  * need.  This is just a starting point.
 843  */
 844
 845 NSS_EXTERN NSSCertificate *
 846 NSSPrivateKey_FindBestCertificate
 847 (
 848   NSSPrivateKey *vk,
 849   NSSTime *timeOpt,
 850   NSSUsage *usageOpt,
 851   NSSPolicies *policiesOpt
 852 );
 853
 854 /*
 855  * NSSPublicKey
 856  *
 857  * Once you generate, find, or derive one of these, you can use it
 858  * to perform (simple) cryptographic operations.  Though there may
 859  * be certificates associated with these public keys, they are not
 860  * verified.
 861  */
 862
 863 /*
 864  * NSSPublicKey_Destroy
 865  *
 866  * Free a pointer to a public key object.
 867  */
 868
 869 NSS_EXTERN PRStatus
 870 NSSPublicKey_Destroy
 871 (
 872   NSSPublicKey *bk
 873 );
 874
 875 /*
 876  * NSSPublicKey_DeleteStoredObject
 877  *
 878  * Permanently remove this object, and any related objects (such as the
 879  * corresponding private keys and certificates).
 880  */
 881
 882 NSS_EXTERN PRStatus
 883 NSSPublicKey_DeleteStoredObject
 884 (
 885   NSSPublicKey *bk,
 886   NSSCallback *uhh
 887 );
 888
 889 /*
 890  * NSSPublicKey_Encode
 891  *
 892  */
 893
 894 NSS_EXTERN NSSItem *
 895 NSSPublicKey_Encode
 896 (
 897   NSSPublicKey *bk,
 898   NSSAlgorithmAndParameters *ap,
 899   NSSCallback *uhhOpt,
 900   NSSItem *rvOpt,
 901   NSSArena *arenaOpt
 902 );
 903
 904 /*
 905  * NSSPublicKey_GetTrustDomain
 906  *
 907  * There doesn't have to be one.
 908  */
 909
 910 NSS_EXTERN NSSTrustDomain *
 911 NSSPublicKey_GetTrustDomain
 912 (
 913   NSSPublicKey *bk,
 914   PRStatus *statusOpt
 915 );
 916
 917 /*
 918  * NSSPublicKey_GetToken
 919  *
 920  * There doesn't have to be one.
 921  */
 922
 923 NSS_EXTERN NSSToken *
 924 NSSPublicKey_GetToken
 925 (
 926   NSSPublicKey *bk,
 927   PRStatus *statusOpt
 928 );
 929
 930 /*
 931  * NSSPublicKey_GetSlot
 932  *
 933  * There doesn't have to be one.
 934  */
 935
 936 NSS_EXTERN NSSSlot *
 937 NSSPublicKey_GetSlot
 938 (
 939   NSSPublicKey *bk,
 940   PRStatus *statusOpt
 941 );
 942
 943 /*
 944  * NSSPublicKey_GetModule
 945  *
 946  * There doesn't have to be one.
 947  */
 948
 949 NSS_EXTERN NSSModule *
 950 NSSPublicKey_GetModule
 951 (
 952   NSSPublicKey *bk,
 953   PRStatus *statusOpt
 954 );
 955
 956 /*
 957  * NSSPublicKey_Encrypt
 958  *
 959  * Encrypt a single chunk of data with the public key corresponding to
 960  * this certificate.
 961  */
 962
 963 NSS_EXTERN NSSItem *
 964 NSSPublicKey_Encrypt
 965 (
 966   NSSPublicKey *bk,
 967   NSSAlgorithmAndParameters *apOpt,
 968   NSSItem *data,
 969   NSSCallback *uhh,
 970   NSSItem *rvOpt,
 971   NSSArena *arenaOpt
 972 );
 973
 974 /*
 975  * NSSPublicKey_Verify
 976  *
 977  */
 978
 979 NSS_EXTERN PRStatus
 980 NSSPublicKey_Verify
 981 (
 982   NSSPublicKey *bk,
 983   NSSAlgorithmAndParameters *apOpt,
 984   NSSItem *data,
 985   NSSItem *signature,
 986   NSSCallback *uhh
 987 );
 988
 989 /*
 990  * NSSPublicKey_VerifyRecover
 991  *
 992  */
 993
 994 NSS_EXTERN NSSItem *
 995 NSSPublicKey_VerifyRecover
 996 (
 997   NSSPublicKey *bk,
 998   NSSAlgorithmAndParameters *apOpt,
 999   NSSItem *signature,
1000   NSSCallback *uhh,
1001   NSSItem *rvOpt,
1002   NSSArena *arenaOpt
1003 );
1004
1005 /*
1006  * NSSPublicKey_WrapSymmetricKey
1007  *
1008  */
1009
1010 NSS_EXTERN NSSItem *
1011 NSSPublicKey_WrapSymmetricKey
1012 (
1013   NSSPublicKey *bk,
1014   NSSAlgorithmAndParameters *apOpt,
1015   NSSSymmetricKey *keyToWrap,
1016   NSSCallback *uhh,
1017   NSSItem *rvOpt,
1018   NSSArena *arenaOpt
1019 );
1020
1021 /*
1022  * NSSPublicKey_CreateCryptoContext
1023  *
1024  * Create a crypto context, in this key's trust domain, with this
1025  * as the distinguished public key.
1026  */
1027
1028 NSS_EXTERN NSSCryptoContext *
1029 NSSPublicKey_CreateCryptoContext
1030 (
1031   NSSPublicKey *bk,
1032   NSSAlgorithmAndParameters *apOpt,
1033   NSSCallback *uhh
1034 );
1035
1036 /*
1037  * NSSPublicKey_FindCertificates
1038  *
1039  * Note that there may be more than one certificate for this
1040  * public key.  The current implementation may not find every
1041  * last certificate available for this public key: that would
1042  * involve trolling e.g. huge ldap databases, which will be
1043  * grossly inefficient and not generally useful.
1044  * { FilterCertificates function to further reduce the list }
1045  */
1046
1047 NSS_EXTERN NSSCertificate **
1048 NSSPublicKey_FindCertificates
1049 (
1050   NSSPublicKey *bk,
1051   NSSCertificate *rvOpt[],
1052   PRUint32 maximumOpt, /* 0 for no max */
1053   NSSArena *arenaOpt
1054 );
1055
1056 /*
1057  * NSSPrivateKey_FindBestCertificate
1058  *
1059  * The parameters for this function will depend on what the users
1060  * need.  This is just a starting point.
1061  */
1062
1063 NSS_EXTERN NSSCertificate *
1064 NSSPublicKey_FindBestCertificate
1065 (
1066   NSSPublicKey *bk,
1067   NSSTime *timeOpt,
1068   NSSUsage *usageOpt,
1069   NSSPolicies *policiesOpt
1070 );
1071
1072 /*
1073  * NSSPublicKey_FindPrivateKey
1074  *
1075  */
1076
1077 NSS_EXTERN NSSPrivateKey *
1078 NSSPublicKey_FindPrivateKey
1079 (
1080   NSSPublicKey *bk,
1081   NSSCallback *uhh
1082 );
1083
1084 /*
1085  * NSSSymmetricKey
1086  *
1087  */
1088
1089 /*
1090  * NSSSymmetricKey_Destroy
1091  *
1092  * Free a pointer to a symmetric key object.
1093  */
1094
1095 NSS_EXTERN PRStatus
1096 NSSSymmetricKey_Destroy
1097 (
1098   NSSSymmetricKey *mk
1099 );
1100
1101 /*
1102  * NSSSymmetricKey_DeleteStoredObject
1103  *
1104  * Permanently remove this object.
1105  */
1106
1107 NSS_EXTERN PRStatus
1108 NSSSymmetricKey_DeleteStoredObject
1109 (
1110   NSSSymmetricKey *mk,
1111   NSSCallback *uhh
1112 );
1113
1114 /*
1115  * NSSSymmetricKey_GetKeyLength
1116  *
1117  */
1118
1119 NSS_EXTERN PRUint32
1120 NSSSymmetricKey_GetKeyLength
1121 (
1122   NSSSymmetricKey *mk
1123 );
1124
1125 /*
1126  * NSSSymmetricKey_GetKeyStrength
1127  *
1128  */
1129
1130 NSS_EXTERN PRUint32
1131 NSSSymmetricKey_GetKeyStrength
1132 (
1133   NSSSymmetricKey *mk
1134 );
1135
1136 /*
1137  * NSSSymmetricKey_IsStillPresent
1138  *
1139  */
1140
1141 NSS_EXTERN PRStatus
1142 NSSSymmetricKey_IsStillPresent
1143 (
1144   NSSSymmetricKey *mk
1145 );
1146
1147 /*
1148  * NSSSymmetricKey_GetTrustDomain
1149  *
1150  * There doesn't have to be one.
1151  */
1152
1153 NSS_EXTERN NSSTrustDomain *
1154 NSSSymmetricKey_GetTrustDomain
1155 (
1156   NSSSymmetricKey *mk,
1157   PRStatus *statusOpt
1158 );
1159
1160 /*
1161  * NSSSymmetricKey_GetToken
1162  *
1163  * There doesn't have to be one.
1164  */
1165
1166 NSS_EXTERN NSSToken *
1167 NSSSymmetricKey_GetToken
1168 (
1169   NSSSymmetricKey *mk,
1170   PRStatus *statusOpt
1171 );
1172
1173 /*
1174  * NSSSymmetricKey_GetSlot
1175  *
1176  * There doesn't have to be one.
1177  */
1178
1179 NSS_EXTERN NSSSlot *
1180 NSSSymmetricKey_GetSlot
1181 (
1182   NSSSymmetricKey *mk,
1183   PRStatus *statusOpt
1184 );
1185
1186 /*
1187  * NSSSymmetricKey_GetModule
1188  *
1189  * There doesn't have to be one.
1190  */
1191
1192 NSS_EXTERN NSSModule *
1193 NSSSymmetricKey_GetModule
1194 (
1195   NSSSymmetricKey *mk,
1196   PRStatus *statusOpt
1197 );
1198
1199 /*
1200  * NSSSymmetricKey_Encrypt
1201  *
1202  */
1203
1204 NSS_EXTERN NSSItem *
1205 NSSSymmetricKey_Encrypt
1206 (
1207   NSSSymmetricKey *mk,
1208   NSSAlgorithmAndParameters *apOpt,
1209   NSSItem *data,
1210   NSSCallback *uhh,
1211   NSSItem *rvOpt,
1212   NSSArena *arenaOpt
1213 );
1214
1215 /*
1216  * NSSSymmetricKey_Decrypt
1217  *
1218  */
1219
1220 NSS_EXTERN NSSItem *
1221 NSSSymmetricKey_Decrypt
1222 (
1223   NSSSymmetricKey *mk,
1224   NSSAlgorithmAndParameters *apOpt,
1225   NSSItem *encryptedData,
1226   NSSCallback *uhh,
1227   NSSItem *rvOpt,
1228   NSSArena *arenaOpt
1229 );
1230
1231 /*
1232  * NSSSymmetricKey_Sign
1233  *
1234  */
1235
1236 NSS_EXTERN NSSItem *
1237 NSSSymmetricKey_Sign
1238 (
1239   NSSSymmetricKey *mk,
1240   NSSAlgorithmAndParameters *apOpt,
1241   NSSItem *data,
1242   NSSCallback *uhh,
1243   NSSItem *rvOpt,
1244   NSSArena *arenaOpt
1245 );
1246
1247 /*
1248  * NSSSymmetricKey_SignRecover
1249  *
1250  */
1251
1252 NSS_EXTERN NSSItem *
1253 NSSSymmetricKey_SignRecover
1254 (
1255   NSSSymmetricKey *mk,
1256   NSSAlgorithmAndParameters *apOpt,
1257   NSSItem *data,
1258   NSSCallback *uhh,
1259   NSSItem *rvOpt,
1260   NSSArena *arenaOpt
1261 );
1262
1263 /*
1264  * NSSSymmetricKey_Verify
1265  *
1266  */
1267
1268 NSS_EXTERN PRStatus
1269 NSSSymmetricKey_Verify
1270 (
1271   NSSSymmetricKey *mk,
1272   NSSAlgorithmAndParameters *apOpt,
1273   NSSItem *data,
1274   NSSItem *signature,
1275   NSSCallback *uhh
1276 );
1277
1278 /*
1279  * NSSSymmetricKey_VerifyRecover
1280  *
1281  */
1282
1283 NSS_EXTERN NSSItem *
1284 NSSSymmetricKey_VerifyRecover
1285 (
1286   NSSSymmetricKey *mk,
1287   NSSAlgorithmAndParameters *apOpt,
1288   NSSItem *signature,
1289   NSSCallback *uhh,
1290   NSSItem *rvOpt,
1291   NSSArena *arenaOpt
1292 );
1293
1294 /*
1295  * NSSSymmetricKey_WrapSymmetricKey
1296  *
1297  */
1298
1299 NSS_EXTERN NSSItem *
1300 NSSSymmetricKey_WrapSymmetricKey
1301 (
1302   NSSSymmetricKey *wrappingKey,
1303   NSSAlgorithmAndParameters *apOpt,
1304   NSSSymmetricKey *keyToWrap,
1305   NSSCallback *uhh,
1306   NSSItem *rvOpt,
1307   NSSArena *arenaOpt
1308 );
1309
1310 /*
1311  * NSSSymmetricKey_WrapPrivateKey
1312  *
1313  */
1314
1315 NSS_EXTERN NSSItem *
1316 NSSSymmetricKey_WrapPrivateKey
1317 (
1318   NSSSymmetricKey *wrappingKey,
1319   NSSAlgorithmAndParameters *apOpt,
1320   NSSPrivateKey *keyToWrap,
1321   NSSCallback *uhh,
1322   NSSItem *rvOpt,
1323   NSSArena *arenaOpt
1324 );
1325
1326 /*
1327  * NSSSymmetricKey_UnwrapSymmetricKey
1328  *
1329  */
1330
1331 NSS_EXTERN NSSSymmetricKey *
1332 NSSSymmetricKey_UnwrapSymmetricKey
1333 (
1334   NSSSymmetricKey *wrappingKey,
1335   NSSAlgorithmAndParameters *apOpt,
1336   NSSItem *wrappedKey,
1337   NSSOID *target,
1338   PRUint32 keySizeOpt,
1339   NSSOperations operations,
1340   NSSCallback *uhh
1341 );
1342
1343 /*
1344  * NSSSymmetricKey_UnwrapPrivateKey
1345  *
1346  */
1347
1348 NSS_EXTERN NSSPrivateKey *
1349 NSSSymmetricKey_UnwrapPrivateKey
1350 (
1351   NSSSymmetricKey *wrappingKey,
1352   NSSAlgorithmAndParameters *apOpt,
1353   NSSItem *wrappedKey,
1354   NSSUTF8 *labelOpt,
1355   NSSItem *keyIDOpt,
1356   PRBool persistant,
1357   PRBool sensitive,
1358   NSSToken *destinationOpt,
1359   NSSCallback *uhh
1360 );
1361
1362 /*
1363  * NSSSymmetricKey_DeriveSymmetricKey
1364  *
1365  */
1366
1367 NSS_EXTERN NSSSymmetricKey *
1368 NSSSymmetricKey_DeriveSymmetricKey
1369 (
1370   NSSSymmetricKey *originalKey,
1371   NSSAlgorithmAndParameters *apOpt,
1372   NSSOID *target,
1373   PRUint32 keySizeOpt,
1374   NSSOperations operations,
1375   NSSCallback *uhh
1376 );
1377
1378 /*
1379  * NSSSymmetricKey_CreateCryptoContext
1380  *
1381  * Create a crypto context, in this key's trust domain,
1382  * with this as the distinguished symmetric key.
1383  */
1384
1385 NSS_EXTERN NSSCryptoContext *
1386 NSSSymmetricKey_CreateCryptoContext
1387 (
1388   NSSSymmetricKey *mk,
1389   NSSAlgorithmAndParameters *apOpt,
1390   NSSCallback *uhh
1391 );
1392
1393 /*
1394  * NSSTrustDomain
1395  *
1396  */
1397
1398 /*
1399  * NSSTrustDomain_Create
1400  *
1401  * This creates a trust domain, optionally with an initial cryptoki
1402  * module.  If the module name is not null, the module is loaded if
1403  * needed (using the uriOpt argument), and initialized with the
1404  * opaqueOpt argument.  If mumble mumble priority settings, then
1405  * module-specification objects in the module can cause the loading
1406  * and initialization of further modules.
1407  *
1408  * The uriOpt is defined to take a URI.  At present, we only
1409  * support file: URLs pointing to platform-native shared libraries.
1410  * However, by specifying this as a URI, this keeps open the
1411  * possibility of supporting other, possibly remote, resources.
1412  *
1413  * The "reserved" arguments is held for when we figure out the
1414  * module priority stuff.
1415  */
1416
1417 NSS_EXTERN NSSTrustDomain *
1418 NSSTrustDomain_Create
1419 (
1420   NSSUTF8 *moduleOpt,
1421   NSSUTF8 *uriOpt,
1422   NSSUTF8 *opaqueOpt,
1423   void *reserved
1424 );
1425
1426 /*
1427  * NSSTrustDomain_Destroy
1428  *
1429  */
1430
1431 NSS_EXTERN PRStatus
1432 NSSTrustDomain_Destroy
1433 (
1434   NSSTrustDomain *td
1435 );
1436
1437 /*
1438  * NSSTrustDomain_SetDefaultCallback
1439  *
1440  */
1441
1442 NSS_EXTERN PRStatus
1443 NSSTrustDomain_SetDefaultCallback
1444 (
1445   NSSTrustDomain *td,
1446   NSSCallback *newCallback,
1447   NSSCallback **oldCallbackOpt
1448 );
1449
1450 /*
1451  * NSSTrustDomain_GetDefaultCallback
1452  *
1453  */
1454
1455 NSS_EXTERN NSSCallback *
1456 NSSTrustDomain_GetDefaultCallback
1457 (
1458   NSSTrustDomain *td,
1459   PRStatus *statusOpt
1460 );
1461
1462 /*
1463  * Default policies?
1464  * Default usage?
1465  * Default time, for completeness?
1466  */
1467
1468 /*
1469  * NSSTrustDomain_LoadModule
1470  *
1471  */
1472
1473 NSS_EXTERN PRStatus
1474 NSSTrustDomain_LoadModule
1475 (
1476   NSSTrustDomain *td,
1477   NSSUTF8 *moduleOpt,
1478   NSSUTF8 *uriOpt,
1479   NSSUTF8 *opaqueOpt,
1480   void *reserved
1481 );
1482
1483 /*
1484  * NSSTrustDomain_AddModule
1485  * NSSTrustDomain_AddSlot
1486  * NSSTrustDomain_UnloadModule
1487  * Managing modules, slots, tokens; priorities;
1488  * Traversing all of the above
1489  * this needs more work
1490  */
1491
1492 /*
1493  * NSSTrustDomain_DisableToken
1494  *
1495  */
1496
1497 NSS_EXTERN PRStatus
1498 NSSTrustDomain_DisableToken
1499 (
1500   NSSTrustDomain *td,
1501   NSSToken *token,
1502   NSSError why
1503 );
1504
1505 /*
1506  * NSSTrustDomain_EnableToken
1507  *
1508  */
1509
1510 NSS_EXTERN PRStatus
1511 NSSTrustDomain_EnableToken
1512 (
1513   NSSTrustDomain *td,
1514   NSSToken *token
1515 );
1516
1517 /*
1518  * NSSTrustDomain_IsTokenEnabled
1519  *
1520  * If disabled, "why" is always on the error stack.
1521  * The optional argument is just for convenience.
1522  */
1523
1524 NSS_EXTERN PRStatus
1525 NSSTrustDomain_IsTokenEnabled
1526 (
1527   NSSTrustDomain *td,
1528   NSSToken *token,
1529   NSSError *whyOpt
1530 );
1531
1532 /*
1533  * NSSTrustDomain_FindSlotByName
1534  *
1535  */
1536
1537 NSS_EXTERN NSSSlot *
1538 NSSTrustDomain_FindSlotByName
1539 (
1540   NSSTrustDomain *td,
1541   NSSUTF8 *slotName
1542 );
1543
1544 /*
1545  * NSSTrustDomain_FindTokenByName
1546  *
1547  */
1548
1549 NSS_EXTERN NSSToken *
1550 NSSTrustDomain_FindTokenByName
1551 (
1552   NSSTrustDomain *td,
1553   NSSUTF8 *tokenName
1554 );
1555
1556 /*
1557  * NSSTrustDomain_FindTokenBySlotName
1558  *
1559  */
1560
1561 NSS_EXTERN NSSToken *
1562 NSSTrustDomain_FindTokenBySlotName
1563 (
1564   NSSTrustDomain *td,
1565   NSSUTF8 *slotName
1566 );
1567
1568 /*
1569  * NSSTrustDomain_FindBestTokenForAlgorithm
1570  *
1571  */
1572
1573 NSS_EXTERN NSSToken *
1574 NSSTrustDomain_FindTokenForAlgorithm
1575 (
1576   NSSTrustDomain *td,
1577   NSSOID *algorithm
1578 );
1579
1580 /*
1581  * NSSTrustDomain_FindBestTokenForAlgorithms
1582  *
1583  */
1584
1585 NSS_EXTERN NSSToken *
1586 NSSTrustDomain_FindBestTokenForAlgorithms
1587 (
1588   NSSTrustDomain *td,
1589   NSSOID *algorithms[], /* may be null-terminated */
1590   PRUint32 nAlgorithmsOpt /* limits the array if nonzero */
1591 );
1592
1593 /*
1594  * NSSTrustDomain_Login
1595  *
1596  */
1597
1598 NSS_EXTERN PRStatus
1599 NSSTrustDomain_Login
1600 (
1601   NSSTrustDomain *td,
1602   NSSCallback *uhhOpt
1603 );
1604
1605 /*
1606  * NSSTrustDomain_Logout
1607  *
1608  */
1609
1610 NSS_EXTERN PRStatus
1611 NSSTrustDomain_Logout
1612 (
1613   NSSTrustDomain *td
1614 );
1615
1616 /* Importing things */
1617
1618 /*
1619  * NSSTrustDomain_ImportCertificate
1620  *
1621  * The implementation will pull some data out of the certificate
1622  * (e.g. e-mail address) for use in pkcs#11 object attributes.
1623  */
1624
1625 NSS_EXTERN NSSCertificate *
1626 NSSTrustDomain_ImportCertificate
1627 (
1628   NSSTrustDomain *td,
1629   NSSCertificate *c
1630 );
1631
1632 /*
1633  * NSSTrustDomain_ImportPKIXCertificate
1634  *
1635  */
1636
1637 NSS_EXTERN NSSCertificate *
1638 NSSTrustDomain_ImportPKIXCertificate
1639 (
1640   NSSTrustDomain *td,
1641   /* declared as a struct until these "data types" are defined */
1642   struct NSSPKIXCertificateStr *pc
1643 );
1644
1645 /*
1646  * NSSTrustDomain_ImportEncodedCertificate
1647  *
1648  * Imports any type of certificate we support.
1649  */
1650
1651 NSS_EXTERN NSSCertificate *
1652 NSSTrustDomain_ImportEncodedCertificate
1653 (
1654   NSSTrustDomain *td,
1655   NSSBER *ber
1656 );
1657
1658 /*
1659  * NSSTrustDomain_ImportEncodedCertificateChain
1660  *
1661  * If you just want the leaf, pass in a maximum of one.
1662  */
1663
1664 NSS_EXTERN NSSCertificate **
1665 NSSTrustDomain_ImportEncodedCertificateChain
1666 (
1667   NSSTrustDomain *td,
1668   NSSBER *ber,
1669   NSSCertificate *rvOpt[],
1670   PRUint32 maximumOpt, /* 0 for no max */
1671   NSSArena *arenaOpt
1672 );
1673
1674 /*
1675  * NSSTrustDomain_ImportEncodedPrivateKey
1676  *
1677  */
1678
1679 NSS_EXTERN NSSPrivateKey *
1680 NSSTrustDomain_ImportEncodedPrivateKey
1681 (
1682   NSSTrustDomain *td,
1683   NSSBER *ber,
1684   NSSItem *passwordOpt, /* NULL will cause a callback */
1685   NSSCallback *uhhOpt,
1686   NSSToken *destination
1687 );
1688
1689 /*
1690  * NSSTrustDomain_ImportEncodedPublicKey
1691  *
1692  */
1693
1694 NSS_EXTERN NSSPublicKey *
1695 NSSTrustDomain_ImportEncodedPublicKey
1696 (
1697   NSSTrustDomain *td,
1698   NSSBER *ber
1699 );
1700
1701 /* Other importations: S/MIME capabilities */
1702
1703 /*
1704  * NSSTrustDomain_FindBestCertificateByNickname
1705  *
1706  */
1707
1708 NSS_EXTERN NSSCertificate *
1709 NSSTrustDomain_FindBestCertificateByNickname
1710 (
1711   NSSTrustDomain *td,
1712   const NSSUTF8 *name,
1713   NSSTime *timeOpt, /* NULL for "now" */
1714   NSSUsage *usage,
1715   NSSPolicies *policiesOpt /* NULL for none */
1716 );
1717
1718 /*
1719  * NSSTrustDomain_FindCertificatesByNickname
1720  *
1721  */
1722
1723 NSS_EXTERN NSSCertificate **
1724 NSSTrustDomain_FindCertificatesByNickname
1725 (
1726   NSSTrustDomain *td,
1727   NSSUTF8 *name,
1728   NSSCertificate *rvOpt[],
1729   PRUint32 maximumOpt, /* 0 for no max */
1730   NSSArena *arenaOpt
1731 );
1732
1733 /*
1734  * NSSTrustDomain_FindCertificateByIssuerAndSerialNumber
1735  *
1736  */
1737
1738 NSS_EXTERN NSSCertificate *
1739 NSSTrustDomain_FindCertificateByIssuerAndSerialNumber
1740 (
1741   NSSTrustDomain *td,
1742   NSSDER *issuer,
1743   NSSDER *serialNumber
1744 );
1745
1746 /*
1747  * NSSTrustDomain_FindCertificatesByIssuerAndSerialNumber
1748  *
1749  * Theoretically, this should never happen.  However, some companies
1750  * we know have issued duplicate certificates with the same issuer
1751  * and serial number.  Do we just ignore them?  I'm thinking yes.
1752  */
1753
1754 /*
1755  * NSSTrustDomain_FindBestCertificateBySubject
1756  *
1757  * This does not search through alternate names hidden in extensions.
1758  */
1759
1760 NSS_EXTERN NSSCertificate *
1761 NSSTrustDomain_FindBestCertificateBySubject
1762 (
1763   NSSTrustDomain *td,
1764   NSSDER /*NSSUTF8*/ *subject,
1765   NSSTime *timeOpt,
1766   NSSUsage *usage,
1767   NSSPolicies *policiesOpt
1768 );
1769
1770 /*
1771  * NSSTrustDomain_FindCertificatesBySubject
1772  *
1773  * This does not search through alternate names hidden in extensions.
1774  */
1775
1776 NSS_EXTERN NSSCertificate **
1777 NSSTrustDomain_FindCertificatesBySubject
1778 (
1779   NSSTrustDomain *td,
1780   NSSDER /*NSSUTF8*/ *subject,
1781   NSSCertificate *rvOpt[],
1782   PRUint32 maximumOpt, /* 0 for no max */
1783   NSSArena *arenaOpt
1784 );
1785
1786 /*
1787  * NSSTrustDomain_FindBestCertificateByNameComponents
1788  *
1789  * This call does try several tricks, including a pseudo pkcs#11
1790  * attribute for the ldap module to try as a query.  Eventually
1791  * this call falls back to a traversal if that's what's required.
1792  * It will search through alternate names hidden in extensions.
1793  */
1794
1795 NSS_EXTERN NSSCertificate *
1796 NSSTrustDomain_FindBestCertificateByNameComponents
1797 (
1798   NSSTrustDomain *td,
1799   NSSUTF8 *nameComponents,
1800   NSSTime *timeOpt,
1801   NSSUsage *usage,
1802   NSSPolicies *policiesOpt
1803 );
1804
1805 /*
1806  * NSSTrustDomain_FindCertificatesByNameComponents
1807  *
1808  * This call, too, tries several tricks.  It will stop on the first
1809  * attempt that generates results, so it won't e.g. traverse the
1810  * entire ldap database.
1811  */
1812
1813 NSS_EXTERN NSSCertificate **
1814 NSSTrustDomain_FindCertificatesByNameComponents
1815 (
1816   NSSTrustDomain *td,
1817   NSSUTF8 *nameComponents,
1818   NSSCertificate *rvOpt[],
1819   PRUint32 maximumOpt, /* 0 for no max */
1820   NSSArena *arenaOpt
1821 );
1822
1823 /*
1824  * NSSTrustDomain_FindCertificateByEncodedCertificate
1825  *
1826  */
1827
1828 NSS_EXTERN NSSCertificate *
1829 NSSTrustDomain_FindCertificateByEncodedCertificate
1830 (
1831   NSSTrustDomain *td,
1832   NSSBER *encodedCertificate
1833 );
1834
1835 /*
1836  * NSSTrustDomain_FindBestCertificateByEmail
1837  *
1838  */
1839
1840 NSS_EXTERN NSSCertificate *
1841 NSSTrustDomain_FindCertificateByEmail
1842 (
1843   NSSTrustDomain *td,
1844   NSSASCII7 *email,
1845   NSSTime *timeOpt,
1846   NSSUsage *usage,
1847   NSSPolicies *policiesOpt
1848 );
1849
1850 /*
1851  * NSSTrustDomain_FindCertificatesByEmail
1852  *
1853  */
1854
1855 NSS_EXTERN NSSCertificate **
1856 NSSTrustDomain_FindCertificatesByEmail
1857 (
1858   NSSTrustDomain *td,
1859   NSSASCII7 *email,
1860   NSSCertificate *rvOpt[],
1861   PRUint32 maximumOpt, /* 0 for no max */
1862   NSSArena *arenaOpt
1863 );
1864
1865 /*
1866  * NSSTrustDomain_FindCertificateByOCSPHash
1867  *
1868  * There can be only one.
1869  */
1870
1871 NSS_EXTERN NSSCertificate *
1872 NSSTrustDomain_FindCertificateByOCSPHash
1873 (
1874   NSSTrustDomain *td,
1875   NSSItem *hash
1876 );
1877
1878 /*
1879  * NSSTrustDomain_TraverseCertificates
1880  *
1881  * This function descends from one in older versions of NSS which
1882  * traverses the certs in the permanent database.  That function
1883  * was used to implement selection routines, but was directly
1884  * available too.  Trust domains are going to contain a lot more
1885  * certs now (e.g., an ldap server), so we'd really like to
1886  * discourage traversal.  Thus for now, this is commented out.
1887  * If it's needed, let's look at the situation more closely to
1888  * find out what the actual requirements are.
1889  */
1890
1891 /* For now, adding this function.  This may only be for debugging
1892  * purposes.
1893  * Perhaps some equivalent function, on a specified token, will be
1894  * needed in a "friend" header file?
1895  */
1896 NSS_EXTERN PRStatus *
1897 NSSTrustDomain_TraverseCertificates
1898 (
1899   NSSTrustDomain *td,
1900   PRStatus (*callback)(NSSCertificate *c, void *arg),
1901   void *arg
1902 );
1903
1904 /*
1905  * NSSTrustDomain_FindBestUserCertificate
1906  *
1907  */
1908
1909 NSS_EXTERN NSSCertificate *
1910 NSSTrustDomain_FindBestUserCertificate
1911 (
1912   NSSTrustDomain *td,
1913   NSSTime *timeOpt,
1914   NSSUsage *usage,
1915   NSSPolicies *policiesOpt
1916 );
1917
1918 /*
1919  * NSSTrustDomain_FindUserCertificates
1920  *
1921  */
1922
1923 NSS_EXTERN NSSCertificate **
1924 NSSTrustDomain_FindUserCertificates
1925 (
1926   NSSTrustDomain *td,
1927   NSSTime *timeOpt,
1928   NSSUsage *usageOpt,
1929   NSSPolicies *policiesOpt,
1930   NSSCertificate **rvOpt,
1931   PRUint32 rvLimit, /* zero for no limit */
1932   NSSArena *arenaOpt
1933 );
1934
1935 /*
1936  * NSSTrustDomain_FindBestUserCertificateForSSLClientAuth
1937  *
1938  */
1939
1940 NSS_EXTERN NSSCertificate *
1941 NSSTrustDomain_FindBestUserCertificateForSSLClientAuth
1942 (
1943   NSSTrustDomain *td,
1944   NSSUTF8 *sslHostOpt,
1945   NSSDER *rootCAsOpt[], /* null pointer for none */
1946   PRUint32 rootCAsMaxOpt, /* zero means list is null-terminated */
1947   NSSAlgorithmAndParameters *apOpt,
1948   NSSPolicies *policiesOpt
1949 );
1950
1951 /*
1952  * NSSTrustDomain_FindUserCertificatesForSSLClientAuth
1953  *
1954  */
1955
1956 NSS_EXTERN NSSCertificate **
1957 NSSTrustDomain_FindUserCertificatesForSSLClientAuth
1958 (
1959   NSSTrustDomain *td,
1960   NSSUTF8 *sslHostOpt,
1961   NSSDER *rootCAsOpt[], /* null pointer for none */
1962   PRUint32 rootCAsMaxOpt, /* zero means list is null-terminated */
1963   NSSAlgorithmAndParameters *apOpt,
1964   NSSPolicies *policiesOpt,
1965   NSSCertificate **rvOpt,
1966   PRUint32 rvLimit, /* zero for no limit */
1967   NSSArena *arenaOpt
1968 );
1969
1970 /*
1971  * NSSTrustDomain_FindBestUserCertificateForEmailSigning
1972  *
1973  */
1974
1975 NSS_EXTERN NSSCertificate *
1976 NSSTrustDomain_FindBestUserCertificateForEmailSigning
1977 (
1978   NSSTrustDomain *td,
1979   NSSASCII7 *signerOpt,
1980   NSSASCII7 *recipientOpt,
1981   /* anything more here? */
1982   NSSAlgorithmAndParameters *apOpt,
1983   NSSPolicies *policiesOpt
1984 );
1985
1986 /*
1987  * NSSTrustDomain_FindUserCertificatesForEmailSigning
1988  *
1989  */
1990
1991 NSS_EXTERN NSSCertificate **
1992 NSSTrustDomain_FindUserCertificatesForEmailSigning
1993 (
1994   NSSTrustDomain *td,
1995   NSSASCII7 *signerOpt,
1996   NSSASCII7 *recipientOpt,
1997   /* anything more here? */
1998   NSSAlgorithmAndParameters *apOpt,
1999   NSSPolicies *policiesOpt,
2000   NSSCertificate **rvOpt,
2001   PRUint32 rvLimit, /* zero for no limit */
2002   NSSArena *arenaOpt
2003 );
2004
2005 /*
2006  * Here is where we'd add more Find[Best]UserCertificate[s]For<usage>
2007  * routines.
2008  */
2009
2010 /* Private Keys */
2011
2012 /*
2013  * NSSTrustDomain_GenerateKeyPair
2014  *
2015  * Creates persistant objects.  If you want session objects, use
2016  * NSSCryptoContext_GenerateKeyPair.  The destination token is where
2017  * the keys are stored.  If that token can do the required math, then
2018  * that's where the keys are generated too.  Otherwise, the keys are
2019  * generated elsewhere and moved to that token.
2020  */
2021
2022 NSS_EXTERN PRStatus
2023 NSSTrustDomain_GenerateKeyPair
2024 (
2025   NSSTrustDomain *td,
2026   NSSAlgorithmAndParameters *ap,
2027   NSSPrivateKey **pvkOpt,
2028   NSSPublicKey **pbkOpt,
2029   PRBool privateKeyIsSensitive,
2030   NSSToken *destination,
2031   NSSCallback *uhhOpt
2032 );
2033
2034 /*
2035  * NSSTrustDomain_TraversePrivateKeys
2036  *
2037  *
2038  * NSS_EXTERN PRStatus *
2039  * NSSTrustDomain_TraversePrivateKeys
2040  * (
2041  *   NSSTrustDomain *td,
2042  *   PRStatus (*callback)(NSSPrivateKey *vk, void *arg),
2043  *   void *arg
2044  * );
2045  */
2046
2047 /* Symmetric Keys */
2048
2049 /*
2050  * NSSTrustDomain_GenerateSymmetricKey
2051  *
2052  */
2053
2054 NSS_EXTERN NSSSymmetricKey *
2055 NSSTrustDomain_GenerateSymmetricKey
2056 (
2057   NSSTrustDomain *td,
2058   NSSAlgorithmAndParameters *ap,
2059   PRUint32 keysize,
2060   NSSToken *destination,
2061   NSSCallback *uhhOpt
2062 );
2063
2064 /*
2065  * NSSTrustDomain_GenerateSymmetricKeyFromPassword
2066  *
2067  */
2068
2069 NSS_EXTERN NSSSymmetricKey *
2070 NSSTrustDomain_GenerateSymmetricKeyFromPassword
2071 (
2072   NSSTrustDomain *td,
2073   NSSAlgorithmAndParameters *ap,
2074   NSSUTF8 *passwordOpt, /* if null, prompt */
2075   NSSToken *destinationOpt,
2076   NSSCallback *uhhOpt
2077 );
2078
2079 /*
2080  * NSSTrustDomain_FindSymmetricKeyByAlgorithm
2081  *
2082  * Is this still needed?
2083  *
2084  * NSS_EXTERN NSSSymmetricKey *
2085  * NSSTrustDomain_FindSymmetricKeyByAlgorithm
2086  * (
2087  *   NSSTrustDomain *td,
2088  *   NSSOID *algorithm,
2089  *   NSSCallback *uhhOpt
2090  * );
2091  */
2092
2093 /*
2094  * NSSTrustDomain_FindSymmetricKeyByAlgorithmAndKeyID
2095  *
2096  */
2097
2098 NSS_EXTERN NSSSymmetricKey *
2099 NSSTrustDomain_FindSymmetricKeyByAlgorithmAndKeyID
2100 (
2101   NSSTrustDomain *td,
2102   NSSOID *algorithm,
2103   NSSItem *keyID,
2104   NSSCallback *uhhOpt
2105 );
2106
2107 /*
2108  * NSSTrustDomain_TraverseSymmetricKeys
2109  *
2110  *
2111  * NSS_EXTERN PRStatus *
2112  * NSSTrustDomain_TraverseSymmetricKeys
2113  * (
2114  *   NSSTrustDomain *td,
2115  *   PRStatus (*callback)(NSSSymmetricKey *mk, void *arg),
2116  *   void *arg
2117  * );
2118  */
2119
2120 /*
2121  * NSSTrustDomain_CreateCryptoContext
2122  *
2123  * If a callback object is specified, it becomes the for the crypto
2124  * context; otherwise, this trust domain's default (if any) is
2125  * inherited.
2126  */
2127
2128 NSS_EXTERN NSSCryptoContext *
2129 NSSTrustDomain_CreateCryptoContext
2130 (
2131   NSSTrustDomain *td,
2132   NSSCallback *uhhOpt
2133 );
2134
2135 /*
2136  * NSSTrustDomain_CreateCryptoContextForAlgorithm
2137  *
2138  */
2139
2140 NSS_EXTERN NSSCryptoContext *
2141 NSSTrustDomain_CreateCryptoContextForAlgorithm
2142 (
2143   NSSTrustDomain *td,
2144   NSSOID *algorithm
2145 );
2146
2147 /*
2148  * NSSTrustDomain_CreateCryptoContextForAlgorithmAndParameters
2149  *
2150  */
2151
2152 NSS_EXTERN NSSCryptoContext *
2153 NSSTrustDomain_CreateCryptoContextForAlgorithmAndParameters
2154 (
2155   NSSTrustDomain *td,
2156   NSSAlgorithmAndParameters *ap
2157 );
2158
2159 /* find/traverse other objects, e.g. s/mime profiles */
2160
2161 /*
2162  * NSSCryptoContext
2163  *
2164  * A crypto context is sort of a short-term snapshot of a trust domain,
2165  * used for the life of "one crypto operation."  You can also think of
2166  * it as a "temporary database."
2167  *
2168  * Just about all of the things you can do with a trust domain -- importing
2169  * or creating certs, keys, etc. -- can be done with a crypto context.
2170  * The difference is that the objects will be temporary ("session") objects.
2171  *
2172  * Also, if the context was created for a key, cert, and/or algorithm; or
2173  * if such objects have been "associated" with the context, then the context
2174  * can do everything the keys can, like crypto operations.
2175  *
2176  * And finally, because it keeps the state of the crypto operations, it
2177  * can do streaming crypto ops.
2178  */
2179
2180 /*
2181  * NSSTrustDomain_Destroy
2182  *
2183  */
2184
2185 NSS_EXTERN PRStatus
2186 NSSCryptoContext_Destroy
2187 (
2188   NSSCryptoContext *cc
2189 );
2190
2191 /* establishing a default callback */
2192
2193 /*
2194  * NSSCryptoContext_SetDefaultCallback
2195  *
2196  */
2197
2198 NSS_EXTERN PRStatus
2199 NSSCryptoContext_SetDefaultCallback
2200 (
2201   NSSCryptoContext *cc,
2202   NSSCallback *newCallback,
2203   NSSCallback **oldCallbackOpt
2204 );
2205
2206 /*
2207  * NSSCryptoContext_GetDefaultCallback
2208  *
2209  */
2210
2211 NSS_EXTERN NSSCallback *
2212 NSSCryptoContext_GetDefaultCallback
2213 (
2214   NSSCryptoContext *cc,
2215   PRStatus *statusOpt
2216 );
2217
2218 /*
2219  * NSSCryptoContext_GetTrustDomain
2220  *
2221  */
2222
2223 NSS_EXTERN NSSTrustDomain *
2224 NSSCryptoContext_GetTrustDomain
2225 (
2226   NSSCryptoContext *cc
2227 );
2228
2229 /* AddModule, etc: should we allow "temporary" changes here? */
2230 /* DisableToken, etc: ditto */
2231 /* Ordering of tokens? */
2232 /* Finding slots+token etc. */
2233 /* login+logout */
2234
2235 /* Importing things */
2236
2237 /*
2238  * NSSCryptoContext_FindOrImportCertificate
2239  *
2240  * If the certificate store already contains this DER cert, return the
2241  * address of the matching NSSCertificate that is already in the store,
2242  * and bump its reference count.
2243  *
2244  * If this DER cert is NOT already in the store, then add the new
2245  * NSSCertificate to the store and bump its reference count,
2246  * then return its address.
2247  *
2248  * if this DER cert is not in the store and cannot be added to it,
2249  * return NULL;
2250  *
2251  * Record the associated crypto context in the certificate.
2252  */
2253
2254 NSS_EXTERN NSSCertificate *
2255 NSSCryptoContext_FindOrImportCertificate (
2256   NSSCryptoContext *cc,
2257   NSSCertificate *c
2258 );
2259
2260 /*
2261  * NSSCryptoContext_ImportPKIXCertificate
2262  *
2263  */
2264
2265 NSS_EXTERN NSSCertificate *
2266 NSSCryptoContext_ImportPKIXCertificate
2267 (
2268   NSSCryptoContext *cc,
2269   struct NSSPKIXCertificateStr *pc
2270 );
2271
2272 /*
2273  * NSSCryptoContext_ImportEncodedCertificate
2274  *
2275  */
2276
2277 NSS_EXTERN NSSCertificate *
2278 NSSCryptoContext_ImportEncodedCertificate
2279 (
2280   NSSCryptoContext *cc,
2281   NSSBER *ber
2282 );
2283
2284 /*
2285  * NSSCryptoContext_ImportEncodedPKIXCertificateChain
2286  *
2287  */
2288
2289 NSS_EXTERN PRStatus
2290 NSSCryptoContext_ImportEncodedPKIXCertificateChain
2291 (
2292   NSSCryptoContext *cc,
2293   NSSBER *ber
2294 );
2295
2296 /* Other importations: S/MIME capabilities
2297  */
2298
2299 /*
2300  * NSSCryptoContext_FindBestCertificateByNickname
2301  *
2302  */
2303
2304 NSS_EXTERN NSSCertificate *
2305 NSSCryptoContext_FindBestCertificateByNickname
2306 (
2307   NSSCryptoContext *cc,
2308   const NSSUTF8 *name,
2309   NSSTime *timeOpt, /* NULL for "now" */
2310   NSSUsage *usage,
2311   NSSPolicies *policiesOpt /* NULL for none */
2312 );
2313
2314 /*
2315  * NSSCryptoContext_FindCertificatesByNickname
2316  *
2317  */
2318
2319 NSS_EXTERN NSSCertificate **
2320 NSSCryptoContext_FindCertificatesByNickname
2321 (
2322   NSSCryptoContext *cc,
2323   NSSUTF8 *name,
2324   NSSCertificate *rvOpt[],
2325   PRUint32 maximumOpt, /* 0 for no max */
2326   NSSArena *arenaOpt
2327 );
2328
2329 /*
2330  * NSSCryptoContext_FindCertificateByIssuerAndSerialNumber
2331  *
2332  */
2333
2334 NSS_EXTERN NSSCertificate *
2335 NSSCryptoContext_FindCertificateByIssuerAndSerialNumber
2336 (
2337   NSSCryptoContext *cc,
2338   NSSDER *issuer,
2339   NSSDER *serialNumber
2340 );
2341
2342 /*
2343  * NSSCryptoContext_FindBestCertificateBySubject
2344  *
2345  * This does not search through alternate names hidden in extensions.
2346  */
2347
2348 NSS_EXTERN NSSCertificate *
2349 NSSCryptoContext_FindBestCertificateBySubject
2350 (
2351   NSSCryptoContext *cc,
2352   NSSDER /*NSSUTF8*/ *subject,
2353   NSSTime *timeOpt,
2354   NSSUsage *usage,
2355   NSSPolicies *policiesOpt
2356 );
2357
2358 /*
2359  * NSSCryptoContext_FindCertificatesBySubject
2360  *
2361  * This does not search through alternate names hidden in extensions.
2362  */
2363
2364 NSS_EXTERN NSSCertificate **
2365 NSSCryptoContext_FindCertificatesBySubject
2366 (
2367   NSSCryptoContext *cc,
2368   NSSDER /*NSSUTF8*/ *subject,
2369   NSSCertificate *rvOpt[],
2370   PRUint32 maximumOpt, /* 0 for no max */
2371   NSSArena *arenaOpt
2372 );
2373
2374 /*
2375  * NSSCryptoContext_FindBestCertificateByNameComponents
2376  *
2377  * This call does try several tricks, including a pseudo pkcs#11
2378  * attribute for the ldap module to try as a query.  Eventually
2379  * this call falls back to a traversal if that's what's required.
2380  * It will search through alternate names hidden in extensions.
2381  */
2382
2383 NSS_EXTERN NSSCertificate *
2384 NSSCryptoContext_FindBestCertificateByNameComponents
2385 (
2386   NSSCryptoContext *cc,
2387   NSSUTF8 *nameComponents,
2388   NSSTime *timeOpt,
2389   NSSUsage *usage,
2390   NSSPolicies *policiesOpt
2391 );
2392
2393 /*
2394  * NSSCryptoContext_FindCertificatesByNameComponents
2395  *
2396  * This call, too, tries several tricks.  It will stop on the first
2397  * attempt that generates results, so it won't e.g. traverse the
2398  * entire ldap database.
2399  */
2400
2401 NSS_EXTERN NSSCertificate **
2402 NSSCryptoContext_FindCertificatesByNameComponents
2403 (
2404   NSSCryptoContext *cc,
2405   NSSUTF8 *nameComponents,
2406   NSSCertificate *rvOpt[],
2407   PRUint32 maximumOpt, /* 0 for no max */
2408   NSSArena *arenaOpt
2409 );
2410
2411 /*
2412  * NSSCryptoContext_FindCertificateByEncodedCertificate
2413  *
2414  */
2415
2416 NSS_EXTERN NSSCertificate *
2417 NSSCryptoContext_FindCertificateByEncodedCertificate
2418 (
2419   NSSCryptoContext *cc,
2420   NSSBER *encodedCertificate
2421 );
2422
2423 /*
2424  * NSSCryptoContext_FindBestCertificateByEmail
2425  *
2426  */
2427
2428 NSS_EXTERN NSSCertificate *
2429 NSSCryptoContext_FindBestCertificateByEmail
2430 (
2431   NSSCryptoContext *cc,
2432   NSSASCII7 *email,
2433   NSSTime *timeOpt,
2434   NSSUsage *usage,
2435   NSSPolicies *policiesOpt
2436 );
2437
2438 /*
2439  * NSSCryptoContext_FindCertificatesByEmail
2440  *
2441  */
2442
2443 NSS_EXTERN NSSCertificate **
2444 NSSCryptoContext_FindCertificatesByEmail
2445 (
2446   NSSCryptoContext *cc,
2447   NSSASCII7 *email,
2448   NSSCertificate *rvOpt[],
2449   PRUint32 maximumOpt, /* 0 for no max */
2450   NSSArena *arenaOpt
2451 );
2452
2453 /*
2454  * NSSCryptoContext_FindCertificateByOCSPHash
2455  *
2456  */
2457
2458 NSS_EXTERN NSSCertificate *
2459 NSSCryptoContext_FindCertificateByOCSPHash
2460 (
2461   NSSCryptoContext *cc,
2462   NSSItem *hash
2463 );
2464
2465 /*
2466  * NSSCryptoContext_TraverseCertificates
2467  *
2468  *
2469  * NSS_EXTERN PRStatus *
2470  * NSSCryptoContext_TraverseCertificates
2471  * (
2472  *   NSSCryptoContext *cc,
2473  *   PRStatus (*callback)(NSSCertificate *c, void *arg),
2474  *   void *arg
2475  * );
2476  */
2477
2478 /*
2479  * NSSCryptoContext_FindBestUserCertificate
2480  *
2481  */
2482
2483 NSS_EXTERN NSSCertificate *
2484 NSSCryptoContext_FindBestUserCertificate
2485 (
2486   NSSCryptoContext *cc,
2487   NSSTime *timeOpt,
2488   NSSUsage *usage,
2489   NSSPolicies *policiesOpt
2490 );
2491
2492 /*
2493  * NSSCryptoContext_FindUserCertificates
2494  *
2495  */
2496
2497 NSS_EXTERN NSSCertificate **
2498 NSSCryptoContext_FindUserCertificates
2499 (
2500   NSSCryptoContext *cc,
2501   NSSTime *timeOpt,
2502   NSSUsage *usageOpt,
2503   NSSPolicies *policiesOpt,
2504   NSSCertificate **rvOpt,
2505   PRUint32 rvLimit, /* zero for no limit */
2506   NSSArena *arenaOpt
2507 );
2508
2509 /*
2510  * NSSCryptoContext_FindBestUserCertificateForSSLClientAuth
2511  *
2512  */
2513
2514 NSS_EXTERN NSSCertificate *
2515 NSSCryptoContext_FindBestUserCertificateForSSLClientAuth
2516 (
2517   NSSCryptoContext *cc,
2518   NSSUTF8 *sslHostOpt,
2519   NSSDER *rootCAsOpt[], /* null pointer for none */
2520   PRUint32 rootCAsMaxOpt, /* zero means list is null-terminated */
2521   NSSAlgorithmAndParameters *apOpt,
2522   NSSPolicies *policiesOpt
2523 );
2524
2525 /*
2526  * NSSCryptoContext_FindUserCertificatesForSSLClientAuth
2527  *
2528  */
2529
2530 NSS_EXTERN NSSCertificate **
2531 NSSCryptoContext_FindUserCertificatesForSSLClientAuth
2532 (
2533   NSSCryptoContext *cc,
2534   NSSUTF8 *sslHostOpt,
2535   NSSDER *rootCAsOpt[], /* null pointer for none */
2536   PRUint32 rootCAsMaxOpt, /* zero means list is null-terminated */
2537   NSSAlgorithmAndParameters *apOpt,
2538   NSSPolicies *policiesOpt,
2539   NSSCertificate **rvOpt,
2540   PRUint32 rvLimit, /* zero for no limit */
2541   NSSArena *arenaOpt
2542 );
2543
2544 /*
2545  * NSSCryptoContext_FindBestUserCertificateForEmailSigning
2546  *
2547  */
2548
2549 NSS_EXTERN NSSCertificate *
2550 NSSCryptoContext_FindBestUserCertificateForEmailSigning
2551 (
2552   NSSCryptoContext *cc,
2553   NSSASCII7 *signerOpt,
2554   NSSASCII7 *recipientOpt,
2555   /* anything more here? */
2556   NSSAlgorithmAndParameters *apOpt,
2557   NSSPolicies *policiesOpt
2558 );
2559
2560 /*
2561  * NSSCryptoContext_FindUserCertificatesForEmailSigning
2562  *
2563  */
2564
2565 NSS_EXTERN NSSCertificate *
2566 NSSCryptoContext_FindUserCertificatesForEmailSigning
2567 (
2568   NSSCryptoContext *cc,
2569   NSSASCII7 *signerOpt, /* fgmr or a more general name? */
2570   NSSASCII7 *recipientOpt,
2571   /* anything more here? */
2572   NSSAlgorithmAndParameters *apOpt,
2573   NSSPolicies *policiesOpt,
2574   NSSCertificate **rvOpt,
2575   PRUint32 rvLimit, /* zero for no limit */
2576   NSSArena *arenaOpt
2577 );
2578
2579 /* Private Keys */
2580
2581 /*
2582  * NSSCryptoContext_GenerateKeyPair
2583  *
2584  * Creates session objects.  If you want persistant objects, use
2585  * NSSTrustDomain_GenerateKeyPair.  The destination token is where
2586  * the keys are stored.  If that token can do the required math, then
2587  * that's where the keys are generated too.  Otherwise, the keys are
2588  * generated elsewhere and moved to that token.
2589  */
2590
2591 NSS_EXTERN PRStatus
2592 NSSCryptoContext_GenerateKeyPair
2593 (
2594   NSSCryptoContext *cc,
2595   NSSAlgorithmAndParameters *ap,
2596   NSSPrivateKey **pvkOpt,
2597   NSSPublicKey **pbkOpt,
2598   PRBool privateKeyIsSensitive,
2599   NSSToken *destination,
2600   NSSCallback *uhhOpt
2601 );
2602
2603 /*
2604  * NSSCryptoContext_TraversePrivateKeys
2605  *
2606  *
2607  * NSS_EXTERN PRStatus *
2608  * NSSCryptoContext_TraversePrivateKeys
2609  * (
2610  *   NSSCryptoContext *cc,
2611  *   PRStatus (*callback)(NSSPrivateKey *vk, void *arg),
2612  *   void *arg
2613  * );
2614  */
2615
2616 /* Symmetric Keys */
2617
2618 /*
2619  * NSSCryptoContext_GenerateSymmetricKey
2620  *
2621  */
2622
2623 NSS_EXTERN NSSSymmetricKey *
2624 NSSCryptoContext_GenerateSymmetricKey
2625 (
2626   NSSCryptoContext *cc,
2627   NSSAlgorithmAndParameters *ap,
2628   PRUint32 keysize,
2629   NSSToken *destination,
2630   NSSCallback *uhhOpt
2631 );
2632
2633 /*
2634  * NSSCryptoContext_GenerateSymmetricKeyFromPassword
2635  *
2636  */
2637
2638 NSS_EXTERN NSSSymmetricKey *
2639 NSSCryptoContext_GenerateSymmetricKeyFromPassword
2640 (
2641   NSSCryptoContext *cc,
2642   NSSAlgorithmAndParameters *ap,
2643   NSSUTF8 *passwordOpt, /* if null, prompt */
2644   NSSToken *destinationOpt,
2645   NSSCallback *uhhOpt
2646 );
2647
2648 /*
2649  * NSSCryptoContext_FindSymmetricKeyByAlgorithm
2650  *
2651  *
2652  * NSS_EXTERN NSSSymmetricKey *
2653  * NSSCryptoContext_FindSymmetricKeyByType
2654  * (
2655  *   NSSCryptoContext *cc,
2656  *   NSSOID *type,
2657  *   NSSCallback *uhhOpt
2658  * );
2659  */
2660
2661 /*
2662  * NSSCryptoContext_FindSymmetricKeyByAlgorithmAndKeyID
2663  *
2664  */
2665
2666 NSS_EXTERN NSSSymmetricKey *
2667 NSSCryptoContext_FindSymmetricKeyByAlgorithmAndKeyID
2668 (
2669   NSSCryptoContext *cc,
2670   NSSOID *algorithm,
2671   NSSItem *keyID,
2672   NSSCallback *uhhOpt
2673 );
2674
2675 /*
2676  * NSSCryptoContext_TraverseSymmetricKeys
2677  *
2678  *
2679  * NSS_EXTERN PRStatus *
2680  * NSSCryptoContext_TraverseSymmetricKeys
2681  * (
2682  *   NSSCryptoContext *cc,
2683  *   PRStatus (*callback)(NSSSymmetricKey *mk, void *arg),
2684  *   void *arg
2685  * );
2686  */
2687
2688 /* Crypto ops on distinguished keys */
2689
2690 /*
2691  * NSSCryptoContext_Decrypt
2692  *
2693  */
2694
2695 NSS_EXTERN NSSItem *
2696 NSSCryptoContext_Decrypt
2697 (
2698   NSSCryptoContext *cc,
2699   NSSAlgorithmAndParameters *apOpt,
2700   NSSItem *encryptedData,
2701   NSSCallback *uhhOpt,
2702   NSSItem *rvOpt,
2703   NSSArena *arenaOpt
2704 );
2705
2706 /*
2707  * NSSCryptoContext_BeginDecrypt
2708  *
2709  */
2710
2711 NSS_EXTERN PRStatus
2712 NSSCryptoContext_BeginDecrypt
2713 (
2714   NSSCryptoContext *cc,
2715   NSSAlgorithmAndParameters *apOpt,
2716   NSSCallback *uhhOpt
2717 );
2718
2719 /*
2720  * NSSCryptoContext_ContinueDecrypt
2721  *
2722  */
2723
2724 /*
2725  * NSSItem semantics:
2726  *
2727  *   If rvOpt is NULL, a new NSSItem and buffer are allocated.
2728  *   If rvOpt is not null, but the buffer pointer is null,
2729  *     then rvOpt is returned but a new buffer is allocated.
2730  *     In this case, if the length value is not zero, then
2731  *     no more than that much space will be allocated.
2732  *   If rvOpt is not null and the buffer pointer is not null,
2733  *     then that buffer is re-used.  No more than the buffer
2734  *     length value will be used; if it's not enough, an
2735  *     error is returned.  If less is used, the number is
2736  *     adjusted downwards.
2737  *
2738  *  Note that although this is short of some ideal "Item"
2739  *  definition, we can usually tell how big these buffers
2740  *  have to be.
2741  *
2742  *  Feedback is requested; and earlier is better than later.
2743  */
2744
2745 NSS_EXTERN NSSItem *
2746 NSSCryptoContext_ContinueDecrypt
2747 (
2748   NSSCryptoContext *cc,
2749   NSSItem *data,
2750   NSSItem *rvOpt,
2751   NSSArena *arenaOpt
2752 );
2753
2754 /*
2755  * NSSCryptoContext_FinishDecrypt
2756  *
2757  */
2758
2759 NSS_EXTERN NSSItem *
2760 NSSCryptoContext_FinishDecrypt
2761 (
2762   NSSCryptoContext *cc,
2763   NSSItem *rvOpt,
2764   NSSArena *arenaOpt
2765 );
2766
2767 /*
2768  * NSSCryptoContext_Sign
2769  *
2770  */
2771
2772 NSS_EXTERN NSSItem *
2773 NSSCryptoContext_Sign
2774 (
2775   NSSCryptoContext *cc,
2776   NSSAlgorithmAndParameters *apOpt,
2777   NSSItem *data,
2778   NSSCallback *uhhOpt,
2779   NSSItem *rvOpt,
2780   NSSArena *arenaOpt
2781 );
2782
2783 /*
2784  * NSSCryptoContext_BeginSign
2785  *
2786  */
2787
2788 NSS_EXTERN PRStatus
2789 NSSCryptoContext_BeginSign
2790 (
2791   NSSCryptoContext *cc,
2792   NSSAlgorithmAndParameters *apOpt,
2793   NSSCallback *uhhOpt
2794 );
2795
2796 /*
2797  * NSSCryptoContext_ContinueSign
2798  *
2799  */
2800
2801 NSS_EXTERN PRStatus
2802 NSSCryptoContext_ContinueSign
2803 (
2804   NSSCryptoContext *cc,
2805   NSSItem *data
2806 );
2807
2808 /*
2809  * NSSCryptoContext_FinishSign
2810  *
2811  */
2812
2813 NSS_EXTERN NSSItem *
2814 NSSCryptoContext_FinishSign
2815 (
2816   NSSCryptoContext *cc,
2817   NSSItem *rvOpt,
2818   NSSArena *arenaOpt
2819 );
2820
2821 /*
2822  * NSSCryptoContext_SignRecover
2823  *
2824  */
2825
2826 NSS_EXTERN NSSItem *
2827 NSSCryptoContext_SignRecover
2828 (
2829   NSSCryptoContext *cc,
2830   NSSAlgorithmAndParameters *apOpt,
2831   NSSItem *data,
2832   NSSCallback *uhhOpt,
2833   NSSItem *rvOpt,
2834   NSSArena *arenaOpt
2835 );
2836
2837 /*
2838  * NSSCryptoContext_BeginSignRecover
2839  *
2840  */
2841
2842 NSS_EXTERN PRStatus
2843 NSSCryptoContext_BeginSignRecover
2844 (
2845   NSSCryptoContext *cc,
2846   NSSAlgorithmAndParameters *apOpt,
2847   NSSCallback *uhhOpt
2848 );
2849
2850 /*
2851  * NSSCryptoContext_ContinueSignRecover
2852  *
2853  */
2854
2855 NSS_EXTERN NSSItem *
2856 NSSCryptoContext_ContinueSignRecover
2857 (
2858   NSSCryptoContext *cc,
2859   NSSItem *data,
2860   NSSItem *rvOpt,
2861   NSSArena *arenaOpt
2862 );
2863
2864 /*
2865  * NSSCryptoContext_FinishSignRecover
2866  *
2867  */
2868
2869 NSS_EXTERN NSSItem *
2870 NSSCryptoContext_FinishSignRecover
2871 (
2872   NSSCryptoContext *cc,
2873   NSSItem *rvOpt,
2874   NSSArena *arenaOpt
2875 );
2876
2877 /*
2878  * NSSCryptoContext_UnwrapSymmetricKey
2879  *
2880  */
2881
2882 NSS_EXTERN NSSSymmetricKey *
2883 NSSCryptoContext_UnwrapSymmetricKey
2884 (
2885   NSSCryptoContext *cc,
2886   NSSAlgorithmAndParameters *apOpt,
2887   NSSItem *wrappedKey,
2888   NSSCallback *uhhOpt
2889 );
2890
2891 /*
2892  * NSSCryptoContext_DeriveSymmetricKey
2893  *
2894  */
2895
2896 NSS_EXTERN NSSSymmetricKey *
2897 NSSCryptoContext_DeriveSymmetricKey
2898 (
2899   NSSCryptoContext *cc,
2900   NSSPublicKey *bk,
2901   NSSAlgorithmAndParameters *apOpt,
2902   NSSOID *target,
2903   PRUint32 keySizeOpt, /* zero for best allowed */
2904   NSSOperations operations,
2905   NSSCallback *uhhOpt
2906 );
2907
2908 /*
2909  * NSSCryptoContext_Encrypt
2910  *
2911  * Encrypt a single chunk of data with the distinguished public key
2912  * of this crypto context.
2913  */
2914
2915 NSS_EXTERN NSSItem *
2916 NSSCryptoContext_Encrypt
2917 (
2918   NSSCryptoContext *cc,
2919   NSSAlgorithmAndParameters *apOpt,
2920   NSSItem *data,
2921   NSSCallback *uhhOpt,
2922   NSSItem *rvOpt,
2923   NSSArena *arenaOpt
2924 );
2925
2926 /*
2927  * NSSCryptoContext_BeginEncrypt
2928  *
2929  */
2930
2931 NSS_EXTERN PRStatus
2932 NSSCryptoContext_BeginEncrypt
2933 (
2934   NSSCryptoContext *cc,
2935   NSSAlgorithmAndParameters *apOpt,
2936   NSSCallback *uhhOpt
2937 );
2938
2939 /*
2940  * NSSCryptoContext_ContinueEncrypt
2941  *
2942  */
2943
2944 NSS_EXTERN NSSItem *
2945 NSSCryptoContext_ContinueEncrypt
2946 (
2947   NSSCryptoContext *cc,
2948   NSSItem *data,
2949   NSSItem *rvOpt,
2950   NSSArena *arenaOpt
2951 );
2952
2953 /*
2954  * NSSCryptoContext_FinishEncrypt
2955  *
2956  */
2957
2958 NSS_EXTERN NSSItem *
2959 NSSCryptoContext_FinishEncrypt
2960 (
2961   NSSCryptoContext *cc,
2962   NSSItem *rvOpt,
2963   NSSArena *arenaOpt
2964 );
2965
2966 /*
2967  * NSSCryptoContext_Verify
2968  *
2969  */
2970
2971 NSS_EXTERN PRStatus
2972 NSSCryptoContext_Verify
2973 (
2974   NSSCryptoContext *cc,
2975   NSSAlgorithmAndParameters *apOpt,
2976   NSSItem *data,
2977   NSSItem *signature,
2978   NSSCallback *uhhOpt
2979 );
2980
2981 /*
2982  * NSSCryptoContext_BeginVerify
2983  *
2984  */
2985
2986 NSS_EXTERN PRStatus
2987 NSSCryptoContext_BeginVerify
2988 (
2989   NSSCryptoContext *cc,
2990   NSSAlgorithmAndParameters *apOpt,
2991   NSSItem *signature,
2992   NSSCallback *uhhOpt
2993 );
2994
2995 /*
2996  * NSSCryptoContext_ContinueVerify
2997  *
2998  */
2999
3000 NSS_EXTERN PRStatus
3001 NSSCryptoContext_ContinueVerify
3002 (
3003   NSSCryptoContext *cc,
3004   NSSItem *data
3005 );
3006
3007 /*
3008  * NSSCryptoContext_FinishVerify
3009  *
3010  */
3011
3012 NSS_EXTERN PRStatus
3013 NSSCryptoContext_FinishVerify
3014 (
3015   NSSCryptoContext *cc
3016 );
3017
3018 /*
3019  * NSSCryptoContext_VerifyRecover
3020  *
3021  */
3022
3023 NSS_EXTERN NSSItem *
3024 NSSCryptoContext_VerifyRecover
3025 (
3026   NSSCryptoContext *cc,
3027   NSSAlgorithmAndParameters *apOpt,
3028   NSSItem *signature,
3029   NSSCallback *uhhOpt,
3030   NSSItem *rvOpt,
3031   NSSArena *arenaOpt
3032 );
3033
3034 /*
3035  * NSSCryptoContext_BeginVerifyRecover
3036  *
3037  */
3038
3039 NSS_EXTERN PRStatus
3040 NSSCryptoContext_BeginVerifyRecover
3041 (
3042   NSSCryptoContext *cc,
3043   NSSAlgorithmAndParameters *apOpt,
3044   NSSCallback *uhhOpt
3045 );
3046
3047 /*
3048  * NSSCryptoContext_ContinueVerifyRecover
3049  *
3050  */
3051
3052 NSS_EXTERN NSSItem *
3053 NSSCryptoContext_ContinueVerifyRecover
3054 (
3055   NSSCryptoContext *cc,
3056   NSSItem *data,
3057   NSSItem *rvOpt,
3058   NSSArena *arenaOpt
3059 );
3060
3061 /*
3062  * NSSCryptoContext_FinishVerifyRecover
3063  *
3064  */
3065
3066 NSS_EXTERN NSSItem *
3067 NSSCryptoContext_FinishVerifyRecover
3068 (
3069   NSSCryptoContext *cc,
3070   NSSItem *rvOpt,
3071   NSSArena *arenaOpt
3072 );
3073
3074 /*
3075  * NSSCryptoContext_WrapSymmetricKey
3076  *
3077  */
3078
3079 NSS_EXTERN NSSItem *
3080 NSSCryptoContext_WrapSymmetricKey
3081 (
3082   NSSCryptoContext *cc,
3083   NSSAlgorithmAndParameters *apOpt,
3084   NSSSymmetricKey *keyToWrap,
3085   NSSCallback *uhhOpt,
3086   NSSItem *rvOpt,
3087   NSSArena *arenaOpt
3088 );
3089
3090 /*
3091  * NSSCryptoContext_Digest
3092  *
3093  * Digest a single chunk of data with the distinguished digest key
3094  * of this crypto context.
3095  */
3096
3097 NSS_EXTERN NSSItem *
3098 NSSCryptoContext_Digest
3099 (
3100   NSSCryptoContext *cc,
3101   NSSAlgorithmAndParameters *apOpt,
3102   NSSItem *data,
3103   NSSCallback *uhhOpt,
3104   NSSItem *rvOpt,
3105   NSSArena *arenaOpt
3106 );
3107
3108 /*
3109  * NSSCryptoContext_BeginDigest
3110  *
3111  */
3112
3113 NSS_EXTERN PRStatus
3114 NSSCryptoContext_BeginDigest
3115 (
3116   NSSCryptoContext *cc,
3117   NSSAlgorithmAndParameters *apOpt,
3118   NSSCallback *uhhOpt
3119 );
3120
3121 /*
3122  * NSSCryptoContext_ContinueDigest
3123  *
3124  */
3125
3126 NSS_EXTERN PRStatus
3127 NSSCryptoContext_ContinueDigest
3128 (
3129   NSSCryptoContext *cc,
3130   NSSAlgorithmAndParameters *apOpt,
3131   NSSItem *item
3132 );
3133
3134 /*
3135  * NSSCryptoContext_FinishDigest
3136  *
3137  */
3138
3139 NSS_EXTERN NSSItem *
3140 NSSCryptoContext_FinishDigest
3141 (
3142   NSSCryptoContext *cc,
3143   NSSItem *rvOpt,
3144   NSSArena *arenaOpt
3145 );
3146
3147 /*
3148  * tbd: Combination ops
3149  */
3150
3151 /*
3152  * NSSCryptoContext_Clone
3153  *
3154  */
3155
3156 NSS_EXTERN NSSCryptoContext *
3157 NSSCryptoContext_Clone
3158 (
3159   NSSCryptoContext *cc
3160 );
3161
3162 /*
3163  * NSSCryptoContext_Save
3164  * NSSCryptoContext_Restore
3165  *
3166  * We need to be able to save and restore the state of contexts.
3167  * Perhaps a mark-and-release mechanism would be better?
3168  */
3169
3170 /*
3171  * ..._SignTBSCertificate
3172  *
3173  * This requires feedback from the cert server team.
3174  */
3175
3176 /*
3177  * PRBool NSSCertificate_GetIsTrustedFor{xxx}(NSSCertificate *c);
3178  * PRStatus NSSCertificate_SetIsTrustedFor{xxx}(NSSCertificate *c, PRBool trusted);
3179  *
3180  * These will be helper functions which get the trust object for a cert,
3181  * and then call the corresponding function(s) on it.
3182  *
3183  * PKIX trust objects will have methods to manipulate the low-level trust
3184  * bits (which are based on key usage and extended key usage), and also the
3185  * conceptual high-level usages (e.g. ssl client auth, email encryption, etc.)
3186  *
3187  * Other types of trust objects (if any) might have different low-level
3188  * representations, but hopefully high-level concepts would map.
3189  *
3190  * Only these high-level general routines would be promoted to the
3191  * general certificate level here.  Hence the {xxx} above would be things
3192  * like "EmailSigning."
3193  *
3194  *
3195  * NSSPKIXTrust *NSSCertificate_GetPKIXTrustObject(NSSCertificate *c);
3196  * PRStatus NSSCertificate_SetPKIXTrustObject(NSSCertificate *c, NSPKIXTrust *t);
3197  *
3198  * I want to hold off on any general trust object until we've investigated
3199  * other models more thoroughly.
3200  */
3201
3202 PR_END_EXTERN_C
3203
3204 #endif /* NSSPKI_H */