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