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 * Support routines for CMS implementation, none of which are exported.
36 *
37 * Do not export this file!  If something in here is really needed outside
38 * of smime code, first try to add a CMS interface which will do it for
39 * you.  If that has a problem, then just move out what you need, changing
40 * its name as appropriate!
41 */
42
43#ifndef _CMSLOCAL_H_
44#define _CMSLOCAL_H_
45
46#include "cmspriv.h"
47#include "cmsreclist.h"
48#include <Security/secasn1t.h>
49
50extern const SecAsn1Template SecCmsIssuerAndSNTemplate[];
51extern const SecAsn1Template SecCmsContentInfoTemplate[];
52
53/************************************************************************/
54SEC_BEGIN_PROTOS
55
56/***********************************************************************
57 * cmscipher.c - en/decryption routines
58 ***********************************************************************/
59
60/*
61 * SecCmsCipherContextStartDecrypt - create a cipher context to do decryption
62 * based on the given bulk * encryption key and algorithm identifier (which may include an iv).
63 */
64extern SecCmsCipherContextRef
65SecCmsCipherContextStartDecrypt(SecSymmetricKeyRef key, SECAlgorithmID *algid);
66
67/*
68 * SecCmsCipherContextStartEncrypt - create a cipher object to do encryption,
69 * based on the given bulk encryption key and algorithm tag.  Fill in the algorithm
70 * identifier (which may include an iv) appropriately.
71 */
72extern SecCmsCipherContextRef
73SecCmsCipherContextStartEncrypt(PRArenaPool *poolp, SecSymmetricKeyRef key, SECAlgorithmID *algid);
74
75extern void
76SecCmsCipherContextDestroy(SecCmsCipherContextRef cc);
77
78/*
79 * SecCmsCipherContextDecryptLength - find the output length of the next call to decrypt.
80 *
81 * cc - the cipher context
82 * input_len - number of bytes used as input
83 * final - true if this is the final chunk of data
84 *
85 * Result can be used to perform memory allocations.  Note that the amount
86 * is exactly accurate only when not doing a block cipher or when final
87 * is false, otherwise it is an upper bound on the amount because until
88 * we see the data we do not know how many padding bytes there are
89 * (always between 1 and bsize).
90 */
91extern size_t
92SecCmsCipherContextDecryptLength(SecCmsCipherContextRef cc, size_t input_len, Boolean final);
93
94/*
95 * SecCmsCipherContextEncryptLength - find the output length of the next call to encrypt.
96 *
97 * cc - the cipher context
98 * input_len - number of bytes used as input
99 * final - true if this is the final chunk of data
100 *
101 * Result can be used to perform memory allocations.
102 */
103extern size_t
104SecCmsCipherContextEncryptLength(SecCmsCipherContextRef cc, size_t input_len, Boolean final);
105
106/*
107 * SecCmsCipherContextDecrypt - do the decryption
108 *
109 * cc - the cipher context
110 * output - buffer for decrypted result bytes
111 * output_len_p - number of bytes in output
112 * max_output_len - upper bound on bytes to put into output
113 * input - pointer to input bytes
114 * input_len - number of input bytes
115 * final - true if this is the final chunk of data
116 *
117 * Decrypts a given length of input buffer (starting at "input" and
118 * containing "input_len" bytes), placing the decrypted bytes in
119 * "output" and storing the output length in "*output_len_p".
120 * "cc" is the return value from SecCmsCipherStartDecrypt.
121 * When "final" is true, this is the last of the data to be decrypted.
122 */
123extern OSStatus
124SecCmsCipherContextDecrypt(SecCmsCipherContextRef cc, unsigned char *output,
125		  size_t *output_len_p, size_t max_output_len,
126		  const unsigned char *input, size_t input_len,
127		  Boolean final);
128
129/*
130 * SecCmsCipherContextEncrypt - do the encryption
131 *
132 * cc - the cipher context
133 * output - buffer for decrypted result bytes
134 * output_len_p - number of bytes in output
135 * max_output_len - upper bound on bytes to put into output
136 * input - pointer to input bytes
137 * input_len - number of input bytes
138 * final - true if this is the final chunk of data
139 *
140 * Encrypts a given length of input buffer (starting at "input" and
141 * containing "input_len" bytes), placing the encrypted bytes in
142 * "output" and storing the output length in "*output_len_p".
143 * "cc" is the return value from SecCmsCipherStartEncrypt.
144 * When "final" is true, this is the last of the data to be encrypted.
145 */
146extern OSStatus
147SecCmsCipherContextEncrypt(SecCmsCipherContextRef cc, unsigned char *output,
148		  size_t *output_len_p, size_t max_output_len,
149		  const unsigned char *input, size_t input_len,
150		  Boolean final);
151
152/************************************************************************
153 * cmspubkey.c - public key operations
154 ************************************************************************/
155
156/*
157 * SecCmsUtilEncryptSymKeyRSA - wrap a symmetric key with RSA
158 *
159 * this function takes a symmetric key and encrypts it using an RSA public key
160 * according to PKCS#1 and RFC2633 (S/MIME)
161 */
162extern OSStatus
163SecCmsUtilEncryptSymKeyRSA(PLArenaPool *poolp, SecCertificateRef cert,
164                              SecSymmetricKeyRef key,
165                              CSSM_DATA_PTR encKey);
166
167extern OSStatus
168SecCmsUtilEncryptSymKeyRSAPubKey(PLArenaPool *poolp,
169                                    SecPublicKeyRef publickey,
170                                    SecSymmetricKeyRef bulkkey, CSSM_DATA_PTR encKey);
171
172/*
173 * SecCmsUtilDecryptSymKeyRSA - unwrap a RSA-wrapped symmetric key
174 *
175 * this function takes an RSA-wrapped symmetric key and unwraps it, returning a symmetric
176 * key handle. Please note that the actual unwrapped key data may not be allowed to leave
177 * a hardware token...
178 */
179extern SecSymmetricKeyRef
180SecCmsUtilDecryptSymKeyRSA(SecPrivateKeyRef privkey, CSSM_DATA_PTR encKey, SECOidTag bulkalgtag);
181
182extern OSStatus
183SecCmsUtilEncryptSymKeyECDH(PLArenaPool *poolp, SecCertificateRef cert, SecSymmetricKeyRef key,
184			CSSM_DATA_PTR encKey, CSSM_DATA_PTR ukm, SECAlgorithmID *keyEncAlg,
185			CSSM_DATA_PTR originatorPubKey);
186
187extern SecSymmetricKeyRef
188SecCmsUtilDecryptSymKeyECDH(SecPrivateKeyRef privkey, CSSM_DATA_PTR encKey, CSSM_DATA_PTR ukm,
189    SECAlgorithmID *keyEncAlg, SECOidTag bulkalgtag, CSSM_DATA_PTR pubKey);
190
191#if 0
192extern OSStatus
193SecCmsUtilEncryptSymKeyMISSI(PLArenaPool *poolp, SecCertificateRef cert, SecSymmetricKeyRef key,
194			SECOidTag symalgtag, CSSM_DATA_PTR encKey, CSSM_DATA_PTR *pparams, void *pwfn_arg);
195
196extern SecSymmetricKeyRef
197SecCmsUtilDecryptSymKeyMISSI(SecPrivateKeyRef privkey, CSSM_DATA_PTR encKey,
198			SECAlgorithmID *keyEncAlg, SECOidTag bulkalgtag, void *pwfn_arg);
199
200extern OSStatus
201SecCmsUtilEncryptSymKeyESDH(PLArenaPool *poolp, SecCertificateRef cert, SecSymmetricKeyRef key,
202			CSSM_DATA_PTR encKey, CSSM_DATA_PTR ukm, SECAlgorithmID *keyEncAlg,
203			CSSM_DATA_PTR originatorPubKey);
204
205extern SecSymmetricKeyRef
206SecCmsUtilDecryptSymKeyESDH(SecPrivateKeyRef privkey, CSSM_DATA_PTR encKey,
207			SECAlgorithmID *keyEncAlg, SECOidTag bulkalgtag, void *pwfn_arg);
208#endif
209
210/************************************************************************
211 * cmsreclist.c - recipient list stuff
212 ************************************************************************/
213extern SecCmsRecipient **nss_cms_recipient_list_create(SecCmsRecipientInfoRef *recipientinfos);
214extern void nss_cms_recipient_list_destroy(SecCmsRecipient **recipient_list);
215extern SecCmsRecipientEncryptedKey *SecCmsRecipientEncryptedKeyCreate(PLArenaPool *poolp);
216
217/************************************************************************
218 * cmsarray.c - misc array functions
219 ************************************************************************/
220/*
221 * SecCmsArrayAlloc - allocate an array in an arena
222 */
223extern void **
224SecCmsArrayAlloc(PRArenaPool *poolp, int n);
225
226/*
227 * SecCmsArrayAdd - add an element to the end of an array
228 */
229extern OSStatus
230SecCmsArrayAdd(PRArenaPool *poolp, void ***array, void *obj);
231
232/*
233 * SecCmsArrayIsEmpty - check if array is empty
234 */
235extern Boolean
236SecCmsArrayIsEmpty(void **array);
237
238/*
239 * SecCmsArrayCount - count number of elements in array
240 */
241extern int
242SecCmsArrayCount(void **array);
243
244/*
245 * SecCmsArraySort - sort an array ascending, in place
246 *
247 * If "secondary" is not NULL, the same reordering gets applied to it.
248 * If "tertiary" is not NULL, the same reordering gets applied to it.
249 * "compare" is a function that returns
250 *  < 0 when the first element is less than the second
251 *  = 0 when the first element is equal to the second
252 *  > 0 when the first element is greater than the second
253 */
254extern void
255SecCmsArraySort(void **primary, int (*compare)(void *,void *), void **secondary, void **tertiary);
256
257/************************************************************************
258 * cmsattr.c - misc attribute functions
259 ************************************************************************/
260/*
261 * SecCmsAttributeCreate - create an attribute
262 *
263 * if value is NULL, the attribute won't have a value. It can be added later
264 * with SecCmsAttributeAddValue.
265 */
266extern SecCmsAttribute *
267SecCmsAttributeCreate(PRArenaPool *poolp, SECOidTag oidtag, CSSM_DATA_PTR value, Boolean encoded);
268
269/*
270 * SecCmsAttributeAddValue - add another value to an attribute
271 */
272extern OSStatus
273SecCmsAttributeAddValue(PLArenaPool *poolp, SecCmsAttribute *attr, CSSM_DATA_PTR value);
274
275/*
276 * SecCmsAttributeGetType - return the OID tag
277 */
278extern SECOidTag
279SecCmsAttributeGetType(SecCmsAttribute *attr);
280
281/*
282 * SecCmsAttributeGetValue - return the first attribute value
283 *
284 * We do some sanity checking first:
285 * - Multiple values are *not* expected.
286 * - Empty values are *not* expected.
287 */
288extern CSSM_DATA_PTR
289SecCmsAttributeGetValue(SecCmsAttribute *attr);
290
291/*
292 * SecCmsAttributeCompareValue - compare the attribute's first value against data
293 */
294extern Boolean
295SecCmsAttributeCompareValue(SecCmsAttribute *attr, CSSM_DATA_PTR av);
296
297/*
298 * SecCmsAttributeArrayEncode - encode an Attribute array as SET OF Attributes
299 *
300 * If you are wondering why this routine does not reorder the attributes
301 * first, and might be tempted to make it do so, see the comment by the
302 * call to ReorderAttributes in cmsencode.c.  (Or, see who else calls this
303 * and think long and hard about the implications of making it always
304 * do the reordering.)
305 */
306extern CSSM_DATA_PTR
307SecCmsAttributeArrayEncode(PRArenaPool *poolp, SecCmsAttribute ***attrs, CSSM_DATA_PTR dest);
308
309/*
310 * SecCmsAttributeArrayReorder - sort attribute array by attribute's DER encoding
311 *
312 * make sure that the order of the attributes guarantees valid DER (which must be
313 * in lexigraphically ascending order for a SET OF); if reordering is necessary it
314 * will be done in place (in attrs).
315 */
316extern OSStatus
317SecCmsAttributeArrayReorder(SecCmsAttribute **attrs);
318
319/*
320 * SecCmsAttributeArrayFindAttrByOidTag - look through a set of attributes and
321 * find one that matches the specified object ID.
322 *
323 * If "only" is true, then make sure that there is not more than one attribute
324 * of the same type.  Otherwise, just return the first one found. (XXX Does
325 * anybody really want that first-found behavior?  It was like that when I found it...)
326 */
327extern SecCmsAttribute *
328SecCmsAttributeArrayFindAttrByOidTag(SecCmsAttribute **attrs, SECOidTag oidtag, Boolean only);
329
330/*
331 * SecCmsAttributeArrayAddAttr - add an attribute to an
332 * array of attributes.
333 */
334extern OSStatus
335SecCmsAttributeArrayAddAttr(PLArenaPool *poolp, SecCmsAttribute ***attrs, SecCmsAttribute *attr);
336
337/*
338 * SecCmsAttributeArraySetAttr - set an attribute's value in a set of attributes
339 */
340extern OSStatus
341SecCmsAttributeArraySetAttr(PLArenaPool *poolp, SecCmsAttribute ***attrs, SECOidTag type, CSSM_DATA_PTR value, Boolean encoded);
342
343/************************************************************************/
344SEC_END_PROTOS
345
346#endif /* _CMSLOCAL_H_ */
347