Back to index

lightning-sunbird  0.9+nobinonly
cmslocal.h
Go to the documentation of this file.
00001 /* ***** BEGIN LICENSE BLOCK *****
00002  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00003  *
00004  * The contents of this file are subject to the Mozilla Public License Version
00005  * 1.1 (the "License"); you may not use this file except in compliance with
00006  * the License. You may obtain a copy of the License at
00007  * http://www.mozilla.org/MPL/
00008  *
00009  * Software distributed under the License is distributed on an "AS IS" basis,
00010  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00011  * for the specific language governing rights and limitations under the
00012  * License.
00013  *
00014  * The Original Code is the Netscape security libraries.
00015  *
00016  * The Initial Developer of the Original Code is
00017  * Netscape Communications Corporation.
00018  * Portions created by the Initial Developer are Copyright (C) 1994-2000
00019  * the Initial Developer. All Rights Reserved.
00020  *
00021  * Contributor(s):
00022  *
00023  * Alternatively, the contents of this file may be used under the terms of
00024  * either the GNU General Public License Version 2 or later (the "GPL"), or
00025  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00026  * in which case the provisions of the GPL or the LGPL are applicable instead
00027  * of those above. If you wish to allow use of your version of this file only
00028  * under the terms of either the GPL or the LGPL, and not to allow others to
00029  * use your version of this file under the terms of the MPL, indicate your
00030  * decision by deleting the provisions above and replace them with the notice
00031  * and other provisions required by the GPL or the LGPL. If you do not delete
00032  * the provisions above, a recipient may use your version of this file under
00033  * the terms of any one of the MPL, the GPL or the LGPL.
00034  *
00035  * ***** END LICENSE BLOCK ***** */
00036 
00037 /*
00038  * Support routines for CMS implementation, none of which are exported.
00039  *
00040  * Do not export this file!  If something in here is really needed outside
00041  * of smime code, first try to add a CMS interface which will do it for
00042  * you.  If that has a problem, then just move out what you need, changing
00043  * its name as appropriate!
00044  *
00045  * $Id: cmslocal.h,v 1.5 2005/06/27 22:21:18 julien.pierre.bugs%sun.com Exp $
00046  */
00047 
00048 #ifndef _CMSLOCAL_H_
00049 #define _CMSLOCAL_H_
00050 
00051 #include "cms.h"
00052 #include "cmsreclist.h"
00053 #include "secasn1t.h"
00054 
00055 extern const SEC_ASN1Template NSSCMSContentInfoTemplate[];
00056 
00057 /************************************************************************/
00058 SEC_BEGIN_PROTOS
00059 
00060 /***********************************************************************
00061  * cmscipher.c - en/decryption routines
00062  ***********************************************************************/
00063 
00064 /*
00065  * NSS_CMSCipherContext_StartDecrypt - create a cipher context to do decryption
00066  * based on the given bulk * encryption key and algorithm identifier (which may include an iv).
00067  */
00068 extern NSSCMSCipherContext *
00069 NSS_CMSCipherContext_StartDecrypt(PK11SymKey *key, SECAlgorithmID *algid);
00070 
00071 /*
00072  * NSS_CMSCipherContext_StartEncrypt - create a cipher object to do encryption,
00073  * based on the given bulk encryption key and algorithm tag.  Fill in the algorithm
00074  * identifier (which may include an iv) appropriately.
00075  */
00076 extern NSSCMSCipherContext *
00077 NSS_CMSCipherContext_StartEncrypt(PRArenaPool *poolp, PK11SymKey *key, SECAlgorithmID *algid);
00078 
00079 extern void
00080 NSS_CMSCipherContext_Destroy(NSSCMSCipherContext *cc);
00081 
00082 /*
00083  * NSS_CMSCipherContext_DecryptLength - find the output length of the next call to decrypt.
00084  *
00085  * cc - the cipher context
00086  * input_len - number of bytes used as input
00087  * final - true if this is the final chunk of data
00088  *
00089  * Result can be used to perform memory allocations.  Note that the amount
00090  * is exactly accurate only when not doing a block cipher or when final
00091  * is false, otherwise it is an upper bound on the amount because until
00092  * we see the data we do not know how many padding bytes there are
00093  * (always between 1 and bsize).
00094  */
00095 extern unsigned int
00096 NSS_CMSCipherContext_DecryptLength(NSSCMSCipherContext *cc, unsigned int input_len, PRBool final);
00097 
00098 /*
00099  * NSS_CMSCipherContext_EncryptLength - find the output length of the next call to encrypt.
00100  *
00101  * cc - the cipher context
00102  * input_len - number of bytes used as input
00103  * final - true if this is the final chunk of data
00104  *
00105  * Result can be used to perform memory allocations.
00106  */
00107 extern unsigned int
00108 NSS_CMSCipherContext_EncryptLength(NSSCMSCipherContext *cc, unsigned int input_len, PRBool final);
00109 
00110 /*
00111  * NSS_CMSCipherContext_Decrypt - do the decryption
00112  *
00113  * cc - the cipher context
00114  * output - buffer for decrypted result bytes
00115  * output_len_p - number of bytes in output
00116  * max_output_len - upper bound on bytes to put into output
00117  * input - pointer to input bytes
00118  * input_len - number of input bytes
00119  * final - true if this is the final chunk of data
00120  *
00121  * Decrypts a given length of input buffer (starting at "input" and
00122  * containing "input_len" bytes), placing the decrypted bytes in
00123  * "output" and storing the output length in "*output_len_p".
00124  * "cc" is the return value from NSS_CMSCipher_StartDecrypt.
00125  * When "final" is true, this is the last of the data to be decrypted.
00126  */ 
00127 extern SECStatus
00128 NSS_CMSCipherContext_Decrypt(NSSCMSCipherContext *cc, unsigned char *output,
00129                 unsigned int *output_len_p, unsigned int max_output_len,
00130                 const unsigned char *input, unsigned int input_len,
00131                 PRBool final);
00132 
00133 /*
00134  * NSS_CMSCipherContext_Encrypt - do the encryption
00135  *
00136  * cc - the cipher context
00137  * output - buffer for decrypted result bytes
00138  * output_len_p - number of bytes in output
00139  * max_output_len - upper bound on bytes to put into output
00140  * input - pointer to input bytes
00141  * input_len - number of input bytes
00142  * final - true if this is the final chunk of data
00143  *
00144  * Encrypts a given length of input buffer (starting at "input" and
00145  * containing "input_len" bytes), placing the encrypted bytes in
00146  * "output" and storing the output length in "*output_len_p".
00147  * "cc" is the return value from NSS_CMSCipher_StartEncrypt.
00148  * When "final" is true, this is the last of the data to be encrypted.
00149  */ 
00150 extern SECStatus
00151 NSS_CMSCipherContext_Encrypt(NSSCMSCipherContext *cc, unsigned char *output,
00152                 unsigned int *output_len_p, unsigned int max_output_len,
00153                 const unsigned char *input, unsigned int input_len,
00154                 PRBool final);
00155 
00156 /************************************************************************
00157  * cmspubkey.c - public key operations
00158  ************************************************************************/
00159 
00160 /*
00161  * NSS_CMSUtil_EncryptSymKey_RSA - wrap a symmetric key with RSA
00162  *
00163  * this function takes a symmetric key and encrypts it using an RSA public key
00164  * according to PKCS#1 and RFC2633 (S/MIME)
00165  */
00166 extern SECStatus
00167 NSS_CMSUtil_EncryptSymKey_RSA(PLArenaPool *poolp, CERTCertificate *cert,
00168                               PK11SymKey *key,
00169                               SECItem *encKey);
00170 
00171 extern SECStatus
00172 NSS_CMSUtil_EncryptSymKey_RSAPubKey(PLArenaPool *poolp,
00173                                     SECKEYPublicKey *publickey,
00174                                     PK11SymKey *bulkkey, SECItem *encKey);
00175 
00176 /*
00177  * NSS_CMSUtil_DecryptSymKey_RSA - unwrap a RSA-wrapped symmetric key
00178  *
00179  * this function takes an RSA-wrapped symmetric key and unwraps it, returning a symmetric
00180  * key handle. Please note that the actual unwrapped key data may not be allowed to leave
00181  * a hardware token...
00182  */
00183 extern PK11SymKey *
00184 NSS_CMSUtil_DecryptSymKey_RSA(SECKEYPrivateKey *privkey, SECItem *encKey, SECOidTag bulkalgtag);
00185 
00186 extern SECStatus
00187 NSS_CMSUtil_EncryptSymKey_MISSI(PLArenaPool *poolp, CERTCertificate *cert, PK11SymKey *key,
00188                      SECOidTag symalgtag, SECItem *encKey, SECItem **pparams, void *pwfn_arg);
00189 
00190 extern PK11SymKey *
00191 NSS_CMSUtil_DecryptSymKey_MISSI(SECKEYPrivateKey *privkey, SECItem *encKey,
00192                      SECAlgorithmID *keyEncAlg, SECOidTag bulkalgtag, void *pwfn_arg);
00193 
00194 extern SECStatus
00195 NSS_CMSUtil_EncryptSymKey_ESDH(PLArenaPool *poolp, CERTCertificate *cert, PK11SymKey *key,
00196                      SECItem *encKey, SECItem **ukm, SECAlgorithmID *keyEncAlg,
00197                      SECItem *originatorPubKey);
00198 
00199 extern PK11SymKey *
00200 NSS_CMSUtil_DecryptSymKey_ESDH(SECKEYPrivateKey *privkey, SECItem *encKey,
00201                      SECAlgorithmID *keyEncAlg, SECOidTag bulkalgtag, void *pwfn_arg);
00202 
00203 /************************************************************************
00204  * cmsreclist.c - recipient list stuff
00205  ************************************************************************/
00206 extern NSSCMSRecipient **nss_cms_recipient_list_create(NSSCMSRecipientInfo **recipientinfos);
00207 extern void nss_cms_recipient_list_destroy(NSSCMSRecipient **recipient_list);
00208 extern NSSCMSRecipientEncryptedKey *NSS_CMSRecipientEncryptedKey_Create(PLArenaPool *poolp);
00209 
00210 /************************************************************************
00211  * cmsarray.c - misc array functions
00212  ************************************************************************/
00213 /*
00214  * NSS_CMSArray_Alloc - allocate an array in an arena
00215  */
00216 extern void **
00217 NSS_CMSArray_Alloc(PRArenaPool *poolp, int n);
00218 
00219 /*
00220  * NSS_CMSArray_Add - add an element to the end of an array
00221  */
00222 extern SECStatus
00223 NSS_CMSArray_Add(PRArenaPool *poolp, void ***array, void *obj);
00224 
00225 /*
00226  * NSS_CMSArray_IsEmpty - check if array is empty
00227  */
00228 extern PRBool
00229 NSS_CMSArray_IsEmpty(void **array);
00230 
00231 /*
00232  * NSS_CMSArray_Count - count number of elements in array
00233  */
00234 extern int
00235 NSS_CMSArray_Count(void **array);
00236 
00237 /*
00238  * NSS_CMSArray_Sort - sort an array ascending, in place
00239  *
00240  * If "secondary" is not NULL, the same reordering gets applied to it.
00241  * If "tertiary" is not NULL, the same reordering gets applied to it.
00242  * "compare" is a function that returns 
00243  *  < 0 when the first element is less than the second
00244  *  = 0 when the first element is equal to the second
00245  *  > 0 when the first element is greater than the second
00246  */
00247 extern void
00248 NSS_CMSArray_Sort(void **primary, int (*compare)(void *,void *), void **secondary, void **tertiary);
00249 
00250 /************************************************************************
00251  * cmsattr.c - misc attribute functions
00252  ************************************************************************/
00253 /*
00254  * NSS_CMSAttribute_Create - create an attribute
00255  *
00256  * if value is NULL, the attribute won't have a value. It can be added later
00257  * with NSS_CMSAttribute_AddValue.
00258  */
00259 extern NSSCMSAttribute *
00260 NSS_CMSAttribute_Create(PRArenaPool *poolp, SECOidTag oidtag, SECItem *value, PRBool encoded);
00261 
00262 /*
00263  * NSS_CMSAttribute_AddValue - add another value to an attribute
00264  */
00265 extern SECStatus
00266 NSS_CMSAttribute_AddValue(PLArenaPool *poolp, NSSCMSAttribute *attr, SECItem *value);
00267 
00268 /*
00269  * NSS_CMSAttribute_GetType - return the OID tag
00270  */
00271 extern SECOidTag
00272 NSS_CMSAttribute_GetType(NSSCMSAttribute *attr);
00273 
00274 /*
00275  * NSS_CMSAttribute_GetValue - return the first attribute value
00276  *
00277  * We do some sanity checking first:
00278  * - Multiple values are *not* expected.
00279  * - Empty values are *not* expected.
00280  */
00281 extern SECItem *
00282 NSS_CMSAttribute_GetValue(NSSCMSAttribute *attr);
00283 
00284 /*
00285  * NSS_CMSAttribute_CompareValue - compare the attribute's first value against data
00286  */
00287 extern PRBool
00288 NSS_CMSAttribute_CompareValue(NSSCMSAttribute *attr, SECItem *av);
00289 
00290 /*
00291  * NSS_CMSAttributeArray_Encode - encode an Attribute array as SET OF Attributes
00292  *
00293  * If you are wondering why this routine does not reorder the attributes
00294  * first, and might be tempted to make it do so, see the comment by the
00295  * call to ReorderAttributes in cmsencode.c.  (Or, see who else calls this
00296  * and think long and hard about the implications of making it always
00297  * do the reordering.)
00298  */
00299 extern SECItem *
00300 NSS_CMSAttributeArray_Encode(PRArenaPool *poolp, NSSCMSAttribute ***attrs, SECItem *dest);
00301 
00302 /*
00303  * NSS_CMSAttributeArray_Reorder - sort attribute array by attribute's DER encoding
00304  *
00305  * make sure that the order of the attributes guarantees valid DER (which must be
00306  * in lexigraphically ascending order for a SET OF); if reordering is necessary it
00307  * will be done in place (in attrs).
00308  */
00309 extern SECStatus
00310 NSS_CMSAttributeArray_Reorder(NSSCMSAttribute **attrs);
00311 
00312 /*
00313  * NSS_CMSAttributeArray_FindAttrByOidTag - look through a set of attributes and
00314  * find one that matches the specified object ID.
00315  *
00316  * If "only" is true, then make sure that there is not more than one attribute
00317  * of the same type.  Otherwise, just return the first one found. (XXX Does
00318  * anybody really want that first-found behavior?  It was like that when I found it...)
00319  */
00320 extern NSSCMSAttribute *
00321 NSS_CMSAttributeArray_FindAttrByOidTag(NSSCMSAttribute **attrs, SECOidTag oidtag, PRBool only);
00322 
00323 /*
00324  * NSS_CMSAttributeArray_AddAttr - add an attribute to an
00325  * array of attributes. 
00326  */
00327 extern SECStatus
00328 NSS_CMSAttributeArray_AddAttr(PLArenaPool *poolp, NSSCMSAttribute ***attrs, NSSCMSAttribute *attr);
00329 
00330 /*
00331  * NSS_CMSAttributeArray_SetAttr - set an attribute's value in a set of attributes
00332  */
00333 extern SECStatus
00334 NSS_CMSAttributeArray_SetAttr(PLArenaPool *poolp, NSSCMSAttribute ***attrs, SECOidTag type, SECItem *value, PRBool encoded);
00335 
00336 /*
00337  * NSS_CMSSignedData_AddTempCertificate - add temporary certificate references.
00338  * They may be needed for signature verification on the data, for example.
00339  */
00340 extern SECStatus
00341 NSS_CMSSignedData_AddTempCertificate(NSSCMSSignedData *sigd, CERTCertificate *cert);
00342 
00343 /************************************************************************/
00344 SEC_END_PROTOS
00345 
00346 #endif /* _CMSLOCAL_H_ */