1/*
2 * The contents of this file are subject to the Mozilla Public
3 * License Version 1.1 (the "License"); you may not use this file
4 * except in compliance with the License. You may obtain a copy of
5 * the License at http://www.mozilla.org/MPL/
6 *
7 * Software distributed under the License is distributed on an "AS
8 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
9 * implied. See the License for the specific language governing
10 * rights and limitations under the License.
11 *
12 * The Original Code is the Netscape security libraries.
13 *
14 * The Initial Developer of the Original Code is Netscape
15 * Communications Corporation.  Portions created by Netscape are
16 * Copyright (C) 1994-2000 Netscape Communications Corporation.  All
17 * Rights Reserved.
18 *
19 * Contributor(s):
20 *
21 * Alternatively, the contents of this file may be used under the
22 * terms of the GNU General Public License Version 2 or later (the
23 * "GPL"), in which case the provisions of the GPL are applicable
24 * instead of those above.  If you wish to allow use of your
25 * version of this file only under the terms of the GPL and not to
26 * allow others to use your version of this file under the MPL,
27 * indicate your decision by deleting the provisions above and
28 * replace them with the notice and other provisions required by
29 * the GPL.  If you do not delete the provisions above, a recipient
30 * may use your version of this file under either the MPL or the
31 * GPL.
32 */
33
34/*
35 * Interfaces of the CMS implementation.
36 */
37
38#ifndef _CMSPRIV_H_
39#define _CMSPRIV_H_
40
41#include <Security/SecTrust.h>
42#include <security_asn1/seccomon.h> // SEC_BEGIN_PROTOS
43#include "cmstpriv.h"
44
45/************************************************************************/
46SEC_BEGIN_PROTOS
47
48/************************************************************************
49 * cmsutil.c - CMS misc utility functions
50 ************************************************************************/
51
52
53/*
54 * SecCmsArraySortByDER - sort array of objects by objects' DER encoding
55 *
56 * make sure that the order of the objects guarantees valid DER (which must be
57 * in lexigraphically ascending order for a SET OF); if reordering is necessary it
58 * will be done in place (in objs).
59 */
60extern OSStatus
61SecCmsArraySortByDER(void **objs, const SecAsn1Template *objtemplate, void **objs2);
62
63/*
64 * SecCmsUtilDERCompare - for use with SecCmsArraySort to
65 *  sort arrays of SecAsn1Items containing DER
66 */
67extern int
68SecCmsUtilDERCompare(void *a, void *b);
69
70/*
71 * SecCmsAlgArrayGetIndexByAlgID - find a specific algorithm in an array of
72 * algorithms.
73 *
74 * algorithmArray - array of algorithm IDs
75 * algid - algorithmid of algorithm to pick
76 *
77 * Returns:
78 *  An integer containing the index of the algorithm in the array or -1 if
79 *  algorithm was not found.
80 */
81extern int
82SecCmsAlgArrayGetIndexByAlgID(SECAlgorithmID **algorithmArray, SECAlgorithmID *algid);
83
84/*
85 * SecCmsAlgArrayGetIndexByAlgID - find a specific algorithm in an array of
86 * algorithms.
87 *
88 * algorithmArray - array of algorithm IDs
89 * algiddata - id of algorithm to pick
90 *
91 * Returns:
92 *  An integer containing the index of the algorithm in the array or -1 if
93 *  algorithm was not found.
94 */
95extern int
96SecCmsAlgArrayGetIndexByAlgTag(SECAlgorithmID **algorithmArray, SECOidTag algtag);
97
98#if USE_CDSA_CRYPTO
99extern CSSM_CC_HANDLE
100#else
101extern void *
102#endif
103SecCmsUtilGetHashObjByAlgID(SECAlgorithmID *algid);
104
105/*
106 * XXX I would *really* like to not have to do this, but the current
107 * signing interface gives me little choice.
108 */
109extern SECOidTag
110SecCmsUtilMakeSignatureAlgorithm(SECOidTag hashalg, SECOidTag encalg);
111
112extern const SecAsn1Template *
113SecCmsUtilGetTemplateByTypeTag(SECOidTag type);
114
115extern size_t
116SecCmsUtilGetSizeByTypeTag(SECOidTag type);
117
118extern SecCmsContentInfoRef
119SecCmsContentGetContentInfo(void *msg, SECOidTag type);
120
121/************************************************************************
122* cmsmessage.c - CMS message methods
123************************************************************************/
124
125/*!
126@function
127 @abstract Set up a CMS message object for encoding or decoding.
128 @discussion used internally.
129 @param cmsg Pointer to a SecCmsMessage object
130 @param pwfn callback function for getting token password for enveloped
131 data content with a password recipient.
132 @param pwfn_arg first argument passed to pwfn when it is called.
133 @param encrypt_key_cb callback function for getting bulk key for encryptedData content.
134 @param encrypt_key_cb_arg first argument passed to encrypt_key_cb when it is
135 called.
136 @param detached_digestalgs digest algorithms in detached_digests
137 @param detached_digests digests from detached content (one for every element
138                                                        in detached_digestalgs).
139 */
140extern void
141SecCmsMessageSetEncodingParams(SecCmsMessageRef cmsg,
142                               PK11PasswordFunc pwfn, void *pwfn_arg,
143                               SecCmsGetDecryptKeyCallback encrypt_key_cb, void *encrypt_key_cb_arg);
144
145/************************************************************************
146 * cmscinfo.c - CMS contentInfo methods
147 ************************************************************************/
148
149/*!
150    Destroy a CMS contentInfo and all of its sub-pieces.
151    @param cinfo The contentInfo object to destroy.
152 */
153extern void
154SecCmsContentInfoDestroy(SecCmsContentInfoRef cinfo);
155
156/*
157 * SecCmsContentInfoSetContent - set cinfo's content type & content to CMS object
158 */
159extern OSStatus
160SecCmsContentInfoSetContent(SecCmsContentInfoRef cinfo, SECOidTag type, void *ptr);
161
162
163/************************************************************************
164 * cmssigdata.c - CMS signedData methods
165 ************************************************************************/
166
167extern OSStatus
168SecCmsSignedDataSetDigestValue(SecCmsSignedDataRef sigd,
169				SECOidTag digestalgtag,
170				SecAsn1Item * digestdata);
171
172extern OSStatus
173SecCmsSignedDataAddDigest(PRArenaPool *poolp,
174				SecCmsSignedDataRef sigd,
175				SECOidTag digestalgtag,
176				SecAsn1Item * digest);
177
178extern SecAsn1Item *
179SecCmsSignedDataGetDigestByAlgTag(SecCmsSignedDataRef sigd, SECOidTag algtag);
180
181extern SecAsn1Item *
182SecCmsSignedDataGetDigestValue(SecCmsSignedDataRef sigd, SECOidTag digestalgtag);
183
184/*!
185    @function
186 */
187extern OSStatus
188SecCmsSignedDataAddSignerInfo(SecCmsSignedDataRef sigd,
189				SecCmsSignerInfoRef signerinfo);
190
191/*!
192	@function
193 */
194extern OSStatus
195SecCmsSignedDataSetDigests(SecCmsSignedDataRef sigd,
196				SECAlgorithmID **digestalgs,
197				SecAsn1Item * *digests);
198
199/*
200 * SecCmsSignedDataEncodeBeforeStart - do all the necessary things to a SignedData
201 *     before start of encoding.
202 *
203 * In detail:
204 *  - find out about the right value to put into sigd->version
205 *  - come up with a list of digestAlgorithms (which should be the union of the algorithms
206 *         in the signerinfos).
207 *         If we happen to have a pre-set list of algorithms (and digest values!), we
208 *         check if we have all the signerinfos' algorithms. If not, this is an error.
209 */
210extern OSStatus
211SecCmsSignedDataEncodeBeforeStart(SecCmsSignedDataRef sigd);
212
213extern OSStatus
214SecCmsSignedDataEncodeBeforeData(SecCmsSignedDataRef sigd);
215
216/*
217 * SecCmsSignedDataEncodeAfterData - do all the necessary things to a SignedData
218 *     after all the encapsulated data was passed through the encoder.
219 *
220 * In detail:
221 *  - create the signatures in all the SignerInfos
222 *
223 * Please note that nothing is done to the Certificates and CRLs in the message - this
224 * is entirely the responsibility of our callers.
225 */
226extern OSStatus
227SecCmsSignedDataEncodeAfterData(SecCmsSignedDataRef sigd);
228
229extern OSStatus
230SecCmsSignedDataDecodeBeforeData(SecCmsSignedDataRef sigd);
231
232/*
233 * SecCmsSignedDataDecodeAfterData - do all the necessary things to a SignedData
234 *     after all the encapsulated data was passed through the decoder.
235 */
236extern OSStatus
237SecCmsSignedDataDecodeAfterData(SecCmsSignedDataRef sigd);
238
239/*
240 * SecCmsSignedDataDecodeAfterEnd - do all the necessary things to a SignedData
241 *     after all decoding is finished.
242 */
243extern OSStatus
244SecCmsSignedDataDecodeAfterEnd(SecCmsSignedDataRef sigd);
245
246
247/************************************************************************
248 * cmssiginfo.c - CMS signerInfo methods
249 ************************************************************************/
250
251/*
252 * SecCmsSignerInfoSign - sign something
253 *
254 */
255extern OSStatus
256SecCmsSignerInfoSign(SecCmsSignerInfoRef signerinfo, SecAsn1Item * digest, SecAsn1Item * contentType);
257
258/*
259 * If trustRef is NULL the cert chain is verified and the VerificationStatus is set accordingly.
260 * Otherwise a SecTrust object is returned for the caller to evaluate using SecTrustEvaluate().
261 */
262extern OSStatus
263SecCmsSignerInfoVerifyCertificate(SecCmsSignerInfoRef signerinfo, SecKeychainRef keychainOrArray,
264				  CFTypeRef policies, SecTrustRef *trustRef);
265
266/*
267 * SecCmsSignerInfoVerify - verify the signature of a single SignerInfo
268 *
269 * Just verifies the signature. The assumption is that verification of the certificate
270 * is done already.
271 */
272extern OSStatus
273SecCmsSignerInfoVerify(SecCmsSignerInfoRef signerinfo, SecAsn1Item * digest, SecAsn1Item * contentType);
274
275/*
276 * SecCmsSignerInfoAddAuthAttr - add an attribute to the
277 * authenticated (i.e. signed) attributes of "signerinfo".
278 */
279extern OSStatus
280SecCmsSignerInfoAddAuthAttr(SecCmsSignerInfoRef signerinfo, SecCmsAttribute *attr);
281
282/*
283 * SecCmsSignerInfoAddUnauthAttr - add an attribute to the
284 * unauthenticated attributes of "signerinfo".
285 */
286extern OSStatus
287SecCmsSignerInfoAddUnauthAttr(SecCmsSignerInfoRef signerinfo, SecCmsAttribute *attr);
288
289extern int
290SecCmsSignerInfoGetVersion(SecCmsSignerInfoRef signerinfo);
291
292/*!
293    @function
294    @abstract Destroy a SignerInfo data structure.
295 */
296extern void
297SecCmsSignerInfoDestroy(SecCmsSignerInfoRef si);
298
299
300/************************************************************************
301 * cmsenvdata.c - CMS envelopedData methods
302 ************************************************************************/
303
304/*!
305    @function
306    @abstract Add a recipientinfo to the enveloped data msg.
307    @discussion Rip must be created on the same pool as edp - this is not enforced, though.
308 */
309extern OSStatus
310SecCmsEnvelopedDataAddRecipient(SecCmsEnvelopedDataRef edp, SecCmsRecipientInfoRef rip);
311
312/*
313 * SecCmsEnvelopedDataEncodeBeforeStart - prepare this envelopedData for encoding
314 *
315 * at this point, we need
316 * - recipientinfos set up with recipient's certificates
317 * - a content encryption algorithm (if none, 3DES will be used)
318 *
319 * this function will generate a random content encryption key (aka bulk key),
320 * initialize the recipientinfos with certificate identification and wrap the bulk key
321 * using the proper algorithm for every certificiate.
322 * it will finally set the bulk algorithm and key so that the encode step can find it.
323 */
324extern OSStatus
325SecCmsEnvelopedDataEncodeBeforeStart(SecCmsEnvelopedDataRef envd);
326
327/*
328 * SecCmsEnvelopedDataEncodeBeforeData - set up encryption
329 */
330extern OSStatus
331SecCmsEnvelopedDataEncodeBeforeData(SecCmsEnvelopedDataRef envd);
332
333/*
334 * SecCmsEnvelopedDataEncodeAfterData - finalize this envelopedData for encoding
335 */
336extern OSStatus
337SecCmsEnvelopedDataEncodeAfterData(SecCmsEnvelopedDataRef envd);
338
339/*
340 * SecCmsEnvelopedDataDecodeBeforeData - find our recipientinfo,
341 * derive bulk key & set up our contentinfo
342 */
343extern OSStatus
344SecCmsEnvelopedDataDecodeBeforeData(SecCmsEnvelopedDataRef envd);
345
346/*
347 * SecCmsEnvelopedDataDecodeAfterData - finish decrypting this envelopedData's content
348 */
349extern OSStatus
350SecCmsEnvelopedDataDecodeAfterData(SecCmsEnvelopedDataRef envd);
351
352/*
353 * SecCmsEnvelopedDataDecodeAfterEnd - finish decoding this envelopedData
354 */
355extern OSStatus
356SecCmsEnvelopedDataDecodeAfterEnd(SecCmsEnvelopedDataRef envd);
357
358
359/************************************************************************
360 * cmsrecinfo.c - CMS recipientInfo methods
361 ************************************************************************/
362
363extern int
364SecCmsRecipientInfoGetVersion(SecCmsRecipientInfoRef ri);
365
366extern SecAsn1Item *
367SecCmsRecipientInfoGetEncryptedKey(SecCmsRecipientInfoRef ri, int subIndex);
368
369
370extern SECOidTag
371SecCmsRecipientInfoGetKeyEncryptionAlgorithmTag(SecCmsRecipientInfoRef ri);
372
373extern OSStatus
374SecCmsRecipientInfoWrapBulkKey(SecCmsRecipientInfoRef ri, SecSymmetricKeyRef bulkkey, SECOidTag bulkalgtag);
375
376extern SecSymmetricKeyRef
377SecCmsRecipientInfoUnwrapBulkKey(SecCmsRecipientInfoRef ri, int subIndex,
378		SecCertificateRef cert, SecPrivateKeyRef privkey, SECOidTag bulkalgtag);
379
380/*!
381    @function
382 */
383extern void
384SecCmsRecipientInfoDestroy(SecCmsRecipientInfoRef ri);
385
386
387/************************************************************************
388 * cmsencdata.c - CMS encryptedData methods
389 ************************************************************************/
390
391/*
392 * SecCmsEncryptedDataEncodeBeforeStart - do all the necessary things to a EncryptedData
393 *     before encoding begins.
394 *
395 * In particular:
396 *  - set the correct version value.
397 *  - get the encryption key
398 */
399extern OSStatus
400SecCmsEncryptedDataEncodeBeforeStart(SecCmsEncryptedDataRef encd);
401
402/*
403 * SecCmsEncryptedDataEncodeBeforeData - set up encryption
404 */
405extern OSStatus
406SecCmsEncryptedDataEncodeBeforeData(SecCmsEncryptedDataRef encd);
407
408/*
409 * SecCmsEncryptedDataEncodeAfterData - finalize this encryptedData for encoding
410 */
411extern OSStatus
412SecCmsEncryptedDataEncodeAfterData(SecCmsEncryptedDataRef encd);
413
414/*
415 * SecCmsEncryptedDataDecodeBeforeData - find bulk key & set up decryption
416 */
417extern OSStatus
418SecCmsEncryptedDataDecodeBeforeData(SecCmsEncryptedDataRef encd);
419
420/*
421 * SecCmsEncryptedDataDecodeAfterData - finish decrypting this encryptedData's content
422 */
423extern OSStatus
424SecCmsEncryptedDataDecodeAfterData(SecCmsEncryptedDataRef encd);
425
426/*
427 * SecCmsEncryptedDataDecodeAfterEnd - finish decoding this encryptedData
428 */
429extern OSStatus
430SecCmsEncryptedDataDecodeAfterEnd(SecCmsEncryptedDataRef encd);
431
432
433/************************************************************************
434 * cmsdigdata.c - CMS encryptedData methods
435 ************************************************************************/
436
437/*
438 * SecCmsDigestedDataEncodeBeforeStart - do all the necessary things to a DigestedData
439 *     before encoding begins.
440 *
441 * In particular:
442 *  - set the right version number. The contentInfo's content type must be set up already.
443 */
444extern OSStatus
445SecCmsDigestedDataEncodeBeforeStart(SecCmsDigestedDataRef digd);
446
447/*
448 * SecCmsDigestedDataEncodeBeforeData - do all the necessary things to a DigestedData
449 *     before the encapsulated data is passed through the encoder.
450 *
451 * In detail:
452 *  - set up the digests if necessary
453 */
454extern OSStatus
455SecCmsDigestedDataEncodeBeforeData(SecCmsDigestedDataRef digd);
456
457/*
458 * SecCmsDigestedDataEncodeAfterData - do all the necessary things to a DigestedData
459 *     after all the encapsulated data was passed through the encoder.
460 *
461 * In detail:
462 *  - finish the digests
463 */
464extern OSStatus
465SecCmsDigestedDataEncodeAfterData(SecCmsDigestedDataRef digd);
466
467/*
468 * SecCmsDigestedDataDecodeBeforeData - do all the necessary things to a DigestedData
469 *     before the encapsulated data is passed through the encoder.
470 *
471 * In detail:
472 *  - set up the digests if necessary
473 */
474extern OSStatus
475SecCmsDigestedDataDecodeBeforeData(SecCmsDigestedDataRef digd);
476
477/*
478 * SecCmsDigestedDataDecodeAfterData - do all the necessary things to a DigestedData
479 *     after all the encapsulated data was passed through the encoder.
480 *
481 * In detail:
482 *  - finish the digests
483 */
484extern OSStatus
485SecCmsDigestedDataDecodeAfterData(SecCmsDigestedDataRef digd);
486
487/*
488 * SecCmsDigestedDataDecodeAfterEnd - finalize a digestedData.
489 *
490 * In detail:
491 *  - check the digests for equality
492 */
493extern OSStatus
494SecCmsDigestedDataDecodeAfterEnd(SecCmsDigestedDataRef digd);
495
496
497/************************************************************************
498 * cmsdigest.c - CMS encryptedData methods
499 ************************************************************************/
500
501/*
502 * SecCmsDigestContextStartSingle - same as SecCmsDigestContextStartMultiple, but
503 *  only one algorithm.
504 */
505extern SecCmsDigestContextRef
506SecCmsDigestContextStartSingle(SECAlgorithmID *digestalg);
507
508/*
509 * SecCmsDigestContextFinishSingle - same as SecCmsDigestContextFinishMultiple,
510 *  but for one digest.
511 */
512extern OSStatus
513SecCmsDigestContextFinishSingle(SecCmsDigestContextRef cmsdigcx,
514			    SecAsn1Item * digest);
515
516/*!
517    @function
518    @abstract Finish the digests being calculated and put them into to parralel
519		arrays of SecAsn1Items.
520    @param cmsdigcx A DigestContext object.
521    @param digestalgsp will contain a to an array of digest algorithms on
522		success.
523    @param digestsp A EncryptedData object to set as the content of the cinfo
524		object.
525    @result A result code. See "SecCmsBase.h" for possible results.
526    @discussion This function requires a DigestContext object which can be made
527		by calling SecCmsDigestContextStartSingle or
528		SecCmsDigestContextStartMultiple.  The returned arrays remain valid
529		until SecCmsDigestContextDestroy is called.
530    @availability 10.4 and later
531 */
532extern OSStatus
533SecCmsDigestContextFinishMultiple(SecCmsDigestContextRef cmsdigcx,
534			    SECAlgorithmID ***digestalgsp,
535			    SecAsn1Item * **digestsp);
536
537
538/************************************************************************/
539SEC_END_PROTOS
540
541#endif /* _CMSPRIV_H_ */
542