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