1/* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
4
5/*
6 * Interfaces of the CMS implementation.
7 */
8
9#ifndef _CMS_H_
10#define _CMS_H_
11
12#include "seccomon.h"
13
14#include "secoidt.h"
15#include "certt.h"
16#include "keythi.h"
17#include "hasht.h"
18#include "cmst.h"
19
20/************************************************************************/
21SEC_BEGIN_PROTOS
22
23/************************************************************************
24 * cmsdecode.c - CMS decoding
25 ************************************************************************/
26
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 */
36extern NSSCMSDecoderContext *
37NSS_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);
41
42/*
43 * NSS_CMSDecoder_Update - feed DER-encoded data to decoder
44 */
45extern SECStatus
46NSS_CMSDecoder_Update(NSSCMSDecoderContext *p7dcx, const char *buf, unsigned long len);
47
48/*
49 * NSS_CMSDecoder_Cancel - cancel a decoding process
50 */
51extern void
52NSS_CMSDecoder_Cancel(NSSCMSDecoderContext *p7dcx);
53
54/*
55 * NSS_CMSDecoder_Finish - mark the end of inner content and finish decoding
56 */
57extern NSSCMSMessage *
58NSS_CMSDecoder_Finish(NSSCMSDecoderContext *p7dcx);
59
60/*
61 * NSS_CMSMessage_CreateFromDER - decode a CMS message from DER encoded data
62 */
63extern NSSCMSMessage *
64NSS_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);
68
69/************************************************************************
70 * cmsencode.c - CMS encoding
71 ************************************************************************/
72
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 */
85extern NSSCMSEncoderContext *
86NSS_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);
92
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 */
100extern SECStatus
101NSS_CMSEncoder_Update(NSSCMSEncoderContext *p7ecx, const char *data, unsigned long len);
102
103/*
104 * NSS_CMSEncoder_Cancel - stop all encoding
105 */
106extern SECStatus
107NSS_CMSEncoder_Cancel(NSSCMSEncoderContext *p7ecx);
108
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 */
114extern SECStatus
115NSS_CMSEncoder_Finish(NSSCMSEncoderContext *p7ecx);
116
117/************************************************************************
118 * cmsmessage.c - CMS message object
119 ************************************************************************/
120
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 */
126extern NSSCMSMessage *
127NSS_CMSMessage_Create(PLArenaPool *poolp);
128
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 */
139extern void
140NSS_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);
144
145/*
146 * NSS_CMSMessage_Destroy - destroy a CMS message and all of its sub-pieces.
147 */
148extern void
149NSS_CMSMessage_Destroy(NSSCMSMessage *cmsg);
150
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 */
157extern NSSCMSMessage *
158NSS_CMSMessage_Copy(NSSCMSMessage *cmsg);
159
160/*
161 * NSS_CMSMessage_GetArena - return a pointer to the message's arena pool
162 */
163extern PLArenaPool *
164NSS_CMSMessage_GetArena(NSSCMSMessage *cmsg);
165
166/*
167 * NSS_CMSMessage_GetContentInfo - return a pointer to the top level contentInfo
168 */
169extern NSSCMSContentInfo *
170NSS_CMSMessage_GetContentInfo(NSSCMSMessage *cmsg);
171
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 */
177extern SECItem *
178NSS_CMSMessage_GetContent(NSSCMSMessage *cmsg);
179
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 */
185extern int
186NSS_CMSMessage_ContentLevelCount(NSSCMSMessage *cmsg);
187
188/*
189 * NSS_CMSMessage_ContentLevel - find content level #n
190 *
191 * CMS data content objects do not count.
192 */
193extern NSSCMSContentInfo *
194NSS_CMSMessage_ContentLevel(NSSCMSMessage *cmsg, int n);
195
196/*
197 * NSS_CMSMessage_ContainsCertsOrCrls - see if message contains certs along the way
198 */
199extern PRBool
200NSS_CMSMessage_ContainsCertsOrCrls(NSSCMSMessage *cmsg);
201
202/*
203 * NSS_CMSMessage_IsEncrypted - see if message contains a encrypted submessage
204 */
205extern PRBool
206NSS_CMSMessage_IsEncrypted(NSSCMSMessage *cmsg);
207
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 */
218extern PRBool
219NSS_CMSMessage_IsSigned(NSSCMSMessage *cmsg);
220
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 */
227extern PRBool
228NSS_CMSMessage_IsContentEmpty(NSSCMSMessage *cmsg, unsigned int minLen);
229
230/************************************************************************
231 * cmscinfo.c - CMS contentInfo methods
232 ************************************************************************/
233
234/*
235 * NSS_CMSContentInfo_Destroy - destroy a CMS contentInfo and all of its sub-pieces.
236 */
237extern void
238NSS_CMSContentInfo_Destroy(NSSCMSContentInfo *cinfo);
239
240/*
241 * NSS_CMSContentInfo_GetChildContentInfo - get content's contentInfo (if it exists)
242 */
243extern NSSCMSContentInfo *
244NSS_CMSContentInfo_GetChildContentInfo(NSSCMSContentInfo *cinfo);
245
246/*
247 * NSS_CMSContentInfo_SetContent - set cinfo's content type & content to CMS object
248 */
249extern SECStatus
250NSS_CMSContentInfo_SetContent(NSSCMSMessage *cmsg, NSSCMSContentInfo *cinfo, SECOidTag type, void *ptr);
251
252/*
253 * NSS_CMSContentInfo_SetContent_XXXX - typesafe wrappers for NSS_CMSContentInfo_SetType
254 * set cinfo's content type & content to CMS object
255 */
256extern SECStatus
257NSS_CMSContentInfo_SetContent_Data(NSSCMSMessage *cmsg, NSSCMSContentInfo *cinfo, SECItem *data, PRBool detached);
258
259extern SECStatus
260NSS_CMSContentInfo_SetContent_SignedData(NSSCMSMessage *cmsg, NSSCMSContentInfo *cinfo, NSSCMSSignedData *sigd);
261
262extern SECStatus
263NSS_CMSContentInfo_SetContent_EnvelopedData(NSSCMSMessage *cmsg, NSSCMSContentInfo *cinfo, NSSCMSEnvelopedData *envd);
264
265extern SECStatus
266NSS_CMSContentInfo_SetContent_DigestedData(NSSCMSMessage *cmsg, NSSCMSContentInfo *cinfo, NSSCMSDigestedData *digd);
267
268extern SECStatus
269NSS_CMSContentInfo_SetContent_EncryptedData(NSSCMSMessage *cmsg, NSSCMSContentInfo *cinfo, NSSCMSEncryptedData *encd);
270
271/*
272 * turn off streaming for this content type.
273 * This could fail with SEC_ERROR_NO_MEMORY in memory constrained conditions.
274 */
275extern SECStatus
276NSS_CMSContentInfo_SetDontStream(NSSCMSContentInfo *cinfo, PRBool dontStream);
277
278/*
279 * NSS_CMSContentInfo_GetContent - get pointer to inner content
280 *
281 * needs to be casted...
282 */
283extern void *
284NSS_CMSContentInfo_GetContent(NSSCMSContentInfo *cinfo);
285
286/*
287 * NSS_CMSContentInfo_GetInnerContent - get pointer to innermost content
288 *
289 * this is typically only called by NSS_CMSMessage_GetContent()
290 */
291extern SECItem *
292NSS_CMSContentInfo_GetInnerContent(NSSCMSContentInfo *cinfo);
293
294/*
295 * NSS_CMSContentInfo_GetContentType{Tag,OID} - find out (saving pointer to lookup result
296 * for future reference) and return the inner content type.
297 */
298extern SECOidTag
299NSS_CMSContentInfo_GetContentTypeTag(NSSCMSContentInfo *cinfo);
300
301extern SECItem *
302NSS_CMSContentInfo_GetContentTypeOID(NSSCMSContentInfo *cinfo);
303
304/*
305 * NSS_CMSContentInfo_GetContentEncAlgTag - find out (saving pointer to lookup result
306 * for future reference) and return the content encryption algorithm tag.
307 */
308extern SECOidTag
309NSS_CMSContentInfo_GetContentEncAlgTag(NSSCMSContentInfo *cinfo);
310
311/*
312 * NSS_CMSContentInfo_GetContentEncAlg - find out and return the content encryption algorithm tag.
313 */
314extern SECAlgorithmID *
315NSS_CMSContentInfo_GetContentEncAlg(NSSCMSContentInfo *cinfo);
316
317extern SECStatus
318NSS_CMSContentInfo_SetContentEncAlg(PLArenaPool *poolp, NSSCMSContentInfo *cinfo,
319 SECOidTag bulkalgtag, SECItem *parameters, int keysize);
320
321extern SECStatus
322NSS_CMSContentInfo_SetContentEncAlgID(PLArenaPool *poolp, NSSCMSContentInfo *cinfo,
323 SECAlgorithmID *algid, int keysize);
324
325extern void
326NSS_CMSContentInfo_SetBulkKey(NSSCMSContentInfo *cinfo, PK11SymKey *bulkkey);
327
328extern PK11SymKey *
329NSS_CMSContentInfo_GetBulkKey(NSSCMSContentInfo *cinfo);
330
331extern int
332NSS_CMSContentInfo_GetBulkKeySize(NSSCMSContentInfo *cinfo);
333
334/************************************************************************
335 * cmsutil.c - CMS misc utility functions
336 ************************************************************************/
337
338/*
339 * NSS_CMSArray_SortByDER - sort array of objects by objects' DER encoding
340 *
341 * make sure that the order of the objects guarantees valid DER (which must be
342 * in lexigraphically ascending order for a SET OF); if reordering is necessary it
343 * will be done in place (in objs).
344 */
345extern SECStatus
346NSS_CMSArray_SortByDER(void **objs, const SEC_ASN1Template *objtemplate, void **objs2);
347
348/*
349 * NSS_CMSUtil_DERCompare - for use with NSS_CMSArray_Sort to
350 * sort arrays of SECItems containing DER
351 */
352extern int
353NSS_CMSUtil_DERCompare(void *a, void *b);
354
355/*
356 * NSS_CMSAlgArray_GetIndexByAlgID - find a specific algorithm in an array of
357 * algorithms.
358 *
359 * algorithmArray - array of algorithm IDs
360 * algid - algorithmid of algorithm to pick
361 *
362 * Returns:
363 * An integer containing the index of the algorithm in the array or -1 if
364 * algorithm was not found.
365 */
366extern int
367NSS_CMSAlgArray_GetIndexByAlgID(SECAlgorithmID **algorithmArray, SECAlgorithmID *algid);
368
369/*
370 * NSS_CMSAlgArray_GetIndexByAlgID - find a specific algorithm in an array of
371 * algorithms.
372 *
373 * algorithmArray - array of algorithm IDs
374 * algiddata - id of algorithm to pick
375 *
376 * Returns:
377 * An integer containing the index of the algorithm in the array or -1 if
378 * algorithm was not found.
379 */
380extern int
381NSS_CMSAlgArray_GetIndexByAlgTag(SECAlgorithmID **algorithmArray, SECOidTag algtag);
382
383extern const SECHashObject *
384NSS_CMSUtil_GetHashObjByAlgID(SECAlgorithmID *algid);
385
386extern const SEC_ASN1Template *
387NSS_CMSUtil_GetTemplateByTypeTag(SECOidTag type);
388
389extern size_t
390NSS_CMSUtil_GetSizeByTypeTag(SECOidTag type);
391
392extern NSSCMSContentInfo *
393NSS_CMSContent_GetContentInfo(void *msg, SECOidTag type);
394
395extern const char *
396NSS_CMSUtil_VerificationStatusToString(NSSCMSVerificationStatus vs);
397
398/************************************************************************
399 * cmssigdata.c - CMS signedData methods
400 ************************************************************************/
401
402extern NSSCMSSignedData *
403NSS_CMSSignedData_Create(NSSCMSMessage *cmsg);
404
405extern void
406NSS_CMSSignedData_Destroy(NSSCMSSignedData *sigd);
407
408/*
409 * NSS_CMSSignedData_Encode_BeforeStart - do all the necessary things to a SignedData
410 * before start of encoding.
411 *
412 * In detail:
413 * - find out about the right value to put into sigd->version
414 * - come up with a list of digestAlgorithms (which should be the union of the algorithms
415 * in the signerinfos).
416 * If we happen to have a pre-set list of algorithms (and digest values!), we
417 * check if we have all the signerinfos' algorithms. If not, this is an error.
418 */
419extern SECStatus
420NSS_CMSSignedData_Encode_BeforeStart(NSSCMSSignedData *sigd);
421
422extern SECStatus
423NSS_CMSSignedData_Encode_BeforeData(NSSCMSSignedData *sigd);
424
425/*
426 * NSS_CMSSignedData_Encode_AfterData - do all the necessary things to a SignedData
427 * after all the encapsulated data was passed through the encoder.
428 *
429 * In detail:
430 * - create the signatures in all the SignerInfos
431 *
432 * Please note that nothing is done to the Certificates and CRLs in the message - this
433 * is entirely the responsibility of our callers.
434 */
435extern SECStatus
436NSS_CMSSignedData_Encode_AfterData(NSSCMSSignedData *sigd);
437
438extern SECStatus
439NSS_CMSSignedData_Decode_BeforeData(NSSCMSSignedData *sigd);
440
441/*
442 * NSS_CMSSignedData_Decode_AfterData - do all the necessary things to a SignedData
443 * after all the encapsulated data was passed through the decoder.
444 */
445extern SECStatus
446NSS_CMSSignedData_Decode_AfterData(NSSCMSSignedData *sigd);
447
448/*
449 * NSS_CMSSignedData_Decode_AfterEnd - do all the necessary things to a SignedData
450 * after all decoding is finished.
451 */
452extern SECStatus
453NSS_CMSSignedData_Decode_AfterEnd(NSSCMSSignedData *sigd);
454
455/*
456 * NSS_CMSSignedData_GetSignerInfos - retrieve the SignedData's signer list
457 */
458extern NSSCMSSignerInfo **
459NSS_CMSSignedData_GetSignerInfos(NSSCMSSignedData *sigd);
460
461extern int
462NSS_CMSSignedData_SignerInfoCount(NSSCMSSignedData *sigd);
463
464extern NSSCMSSignerInfo *
465NSS_CMSSignedData_GetSignerInfo(NSSCMSSignedData *sigd, int i);
466
467/*
468 * NSS_CMSSignedData_GetDigestAlgs - retrieve the SignedData's digest algorithm list
469 */
470extern SECAlgorithmID **
471NSS_CMSSignedData_GetDigestAlgs(NSSCMSSignedData *sigd);
472
473/*
474 * NSS_CMSSignedData_GetContentInfo - return pointer to this signedData's contentinfo
475 */
476extern NSSCMSContentInfo *
477NSS_CMSSignedData_GetContentInfo(NSSCMSSignedData *sigd);
478
479/*
480 * NSS_CMSSignedData_GetCertificateList - retrieve the SignedData's certificate list
481 */
482extern SECItem **
483NSS_CMSSignedData_GetCertificateList(NSSCMSSignedData *sigd);
484
485extern SECStatus
486NSS_CMSSignedData_ImportCerts(NSSCMSSignedData *sigd, CERTCertDBHandle *certdb,
487 SECCertUsage certusage, PRBool keepcerts);
488
489/*
490 * NSS_CMSSignedData_HasDigests - see if we have digests in place
491 */
492extern PRBool
493NSS_CMSSignedData_HasDigests(NSSCMSSignedData *sigd);
494
495/*
496 * NSS_CMSSignedData_VerifySignerInfo - check a signature.
497 *
498 * The digests were either calculated during decoding (and are stored in the
499 * signedData itself) or set after decoding using NSS_CMSSignedData_SetDigests.
500 *
501 * The verification checks if the signing cert is valid and has a trusted chain
502 * for the purpose specified by "certusage".
503 */
504extern SECStatus
505NSS_CMSSignedData_VerifySignerInfo(NSSCMSSignedData *sigd, int i, CERTCertDBHandle *certdb,
506 SECCertUsage certusage);
507
508/*
509 * NSS_CMSSignedData_VerifyCertsOnly - verify the certs in a certs-only message
510*/
511extern SECStatus
512NSS_CMSSignedData_VerifyCertsOnly(NSSCMSSignedData *sigd,
513 CERTCertDBHandle *certdb,
514 SECCertUsage usage);
515
516extern SECStatus
517NSS_CMSSignedData_AddCertList(NSSCMSSignedData *sigd, CERTCertificateList *certlist);
518
519/*
520 * NSS_CMSSignedData_AddCertChain - add cert and its entire chain to the set of certs
521 */
522extern SECStatus
523NSS_CMSSignedData_AddCertChain(NSSCMSSignedData *sigd, CERTCertificate *cert);
524
525extern SECStatus
526NSS_CMSSignedData_AddCertificate(NSSCMSSignedData *sigd, CERTCertificate *cert);
527
528extern PRBool
529NSS_CMSSignedData_ContainsCertsOrCrls(NSSCMSSignedData *sigd);
530
531extern SECStatus
532NSS_CMSSignedData_AddSignerInfo(NSSCMSSignedData *sigd,
533 NSSCMSSignerInfo *signerinfo);
534
535extern SECStatus
536NSS_CMSSignedData_SetDigests(NSSCMSSignedData *sigd,
537 SECAlgorithmID **digestalgs,
538 SECItem **digests);
539
540extern SECStatus
541NSS_CMSSignedData_SetDigestValue(NSSCMSSignedData *sigd,
542 SECOidTag digestalgtag,
543 SECItem *digestdata);
544
545extern SECStatus
546NSS_CMSSignedData_AddDigest(PLArenaPool *poolp,
547 NSSCMSSignedData *sigd,
548 SECOidTag digestalgtag,
549 SECItem *digest);
550
551extern SECItem *
552NSS_CMSSignedData_GetDigestValue(NSSCMSSignedData *sigd, SECOidTag digestalgtag);
553
554/*
555 * NSS_CMSSignedData_CreateCertsOnly - create a certs-only SignedData.
556 *
557 * cert - base certificates that will be included
558 * include_chain - if true, include the complete cert chain for cert
559 *
560 * More certs and chains can be added via AddCertificate and AddCertChain.
561 *
562 * An error results in a return value of NULL and an error set.
563 */
564extern NSSCMSSignedData *
565NSS_CMSSignedData_CreateCertsOnly(NSSCMSMessage *cmsg, CERTCertificate *cert, PRBool include_chain);
566
567/************************************************************************
568 * cmssiginfo.c - signerinfo methods
569 ************************************************************************/
570
571extern NSSCMSSignerInfo *
572NSS_CMSSignerInfo_Create(NSSCMSMessage *cmsg, CERTCertificate *cert, SECOidTag digestalgtag);
573extern NSSCMSSignerInfo *
574NSS_CMSSignerInfo_CreateWithSubjKeyID(NSSCMSMessage *cmsg, SECItem *subjKeyID, SECKEYPublicKey *pubKey, SECKEYPrivateKey *signingKey, SECOidTag digestalgtag);
575
576/*
577 * NSS_CMSSignerInfo_Destroy - destroy a SignerInfo data structure
578 */
579extern void
580NSS_CMSSignerInfo_Destroy(NSSCMSSignerInfo *si);
581
582/*
583 * NSS_CMSSignerInfo_Sign - sign something
584 *
585 */
586extern SECStatus
587NSS_CMSSignerInfo_Sign(NSSCMSSignerInfo *signerinfo, SECItem *digest, SECItem *contentType);
588
589extern SECStatus
590NSS_CMSSignerInfo_VerifyCertificate(NSSCMSSignerInfo *signerinfo, CERTCertDBHandle *certdb,
591 SECCertUsage certusage);
592
593/*
594 * NSS_CMSSignerInfo_Verify - verify the signature of a single SignerInfo
595 *
596 * Just verifies the signature. The assumption is that verification of the certificate
597 * is done already.
598 */
599extern SECStatus
600NSS_CMSSignerInfo_Verify(NSSCMSSignerInfo *signerinfo, SECItem *digest, SECItem *contentType);
601
602extern NSSCMSVerificationStatus
603NSS_CMSSignerInfo_GetVerificationStatus(NSSCMSSignerInfo *signerinfo);
604
605extern SECOidData *
606NSS_CMSSignerInfo_GetDigestAlg(NSSCMSSignerInfo *signerinfo);
607
608extern SECOidTag
609NSS_CMSSignerInfo_GetDigestAlgTag(NSSCMSSignerInfo *signerinfo);
610
611extern int
612NSS_CMSSignerInfo_GetVersion(NSSCMSSignerInfo *signerinfo);
613
614extern CERTCertificateList *
615NSS_CMSSignerInfo_GetCertList(NSSCMSSignerInfo *signerinfo);
616
617/*
618 * NSS_CMSSignerInfo_GetSigningTime - return the signing time,
619 * in UTCTime format, of a CMS signerInfo.
620 *
621 * sinfo - signerInfo data for this signer
622 *
623 * Returns a pointer to XXXX (what?)
624 * A return value of NULL is an error.
625 */
626extern SECStatus
627NSS_CMSSignerInfo_GetSigningTime(NSSCMSSignerInfo *sinfo, PRTime *stime);
628
629/*
630 * Return the signing cert of a CMS signerInfo.
631 *
632 * the certs in the enclosing SignedData must have been imported already
633 */
634extern CERTCertificate *
635NSS_CMSSignerInfo_GetSigningCertificate(NSSCMSSignerInfo *signerinfo, CERTCertDBHandle *certdb);
636
637/*
638 * NSS_CMSSignerInfo_GetSignerCommonName - return the common name of the signer
639 *
640 * sinfo - signerInfo data for this signer
641 *
642 * Returns a pointer to allocated memory, which must be freed with PORT_Free.
643 * A return value of NULL is an error.
644 */
645extern char *
646NSS_CMSSignerInfo_GetSignerCommonName(NSSCMSSignerInfo *sinfo);
647
648/*
649 * NSS_CMSSignerInfo_GetSignerEmailAddress - return the common name of the signer
650 *
651 * sinfo - signerInfo data for this signer
652 *
653 * Returns a pointer to allocated memory, which must be freed.
654 * A return value of NULL is an error.
655 */
656extern char *
657NSS_CMSSignerInfo_GetSignerEmailAddress(NSSCMSSignerInfo *sinfo);
658
659/*
660 * NSS_CMSSignerInfo_AddAuthAttr - add an attribute to the
661 * authenticated (i.e. signed) attributes of "signerinfo".
662 */
663extern SECStatus
664NSS_CMSSignerInfo_AddAuthAttr(NSSCMSSignerInfo *signerinfo, NSSCMSAttribute *attr);
665
666/*
667 * NSS_CMSSignerInfo_AddUnauthAttr - add an attribute to the
668 * unauthenticated attributes of "signerinfo".
669 */
670extern SECStatus
671NSS_CMSSignerInfo_AddUnauthAttr(NSSCMSSignerInfo *signerinfo, NSSCMSAttribute *attr);
672
673/*
674 * NSS_CMSSignerInfo_AddSigningTime - add the signing time to the
675 * authenticated (i.e. signed) attributes of "signerinfo".
676 *
677 * This is expected to be included in outgoing signed
678 * messages for email (S/MIME) but is likely useful in other situations.
679 *
680 * This should only be added once; a second call will do nothing.
681 *
682 * XXX This will probably just shove the current time into "signerinfo"
683 * but it will not actually get signed until the entire item is
684 * processed for encoding. Is this (expected to be small) delay okay?
685 */
686extern SECStatus
687NSS_CMSSignerInfo_AddSigningTime(NSSCMSSignerInfo *signerinfo, PRTime t);
688
689/*
690 * NSS_CMSSignerInfo_AddSMIMECaps - add a SMIMECapabilities attribute to the
691 * authenticated (i.e. signed) attributes of "signerinfo".
692 *
693 * This is expected to be included in outgoing signed
694 * messages for email (S/MIME).
695 */
696extern SECStatus
697NSS_CMSSignerInfo_AddSMIMECaps(NSSCMSSignerInfo *signerinfo);
698
699/*
700 * NSS_CMSSignerInfo_AddSMIMEEncKeyPrefs - add a SMIMEEncryptionKeyPreferences attribute to the
701 * authenticated (i.e. signed) attributes of "signerinfo".
702 *
703 * This is expected to be included in outgoing signed messages for email (S/MIME).
704 */
705SECStatus
706NSS_CMSSignerInfo_AddSMIMEEncKeyPrefs(NSSCMSSignerInfo *signerinfo, CERTCertificate *cert, CERTCertDBHandle *certdb);
707
708/*
709 * NSS_CMSSignerInfo_AddMSSMIMEEncKeyPrefs - add a SMIMEEncryptionKeyPreferences attribute to the
710 * authenticated (i.e. signed) attributes of "signerinfo", using the OID preferred by Microsoft.
711 *
712 * This is expected to be included in outgoing signed messages for email (S/MIME),
713 * if compatibility with Microsoft mail clients is wanted.
714 */
715SECStatus
716NSS_CMSSignerInfo_AddMSSMIMEEncKeyPrefs(NSSCMSSignerInfo *signerinfo, CERTCertificate *cert, CERTCertDBHandle *certdb);
717
718/*
719 * NSS_CMSSignerInfo_AddCounterSignature - countersign a signerinfo
720 */
721extern SECStatus
722NSS_CMSSignerInfo_AddCounterSignature(NSSCMSSignerInfo *signerinfo,
723 SECOidTag digestalg, CERTCertificate signingcert);
724
725/*
726 * XXXX the following needs to be done in the S/MIME layer code
727 * after signature of a signerinfo is verified
728 */
729extern SECStatus
730NSS_SMIMESignerInfo_SaveSMIMEProfile(NSSCMSSignerInfo *signerinfo);
731
732/*
733 * NSS_CMSSignerInfo_IncludeCerts - set cert chain inclusion mode for this signer
734 */
735extern SECStatus
736NSS_CMSSignerInfo_IncludeCerts(NSSCMSSignerInfo *signerinfo, NSSCMSCertChainMode cm, SECCertUsage usage);
737
738/************************************************************************
739 * cmsenvdata.c - CMS envelopedData methods
740 ************************************************************************/
741
742/*
743 * NSS_CMSEnvelopedData_Create - create an enveloped data message
744 */
745extern NSSCMSEnvelopedData *
746NSS_CMSEnvelopedData_Create(NSSCMSMessage *cmsg, SECOidTag algorithm, int keysize);
747
748/*
749 * NSS_CMSEnvelopedData_Destroy - destroy an enveloped data message
750 */
751extern void
752NSS_CMSEnvelopedData_Destroy(NSSCMSEnvelopedData *edp);
753
754/*
755 * NSS_CMSEnvelopedData_GetContentInfo - return pointer to this envelopedData's contentinfo
756 */
757extern NSSCMSContentInfo *
758NSS_CMSEnvelopedData_GetContentInfo(NSSCMSEnvelopedData *envd);
759
760/*
761 * NSS_CMSEnvelopedData_AddRecipient - add a recipientinfo to the enveloped data msg
762 *
763 * rip must be created on the same pool as edp - this is not enforced, though.
764 */
765extern SECStatus
766NSS_CMSEnvelopedData_AddRecipient(NSSCMSEnvelopedData *edp, NSSCMSRecipientInfo *rip);
767
768/*
769 * NSS_CMSEnvelopedData_Encode_BeforeStart - prepare this envelopedData for encoding
770 *
771 * at this point, we need
772 * - recipientinfos set up with recipient's certificates
773 * - a content encryption algorithm (if none, 3DES will be used)
774 *
775 * this function will generate a random content encryption key (aka bulk key),
776 * initialize the recipientinfos with certificate identification and wrap the bulk key
777 * using the proper algorithm for every certificiate.
778 * it will finally set the bulk algorithm and key so that the encode step can find it.
779 */
780extern SECStatus
781NSS_CMSEnvelopedData_Encode_BeforeStart(NSSCMSEnvelopedData *envd);
782
783/*
784 * NSS_CMSEnvelopedData_Encode_BeforeData - set up encryption
785 */
786extern SECStatus
787NSS_CMSEnvelopedData_Encode_BeforeData(NSSCMSEnvelopedData *envd);
788
789/*
790 * NSS_CMSEnvelopedData_Encode_AfterData - finalize this envelopedData for encoding
791 */
792extern SECStatus
793NSS_CMSEnvelopedData_Encode_AfterData(NSSCMSEnvelopedData *envd);
794
795/*
796 * NSS_CMSEnvelopedData_Decode_BeforeData - find our recipientinfo,
797 * derive bulk key & set up our contentinfo
798 */
799extern SECStatus
800NSS_CMSEnvelopedData_Decode_BeforeData(NSSCMSEnvelopedData *envd);
801
802/*
803 * NSS_CMSEnvelopedData_Decode_AfterData - finish decrypting this envelopedData's content
804 */
805extern SECStatus
806NSS_CMSEnvelopedData_Decode_AfterData(NSSCMSEnvelopedData *envd);
807
808/*
809 * NSS_CMSEnvelopedData_Decode_AfterEnd - finish decoding this envelopedData
810 */
811extern SECStatus
812NSS_CMSEnvelopedData_Decode_AfterEnd(NSSCMSEnvelopedData *envd);
813
814/************************************************************************
815 * cmsrecinfo.c - CMS recipientInfo methods
816 ************************************************************************/
817
818/*
819 * NSS_CMSRecipientInfo_Create - create a recipientinfo
820 *
821 * we currently do not create KeyAgreement recipientinfos with multiple recipientEncryptedKeys
822 * the certificate is supposed to have been verified by the caller
823 */
824extern NSSCMSRecipientInfo *
825NSS_CMSRecipientInfo_Create(NSSCMSMessage *cmsg, CERTCertificate *cert);
826
827extern NSSCMSRecipientInfo *
828NSS_CMSRecipientInfo_CreateWithSubjKeyID(NSSCMSMessage *cmsg,
829 SECItem *subjKeyID,
830 SECKEYPublicKey *pubKey);
831
832extern NSSCMSRecipientInfo *
833NSS_CMSRecipientInfo_CreateWithSubjKeyIDFromCert(NSSCMSMessage *cmsg,
834 CERTCertificate *cert);
835
836/*
837 * NSS_CMSRecipientInfo_CreateNew - create a blank recipientinfo for
838 * applications which want to encode their own CMS structures and
839 * key exchange types.
840 */
841extern NSSCMSRecipientInfo *
842NSS_CMSRecipientInfo_CreateNew(void *pwfn_arg);
843
844/*
845 * NSS_CMSRecipientInfo_CreateFromDER - create a recipientinfo from partially
846 * decoded DER data for applications which want to encode their own CMS
847 * structures and key exchange types.
848 */
849extern NSSCMSRecipientInfo *
850NSS_CMSRecipientInfo_CreateFromDER(SECItem *input, void *pwfn_arg);
851
852extern void
853NSS_CMSRecipientInfo_Destroy(NSSCMSRecipientInfo *ri);
854
855/*
856 * NSS_CMSRecipientInfo_GetCertAndKey - retrieve the cert and key from the
857 * recipientInfo struct. If retcert or retkey are NULL, the cert or
858 * key (respectively) would not be returned). This function is a no-op if both
859 * retcert and retkey are NULL. Caller inherits ownership of the cert and key
860 * he requested (and is responsible to free them).
861 */
862SECStatus NSS_CMSRecipientInfo_GetCertAndKey(NSSCMSRecipientInfo *ri,
863 CERTCertificate **retcert,
864 SECKEYPrivateKey **retkey);
865
866extern int
867NSS_CMSRecipientInfo_GetVersion(NSSCMSRecipientInfo *ri);
868
869extern SECItem *
870NSS_CMSRecipientInfo_GetEncryptedKey(NSSCMSRecipientInfo *ri, int subIndex);
871
872/*
873 * NSS_CMSRecipientInfo_Encode - encode an NSS_CMSRecipientInfo as ASN.1
874 */
875SECStatus NSS_CMSRecipientInfo_Encode(PLArenaPool *poolp,
876 const NSSCMSRecipientInfo *src,
877 SECItem *returned);
878
879extern SECOidTag
880NSS_CMSRecipientInfo_GetKeyEncryptionAlgorithmTag(NSSCMSRecipientInfo *ri);
881
882extern SECStatus
883NSS_CMSRecipientInfo_WrapBulkKey(NSSCMSRecipientInfo *ri, PK11SymKey *bulkkey,
884 SECOidTag bulkalgtag);
885
886extern PK11SymKey *
887NSS_CMSRecipientInfo_UnwrapBulkKey(NSSCMSRecipientInfo *ri, int subIndex,
888 CERTCertificate *cert, SECKEYPrivateKey *privkey,
889 SECOidTag bulkalgtag);
890
891/************************************************************************
892 * cmsencdata.c - CMS encryptedData methods
893 ************************************************************************/
894/*
895 * NSS_CMSEncryptedData_Create - create an empty encryptedData object.
896 *
897 * "algorithm" specifies the bulk encryption algorithm to use.
898 * "keysize" is the key size.
899 *
900 * An error results in a return value of NULL and an error set.
901 * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
902 */
903extern NSSCMSEncryptedData *
904NSS_CMSEncryptedData_Create(NSSCMSMessage *cmsg, SECOidTag algorithm, int keysize);
905
906/*
907 * NSS_CMSEncryptedData_Destroy - destroy an encryptedData object
908 */
909extern void
910NSS_CMSEncryptedData_Destroy(NSSCMSEncryptedData *encd);
911
912/*
913 * NSS_CMSEncryptedData_GetContentInfo - return pointer to encryptedData object's contentInfo
914 */
915extern NSSCMSContentInfo *
916NSS_CMSEncryptedData_GetContentInfo(NSSCMSEncryptedData *encd);
917
918/*
919 * NSS_CMSEncryptedData_Encode_BeforeStart - do all the necessary things to a EncryptedData
920 * before encoding begins.
921 *
922 * In particular:
923 * - set the correct version value.
924 * - get the encryption key
925 */
926extern SECStatus
927NSS_CMSEncryptedData_Encode_BeforeStart(NSSCMSEncryptedData *encd);
928
929/*
930 * NSS_CMSEncryptedData_Encode_BeforeData - set up encryption
931 */
932extern SECStatus
933NSS_CMSEncryptedData_Encode_BeforeData(NSSCMSEncryptedData *encd);
934
935/*
936 * NSS_CMSEncryptedData_Encode_AfterData - finalize this encryptedData for encoding
937 */
938extern SECStatus
939NSS_CMSEncryptedData_Encode_AfterData(NSSCMSEncryptedData *encd);
940
941/*
942 * NSS_CMSEncryptedData_Decode_BeforeData - find bulk key & set up decryption
943 */
944extern SECStatus
945NSS_CMSEncryptedData_Decode_BeforeData(NSSCMSEncryptedData *encd);
946
947/*
948 * NSS_CMSEncryptedData_Decode_AfterData - finish decrypting this encryptedData's content
949 */
950extern SECStatus
951NSS_CMSEncryptedData_Decode_AfterData(NSSCMSEncryptedData *encd);
952
953/*
954 * NSS_CMSEncryptedData_Decode_AfterEnd - finish decoding this encryptedData
955 */
956extern SECStatus
957NSS_CMSEncryptedData_Decode_AfterEnd(NSSCMSEncryptedData *encd);
958
959/************************************************************************
960 * cmsdigdata.c - CMS encryptedData methods
961 ************************************************************************/
962/*
963 * NSS_CMSDigestedData_Create - create a digestedData object (presumably for encoding)
964 *
965 * version will be set by NSS_CMSDigestedData_Encode_BeforeStart
966 * digestAlg is passed as parameter
967 * contentInfo must be filled by the user
968 * digest will be calculated while encoding
969 */
970extern NSSCMSDigestedData *
971NSS_CMSDigestedData_Create(NSSCMSMessage *cmsg, SECAlgorithmID *digestalg);
972
973/*
974 * NSS_CMSDigestedData_Destroy - destroy a digestedData object
975 */
976extern void
977NSS_CMSDigestedData_Destroy(NSSCMSDigestedData *digd);
978
979/*
980 * NSS_CMSDigestedData_GetContentInfo - return pointer to digestedData object's contentInfo
981 */
982extern NSSCMSContentInfo *
983NSS_CMSDigestedData_GetContentInfo(NSSCMSDigestedData *digd);
984
985/*
986 * NSS_CMSDigestedData_Encode_BeforeStart - do all the necessary things to a DigestedData
987 * before encoding begins.
988 *
989 * In particular:
990 * - set the right version number. The contentInfo's content type must be set up already.
991 */
992extern SECStatus
993NSS_CMSDigestedData_Encode_BeforeStart(NSSCMSDigestedData *digd);
994
995/*
996 * NSS_CMSDigestedData_Encode_BeforeData - do all the necessary things to a DigestedData
997 * before the encapsulated data is passed through the encoder.
998 *
999 * In detail:
1000 * - set up the digests if necessary
1001 */
1002extern SECStatus
1003NSS_CMSDigestedData_Encode_BeforeData(NSSCMSDigestedData *digd);
1004
1005/*
1006 * NSS_CMSDigestedData_Encode_AfterData - do all the necessary things to a DigestedData
1007 * after all the encapsulated data was passed through the encoder.
1008 *
1009 * In detail:
1010 * - finish the digests
1011 */
1012extern SECStatus
1013NSS_CMSDigestedData_Encode_AfterData(NSSCMSDigestedData *digd);
1014
1015/*
1016 * NSS_CMSDigestedData_Decode_BeforeData - do all the necessary things to a DigestedData
1017 * before the encapsulated data is passed through the encoder.
1018 *
1019 * In detail:
1020 * - set up the digests if necessary
1021 */
1022extern SECStatus
1023NSS_CMSDigestedData_Decode_BeforeData(NSSCMSDigestedData *digd);
1024
1025/*
1026 * NSS_CMSDigestedData_Decode_AfterData - do all the necessary things to a DigestedData
1027 * after all the encapsulated data was passed through the encoder.
1028 *
1029 * In detail:
1030 * - finish the digests
1031 */
1032extern SECStatus
1033NSS_CMSDigestedData_Decode_AfterData(NSSCMSDigestedData *digd);
1034
1035/*
1036 * NSS_CMSDigestedData_Decode_AfterEnd - finalize a digestedData.
1037 *
1038 * In detail:
1039 * - check the digests for equality
1040 */
1041extern SECStatus
1042NSS_CMSDigestedData_Decode_AfterEnd(NSSCMSDigestedData *digd);
1043
1044/************************************************************************
1045 * cmsdigest.c - digestion routines
1046 ************************************************************************/
1047
1048/*
1049 * NSS_CMSDigestContext_StartMultiple - start digest calculation using all the
1050 * digest algorithms in "digestalgs" in parallel.
1051 */
1052extern NSSCMSDigestContext *
1053NSS_CMSDigestContext_StartMultiple(SECAlgorithmID **digestalgs);
1054
1055/*
1056 * NSS_CMSDigestContext_StartSingle - same as NSS_CMSDigestContext_StartMultiple, but
1057 * only one algorithm.
1058 */
1059extern NSSCMSDigestContext *
1060NSS_CMSDigestContext_StartSingle(SECAlgorithmID *digestalg);
1061
1062/*
1063 * NSS_CMSDigestContext_Update - feed more data into the digest machine
1064 */
1065extern void
1066NSS_CMSDigestContext_Update(NSSCMSDigestContext *cmsdigcx, const unsigned char *data, int len);
1067
1068/*
1069 * NSS_CMSDigestContext_Cancel - cancel digesting operation
1070 */
1071extern void
1072NSS_CMSDigestContext_Cancel(NSSCMSDigestContext *cmsdigcx);
1073
1074/*
1075 * NSS_CMSDigestContext_FinishMultiple - finish the digests and put them
1076 * into an array of SECItems (allocated on poolp)
1077 */
1078extern SECStatus
1079NSS_CMSDigestContext_FinishMultiple(NSSCMSDigestContext *cmsdigcx, PLArenaPool *poolp,
1080 SECItem ***digestsp);
1081
1082/*
1083 * NSS_CMSDigestContext_FinishSingle - same as NSS_CMSDigestContext_FinishMultiple,
1084 * but for one digest.
1085 */
1086extern SECStatus
1087NSS_CMSDigestContext_FinishSingle(NSSCMSDigestContext *cmsdigcx, PLArenaPool *poolp,
1088 SECItem *digest);
1089
1090/************************************************************************
1091 *
1092 ************************************************************************/
1093
1094/* shortcuts for basic use */
1095
1096/*
1097 * NSS_CMSDEREncode - DER Encode a CMS message, with input being
1098 * the plaintext message and derOut being the output,
1099 * stored in arena's pool.
1100 */
1101extern SECStatus
1102NSS_CMSDEREncode(NSSCMSMessage *cmsg, SECItem *input, SECItem *derOut,
1103 PLArenaPool *arena);
1104
1105/************************************************************************
1106 *
1107 ************************************************************************/
1108
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 */
1139SECStatus 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);
1149
1150/************************************************************************/
1151SEC_END_PROTOS
1152
1153#endif /* _CMS_H_ */
1154

source code of include/nss/cms.h