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 DEV_H 6 #define DEV_H 7 8 /* 9 * dev.h 10 * 11 * Low-level methods for interaction with cryptoki devices 12 */ 13 14 #ifndef NSSDEV_H 15 #include "nssdev.h" 16 #endif /* NSSDEV_H */ 17 18 #ifndef DEVT_H 19 #include "devt.h" 20 #endif /* DEVT_H */ 21 22 PR_BEGIN_EXTERN_C 23 24 /* the global module list 25 * 26 * These functions are for managing the global set of modules. Trust Domains, 27 * etc., will draw from this set. These functions are completely internal 28 * and only invoked when there are changes to the global module state 29 * (load or unload). 30 * 31 * nss_InitializeGlobalModuleList 32 * nss_DestroyGlobalModuleList 33 * nss_GetLoadedModules 34 * 35 * nssGlobalModuleList_Add 36 * nssGlobalModuleList_Remove 37 * nssGlobalModuleList_FindModuleByName 38 * nssGlobalModuleList_FindSlotByName 39 * nssGlobalModuleList_FindTokenByName 40 */ 41 42 NSS_EXTERN PRStatus 43 nss_InitializeGlobalModuleList( 44 void); 45 46 NSS_EXTERN PRStatus 47 nss_DestroyGlobalModuleList( 48 void); 49 50 NSS_EXTERN NSSModule ** 51 nss_GetLoadedModules( 52 void); 53 54 NSS_EXTERN PRStatus 55 nssGlobalModuleList_Add( 56 NSSModule *module); 57 58 NSS_EXTERN PRStatus 59 nssGlobalModuleList_Remove( 60 NSSModule *module); 61 62 NSS_EXTERN NSSModule * 63 nssGlobalModuleList_FindModuleByName( 64 NSSUTF8 *moduleName); 65 66 NSS_EXTERN NSSSlot * 67 nssGlobalModuleList_FindSlotByName( 68 NSSUTF8 *slotName); 69 70 NSS_EXTERN NSSToken * 71 nssGlobalModuleList_FindTokenByName( 72 NSSUTF8 *tokenName); 73 74 NSS_EXTERN NSSToken * 75 nss_GetDefaultCryptoToken( 76 void); 77 78 NSS_EXTERN NSSToken * 79 nss_GetDefaultDatabaseToken( 80 void); 81 82 /* 83 * |-----------|<---> NSSSlot <--> NSSToken 84 * | NSSModule |<---> NSSSlot <--> NSSToken 85 * |-----------|<---> NSSSlot <--> NSSToken 86 */ 87 88 /* NSSModule 89 * 90 * nssModule_Create 91 * nssModule_CreateFromSpec 92 * nssModule_AddRef 93 * nssModule_GetName 94 * nssModule_GetSlots 95 * nssModule_FindSlotByName 96 * nssModule_FindTokenByName 97 * nssModule_GetCertOrder 98 */ 99 100 NSS_EXTERN NSSModule * 101 nssModule_Create( 102 NSSUTF8 *moduleOpt, 103 NSSUTF8 *uriOpt, 104 NSSUTF8 *opaqueOpt, 105 void *reserved); 106 107 /* This is to use the new loading mechanism. */ 108 NSS_EXTERN NSSModule * 109 nssModule_CreateFromSpec( 110 NSSUTF8 *moduleSpec, 111 NSSModule *parent, 112 PRBool loadSubModules); 113 114 NSS_EXTERN PRStatus 115 nssModule_Destroy( 116 NSSModule *mod); 117 118 NSS_EXTERN NSSModule * 119 nssModule_AddRef( 120 NSSModule *mod); 121 122 NSS_EXTERN NSSUTF8 * 123 nssModule_GetName( 124 NSSModule *mod); 125 126 NSS_EXTERN NSSSlot ** 127 nssModule_GetSlots( 128 NSSModule *mod); 129 130 NSS_EXTERN NSSSlot * 131 nssModule_FindSlotByName( 132 NSSModule *mod, 133 NSSUTF8 *slotName); 134 135 NSS_EXTERN NSSToken * 136 nssModule_FindTokenByName( 137 NSSModule *mod, 138 NSSUTF8 *tokenName); 139 140 NSS_EXTERN PRInt32 141 nssModule_GetCertOrder( 142 NSSModule *module); 143 144 /* NSSSlot 145 * 146 * nssSlot_Destroy 147 * nssSlot_AddRef 148 * nssSlot_GetName 149 * nssSlot_GetTokenName 150 * nssSlot_IsTokenPresent 151 * nssSlot_IsPermanent 152 * nssSlot_IsFriendly 153 * nssSlot_IsHardware 154 * nssSlot_Refresh 155 * nssSlot_GetModule 156 * nssSlot_GetToken 157 * nssSlot_Login 158 * nssSlot_Logout 159 * nssSlot_SetPassword 160 * nssSlot_CreateSession 161 */ 162 163 NSS_EXTERN PRStatus 164 nssSlot_Destroy( 165 NSSSlot *slot); 166 167 NSS_EXTERN NSSSlot * 168 nssSlot_AddRef( 169 NSSSlot *slot); 170 171 NSS_EXTERN void 172 nssSlot_ResetDelay( 173 NSSSlot *slot); 174 175 NSS_EXTERN NSSUTF8 * 176 nssSlot_GetName( 177 NSSSlot *slot); 178 179 NSS_EXTERN NSSUTF8 * 180 nssSlot_GetTokenName( 181 NSSSlot *slot); 182 183 NSS_EXTERN NSSModule * 184 nssSlot_GetModule( 185 NSSSlot *slot); 186 187 NSS_EXTERN NSSToken * 188 nssSlot_GetToken( 189 NSSSlot *slot); 190 191 NSS_EXTERN PRBool 192 nssSlot_IsTokenPresent( 193 NSSSlot *slot); 194 195 NSS_EXTERN PRBool 196 nssSlot_IsPermanent( 197 NSSSlot *slot); 198 199 NSS_EXTERN PRBool 200 nssSlot_IsFriendly( 201 NSSSlot *slot); 202 203 NSS_EXTERN PRBool 204 nssSlot_IsHardware( 205 NSSSlot *slot); 206 207 NSS_EXTERN PRBool 208 nssSlot_IsLoggedIn( 209 NSSSlot *slot); 210 211 NSS_EXTERN PRStatus 212 nssSlot_Refresh( 213 NSSSlot *slot); 214 215 NSS_EXTERN PRStatus 216 nssSlot_Login( 217 NSSSlot *slot, 218 NSSCallback *pwcb); 219 extern const NSSError NSS_ERROR_INVALID_PASSWORD; 220 extern const NSSError NSS_ERROR_USER_CANCELED; 221 222 NSS_EXTERN PRStatus 223 nssSlot_Logout( 224 NSSSlot *slot, 225 nssSession *sessionOpt); 226 227 NSS_EXTERN void 228 nssSlot_EnterMonitor( 229 NSSSlot *slot); 230 231 NSS_EXTERN void 232 nssSlot_ExitMonitor( 233 NSSSlot *slot); 234 235 #define NSSSLOT_ASK_PASSWORD_FIRST_TIME -1 236 #define NSSSLOT_ASK_PASSWORD_EVERY_TIME 0 237 NSS_EXTERN void 238 nssSlot_SetPasswordDefaults( 239 NSSSlot *slot, 240 PRInt32 askPasswordTimeout); 241 242 NSS_EXTERN PRStatus 243 nssSlot_SetPassword( 244 NSSSlot *slot, 245 NSSUTF8 *oldPasswordOpt, 246 NSSUTF8 *newPassword); 247 extern const NSSError NSS_ERROR_INVALID_PASSWORD; 248 extern const NSSError NSS_ERROR_USER_CANCELED; 249 250 /* 251 * nssSlot_IsLoggedIn 252 */ 253 254 NSS_EXTERN nssSession * 255 nssSlot_CreateSession( 256 NSSSlot *slot, 257 NSSArena *arenaOpt, 258 PRBool readWrite /* so far, this is the only flag used */ 259 ); 260 261 /* NSSToken 262 * 263 * nssToken_Destroy 264 * nssToken_AddRef 265 * nssToken_GetName 266 * nssToken_GetModule 267 * nssToken_GetSlot 268 * nssToken_NeedsPINInitialization 269 * nssToken_ImportCertificate 270 * nssToken_ImportTrust 271 * nssToken_ImportCRL 272 * nssToken_GenerateKeyPair 273 * nssToken_GenerateSymmetricKey 274 * nssToken_DeleteStoredObject 275 * nssToken_FindObjects 276 * nssToken_FindCertificatesBySubject 277 * nssToken_FindCertificatesByNickname 278 * nssToken_FindCertificatesByEmail 279 * nssToken_FindCertificateByIssuerAndSerialNumber 280 * nssToken_FindCertificateByEncodedCertificate 281 * nssToken_FindTrustForCertificate 282 * nssToken_FindCRLsBySubject 283 * nssToken_FindPrivateKeys 284 * nssToken_FindPrivateKeyByID 285 * nssToken_Digest 286 * nssToken_BeginDigest 287 * nssToken_ContinueDigest 288 * nssToken_FinishDigest 289 */ 290 291 NSS_EXTERN PRStatus 292 nssToken_Destroy( 293 NSSToken *tok); 294 295 NSS_EXTERN NSSToken * 296 nssToken_AddRef( 297 NSSToken *tok); 298 299 NSS_EXTERN NSSUTF8 * 300 nssToken_GetName( 301 NSSToken *tok); 302 303 NSS_EXTERN NSSModule * 304 nssToken_GetModule( 305 NSSToken *token); 306 307 NSS_EXTERN NSSSlot * 308 nssToken_GetSlot( 309 NSSToken *tok); 310 311 NSS_EXTERN PRBool 312 nssToken_NeedsPINInitialization( 313 NSSToken *token); 314 315 NSS_EXTERN nssCryptokiObject ** 316 nssToken_FindObjectsByTemplate( 317 NSSToken *token, 318 nssSession *sessionOpt, 319 CK_ATTRIBUTE_PTR obj_template, 320 CK_ULONG otsize, 321 PRUint32 maximumOpt, 322 PRStatus *statusOpt); 323 324 NSS_EXTERN nssCryptokiObject * 325 nssToken_ImportCertificate( 326 NSSToken *tok, 327 nssSession *sessionOpt, 328 NSSCertificateType certType, 329 NSSItem *id, 330 const NSSUTF8 *nickname, 331 NSSDER *encoding, 332 NSSDER *issuer, 333 NSSDER *subject, 334 NSSDER *serial, 335 NSSASCII7 *emailAddr, 336 PRBool asTokenObject); 337 338 NSS_EXTERN nssCryptokiObject * 339 nssToken_ImportTrust( 340 NSSToken *tok, 341 nssSession *sessionOpt, 342 NSSDER *certEncoding, 343 NSSDER *certIssuer, 344 NSSDER *certSerial, 345 nssTrustLevel serverAuth, 346 nssTrustLevel clientAuth, 347 nssTrustLevel codeSigning, 348 nssTrustLevel emailProtection, 349 PRBool stepUpApproved, 350 PRBool asTokenObject); 351 352 NSS_EXTERN nssCryptokiObject * 353 nssToken_ImportCRL( 354 NSSToken *token, 355 nssSession *sessionOpt, 356 NSSDER *subject, 357 NSSDER *encoding, 358 PRBool isKRL, 359 NSSUTF8 *url, 360 PRBool asTokenObject); 361 362 /* Permanently remove an object from the token. */ 363 NSS_EXTERN PRStatus 364 nssToken_DeleteStoredObject( 365 nssCryptokiObject *instance); 366 367 NSS_EXTERN nssCryptokiObject ** 368 nssToken_FindObjects( 369 NSSToken *token, 370 nssSession *sessionOpt, 371 CK_OBJECT_CLASS objclass, 372 nssTokenSearchType searchType, 373 PRUint32 maximumOpt, 374 PRStatus *statusOpt); 375 376 NSS_EXTERN nssCryptokiObject ** 377 nssToken_FindCertificatesBySubject( 378 NSSToken *token, 379 nssSession *sessionOpt, 380 NSSDER *subject, 381 nssTokenSearchType searchType, 382 PRUint32 maximumOpt, 383 PRStatus *statusOpt); 384 385 NSS_EXTERN nssCryptokiObject ** 386 nssToken_FindCertificatesByNickname( 387 NSSToken *token, 388 nssSession *sessionOpt, 389 const NSSUTF8 *name, 390 nssTokenSearchType searchType, 391 PRUint32 maximumOpt, 392 PRStatus *statusOpt); 393 394 NSS_EXTERN nssCryptokiObject ** 395 nssToken_FindCertificatesByEmail( 396 NSSToken *token, 397 nssSession *sessionOpt, 398 NSSASCII7 *email, 399 nssTokenSearchType searchType, 400 PRUint32 maximumOpt, 401 PRStatus *statusOpt); 402 403 NSS_EXTERN nssCryptokiObject ** 404 nssToken_FindCertificatesByID( 405 NSSToken *token, 406 nssSession *sessionOpt, 407 NSSItem *id, 408 nssTokenSearchType searchType, 409 PRUint32 maximumOpt, 410 PRStatus *statusOpt); 411 412 NSS_EXTERN nssCryptokiObject * 413 nssToken_FindCertificateByIssuerAndSerialNumber( 414 NSSToken *token, 415 nssSession *sessionOpt, 416 NSSDER *issuer, 417 NSSDER *serial, 418 nssTokenSearchType searchType, 419 PRStatus *statusOpt); 420 421 NSS_EXTERN nssCryptokiObject * 422 nssToken_FindCertificateByEncodedCertificate( 423 NSSToken *token, 424 nssSession *sessionOpt, 425 NSSBER *encodedCertificate, 426 nssTokenSearchType searchType, 427 PRStatus *statusOpt); 428 429 NSS_EXTERN nssCryptokiObject * 430 nssToken_FindTrustForCertificate( 431 NSSToken *token, 432 nssSession *sessionOpt, 433 NSSDER *certEncoding, 434 NSSDER *certIssuer, 435 NSSDER *certSerial, 436 nssTokenSearchType searchType); 437 438 NSS_EXTERN nssCryptokiObject ** 439 nssToken_FindCRLsBySubject( 440 NSSToken *token, 441 nssSession *sessionOpt, 442 NSSDER *subject, 443 nssTokenSearchType searchType, 444 PRUint32 maximumOpt, 445 PRStatus *statusOpt); 446 447 NSS_EXTERN nssCryptokiObject ** 448 nssToken_FindPrivateKeys( 449 NSSToken *token, 450 nssSession *sessionOpt, 451 nssTokenSearchType searchType, 452 PRUint32 maximumOpt, 453 PRStatus *statusOpt); 454 455 NSS_EXTERN nssCryptokiObject * 456 nssToken_FindPrivateKeyByID( 457 NSSToken *token, 458 nssSession *sessionOpt, 459 NSSItem *keyID); 460 461 NSS_EXTERN nssCryptokiObject * 462 nssToken_FindPublicKeyByID( 463 NSSToken *token, 464 nssSession *sessionOpt, 465 NSSItem *keyID); 466 467 NSS_EXTERN NSSItem * 468 nssToken_Digest( 469 NSSToken *tok, 470 nssSession *sessionOpt, 471 NSSAlgorithmAndParameters *ap, 472 NSSItem *data, 473 NSSItem *rvOpt, 474 NSSArena *arenaOpt); 475 476 NSS_EXTERN PRStatus 477 nssToken_BeginDigest( 478 NSSToken *tok, 479 nssSession *sessionOpt, 480 NSSAlgorithmAndParameters *ap); 481 482 NSS_EXTERN PRStatus 483 nssToken_ContinueDigest( 484 NSSToken *tok, 485 nssSession *sessionOpt, 486 NSSItem *item); 487 488 NSS_EXTERN NSSItem * 489 nssToken_FinishDigest( 490 NSSToken *tok, 491 nssSession *sessionOpt, 492 NSSItem *rvOpt, 493 NSSArena *arenaOpt); 494 495 /* nssSession 496 * 497 * nssSession_Destroy 498 * nssSession_EnterMonitor 499 * nssSession_ExitMonitor 500 * nssSession_IsReadWrite 501 */ 502 503 NSS_EXTERN PRStatus 504 nssSession_Destroy( 505 nssSession *s); 506 507 /* would like to inline */ 508 NSS_EXTERN PRStatus 509 nssSession_EnterMonitor( 510 nssSession *s); 511 512 /* would like to inline */ 513 NSS_EXTERN PRStatus 514 nssSession_ExitMonitor( 515 nssSession *s); 516 517 /* would like to inline */ 518 NSS_EXTERN PRBool 519 nssSession_IsReadWrite( 520 nssSession *s); 521 522 /* nssCryptokiObject 523 * 524 * An object living on a cryptoki token. 525 * Not really proper to mix up the object types just because 526 * nssCryptokiObject itself is generic, but doing so anyway. 527 * 528 * nssCryptokiObject_Destroy 529 * nssCryptokiObject_Equal 530 * nssCryptokiObject_Clone 531 * nssCryptokiCertificate_GetAttributes 532 * nssCryptokiPrivateKey_GetAttributes 533 * nssCryptokiPublicKey_GetAttributes 534 * nssCryptokiTrust_GetAttributes 535 * nssCryptokiCRL_GetAttributes 536 */ 537 538 NSS_EXTERN void 539 nssCryptokiObject_Destroy( 540 nssCryptokiObject *object); 541 542 NSS_EXTERN PRBool 543 nssCryptokiObject_Equal( 544 nssCryptokiObject *object1, 545 nssCryptokiObject *object2); 546 547 NSS_EXTERN nssCryptokiObject * 548 nssCryptokiObject_Clone( 549 nssCryptokiObject *object); 550 551 NSS_EXTERN PRStatus 552 nssCryptokiCertificate_GetAttributes( 553 nssCryptokiObject *object, 554 nssSession *sessionOpt, 555 NSSArena *arenaOpt, 556 NSSCertificateType *certTypeOpt, 557 NSSItem *idOpt, 558 NSSDER *encodingOpt, 559 NSSDER *issuerOpt, 560 NSSDER *serialOpt, 561 NSSDER *subjectOpt); 562 563 NSS_EXTERN PRStatus 564 nssCryptokiTrust_GetAttributes( 565 nssCryptokiObject *trustObject, 566 nssSession *sessionOpt, 567 NSSItem *sha1_hash, 568 nssTrustLevel *serverAuth, 569 nssTrustLevel *clientAuth, 570 nssTrustLevel *codeSigning, 571 nssTrustLevel *emailProtection, 572 PRBool *stepUpApproved); 573 574 NSS_EXTERN PRStatus 575 nssCryptokiCRL_GetAttributes( 576 nssCryptokiObject *crlObject, 577 nssSession *sessionOpt, 578 NSSArena *arenaOpt, 579 NSSItem *encodingOpt, 580 NSSItem *subjectOpt, 581 CK_ULONG *crl_class, 582 NSSUTF8 **urlOpt, 583 PRBool *isKRLOpt); 584 585 /* I'm including this to handle import of certificates in NSS 3.5. This 586 * function will set the cert-related attributes of a key, in order to 587 * associate it with a cert. Does it stay like this for 4.0? 588 */ 589 NSS_EXTERN PRStatus 590 nssCryptokiPrivateKey_SetCertificate( 591 nssCryptokiObject *keyObject, 592 nssSession *sessionOpt, 593 const NSSUTF8 *nickname, 594 NSSItem *id, 595 NSSDER *subject); 596 597 NSS_EXTERN void 598 nssModuleArray_Destroy( 599 NSSModule **modules); 600 601 /* nssSlotArray 602 * 603 * nssSlotArray_Destroy 604 */ 605 606 NSS_EXTERN void 607 nssSlotArray_Destroy( 608 NSSSlot **slots); 609 610 /* nssTokenArray 611 * 612 * nssTokenArray_Destroy 613 */ 614 615 NSS_EXTERN void 616 nssTokenArray_Destroy( 617 NSSToken **tokens); 618 619 /* nssCryptokiObjectArray 620 * 621 * nssCryptokiObjectArray_Destroy 622 */ 623 NSS_EXTERN void 624 nssCryptokiObjectArray_Destroy( 625 nssCryptokiObject **object); 626 627 /* nssSlotList 628 * 629 * An ordered list of slots. The order can be anything, it is set in the 630 * Add methods. Perhaps it should be CreateInCertOrder, ...? 631 * 632 * nssSlotList_Create 633 * nssSlotList_Destroy 634 * nssSlotList_Add 635 * nssSlotList_AddModuleSlots 636 * nssSlotList_GetSlots 637 * nssSlotList_FindSlotByName 638 * nssSlotList_FindTokenByName 639 * nssSlotList_GetBestSlot 640 * nssSlotList_GetBestSlotForAlgorithmAndParameters 641 * nssSlotList_GetBestSlotForAlgorithmsAndParameters 642 */ 643 644 /* nssSlotList_Create 645 */ 646 NSS_EXTERN nssSlotList * 647 nssSlotList_Create( 648 NSSArena *arenaOpt); 649 650 /* nssSlotList_Destroy 651 */ 652 NSS_EXTERN void 653 nssSlotList_Destroy( 654 nssSlotList *slotList); 655 656 /* nssSlotList_Add 657 * 658 * Add the given slot in the given order. 659 */ 660 NSS_EXTERN PRStatus 661 nssSlotList_Add( 662 nssSlotList *slotList, 663 NSSSlot *slot, 664 PRUint32 order); 665 666 /* nssSlotList_AddModuleSlots 667 * 668 * Add all slots in the module, in the given order (the slots will have 669 * equal weight). 670 */ 671 NSS_EXTERN PRStatus 672 nssSlotList_AddModuleSlots( 673 nssSlotList *slotList, 674 NSSModule *module, 675 PRUint32 order); 676 677 /* nssSlotList_GetSlots 678 */ 679 NSS_EXTERN NSSSlot ** 680 nssSlotList_GetSlots( 681 nssSlotList *slotList); 682 683 /* nssSlotList_FindSlotByName 684 */ 685 NSS_EXTERN NSSSlot * 686 nssSlotList_FindSlotByName( 687 nssSlotList *slotList, 688 NSSUTF8 *slotName); 689 690 /* nssSlotList_FindTokenByName 691 */ 692 NSS_EXTERN NSSToken * 693 nssSlotList_FindTokenByName( 694 nssSlotList *slotList, 695 NSSUTF8 *tokenName); 696 697 /* nssSlotList_GetBestSlot 698 * 699 * The best slot is the highest ranking in order, i.e., the first in the 700 * list. 701 */ 702 NSS_EXTERN NSSSlot * 703 nssSlotList_GetBestSlot( 704 nssSlotList *slotList); 705 706 /* nssSlotList_GetBestSlotForAlgorithmAndParameters 707 * 708 * Highest-ranking slot than can handle algorithm/parameters. 709 */ 710 NSS_EXTERN NSSSlot * 711 nssSlotList_GetBestSlotForAlgorithmAndParameters( 712 nssSlotList *slotList, 713 NSSAlgorithmAndParameters *ap); 714 715 /* nssSlotList_GetBestSlotForAlgorithmsAndParameters 716 * 717 * Highest-ranking slot than can handle all algorithms/parameters. 718 */ 719 NSS_EXTERN NSSSlot * 720 nssSlotList_GetBestSlotForAlgorithmsAndParameters( 721 nssSlotList *slotList, 722 NSSAlgorithmAndParameters **ap); 723 724 NSS_EXTERN PRBool 725 nssToken_IsPresent( 726 NSSToken *token); 727 728 NSS_EXTERN nssSession * 729 nssToken_GetDefaultSession( 730 NSSToken *token); 731 732 NSS_EXTERN PRStatus 733 nssToken_GetTrustOrder( 734 NSSToken *tok); 735 736 NSS_EXTERN PRStatus 737 nssToken_NotifyCertsNotVisible( 738 NSSToken *tok); 739 740 NSS_EXTERN PRStatus 741 nssToken_TraverseCertificates( 742 NSSToken *token, 743 nssSession *sessionOpt, 744 nssTokenSearchType searchType, 745 PRStatus (*callback)(nssCryptokiObject *instance, void *arg), 746 void *arg); 747 748 NSS_EXTERN PRBool 749 nssToken_IsPrivateKeyAvailable( 750 NSSToken *token, 751 NSSCertificate *c, 752 nssCryptokiObject *instance); 753 754 PR_END_EXTERN_C 755 756 #endif /* DEV_H */ 757