OSX/libsecurity_smime/lib/cmslocal.h

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