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