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