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