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 extern const SecAsn1Template SecCmsContentInfoTemplate[];
  52
  53 /************************************************************************/
  54 SEC_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  */
  64 extern SecCmsCipherContextRef
  65 SecCmsCipherContextStartDecrypt(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  */
  72 extern SecCmsCipherContextRef
  73 SecCmsCipherContextStartEncrypt(PRArenaPool *poolp, SecSymmetricKeyRef key, SECAlgorithmID *algid);
  74
  75 extern void
  76 SecCmsCipherContextDestroy(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  */
  91 extern size_t
  92 SecCmsCipherContextDecryptLength(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  */
 103 extern size_t
 104 SecCmsCipherContextEncryptLength(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  */
 123 extern OSStatus
 124 SecCmsCipherContextDecrypt(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  */
 146 extern OSStatus
 147 SecCmsCipherContextEncrypt(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  */
 162 extern OSStatus
 163 SecCmsUtilEncryptSymKeyRSA(PLArenaPool *poolp, SecCertificateRef cert,
 164                               SecSymmetricKeyRef key,
 165                               CSSM_DATA_PTR encKey);
 166
 167 extern OSStatus
 168 SecCmsUtilEncryptSymKeyRSAPubKey(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  */
 179 extern SecSymmetricKeyRef
 180 SecCmsUtilDecryptSymKeyRSA(SecPrivateKeyRef privkey, CSSM_DATA_PTR encKey, SECOidTag bulkalgtag);
 181
 182 extern OSStatus
 183 SecCmsUtilEncryptSymKeyECDH(PLArenaPool *poolp, SecCertificateRef cert, SecSymmetricKeyRef key,
 184                         CSSM_DATA_PTR encKey, CSSM_DATA_PTR ukm, SECAlgorithmID *keyEncAlg,
 185                         CSSM_DATA_PTR originatorPubKey);
 186
 187 extern SecSymmetricKeyRef
 188 SecCmsUtilDecryptSymKeyECDH(SecPrivateKeyRef privkey, CSSM_DATA_PTR encKey, CSSM_DATA_PTR ukm,
 189     SECAlgorithmID *keyEncAlg, SECOidTag bulkalgtag, CSSM_DATA_PTR pubKey);
 190
 191 #if 0
 192 extern OSStatus
 193 SecCmsUtilEncryptSymKeyMISSI(PLArenaPool *poolp, SecCertificateRef cert, SecSymmetricKeyRef key,
 194                         SECOidTag symalgtag, CSSM_DATA_PTR encKey, CSSM_DATA_PTR *pparams, void *pwfn_arg);
 195
 196 extern SecSymmetricKeyRef
 197 SecCmsUtilDecryptSymKeyMISSI(SecPrivateKeyRef privkey, CSSM_DATA_PTR encKey,
 198                         SECAlgorithmID *keyEncAlg, SECOidTag bulkalgtag, void *pwfn_arg);
 199
 200 extern OSStatus
 201 SecCmsUtilEncryptSymKeyESDH(PLArenaPool *poolp, SecCertificateRef cert, SecSymmetricKeyRef key,
 202                         CSSM_DATA_PTR encKey, CSSM_DATA_PTR ukm, SECAlgorithmID *keyEncAlg,
 203                         CSSM_DATA_PTR originatorPubKey);
 204
 205 extern SecSymmetricKeyRef
 206 SecCmsUtilDecryptSymKeyESDH(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  ************************************************************************/
 213 extern SecCmsRecipient **nss_cms_recipient_list_create(SecCmsRecipientInfoRef *recipientinfos);
 214 extern void nss_cms_recipient_list_destroy(SecCmsRecipient **recipient_list);
 215 extern SecCmsRecipientEncryptedKey *SecCmsRecipientEncryptedKeyCreate(PLArenaPool *poolp);
 216
 217 /************************************************************************
 218  * cmsarray.c - misc array functions
 219  ************************************************************************/
 220 /*
 221  * SecCmsArrayAlloc - allocate an array in an arena
 222  */
 223 extern void **
 224 SecCmsArrayAlloc(PRArenaPool *poolp, int n);
 225
 226 /*
 227  * SecCmsArrayAdd - add an element to the end of an array
 228  */
 229 extern OSStatus
 230 SecCmsArrayAdd(PRArenaPool *poolp, void ***array, void *obj);
 231
 232 /*
 233  * SecCmsArrayIsEmpty - check if array is empty
 234  */
 235 extern Boolean
 236 SecCmsArrayIsEmpty(void **array);
 237
 238 /*
 239  * SecCmsArrayCount - count number of elements in array
 240  */
 241 extern int
 242 SecCmsArrayCount(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  */
 254 extern void
 255 SecCmsArraySort(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  */
 266 extern SecCmsAttribute *
 267 SecCmsAttributeCreate(PRArenaPool *poolp, SECOidTag oidtag, CSSM_DATA_PTR value, Boolean encoded);
 268
 269 /*
 270  * SecCmsAttributeAddValue - add another value to an attribute
 271  */
 272 extern OSStatus
 273 SecCmsAttributeAddValue(PLArenaPool *poolp, SecCmsAttribute *attr, CSSM_DATA_PTR value);
 274
 275 /*
 276  * SecCmsAttributeGetType - return the OID tag
 277  */
 278 extern SECOidTag
 279 SecCmsAttributeGetType(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  */
 288 extern CSSM_DATA_PTR
 289 SecCmsAttributeGetValue(SecCmsAttribute *attr);
 290
 291 /*
 292  * SecCmsAttributeCompareValue - compare the attribute's first value against data
 293  */
 294 extern Boolean
 295 SecCmsAttributeCompareValue(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  */
 306 extern CSSM_DATA_PTR
 307 SecCmsAttributeArrayEncode(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  */
 316 extern OSStatus
 317 SecCmsAttributeArrayReorder(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  */
 327 extern SecCmsAttribute *
 328 SecCmsAttributeArrayFindAttrByOidTag(SecCmsAttribute **attrs, SECOidTag oidtag, Boolean only);
 329
 330 /*
 331  * SecCmsAttributeArrayAddAttr - add an attribute to an
 332  * array of attributes.
 333  */
 334 extern OSStatus
 335 SecCmsAttributeArrayAddAttr(PLArenaPool *poolp, SecCmsAttribute ***attrs, SecCmsAttribute *attr);
 336
 337 /*
 338  * SecCmsAttributeArraySetAttr - set an attribute's value in a set of attributes
 339  */
 340 extern OSStatus
 341 SecCmsAttributeArraySetAttr(PLArenaPool *poolp, SecCmsAttribute ***attrs, SECOidTag type, CSSM_DATA_PTR value, Boolean encoded);
 342
 343 /************************************************************************/
 344 SEC_END_PROTOS
 345
 346 #endif /* _CMSLOCAL_H_ */