]> git.saurik.com Git - apple/security.git/blob - libsecurity_smime/lib/SecCmsSignerInfo.h
Security-55163.44.tar.gz
[apple/security.git] / libsecurity_smime / lib / SecCmsSignerInfo.h
1 /*
2 * Copyright (c) 2004 Apple Computer, 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 SecCmsSignerInfo.h
26 @copyright 2004 Apple Computer, Inc. All Rights Reserved.
27
28 @availability 10.4 and later
29 @abstract Interfaces of the CMS implementation.
30 @discussion The functions here implement functions for encoding
31 and decoding Cryptographic Message Syntax (CMS) objects
32 as described in rfc3369.
33 */
34
35 #ifndef _SECURITY_SECCMSSIGNERINFO_H_
36 #define _SECURITY_SECCMSSIGNERINFO_H_ 1
37
38 #include <Security/SecCmsBase.h>
39
40 #include <Security/SecTrust.h>
41
42
43 #if defined(__cplusplus)
44 extern "C" {
45 #endif
46
47 /*!
48 @function
49 */
50 extern SecCmsSignerInfoRef
51 SecCmsSignerInfoCreate(SecCmsMessageRef cmsg, SecIdentityRef identity, SECOidTag digestalgtag);
52
53 /*!
54 @function
55 */
56 extern SecCmsSignerInfoRef
57 SecCmsSignerInfoCreateWithSubjKeyID(SecCmsMessageRef cmsg, CSSM_DATA_PTR subjKeyID, SecPublicKeyRef pubKey, SecPrivateKeyRef signingKey, SECOidTag digestalgtag);
58
59 /*!
60 @function
61 @abstract Destroy a SignerInfo data structure.
62 */
63 extern void
64 SecCmsSignerInfoDestroy(SecCmsSignerInfoRef si);
65
66 /*!
67 @function
68 */
69 extern SecCmsVerificationStatus
70 SecCmsSignerInfoGetVerificationStatus(SecCmsSignerInfoRef signerinfo);
71
72 /*!
73 @function
74 */
75 extern OSStatus
76 SecCmsSignerInfoVerifyUnAuthAttrs(SecCmsSignerInfoRef signerinfo);
77
78 /*!
79 @function
80 */
81 extern CSSM_DATA *
82 SecCmsSignerInfoGetEncDigest(SecCmsSignerInfoRef signerinfo);
83
84 /*!
85 @function
86 */
87 extern SECOidData *
88 SecCmsSignerInfoGetDigestAlg(SecCmsSignerInfoRef signerinfo);
89
90 /*!
91 @function
92 */
93 extern SECOidTag
94 SecCmsSignerInfoGetDigestAlgTag(SecCmsSignerInfoRef signerinfo);
95
96 /*!
97 @function
98 */
99 extern CFArrayRef
100 SecCmsSignerInfoGetCertList(SecCmsSignerInfoRef signerinfo);
101
102 /*!
103 @function
104 */
105 extern CFArrayRef
106 SecCmsSignerInfoGetTimestampCertList(SecCmsSignerInfoRef signerinfo);
107
108 /*!
109 @function
110 @abstract Return the signing time, in UTCTime format, of a CMS signerInfo.
111 @param sinfo SignerInfo data for this signer.
112 @discussion Returns a pointer to XXXX (what?)
113 @result A return value of NULL is an error.
114 */
115 extern OSStatus
116 SecCmsSignerInfoGetSigningTime(SecCmsSignerInfoRef sinfo, CFAbsoluteTime *stime);
117
118 /*!
119 @function
120 @abstract Return the timestamp time, in UTCTime format, of a CMS signerInfo.
121 @param sinfo SignerInfo data for this signer.
122 @discussion Returns a pointer to XXXX (what?)
123 @result A return value of NULL is an error.
124 */
125 OSStatus
126 SecCmsSignerInfoGetTimestampTime(SecCmsSignerInfoRef sinfo, CFAbsoluteTime *stime);
127
128 /*!
129 @function
130 @abstract Return the signing cert of a CMS signerInfo.
131 @discussion The certs in the enclosing SignedData must have been imported already.
132 */
133 extern SecCertificateRef
134 SecCmsSignerInfoGetSigningCertificate(SecCmsSignerInfoRef signerinfo, SecKeychainRef keychainOrArray);
135
136 /*!
137 @function
138 @abstract Return the common name of the signer.
139 @param sinfo SignerInfo data for this signer.
140 @discussion Returns a CFStringRef containing the common name of the signer.
141 @result A return value of NULL is an error.
142 */
143 extern CFStringRef
144 SecCmsSignerInfoGetSignerCommonName(SecCmsSignerInfoRef sinfo);
145
146 /*!
147 @function
148 @abstract Return the email address of the signer
149 @param sinfo SignerInfo data for this signer.
150 @discussion Returns a CFStringRef containing the name of the signer.
151 @result A return value of NULL is an error.
152 */
153 extern CFStringRef
154 SecCmsSignerInfoGetSignerEmailAddress(SecCmsSignerInfoRef sinfo);
155
156 /*!
157 @function
158 @abstract Add the signing time to the authenticated (i.e. signed) attributes of "signerinfo".
159 @discussion This is expected to be included in outgoing signed
160 messages for email (S/MIME) but is likely useful in other situations.
161
162 This should only be added once; a second call will do nothing.
163
164 XXX This will probably just shove the current time into "signerinfo"
165 but it will not actually get signed until the entire item is
166 processed for encoding. Is this (expected to be small) delay okay?
167 */
168 extern OSStatus
169 SecCmsSignerInfoAddSigningTime(SecCmsSignerInfoRef signerinfo, CFAbsoluteTime t);
170
171 /*!
172 @function
173 @abstract Add a SMIMECapabilities attribute to the authenticated (i.e. signed) attributes of "signerinfo".
174 @discussion This is expected to be included in outgoing signed messages for email (S/MIME).
175 */
176 extern OSStatus
177 SecCmsSignerInfoAddSMIMECaps(SecCmsSignerInfoRef signerinfo);
178
179 /*!
180 @function
181 @abstract Add a SMIMEEncryptionKeyPreferences attribute to the authenticated (i.e. signed) attributes of "signerinfo".
182 @discussion This is expected to be included in outgoing signed messages for email (S/MIME).
183 */
184 OSStatus
185 SecCmsSignerInfoAddSMIMEEncKeyPrefs(SecCmsSignerInfoRef signerinfo, SecCertificateRef cert, SecKeychainRef keychainOrArray);
186
187 /*!
188 @function
189 @abstract Add a SMIMEEncryptionKeyPreferences attribute to the authenticated (i.e. signed) attributes of "signerinfo", using the OID prefered by Microsoft.
190 @discussion This is expected to be included in outgoing signed messages for email (S/MIME), if compatibility with Microsoft mail clients is wanted.
191 */
192 OSStatus
193 SecCmsSignerInfoAddMSSMIMEEncKeyPrefs(SecCmsSignerInfoRef signerinfo, SecCertificateRef cert, SecKeychainRef keychainOrArray);
194
195 /*!
196 @function
197 @abstract Create a timestamp unsigned attribute with a TimeStampToken.
198 */
199 OSStatus
200 SecCmsSignerInfoAddTimeStamp(SecCmsSignerInfoRef signerinfo, CSSM_DATA *tstoken);
201
202 /*!
203 @function
204 @abstract Countersign a signerinfo.
205 */
206 extern OSStatus
207 SecCmsSignerInfoAddCounterSignature(SecCmsSignerInfoRef signerinfo,
208 SECOidTag digestalg, SecIdentityRef identity);
209
210 /*!
211 @function
212 @abstract The following needs to be done in the S/MIME layer code after signature of a signerinfo has been verified.
213 @param signerinfo The SecCmsSignerInfo object for which we verified the signature.
214 @result The preferred encryption certificate of the user who signed this message will be added to the users default Keychain and it will be marked as the preferred certificate to use when sending that person messages from now on.
215 */
216 extern OSStatus
217 SecCmsSignerInfoSaveSMIMEProfile(SecCmsSignerInfoRef signerinfo);
218
219 /*!
220 @function
221 @abstract Set cert chain inclusion mode for this signer.
222 */
223 extern OSStatus
224 SecCmsSignerInfoIncludeCerts(SecCmsSignerInfoRef signerinfo, SecCmsCertChainMode cm, SECCertUsage usage);
225
226 /*! @functiongroup CMS misc utility functions */
227 /*!
228 @function
229 Convert a SecCmsVerificationStatus to a human readable string.
230 */
231 extern const char *
232 SecCmsUtilVerificationStatusToString(SecCmsVerificationStatus vs);
233
234 /*
235 * Preference domain and key for the Microsoft ECDSA compatibility flag.
236 * Default if not present is TRUE, meaning we generate ECDSA-signed messages
237 * which are compatible with Microsoft Entourage. FALSE means we adhere to
238 * the spec (RFC 3278 section 2.1.1).
239 */
240 #define kMSCompatibilityDomain "com.apple.security.smime"
241 #define kMSCompatibilityMode CFSTR("MSCompatibilityMode")
242
243 #if defined(__cplusplus)
244 }
245 #endif
246
247 #endif /* _SECURITY_SECCMSSIGNERINFO_H_ */