OSX/libsecurity_smime/lib/SecSMIMEPriv.h

   1 /*
   2  *  Copyright (c) 2004,2011,2014 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,2011,2014 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
  40 #ifdef __cplusplus
  41 extern "C" {
  42 #endif
  43
  44 /*
  45  * Cipher family IDs used for configuring ciphers for export control
  46  */
  47
  48 /* Cipher Suite "Families" */
  49 #define CIPHER_FAMILYID_MASK                    0xFFFF0000L
  50 #define CIPHER_FAMILYID_SMIME                   0x00010000L
  51
  52 /* SMIME "Cipher Suites" */
  53 /*
  54  * Note that it is assumed that the cipher number itself can be used
  55  * as a bit position in a mask, and that mask is currently 32 bits wide.
  56  * So, if you want to add a cipher that is greater than 0033, secmime.c
  57  * needs to be made smarter at the same time.
  58  */
  59 #define SMIME_RC2_CBC_40                (CIPHER_FAMILYID_SMIME | 0001)
  60 #define SMIME_RC2_CBC_64                (CIPHER_FAMILYID_SMIME | 0002)
  61 #define SMIME_RC2_CBC_128               (CIPHER_FAMILYID_SMIME | 0003)
  62 #define SMIME_DES_CBC_56                (CIPHER_FAMILYID_SMIME | 0011)
  63 #define SMIME_DES_EDE3_168              (CIPHER_FAMILYID_SMIME | 0012)
  64 #define SMIME_AES_CBC_128               (CIPHER_FAMILYID_SMIME | 0013)
  65 #define SMIME_RC5PAD_64_16_40           (CIPHER_FAMILYID_SMIME | 0021)
  66 #define SMIME_RC5PAD_64_16_64           (CIPHER_FAMILYID_SMIME | 0022)
  67 #define SMIME_RC5PAD_64_16_128          (CIPHER_FAMILYID_SMIME | 0023)
  68 #define SMIME_FORTEZZA                  (CIPHER_FAMILYID_SMIME | 0031)
  69
  70
  71 /*
  72  * Initialize the local recording of the user S/MIME cipher preferences.
  73  * This function is called once for each cipher, the order being
  74  * important (first call records greatest preference, and so on).
  75  * When finished, it is called with a "which" of CIPHER_FAMILID_MASK.
  76  * If the function is called again after that, it is assumed that
  77  * the preferences are being reset, and the old preferences are
  78  * discarded.
  79  *
  80  * XXX This is for a particular user, and right now the storage is
  81  * XXX local, static.  The preference should be stored elsewhere to allow
  82  * XXX for multiple uses of one library?  How does SSL handle this;
  83  * XXX it has something similar?
  84  *
  85  *  - The "which" values are defined in ciferfam.h (the SMIME_* values,
  86  *    for example SMIME_DES_CBC_56).
  87  *  - If "on" is non-zero then the named cipher is enabled, otherwise
  88  *    it is disabled.  (It is not necessary to call the function for
  89  *    ciphers that are disabled, however, as that is the default.)
  90  *
  91  * If the cipher preference is successfully recorded, SECSuccess
  92  * is returned.  Otherwise SECFailure is returned.  The only errors
  93  * are due to failure allocating memory or bad parameters/calls:
  94  *      SEC_ERROR_XXX ("which" is not in the S/MIME cipher family)
  95  *      SEC_ERROR_XXX (function is being called more times than there
  96  *              are known/expected ciphers)
  97  */
  98 extern OSStatus SecSMIMEEnableCipher(uint32 which, Boolean on);
  99
 100 /*
 101  * Initialize the local recording of the S/MIME policy.
 102  * This function is called to allow/disallow a particular cipher.
 103  *
 104  * XXX This is for a the current module, I think, so local, static storage
 105  * XXX is okay.  Is that correct, or could multiple uses of the same
 106  * XXX library expect to operate under different policies?
 107  *
 108  *  - The "which" values are defined in ciferfam.h (the SMIME_* values,
 109  *    for example SMIME_DES_CBC_56).
 110  *  - If "on" is non-zero then the named cipher is enabled, otherwise
 111  *    it is disabled.
 112  */
 113 extern OSStatus SecSMIMEAllowCipher(uint32 which, Boolean on);
 114
 115 /*
 116  * Does the current policy allow S/MIME decryption of this particular
 117  * algorithm and keysize?
 118  */
 119 extern Boolean SecSMIMEDecryptionAllowed(SECAlgorithmID *algid, SecSymmetricKeyRef key);
 120
 121 /*
 122  * Does the current policy allow *any* S/MIME encryption (or decryption)?
 123  *
 124  * This tells whether or not *any* S/MIME encryption can be done,
 125  * according to policy.  Callers may use this to do nicer user interface
 126  * (say, greying out a checkbox so a user does not even try to encrypt
 127  * a message when they are not allowed to) or for any reason they want
 128  * to check whether S/MIME encryption (or decryption, for that matter)
 129  * may be done.
 130  *
 131  * It takes no arguments.  The return value is a simple boolean:
 132  *   PR_TRUE means encryption (or decryption) is *possible*
 133  *      (but may still fail due to other reasons, like because we cannot
 134  *      find all the necessary certs, etc.; PR_TRUE is *not* a guarantee)
 135  *   PR_FALSE means encryption (or decryption) is not permitted
 136  *
 137  * There are no errors from this routine.
 138  */
 139 extern Boolean SecSMIMEEncryptionPossible(void);
 140
 141 /*
 142  * SecSMIMECreateSMIMECapabilities - get S/MIME capabilities attr value
 143  *
 144  * scans the list of allowed and enabled ciphers and construct a PKCS9-compliant
 145  * S/MIME capabilities attribute value.
 146  */
 147 extern OSStatus SecSMIMECreateSMIMECapabilities(SecArenaPoolRef pool, CSSM_DATA_PTR dest, Boolean includeFortezzaCiphers);
 148
 149 /*
 150  * SecSMIMECreateSMIMEEncKeyPrefs - create S/MIME encryption key preferences attr value
 151  */
 152 extern OSStatus SecSMIMECreateSMIMEEncKeyPrefs(SecArenaPoolRef pool, CSSM_DATA_PTR dest, SecCertificateRef cert);
 153
 154 /*
 155  * SecSMIMECreateMSSMIMEEncKeyPrefs - create S/MIME encryption key preferences attr value using MS oid
 156  */
 157 extern OSStatus SecSMIMECreateMSSMIMEEncKeyPrefs(SecArenaPoolRef pool, CSSM_DATA_PTR dest, SecCertificateRef cert);
 158
 159 /*
 160  * SecSMIMEGetCertFromEncryptionKeyPreference - find cert marked by EncryptionKeyPreference
 161  *          attribute
 162  */
 163 extern SecCertificateRef SecSMIMEGetCertFromEncryptionKeyPreference(SecKeychainRef keychainOrArray, CSSM_DATA_PTR DERekp);
 164
 165
 166 #ifdef __cplusplus
 167 }
 168 #endif
 169
 170 #endif /* _SECURITY_SECSMIMEPRIV_H_ */