libsecurity_smime/lib/SecSMIMEPriv.h

   1 /*
   2  *  Copyright (c) 2004,2008,2010-2011 Apple Inc. All Rights Reserved.
   3  *
   4  *  @APPLE_LICENSE_HEADER_START@
   5  *
   6  *  This file contains Original Code and/or Modifications of Original Code
   7  *  as defined in and that are subject to the Apple Public Source License
   8  *  Version 2.0 (the 'License'). You may not use this file except in
   9  *  compliance with the License. Please obtain a copy of the License at
  10  *  http://www.opensource.apple.com/apsl/ and read it before using this
  11  *  file.
  12  *
  13  *  The Original Code and all software distributed under the License are
  14  *  distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  *  EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  *  INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  *  FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  *  Please see the License for the specific language governing rights and
  19  *  limitations under the License.
  20  *
  21  *  @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 /*!
  25     @header SecSMIMEPriv.h
  26     @Copyright (c) 2004,2008,2010-2011 Apple Inc. All Rights Reserved.
  27
  28     @availability 10.4 and later
  29     @abstract Private S/MIME Specific routines.
  30     @discussion Header file for routines specific to S/MIME.  Keep
  31                 things that are pure pkcs7 out of here; this is for
  32                 S/MIME policy, S/MIME interoperability, etc.
  33 */
  34
  35 #ifndef _SECURITY_SECSMIMEPRIV_H_
  36 #define _SECURITY_SECSMIMEPRIV_H_ 1
  37
  38 #include <Security/SecCmsBase.h>
  39 #include <security_asn1/plarenas.h>
  40
  41 #ifdef __cplusplus
  42 extern "C" {
  43 #endif
  44
  45 /*
  46  * Cipher family IDs used for configuring ciphers for export control
  47  */
  48
  49 /* Cipher Suite "Families" */
  50 #define CIPHER_FAMILYID_MASK                    0xFFFF0000L
  51 #define CIPHER_FAMILYID_SMIME                   0x00010000L
  52
  53 /* SMIME "Cipher Suites" */
  54 /*
  55  * Note that it is assumed that the cipher number itself can be used
  56  * as a bit position in a mask, and that mask is currently 32 bits wide.
  57  * So, if you want to add a cipher that is greater than 0033, secmime.c
  58  * needs to be made smarter at the same time.
  59  */
  60 #define SMIME_RC2_CBC_40                (CIPHER_FAMILYID_SMIME | 0001)
  61 #define SMIME_RC2_CBC_64                (CIPHER_FAMILYID_SMIME | 0002)
  62 #define SMIME_RC2_CBC_128               (CIPHER_FAMILYID_SMIME | 0003)
  63 #define SMIME_DES_CBC_56                (CIPHER_FAMILYID_SMIME | 0011)
  64 #define SMIME_DES_EDE3_168              (CIPHER_FAMILYID_SMIME | 0012)
  65 #define SMIME_AES_CBC_128               (CIPHER_FAMILYID_SMIME | 0013)
  66 #define SMIME_AES_CBC_192               (CIPHER_FAMILYID_SMIME | 0014)
  67 #define SMIME_AES_CBC_256               (CIPHER_FAMILYID_SMIME | 0015)
  68 #define SMIME_RC5PAD_64_16_40           (CIPHER_FAMILYID_SMIME | 0021)
  69 #define SMIME_RC5PAD_64_16_64           (CIPHER_FAMILYID_SMIME | 0022)
  70 #define SMIME_RC5PAD_64_16_128          (CIPHER_FAMILYID_SMIME | 0023)
  71 #define SMIME_FORTEZZA                  (CIPHER_FAMILYID_SMIME | 0031)
  72
  73
  74 /*
  75  * Initialize the local recording of the user S/MIME cipher preferences.
  76  * This function is called once for each cipher, the order being
  77  * important (first call records greatest preference, and so on).
  78  * When finished, it is called with a "which" of CIPHER_FAMILID_MASK.
  79  * If the function is called again after that, it is assumed that
  80  * the preferences are being reset, and the old preferences are
  81  * discarded.
  82  *
  83  * XXX This is for a particular user, and right now the storage is
  84  * XXX local, static.  The preference should be stored elsewhere to allow
  85  * XXX for multiple uses of one library?  How does SSL handle this;
  86  * XXX it has something similar?
  87  *
  88  *  - The "which" values are defined in ciferfam.h (the SMIME_* values,
  89  *    for example SMIME_DES_CBC_56).
  90  *  - If "on" is non-zero then the named cipher is enabled, otherwise
  91  *    it is disabled.  (It is not necessary to call the function for
  92  *    ciphers that are disabled, however, as that is the default.)
  93  *
  94  * If the cipher preference is successfully recorded, SECSuccess
  95  * is returned.  Otherwise SECFailure is returned.  The only errors
  96  * are due to failure allocating memory or bad parameters/calls:
  97  *      SEC_ERROR_XXX ("which" is not in the S/MIME cipher family)
  98  *      SEC_ERROR_XXX (function is being called more times than there
  99  *              are known/expected ciphers)
 100  */
 101 extern OSStatus SecSMIMEEnableCipher(unsigned long which, Boolean on);
 102
 103 /*
 104  * Initialize the local recording of the S/MIME policy.
 105  * This function is called to allow/disallow a particular cipher.
 106  *
 107  * XXX This is for a the current module, I think, so local, static storage
 108  * XXX is okay.  Is that correct, or could multiple uses of the same
 109  * XXX library expect to operate under different policies?
 110  *
 111  *  - The "which" values are defined in ciferfam.h (the SMIME_* values,
 112  *    for example SMIME_DES_CBC_56).
 113  *  - If "on" is non-zero then the named cipher is enabled, otherwise
 114  *    it is disabled.
 115  */
 116 extern OSStatus SecSMIMEAllowCipher(unsigned long which, Boolean on);
 117
 118 /*
 119  * Does the current policy allow S/MIME decryption of this particular
 120  * algorithm and keysize?
 121  */
 122 extern Boolean SecSMIMEDecryptionAllowed(SECAlgorithmID *algid, SecSymmetricKeyRef key);
 123
 124 /*
 125  * Does the current policy allow *any* S/MIME encryption (or decryption)?
 126  *
 127  * This tells whether or not *any* S/MIME encryption can be done,
 128  * according to policy.  Callers may use this to do nicer user interface
 129  * (say, greying out a checkbox so a user does not even try to encrypt
 130  * a message when they are not allowed to) or for any reason they want
 131  * to check whether S/MIME encryption (or decryption, for that matter)
 132  * may be done.
 133  *
 134  * It takes no arguments.  The return value is a simple boolean:
 135  *   PR_TRUE means encryption (or decryption) is *possible*
 136  *      (but may still fail due to other reasons, like because we cannot
 137  *      find all the necessary certs, etc.; PR_TRUE is *not* a guarantee)
 138  *   PR_FALSE means encryption (or decryption) is not permitted
 139  *
 140  * There are no errors from this routine.
 141  */
 142 extern Boolean SecSMIMEEncryptionPossible(void);
 143
 144 /*
 145  * SecSMIMECreateSMIMECapabilities - get S/MIME capabilities attr value
 146  *
 147  * scans the list of allowed and enabled ciphers and construct a PKCS9-compliant
 148  * S/MIME capabilities attribute value.
 149  */
 150 extern OSStatus SecSMIMECreateSMIMECapabilities(PLArenaPool *poolp, SecAsn1Item * dest, Boolean includeFortezzaCiphers);
 151
 152 /*
 153  * SecSMIMECreateSMIMEEncKeyPrefs - create S/MIME encryption key preferences attr value
 154  */
 155 extern OSStatus SecSMIMECreateSMIMEEncKeyPrefs(PLArenaPool *poolp, SecAsn1Item * dest, SecCertificateRef cert);
 156
 157 /*
 158  * SecSMIMECreateMSSMIMEEncKeyPrefs - create S/MIME encryption key preferences attr value using MS oid
 159  */
 160 extern OSStatus SecSMIMECreateMSSMIMEEncKeyPrefs(PLArenaPool *poolp, SecAsn1Item * dest, SecCertificateRef cert);
 161
 162 /*
 163  * SecSMIMEGetCertFromEncryptionKeyPreference - find cert marked by EncryptionKeyPreference
 164  *          attribute
 165  */
 166 extern SecCertificateRef SecSMIMEGetCertFromEncryptionKeyPreference(SecKeychainRef keychainOrArray, SecAsn1Item * DERekp);
 167
 168
 169 #ifdef __cplusplus
 170 }
 171 #endif
 172
 173 #endif /* _SECURITY_SECSMIMEPRIV_H_ */