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
41extern "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 */
98extern 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 */
113extern 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 */
119extern 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 */
139extern 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 */
147extern OSStatus SecSMIMECreateSMIMECapabilities(SecArenaPoolRef pool, CSSM_DATA_PTR dest, Boolean includeFortezzaCiphers);
148
149/*
150 * SecSMIMECreateSMIMEEncKeyPrefs - create S/MIME encryption key preferences attr value
151 */
152extern 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 */
157extern OSStatus SecSMIMECreateMSSMIMEEncKeyPrefs(SecArenaPoolRef pool, CSSM_DATA_PTR dest, SecCertificateRef cert);
158
159/*
160 * SecSMIMEGetCertFromEncryptionKeyPreference - find cert marked by EncryptionKeyPreference
161 *          attribute
162 */
163extern SecCertificateRef SecSMIMEGetCertFromEncryptionKeyPreference(SecKeychainRef keychainOrArray, CSSM_DATA_PTR DERekp);
164
165
166#ifdef __cplusplus
167}
168#endif
169
170#endif /* _SECURITY_SECSMIMEPRIV_H_ */
171