security/nss/lib/smime/cms.h@6474c204b198
security/nss/lib/smime/cms.h
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
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 /*
6 * Interfaces of the CMS implementation.
7 */
9 #ifndef _CMS_H_
10 #define _CMS_H_
12 #include "seccomon.h"
14 #include "secoidt.h"
15 #include "certt.h"
16 #include "keyt.h"
17 #include "hasht.h"
18 #include "cmst.h"
20 /************************************************************************/
21 SEC_BEGIN_PROTOS
23 /************************************************************************
24 * cmsdecode.c - CMS decoding
25 ************************************************************************/
27 /*
28 * NSS_CMSDecoder_Start - set up decoding of a DER-encoded CMS message
29 *
30 * "poolp" - pointer to arena for message, or NULL if new pool should be created
31 * "cb", "cb_arg" - callback function and argument for delivery of inner content
32 * inner content will be stored in the message if cb is NULL.
33 * "pwfn", pwfn_arg" - callback function for getting token password
34 * "decrypt_key_cb", "decrypt_key_cb_arg" - callback function for getting bulk key for encryptedData
35 */
36 extern NSSCMSDecoderContext *
37 NSS_CMSDecoder_Start(PLArenaPool *poolp,
38 NSSCMSContentCallback cb, void *cb_arg,
39 PK11PasswordFunc pwfn, void *pwfn_arg,
40 NSSCMSGetDecryptKeyCallback decrypt_key_cb, void *decrypt_key_cb_arg);
42 /*
43 * NSS_CMSDecoder_Update - feed DER-encoded data to decoder
44 */
45 extern SECStatus
46 NSS_CMSDecoder_Update(NSSCMSDecoderContext *p7dcx, const char *buf, unsigned long len);
48 /*
49 * NSS_CMSDecoder_Cancel - cancel a decoding process
50 */
51 extern void
52 NSS_CMSDecoder_Cancel(NSSCMSDecoderContext *p7dcx);
54 /*
55 * NSS_CMSDecoder_Finish - mark the end of inner content and finish decoding
56 */
57 extern NSSCMSMessage *
58 NSS_CMSDecoder_Finish(NSSCMSDecoderContext *p7dcx);
60 /*
61 * NSS_CMSMessage_CreateFromDER - decode a CMS message from DER encoded data
62 */
63 extern NSSCMSMessage *
64 NSS_CMSMessage_CreateFromDER(SECItem *DERmessage,
65 NSSCMSContentCallback cb, void *cb_arg,
66 PK11PasswordFunc pwfn, void *pwfn_arg,
67 NSSCMSGetDecryptKeyCallback decrypt_key_cb, void *decrypt_key_cb_arg);
69 /************************************************************************
70 * cmsencode.c - CMS encoding
71 ************************************************************************/
73 /*
74 * NSS_CMSEncoder_Start - set up encoding of a CMS message
75 *
76 * "cmsg" - message to encode
77 * "outputfn", "outputarg" - callback function for delivery of DER-encoded output
78 * will not be called if NULL.
79 * "dest" - if non-NULL, pointer to SECItem that will hold the DER-encoded output
80 * "destpoolp" - pool to allocate DER-encoded output in
81 * "pwfn", pwfn_arg" - callback function for getting token password
82 * "decrypt_key_cb", "decrypt_key_cb_arg" - callback function for getting bulk key for encryptedData
83 * "detached_digestalgs", "detached_digests" - digests from detached content
84 */
85 extern NSSCMSEncoderContext *
86 NSS_CMSEncoder_Start(NSSCMSMessage *cmsg,
87 NSSCMSContentCallback outputfn, void *outputarg,
88 SECItem *dest, PLArenaPool *destpoolp,
89 PK11PasswordFunc pwfn, void *pwfn_arg,
90 NSSCMSGetDecryptKeyCallback decrypt_key_cb, void *decrypt_key_cb_arg,
91 SECAlgorithmID **detached_digestalgs, SECItem **detached_digests);
93 /*
94 * NSS_CMSEncoder_Update - take content data delivery from the user
95 *
96 * "p7ecx" - encoder context
97 * "data" - content data
98 * "len" - length of content data
99 */
100 extern SECStatus
101 NSS_CMSEncoder_Update(NSSCMSEncoderContext *p7ecx, const char *data, unsigned long len);
103 /*
104 * NSS_CMSEncoder_Cancel - stop all encoding
105 */
106 extern SECStatus
107 NSS_CMSEncoder_Cancel(NSSCMSEncoderContext *p7ecx);
109 /*
110 * NSS_CMSEncoder_Finish - signal the end of data
111 *
112 * we need to walk down the chain of encoders and the finish them from the innermost out
113 */
114 extern SECStatus
115 NSS_CMSEncoder_Finish(NSSCMSEncoderContext *p7ecx);
117 /************************************************************************
118 * cmsmessage.c - CMS message object
119 ************************************************************************/
121 /*
122 * NSS_CMSMessage_Create - create a CMS message object
123 *
124 * "poolp" - arena to allocate memory from, or NULL if new arena should be created
125 */
126 extern NSSCMSMessage *
127 NSS_CMSMessage_Create(PLArenaPool *poolp);
129 /*
130 * NSS_CMSMessage_SetEncodingParams - set up a CMS message object for encoding or decoding
131 *
132 * "cmsg" - message object
133 * "pwfn", pwfn_arg" - callback function for getting token password
134 * "decrypt_key_cb", "decrypt_key_cb_arg" - callback function for getting bulk key for encryptedData
135 * "detached_digestalgs", "detached_digests" - digests from detached content
136 *
137 * used internally.
138 */
139 extern void
140 NSS_CMSMessage_SetEncodingParams(NSSCMSMessage *cmsg,
141 PK11PasswordFunc pwfn, void *pwfn_arg,
142 NSSCMSGetDecryptKeyCallback decrypt_key_cb, void *decrypt_key_cb_arg,
143 SECAlgorithmID **detached_digestalgs, SECItem **detached_digests);
145 /*
146 * NSS_CMSMessage_Destroy - destroy a CMS message and all of its sub-pieces.
147 */
148 extern void
149 NSS_CMSMessage_Destroy(NSSCMSMessage *cmsg);
151 /*
152 * NSS_CMSMessage_Copy - return a copy of the given message.
153 *
154 * The copy may be virtual or may be real -- either way, the result needs
155 * to be passed to NSS_CMSMessage_Destroy later (as does the original).
156 */
157 extern NSSCMSMessage *
158 NSS_CMSMessage_Copy(NSSCMSMessage *cmsg);
160 /*
161 * NSS_CMSMessage_GetArena - return a pointer to the message's arena pool
162 */
163 extern PLArenaPool *
164 NSS_CMSMessage_GetArena(NSSCMSMessage *cmsg);
166 /*
167 * NSS_CMSMessage_GetContentInfo - return a pointer to the top level contentInfo
168 */
169 extern NSSCMSContentInfo *
170 NSS_CMSMessage_GetContentInfo(NSSCMSMessage *cmsg);
172 /*
173 * Return a pointer to the actual content.
174 * In the case of those types which are encrypted, this returns the *plain* content.
175 * In case of nested contentInfos, this descends and retrieves the innermost content.
176 */
177 extern SECItem *
178 NSS_CMSMessage_GetContent(NSSCMSMessage *cmsg);
180 /*
181 * NSS_CMSMessage_ContentLevelCount - count number of levels of CMS content objects in this message
182 *
183 * CMS data content objects do not count.
184 */
185 extern int
186 NSS_CMSMessage_ContentLevelCount(NSSCMSMessage *cmsg);
188 /*
189 * NSS_CMSMessage_ContentLevel - find content level #n
190 *
191 * CMS data content objects do not count.
192 */
193 extern NSSCMSContentInfo *
194 NSS_CMSMessage_ContentLevel(NSSCMSMessage *cmsg, int n);
196 /*
197 * NSS_CMSMessage_ContainsCertsOrCrls - see if message contains certs along the way
198 */
199 extern PRBool
200 NSS_CMSMessage_ContainsCertsOrCrls(NSSCMSMessage *cmsg);
202 /*
203 * NSS_CMSMessage_IsEncrypted - see if message contains a encrypted submessage
204 */
205 extern PRBool
206 NSS_CMSMessage_IsEncrypted(NSSCMSMessage *cmsg);
208 /*
209 * NSS_CMSMessage_IsSigned - see if message contains a signed submessage
210 *
211 * If the CMS message has a SignedData with a signature (not just a SignedData)
212 * return true; false otherwise. This can/should be called before calling
213 * VerifySignature, which will always indicate failure if no signature is
214 * present, but that does not mean there even was a signature!
215 * Note that the content itself can be empty (detached content was sent
216 * another way); it is the presence of the signature that matters.
217 */
218 extern PRBool
219 NSS_CMSMessage_IsSigned(NSSCMSMessage *cmsg);
221 /*
222 * NSS_CMSMessage_IsContentEmpty - see if content is empty
223 *
224 * returns PR_TRUE is innermost content length is < minLen
225 * XXX need the encrypted content length (why?)
226 */
227 extern PRBool
228 NSS_CMSMessage_IsContentEmpty(NSSCMSMessage *cmsg, unsigned int minLen);
230 /************************************************************************
231 * cmscinfo.c - CMS contentInfo methods
232 ************************************************************************/
234 /*
235 * NSS_CMSContentInfo_Destroy - destroy a CMS contentInfo and all of its sub-pieces.
236 */
237 extern void
238 NSS_CMSContentInfo_Destroy(NSSCMSContentInfo *cinfo);
240 /*
241 * NSS_CMSContentInfo_GetChildContentInfo - get content's contentInfo (if it exists)
242 */
243 extern NSSCMSContentInfo *
244 NSS_CMSContentInfo_GetChildContentInfo(NSSCMSContentInfo *cinfo);
246 /*
247 * NSS_CMSContentInfo_SetContent - set cinfo's content type & content to CMS object
248 */
249 extern SECStatus
250 NSS_CMSContentInfo_SetContent(NSSCMSMessage *cmsg, NSSCMSContentInfo *cinfo, SECOidTag type, void *ptr);
252 /*
253 * NSS_CMSContentInfo_SetContent_XXXX - typesafe wrappers for NSS_CMSContentInfo_SetType
254 * set cinfo's content type & content to CMS object
255 */
256 extern SECStatus
257 NSS_CMSContentInfo_SetContent_Data(NSSCMSMessage *cmsg, NSSCMSContentInfo *cinfo, SECItem *data, PRBool detached);
259 extern SECStatus
260 NSS_CMSContentInfo_SetContent_SignedData(NSSCMSMessage *cmsg, NSSCMSContentInfo *cinfo, NSSCMSSignedData *sigd);
262 extern SECStatus
263 NSS_CMSContentInfo_SetContent_EnvelopedData(NSSCMSMessage *cmsg, NSSCMSContentInfo *cinfo, NSSCMSEnvelopedData *envd);
265 extern SECStatus
266 NSS_CMSContentInfo_SetContent_DigestedData(NSSCMSMessage *cmsg, NSSCMSContentInfo *cinfo, NSSCMSDigestedData *digd);
268 extern SECStatus
269 NSS_CMSContentInfo_SetContent_EncryptedData(NSSCMSMessage *cmsg, NSSCMSContentInfo *cinfo, NSSCMSEncryptedData *encd);
271 /*
272 * turn off streaming for this content type.
273 * This could fail with SEC_ERROR_NO_MEMORY in memory constrained conditions.
274 */
275 extern SECStatus
276 NSS_CMSContentInfo_SetDontStream(NSSCMSContentInfo *cinfo, PRBool dontStream);
279 /*
280 * NSS_CMSContentInfo_GetContent - get pointer to inner content
281 *
282 * needs to be casted...
283 */
284 extern void *
285 NSS_CMSContentInfo_GetContent(NSSCMSContentInfo *cinfo);
287 /*
288 * NSS_CMSContentInfo_GetInnerContent - get pointer to innermost content
289 *
290 * this is typically only called by NSS_CMSMessage_GetContent()
291 */
292 extern SECItem *
293 NSS_CMSContentInfo_GetInnerContent(NSSCMSContentInfo *cinfo);
295 /*
296 * NSS_CMSContentInfo_GetContentType{Tag,OID} - find out (saving pointer to lookup result
297 * for future reference) and return the inner content type.
298 */
299 extern SECOidTag
300 NSS_CMSContentInfo_GetContentTypeTag(NSSCMSContentInfo *cinfo);
302 extern SECItem *
303 NSS_CMSContentInfo_GetContentTypeOID(NSSCMSContentInfo *cinfo);
305 /*
306 * NSS_CMSContentInfo_GetContentEncAlgTag - find out (saving pointer to lookup result
307 * for future reference) and return the content encryption algorithm tag.
308 */
309 extern SECOidTag
310 NSS_CMSContentInfo_GetContentEncAlgTag(NSSCMSContentInfo *cinfo);
312 /*
313 * NSS_CMSContentInfo_GetContentEncAlg - find out and return the content encryption algorithm tag.
314 */
315 extern SECAlgorithmID *
316 NSS_CMSContentInfo_GetContentEncAlg(NSSCMSContentInfo *cinfo);
318 extern SECStatus
319 NSS_CMSContentInfo_SetContentEncAlg(PLArenaPool *poolp, NSSCMSContentInfo *cinfo,
320 SECOidTag bulkalgtag, SECItem *parameters, int keysize);
322 extern SECStatus
323 NSS_CMSContentInfo_SetContentEncAlgID(PLArenaPool *poolp, NSSCMSContentInfo *cinfo,
324 SECAlgorithmID *algid, int keysize);
326 extern void
327 NSS_CMSContentInfo_SetBulkKey(NSSCMSContentInfo *cinfo, PK11SymKey *bulkkey);
329 extern PK11SymKey *
330 NSS_CMSContentInfo_GetBulkKey(NSSCMSContentInfo *cinfo);
332 extern int
333 NSS_CMSContentInfo_GetBulkKeySize(NSSCMSContentInfo *cinfo);
335 /************************************************************************
336 * cmsutil.c - CMS misc utility functions
337 ************************************************************************/
339 /*
340 * NSS_CMSArray_SortByDER - sort array of objects by objects' DER encoding
341 *
342 * make sure that the order of the objects guarantees valid DER (which must be
343 * in lexigraphically ascending order for a SET OF); if reordering is necessary it
344 * will be done in place (in objs).
345 */
346 extern SECStatus
347 NSS_CMSArray_SortByDER(void **objs, const SEC_ASN1Template *objtemplate, void **objs2);
349 /*
350 * NSS_CMSUtil_DERCompare - for use with NSS_CMSArray_Sort to
351 * sort arrays of SECItems containing DER
352 */
353 extern int
354 NSS_CMSUtil_DERCompare(void *a, void *b);
356 /*
357 * NSS_CMSAlgArray_GetIndexByAlgID - find a specific algorithm in an array of
358 * algorithms.
359 *
360 * algorithmArray - array of algorithm IDs
361 * algid - algorithmid of algorithm to pick
362 *
363 * Returns:
364 * An integer containing the index of the algorithm in the array or -1 if
365 * algorithm was not found.
366 */
367 extern int
368 NSS_CMSAlgArray_GetIndexByAlgID(SECAlgorithmID **algorithmArray, SECAlgorithmID *algid);
370 /*
371 * NSS_CMSAlgArray_GetIndexByAlgID - find a specific algorithm in an array of
372 * algorithms.
373 *
374 * algorithmArray - array of algorithm IDs
375 * algiddata - id of algorithm to pick
376 *
377 * Returns:
378 * An integer containing the index of the algorithm in the array or -1 if
379 * algorithm was not found.
380 */
381 extern int
382 NSS_CMSAlgArray_GetIndexByAlgTag(SECAlgorithmID **algorithmArray, SECOidTag algtag);
384 extern const SECHashObject *
385 NSS_CMSUtil_GetHashObjByAlgID(SECAlgorithmID *algid);
387 extern const SEC_ASN1Template *
388 NSS_CMSUtil_GetTemplateByTypeTag(SECOidTag type);
390 extern size_t
391 NSS_CMSUtil_GetSizeByTypeTag(SECOidTag type);
393 extern NSSCMSContentInfo *
394 NSS_CMSContent_GetContentInfo(void *msg, SECOidTag type);
396 extern const char *
397 NSS_CMSUtil_VerificationStatusToString(NSSCMSVerificationStatus vs);
399 /************************************************************************
400 * cmssigdata.c - CMS signedData methods
401 ************************************************************************/
403 extern NSSCMSSignedData *
404 NSS_CMSSignedData_Create(NSSCMSMessage *cmsg);
406 extern void
407 NSS_CMSSignedData_Destroy(NSSCMSSignedData *sigd);
409 /*
410 * NSS_CMSSignedData_Encode_BeforeStart - do all the necessary things to a SignedData
411 * before start of encoding.
412 *
413 * In detail:
414 * - find out about the right value to put into sigd->version
415 * - come up with a list of digestAlgorithms (which should be the union of the algorithms
416 * in the signerinfos).
417 * If we happen to have a pre-set list of algorithms (and digest values!), we
418 * check if we have all the signerinfos' algorithms. If not, this is an error.
419 */
420 extern SECStatus
421 NSS_CMSSignedData_Encode_BeforeStart(NSSCMSSignedData *sigd);
423 extern SECStatus
424 NSS_CMSSignedData_Encode_BeforeData(NSSCMSSignedData *sigd);
426 /*
427 * NSS_CMSSignedData_Encode_AfterData - do all the necessary things to a SignedData
428 * after all the encapsulated data was passed through the encoder.
429 *
430 * In detail:
431 * - create the signatures in all the SignerInfos
432 *
433 * Please note that nothing is done to the Certificates and CRLs in the message - this
434 * is entirely the responsibility of our callers.
435 */
436 extern SECStatus
437 NSS_CMSSignedData_Encode_AfterData(NSSCMSSignedData *sigd);
439 extern SECStatus
440 NSS_CMSSignedData_Decode_BeforeData(NSSCMSSignedData *sigd);
442 /*
443 * NSS_CMSSignedData_Decode_AfterData - do all the necessary things to a SignedData
444 * after all the encapsulated data was passed through the decoder.
445 */
446 extern SECStatus
447 NSS_CMSSignedData_Decode_AfterData(NSSCMSSignedData *sigd);
449 /*
450 * NSS_CMSSignedData_Decode_AfterEnd - do all the necessary things to a SignedData
451 * after all decoding is finished.
452 */
453 extern SECStatus
454 NSS_CMSSignedData_Decode_AfterEnd(NSSCMSSignedData *sigd);
456 /*
457 * NSS_CMSSignedData_GetSignerInfos - retrieve the SignedData's signer list
458 */
459 extern NSSCMSSignerInfo **
460 NSS_CMSSignedData_GetSignerInfos(NSSCMSSignedData *sigd);
462 extern int
463 NSS_CMSSignedData_SignerInfoCount(NSSCMSSignedData *sigd);
465 extern NSSCMSSignerInfo *
466 NSS_CMSSignedData_GetSignerInfo(NSSCMSSignedData *sigd, int i);
468 /*
469 * NSS_CMSSignedData_GetDigestAlgs - retrieve the SignedData's digest algorithm list
470 */
471 extern SECAlgorithmID **
472 NSS_CMSSignedData_GetDigestAlgs(NSSCMSSignedData *sigd);
474 /*
475 * NSS_CMSSignedData_GetContentInfo - return pointer to this signedData's contentinfo
476 */
477 extern NSSCMSContentInfo *
478 NSS_CMSSignedData_GetContentInfo(NSSCMSSignedData *sigd);
480 /*
481 * NSS_CMSSignedData_GetCertificateList - retrieve the SignedData's certificate list
482 */
483 extern SECItem **
484 NSS_CMSSignedData_GetCertificateList(NSSCMSSignedData *sigd);
486 extern SECStatus
487 NSS_CMSSignedData_ImportCerts(NSSCMSSignedData *sigd, CERTCertDBHandle *certdb,
488 SECCertUsage certusage, PRBool keepcerts);
490 /*
491 * NSS_CMSSignedData_HasDigests - see if we have digests in place
492 */
493 extern PRBool
494 NSS_CMSSignedData_HasDigests(NSSCMSSignedData *sigd);
496 /*
497 * NSS_CMSSignedData_VerifySignerInfo - check a signature.
498 *
499 * The digests were either calculated during decoding (and are stored in the
500 * signedData itself) or set after decoding using NSS_CMSSignedData_SetDigests.
501 *
502 * The verification checks if the signing cert is valid and has a trusted chain
503 * for the purpose specified by "certusage".
504 */
505 extern SECStatus
506 NSS_CMSSignedData_VerifySignerInfo(NSSCMSSignedData *sigd, int i, CERTCertDBHandle *certdb,
507 SECCertUsage certusage);
509 /*
510 * NSS_CMSSignedData_VerifyCertsOnly - verify the certs in a certs-only message
511 */
512 extern SECStatus
513 NSS_CMSSignedData_VerifyCertsOnly(NSSCMSSignedData *sigd,
514 CERTCertDBHandle *certdb,
515 SECCertUsage usage);
517 extern SECStatus
518 NSS_CMSSignedData_AddCertList(NSSCMSSignedData *sigd, CERTCertificateList *certlist);
520 /*
521 * NSS_CMSSignedData_AddCertChain - add cert and its entire chain to the set of certs
522 */
523 extern SECStatus
524 NSS_CMSSignedData_AddCertChain(NSSCMSSignedData *sigd, CERTCertificate *cert);
526 extern SECStatus
527 NSS_CMSSignedData_AddCertificate(NSSCMSSignedData *sigd, CERTCertificate *cert);
529 extern PRBool
530 NSS_CMSSignedData_ContainsCertsOrCrls(NSSCMSSignedData *sigd);
532 extern SECStatus
533 NSS_CMSSignedData_AddSignerInfo(NSSCMSSignedData *sigd,
534 NSSCMSSignerInfo *signerinfo);
536 extern SECStatus
537 NSS_CMSSignedData_SetDigests(NSSCMSSignedData *sigd,
538 SECAlgorithmID **digestalgs,
539 SECItem **digests);
541 extern SECStatus
542 NSS_CMSSignedData_SetDigestValue(NSSCMSSignedData *sigd,
543 SECOidTag digestalgtag,
544 SECItem *digestdata);
546 extern SECStatus
547 NSS_CMSSignedData_AddDigest(PLArenaPool *poolp,
548 NSSCMSSignedData *sigd,
549 SECOidTag digestalgtag,
550 SECItem *digest);
552 extern SECItem *
553 NSS_CMSSignedData_GetDigestValue(NSSCMSSignedData *sigd, SECOidTag digestalgtag);
555 /*
556 * NSS_CMSSignedData_CreateCertsOnly - create a certs-only SignedData.
557 *
558 * cert - base certificates that will be included
559 * include_chain - if true, include the complete cert chain for cert
560 *
561 * More certs and chains can be added via AddCertificate and AddCertChain.
562 *
563 * An error results in a return value of NULL and an error set.
564 */
565 extern NSSCMSSignedData *
566 NSS_CMSSignedData_CreateCertsOnly(NSSCMSMessage *cmsg, CERTCertificate *cert, PRBool include_chain);
568 /************************************************************************
569 * cmssiginfo.c - signerinfo methods
570 ************************************************************************/
572 extern NSSCMSSignerInfo *
573 NSS_CMSSignerInfo_Create(NSSCMSMessage *cmsg, CERTCertificate *cert, SECOidTag digestalgtag);
574 extern NSSCMSSignerInfo *
575 NSS_CMSSignerInfo_CreateWithSubjKeyID(NSSCMSMessage *cmsg, SECItem *subjKeyID, SECKEYPublicKey *pubKey, SECKEYPrivateKey *signingKey, SECOidTag digestalgtag);
577 /*
578 * NSS_CMSSignerInfo_Destroy - destroy a SignerInfo data structure
579 */
580 extern void
581 NSS_CMSSignerInfo_Destroy(NSSCMSSignerInfo *si);
583 /*
584 * NSS_CMSSignerInfo_Sign - sign something
585 *
586 */
587 extern SECStatus
588 NSS_CMSSignerInfo_Sign(NSSCMSSignerInfo *signerinfo, SECItem *digest, SECItem *contentType);
590 extern SECStatus
591 NSS_CMSSignerInfo_VerifyCertificate(NSSCMSSignerInfo *signerinfo, CERTCertDBHandle *certdb,
592 SECCertUsage certusage);
594 /*
595 * NSS_CMSSignerInfo_Verify - verify the signature of a single SignerInfo
596 *
597 * Just verifies the signature. The assumption is that verification of the certificate
598 * is done already.
599 */
600 extern SECStatus
601 NSS_CMSSignerInfo_Verify(NSSCMSSignerInfo *signerinfo, SECItem *digest, SECItem *contentType);
603 extern NSSCMSVerificationStatus
604 NSS_CMSSignerInfo_GetVerificationStatus(NSSCMSSignerInfo *signerinfo);
606 extern SECOidData *
607 NSS_CMSSignerInfo_GetDigestAlg(NSSCMSSignerInfo *signerinfo);
609 extern SECOidTag
610 NSS_CMSSignerInfo_GetDigestAlgTag(NSSCMSSignerInfo *signerinfo);
612 extern int
613 NSS_CMSSignerInfo_GetVersion(NSSCMSSignerInfo *signerinfo);
615 extern CERTCertificateList *
616 NSS_CMSSignerInfo_GetCertList(NSSCMSSignerInfo *signerinfo);
618 /*
619 * NSS_CMSSignerInfo_GetSigningTime - return the signing time,
620 * in UTCTime format, of a CMS signerInfo.
621 *
622 * sinfo - signerInfo data for this signer
623 *
624 * Returns a pointer to XXXX (what?)
625 * A return value of NULL is an error.
626 */
627 extern SECStatus
628 NSS_CMSSignerInfo_GetSigningTime(NSSCMSSignerInfo *sinfo, PRTime *stime);
630 /*
631 * Return the signing cert of a CMS signerInfo.
632 *
633 * the certs in the enclosing SignedData must have been imported already
634 */
635 extern CERTCertificate *
636 NSS_CMSSignerInfo_GetSigningCertificate(NSSCMSSignerInfo *signerinfo, CERTCertDBHandle *certdb);
638 /*
639 * NSS_CMSSignerInfo_GetSignerCommonName - return the common name of the signer
640 *
641 * sinfo - signerInfo data for this signer
642 *
643 * Returns a pointer to allocated memory, which must be freed with PORT_Free.
644 * A return value of NULL is an error.
645 */
646 extern char *
647 NSS_CMSSignerInfo_GetSignerCommonName(NSSCMSSignerInfo *sinfo);
649 /*
650 * NSS_CMSSignerInfo_GetSignerEmailAddress - return the common name of the signer
651 *
652 * sinfo - signerInfo data for this signer
653 *
654 * Returns a pointer to allocated memory, which must be freed.
655 * A return value of NULL is an error.
656 */
657 extern char *
658 NSS_CMSSignerInfo_GetSignerEmailAddress(NSSCMSSignerInfo *sinfo);
660 /*
661 * NSS_CMSSignerInfo_AddAuthAttr - add an attribute to the
662 * authenticated (i.e. signed) attributes of "signerinfo".
663 */
664 extern SECStatus
665 NSS_CMSSignerInfo_AddAuthAttr(NSSCMSSignerInfo *signerinfo, NSSCMSAttribute *attr);
667 /*
668 * NSS_CMSSignerInfo_AddUnauthAttr - add an attribute to the
669 * unauthenticated attributes of "signerinfo".
670 */
671 extern SECStatus
672 NSS_CMSSignerInfo_AddUnauthAttr(NSSCMSSignerInfo *signerinfo, NSSCMSAttribute *attr);
674 /*
675 * NSS_CMSSignerInfo_AddSigningTime - add the signing time to the
676 * authenticated (i.e. signed) attributes of "signerinfo".
677 *
678 * This is expected to be included in outgoing signed
679 * messages for email (S/MIME) but is likely useful in other situations.
680 *
681 * This should only be added once; a second call will do nothing.
682 *
683 * XXX This will probably just shove the current time into "signerinfo"
684 * but it will not actually get signed until the entire item is
685 * processed for encoding. Is this (expected to be small) delay okay?
686 */
687 extern SECStatus
688 NSS_CMSSignerInfo_AddSigningTime(NSSCMSSignerInfo *signerinfo, PRTime t);
690 /*
691 * NSS_CMSSignerInfo_AddSMIMECaps - add a SMIMECapabilities attribute to the
692 * authenticated (i.e. signed) attributes of "signerinfo".
693 *
694 * This is expected to be included in outgoing signed
695 * messages for email (S/MIME).
696 */
697 extern SECStatus
698 NSS_CMSSignerInfo_AddSMIMECaps(NSSCMSSignerInfo *signerinfo);
700 /*
701 * NSS_CMSSignerInfo_AddSMIMEEncKeyPrefs - add a SMIMEEncryptionKeyPreferences attribute to the
702 * authenticated (i.e. signed) attributes of "signerinfo".
703 *
704 * This is expected to be included in outgoing signed messages for email (S/MIME).
705 */
706 SECStatus
707 NSS_CMSSignerInfo_AddSMIMEEncKeyPrefs(NSSCMSSignerInfo *signerinfo, CERTCertificate *cert, CERTCertDBHandle *certdb);
709 /*
710 * NSS_CMSSignerInfo_AddMSSMIMEEncKeyPrefs - add a SMIMEEncryptionKeyPreferences attribute to the
711 * authenticated (i.e. signed) attributes of "signerinfo", using the OID preferred by Microsoft.
712 *
713 * This is expected to be included in outgoing signed messages for email (S/MIME),
714 * if compatibility with Microsoft mail clients is wanted.
715 */
716 SECStatus
717 NSS_CMSSignerInfo_AddMSSMIMEEncKeyPrefs(NSSCMSSignerInfo *signerinfo, CERTCertificate *cert, CERTCertDBHandle *certdb);
719 /*
720 * NSS_CMSSignerInfo_AddCounterSignature - countersign a signerinfo
721 */
722 extern SECStatus
723 NSS_CMSSignerInfo_AddCounterSignature(NSSCMSSignerInfo *signerinfo,
724 SECOidTag digestalg, CERTCertificate signingcert);
726 /*
727 * XXXX the following needs to be done in the S/MIME layer code
728 * after signature of a signerinfo is verified
729 */
730 extern SECStatus
731 NSS_SMIMESignerInfo_SaveSMIMEProfile(NSSCMSSignerInfo *signerinfo);
733 /*
734 * NSS_CMSSignerInfo_IncludeCerts - set cert chain inclusion mode for this signer
735 */
736 extern SECStatus
737 NSS_CMSSignerInfo_IncludeCerts(NSSCMSSignerInfo *signerinfo, NSSCMSCertChainMode cm, SECCertUsage usage);
739 /************************************************************************
740 * cmsenvdata.c - CMS envelopedData methods
741 ************************************************************************/
743 /*
744 * NSS_CMSEnvelopedData_Create - create an enveloped data message
745 */
746 extern NSSCMSEnvelopedData *
747 NSS_CMSEnvelopedData_Create(NSSCMSMessage *cmsg, SECOidTag algorithm, int keysize);
749 /*
750 * NSS_CMSEnvelopedData_Destroy - destroy an enveloped data message
751 */
752 extern void
753 NSS_CMSEnvelopedData_Destroy(NSSCMSEnvelopedData *edp);
755 /*
756 * NSS_CMSEnvelopedData_GetContentInfo - return pointer to this envelopedData's contentinfo
757 */
758 extern NSSCMSContentInfo *
759 NSS_CMSEnvelopedData_GetContentInfo(NSSCMSEnvelopedData *envd);
761 /*
762 * NSS_CMSEnvelopedData_AddRecipient - add a recipientinfo to the enveloped data msg
763 *
764 * rip must be created on the same pool as edp - this is not enforced, though.
765 */
766 extern SECStatus
767 NSS_CMSEnvelopedData_AddRecipient(NSSCMSEnvelopedData *edp, NSSCMSRecipientInfo *rip);
769 /*
770 * NSS_CMSEnvelopedData_Encode_BeforeStart - prepare this envelopedData for encoding
771 *
772 * at this point, we need
773 * - recipientinfos set up with recipient's certificates
774 * - a content encryption algorithm (if none, 3DES will be used)
775 *
776 * this function will generate a random content encryption key (aka bulk key),
777 * initialize the recipientinfos with certificate identification and wrap the bulk key
778 * using the proper algorithm for every certificiate.
779 * it will finally set the bulk algorithm and key so that the encode step can find it.
780 */
781 extern SECStatus
782 NSS_CMSEnvelopedData_Encode_BeforeStart(NSSCMSEnvelopedData *envd);
784 /*
785 * NSS_CMSEnvelopedData_Encode_BeforeData - set up encryption
786 */
787 extern SECStatus
788 NSS_CMSEnvelopedData_Encode_BeforeData(NSSCMSEnvelopedData *envd);
790 /*
791 * NSS_CMSEnvelopedData_Encode_AfterData - finalize this envelopedData for encoding
792 */
793 extern SECStatus
794 NSS_CMSEnvelopedData_Encode_AfterData(NSSCMSEnvelopedData *envd);
796 /*
797 * NSS_CMSEnvelopedData_Decode_BeforeData - find our recipientinfo,
798 * derive bulk key & set up our contentinfo
799 */
800 extern SECStatus
801 NSS_CMSEnvelopedData_Decode_BeforeData(NSSCMSEnvelopedData *envd);
803 /*
804 * NSS_CMSEnvelopedData_Decode_AfterData - finish decrypting this envelopedData's content
805 */
806 extern SECStatus
807 NSS_CMSEnvelopedData_Decode_AfterData(NSSCMSEnvelopedData *envd);
809 /*
810 * NSS_CMSEnvelopedData_Decode_AfterEnd - finish decoding this envelopedData
811 */
812 extern SECStatus
813 NSS_CMSEnvelopedData_Decode_AfterEnd(NSSCMSEnvelopedData *envd);
816 /************************************************************************
817 * cmsrecinfo.c - CMS recipientInfo methods
818 ************************************************************************/
820 /*
821 * NSS_CMSRecipientInfo_Create - create a recipientinfo
822 *
823 * we currently do not create KeyAgreement recipientinfos with multiple recipientEncryptedKeys
824 * the certificate is supposed to have been verified by the caller
825 */
826 extern NSSCMSRecipientInfo *
827 NSS_CMSRecipientInfo_Create(NSSCMSMessage *cmsg, CERTCertificate *cert);
829 extern NSSCMSRecipientInfo *
830 NSS_CMSRecipientInfo_CreateWithSubjKeyID(NSSCMSMessage *cmsg,
831 SECItem *subjKeyID,
832 SECKEYPublicKey *pubKey);
834 extern NSSCMSRecipientInfo *
835 NSS_CMSRecipientInfo_CreateWithSubjKeyIDFromCert(NSSCMSMessage *cmsg,
836 CERTCertificate *cert);
838 /*
839 * NSS_CMSRecipientInfo_CreateNew - create a blank recipientinfo for
840 * applications which want to encode their own CMS structures and
841 * key exchange types.
842 */
843 extern NSSCMSRecipientInfo *
844 NSS_CMSRecipientInfo_CreateNew(void* pwfn_arg);
846 /*
847 * NSS_CMSRecipientInfo_CreateFromDER - create a recipientinfo from partially
848 * decoded DER data for applications which want to encode their own CMS
849 * structures and key exchange types.
850 */
851 extern NSSCMSRecipientInfo *
852 NSS_CMSRecipientInfo_CreateFromDER(SECItem* input, void* pwfn_arg);
854 extern void
855 NSS_CMSRecipientInfo_Destroy(NSSCMSRecipientInfo *ri);
857 /*
858 * NSS_CMSRecipientInfo_GetCertAndKey - retrieve the cert and key from the
859 * recipientInfo struct. If retcert or retkey are NULL, the cert or
860 * key (respectively) would not be returned). This function is a no-op if both
861 * retcert and retkey are NULL. Caller inherits ownership of the cert and key
862 * he requested (and is responsible to free them).
863 */
864 SECStatus NSS_CMSRecipientInfo_GetCertAndKey(NSSCMSRecipientInfo *ri,
865 CERTCertificate** retcert, SECKEYPrivateKey** retkey);
867 extern int
868 NSS_CMSRecipientInfo_GetVersion(NSSCMSRecipientInfo *ri);
870 extern SECItem *
871 NSS_CMSRecipientInfo_GetEncryptedKey(NSSCMSRecipientInfo *ri, int subIndex);
873 /*
874 * NSS_CMSRecipientInfo_Encode - encode an NSS_CMSRecipientInfo as ASN.1
875 */
876 SECStatus NSS_CMSRecipientInfo_Encode(PLArenaPool* poolp,
877 const NSSCMSRecipientInfo *src,
878 SECItem* returned);
880 extern SECOidTag
881 NSS_CMSRecipientInfo_GetKeyEncryptionAlgorithmTag(NSSCMSRecipientInfo *ri);
883 extern SECStatus
884 NSS_CMSRecipientInfo_WrapBulkKey(NSSCMSRecipientInfo *ri, PK11SymKey *bulkkey, SECOidTag bulkalgtag);
886 extern PK11SymKey *
887 NSS_CMSRecipientInfo_UnwrapBulkKey(NSSCMSRecipientInfo *ri, int subIndex,
888 CERTCertificate *cert, SECKEYPrivateKey *privkey, SECOidTag bulkalgtag);
890 /************************************************************************
891 * cmsencdata.c - CMS encryptedData methods
892 ************************************************************************/
893 /*
894 * NSS_CMSEncryptedData_Create - create an empty encryptedData object.
895 *
896 * "algorithm" specifies the bulk encryption algorithm to use.
897 * "keysize" is the key size.
898 *
899 * An error results in a return value of NULL and an error set.
900 * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
901 */
902 extern NSSCMSEncryptedData *
903 NSS_CMSEncryptedData_Create(NSSCMSMessage *cmsg, SECOidTag algorithm, int keysize);
905 /*
906 * NSS_CMSEncryptedData_Destroy - destroy an encryptedData object
907 */
908 extern void
909 NSS_CMSEncryptedData_Destroy(NSSCMSEncryptedData *encd);
911 /*
912 * NSS_CMSEncryptedData_GetContentInfo - return pointer to encryptedData object's contentInfo
913 */
914 extern NSSCMSContentInfo *
915 NSS_CMSEncryptedData_GetContentInfo(NSSCMSEncryptedData *encd);
917 /*
918 * NSS_CMSEncryptedData_Encode_BeforeStart - do all the necessary things to a EncryptedData
919 * before encoding begins.
920 *
921 * In particular:
922 * - set the correct version value.
923 * - get the encryption key
924 */
925 extern SECStatus
926 NSS_CMSEncryptedData_Encode_BeforeStart(NSSCMSEncryptedData *encd);
928 /*
929 * NSS_CMSEncryptedData_Encode_BeforeData - set up encryption
930 */
931 extern SECStatus
932 NSS_CMSEncryptedData_Encode_BeforeData(NSSCMSEncryptedData *encd);
934 /*
935 * NSS_CMSEncryptedData_Encode_AfterData - finalize this encryptedData for encoding
936 */
937 extern SECStatus
938 NSS_CMSEncryptedData_Encode_AfterData(NSSCMSEncryptedData *encd);
940 /*
941 * NSS_CMSEncryptedData_Decode_BeforeData - find bulk key & set up decryption
942 */
943 extern SECStatus
944 NSS_CMSEncryptedData_Decode_BeforeData(NSSCMSEncryptedData *encd);
946 /*
947 * NSS_CMSEncryptedData_Decode_AfterData - finish decrypting this encryptedData's content
948 */
949 extern SECStatus
950 NSS_CMSEncryptedData_Decode_AfterData(NSSCMSEncryptedData *encd);
952 /*
953 * NSS_CMSEncryptedData_Decode_AfterEnd - finish decoding this encryptedData
954 */
955 extern SECStatus
956 NSS_CMSEncryptedData_Decode_AfterEnd(NSSCMSEncryptedData *encd);
958 /************************************************************************
959 * cmsdigdata.c - CMS encryptedData methods
960 ************************************************************************/
961 /*
962 * NSS_CMSDigestedData_Create - create a digestedData object (presumably for encoding)
963 *
964 * version will be set by NSS_CMSDigestedData_Encode_BeforeStart
965 * digestAlg is passed as parameter
966 * contentInfo must be filled by the user
967 * digest will be calculated while encoding
968 */
969 extern NSSCMSDigestedData *
970 NSS_CMSDigestedData_Create(NSSCMSMessage *cmsg, SECAlgorithmID *digestalg);
972 /*
973 * NSS_CMSDigestedData_Destroy - destroy a digestedData object
974 */
975 extern void
976 NSS_CMSDigestedData_Destroy(NSSCMSDigestedData *digd);
978 /*
979 * NSS_CMSDigestedData_GetContentInfo - return pointer to digestedData object's contentInfo
980 */
981 extern NSSCMSContentInfo *
982 NSS_CMSDigestedData_GetContentInfo(NSSCMSDigestedData *digd);
984 /*
985 * NSS_CMSDigestedData_Encode_BeforeStart - do all the necessary things to a DigestedData
986 * before encoding begins.
987 *
988 * In particular:
989 * - set the right version number. The contentInfo's content type must be set up already.
990 */
991 extern SECStatus
992 NSS_CMSDigestedData_Encode_BeforeStart(NSSCMSDigestedData *digd);
994 /*
995 * NSS_CMSDigestedData_Encode_BeforeData - do all the necessary things to a DigestedData
996 * before the encapsulated data is passed through the encoder.
997 *
998 * In detail:
999 * - set up the digests if necessary
1000 */
1001 extern SECStatus
1002 NSS_CMSDigestedData_Encode_BeforeData(NSSCMSDigestedData *digd);
1004 /*
1005 * NSS_CMSDigestedData_Encode_AfterData - do all the necessary things to a DigestedData
1006 * after all the encapsulated data was passed through the encoder.
1007 *
1008 * In detail:
1009 * - finish the digests
1010 */
1011 extern SECStatus
1012 NSS_CMSDigestedData_Encode_AfterData(NSSCMSDigestedData *digd);
1014 /*
1015 * NSS_CMSDigestedData_Decode_BeforeData - do all the necessary things to a DigestedData
1016 * before the encapsulated data is passed through the encoder.
1017 *
1018 * In detail:
1019 * - set up the digests if necessary
1020 */
1021 extern SECStatus
1022 NSS_CMSDigestedData_Decode_BeforeData(NSSCMSDigestedData *digd);
1024 /*
1025 * NSS_CMSDigestedData_Decode_AfterData - do all the necessary things to a DigestedData
1026 * after all the encapsulated data was passed through the encoder.
1027 *
1028 * In detail:
1029 * - finish the digests
1030 */
1031 extern SECStatus
1032 NSS_CMSDigestedData_Decode_AfterData(NSSCMSDigestedData *digd);
1034 /*
1035 * NSS_CMSDigestedData_Decode_AfterEnd - finalize a digestedData.
1036 *
1037 * In detail:
1038 * - check the digests for equality
1039 */
1040 extern SECStatus
1041 NSS_CMSDigestedData_Decode_AfterEnd(NSSCMSDigestedData *digd);
1043 /************************************************************************
1044 * cmsdigest.c - digestion routines
1045 ************************************************************************/
1047 /*
1048 * NSS_CMSDigestContext_StartMultiple - start digest calculation using all the
1049 * digest algorithms in "digestalgs" in parallel.
1050 */
1051 extern NSSCMSDigestContext *
1052 NSS_CMSDigestContext_StartMultiple(SECAlgorithmID **digestalgs);
1054 /*
1055 * NSS_CMSDigestContext_StartSingle - same as NSS_CMSDigestContext_StartMultiple, but
1056 * only one algorithm.
1057 */
1058 extern NSSCMSDigestContext *
1059 NSS_CMSDigestContext_StartSingle(SECAlgorithmID *digestalg);
1061 /*
1062 * NSS_CMSDigestContext_Update - feed more data into the digest machine
1063 */
1064 extern void
1065 NSS_CMSDigestContext_Update(NSSCMSDigestContext *cmsdigcx, const unsigned char *data, int len);
1067 /*
1068 * NSS_CMSDigestContext_Cancel - cancel digesting operation
1069 */
1070 extern void
1071 NSS_CMSDigestContext_Cancel(NSSCMSDigestContext *cmsdigcx);
1073 /*
1074 * NSS_CMSDigestContext_FinishMultiple - finish the digests and put them
1075 * into an array of SECItems (allocated on poolp)
1076 */
1077 extern SECStatus
1078 NSS_CMSDigestContext_FinishMultiple(NSSCMSDigestContext *cmsdigcx, PLArenaPool *poolp,
1079 SECItem ***digestsp);
1081 /*
1082 * NSS_CMSDigestContext_FinishSingle - same as NSS_CMSDigestContext_FinishMultiple,
1083 * but for one digest.
1084 */
1085 extern SECStatus
1086 NSS_CMSDigestContext_FinishSingle(NSSCMSDigestContext *cmsdigcx, PLArenaPool *poolp,
1087 SECItem *digest);
1089 /************************************************************************
1090 *
1091 ************************************************************************/
1093 /* shortcuts for basic use */
1095 /*
1096 * NSS_CMSDEREncode - DER Encode a CMS message, with input being
1097 * the plaintext message and derOut being the output,
1098 * stored in arena's pool.
1099 */
1100 extern SECStatus
1101 NSS_CMSDEREncode(NSSCMSMessage *cmsg, SECItem *input, SECItem *derOut,
1102 PLArenaPool *arena);
1105 /************************************************************************
1106 *
1107 ************************************************************************/
1109 /*
1110 * define new S/MIME content type entries
1111 *
1112 * S/MIME uses the builtin PKCS7 oid types for encoding and decoding the
1113 * various S/MIME content. Some applications have their own content type
1114 * which is different from the standard content type defined by S/MIME.
1115 *
1116 * This function allows you to register new content types. There are basically
1117 * Two different types of content, Wrappping content, and Data.
1118 *
1119 * For data types, All the functions below can be zero or NULL excext
1120 * type and is isData, which should be your oid tag and PR_FALSE respectively
1121 *
1122 * For wrapping types, everything must be provided, or you will get encoder
1123 * failures.
1124 *
1125 * If NSS doesn't already define the OID that you need, you can register
1126 * your own with SECOID_AddEntry.
1127 *
1128 * Once you have defined your new content type, you can pass your new content
1129 * type to NSS_CMSContentInfo_SetContent().
1130 *
1131 * If you are using a wrapping type you can pass your own data structure in
1132 * the ptr field, but it must contain and embedded NSSCMSGenericWrappingData
1133 * structure as the first element. The size you pass to
1134 * NSS_CMSType_RegisterContentType is the total size of your self defined
1135 * data structure. NSS_CMSContentInfo_GetContent will return that data
1136 * structure from the content info. Your ASN1Template will be evaluated
1137 * against that data structure.
1138 */
1139 SECStatus NSS_CMSType_RegisterContentType(SECOidTag type,
1140 SEC_ASN1Template *asn1Template, size_t size,
1141 NSSCMSGenericWrapperDataDestroy destroy,
1142 NSSCMSGenericWrapperDataCallback decode_before,
1143 NSSCMSGenericWrapperDataCallback decode_after,
1144 NSSCMSGenericWrapperDataCallback decode_end,
1145 NSSCMSGenericWrapperDataCallback encode_start,
1146 NSSCMSGenericWrapperDataCallback encode_before,
1147 NSSCMSGenericWrapperDataCallback encode_after,
1148 PRBool isData);
1150 /************************************************************************/
1151 SEC_END_PROTOS
1153 #endif /* _CMS_H_ */
