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