2 * Copyright (c) 2004,2008,2010,2013 Apple Inc. All Rights Reserved.
4 * @APPLE_LICENSE_HEADER_START@
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
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.
21 * @APPLE_LICENSE_HEADER_END@
25 @header SecCmsSignerInfo.h
26 @Copyright (c) 2004,2008,2010,2013 Apple Inc. All Rights Reserved.
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.
35 #ifndef _SECURITY_SECCMSSIGNERINFO_H_
36 #define _SECURITY_SECCMSSIGNERINFO_H_ 1
38 #include <Security/SecCmsBase.h>
40 #include <Security/SecTrust.h>
43 #if defined(__cplusplus)
50 extern SecCmsSignerInfoRef
51 SecCmsSignerInfoCreate(SecCmsSignedDataRef sigd
, SecIdentityRef identity
, SECOidTag digestalgtag
);
56 extern SecCmsSignerInfoRef
57 SecCmsSignerInfoCreateWithSubjKeyID(SecCmsSignedDataRef sigd
, const SecAsn1Item
*subjKeyID
, SecPublicKeyRef pubKey
, SecPrivateKeyRef signingKey
, SECOidTag digestalgtag
);
62 extern SecCmsVerificationStatus
63 SecCmsSignerInfoGetVerificationStatus(SecCmsSignerInfoRef signerinfo
);
69 SecCmsSignerInfoGetDigestAlg(SecCmsSignerInfoRef signerinfo
);
75 SecCmsSignerInfoGetDigestAlgTag(SecCmsSignerInfoRef signerinfo
);
81 SecCmsSignerInfoGetCertList(SecCmsSignerInfoRef signerinfo
);
85 @abstract Return the signing time, in UTCTime format, of a CMS signerInfo.
86 @param sinfo SignerInfo data for this signer.
87 @discussion Returns a pointer to XXXX (what?)
88 @result A return value of NULL is an error.
91 SecCmsSignerInfoGetSigningTime(SecCmsSignerInfoRef sinfo
, CFAbsoluteTime
*stime
);
95 @abstract Return the data in the signed Codesigning Hash Agility attribute.
96 @param sinfo SignerInfo data for this signer, pointer to a CFDataRef for attribute value
97 @discussion Returns a CFDataRef containing the value of the attribute
98 @result A return value of SECFailure is an error.
101 SecCmsSignerInfoGetAppleCodesigningHashAgility(SecCmsSignerInfoRef sinfo
, CFDataRef
*sdata
);
105 @abstract Return the data in the signed Codesigning Hash Agility V2 attribute.
106 @param sinfo SignerInfo data for this signer, pointer to a CFDictionaryRef for attribute values
107 @discussion Returns a CFDictionaryRef containing the values of the attribute. V2 encodes the
108 hash agility values using DER.
109 @result A return value of SECFailure is an error.
112 SecCmsSignerInfoGetAppleCodesigningHashAgilityV2(SecCmsSignerInfoRef sinfo
, CFDictionaryRef
*sdict
);
115 @function SecCmsSignerInfoGetAppleExpirationTime
116 @abstract Return the expriation time, in CFAbsoluteTime, of a CMS signerInfo.
117 @param sinfo SignerInfo data for this signer.
118 @discussion Returns a CFAbsoluteTime
119 @result A return value of SECFailure is an error.
122 SecCmsSignerInfoGetAppleExpirationTime(SecCmsSignerInfoRef sinfo
, CFAbsoluteTime
*etime
);
126 @abstract Return the signing cert of a CMS signerInfo.
127 @discussion The certs in the enclosing SignedData must have been imported already.
129 extern SecCertificateRef
130 SecCmsSignerInfoGetSigningCertificate(SecCmsSignerInfoRef signerinfo
, SecKeychainRef keychainOrArray
);
134 @abstract Return the common name of the signer.
135 @param sinfo SignerInfo data for this signer.
136 @discussion Returns a CFStringRef containing the common name of the signer.
137 @result A return value of NULL is an error.
139 extern CF_RETURNS_RETAINED CFStringRef
140 SecCmsSignerInfoGetSignerCommonName(SecCmsSignerInfoRef sinfo
);
144 @abstract Return the email address of the signer
145 @param sinfo SignerInfo data for this signer.
146 @discussion Returns a CFStringRef containing the name of the signer.
147 @result A return value of NULL is an error.
149 extern CF_RETURNS_RETAINED CFStringRef
150 SecCmsSignerInfoGetSignerEmailAddress(SecCmsSignerInfoRef sinfo
);
154 @abstract Add the signing time to the authenticated (i.e. signed) attributes of "signerinfo".
155 @discussion This is expected to be included in outgoing signed
156 messages for email (S/MIME) but is likely useful in other situations.
158 This should only be added once; a second call will do nothing.
160 XXX This will probably just shove the current time into "signerinfo"
161 but it will not actually get signed until the entire item is
162 processed for encoding. Is this (expected to be small) delay okay?
165 SecCmsSignerInfoAddSigningTime(SecCmsSignerInfoRef signerinfo
, CFAbsoluteTime t
);
169 @abstract Add a SMIMECapabilities attribute to the authenticated (i.e. signed) attributes of "signerinfo".
170 @discussion This is expected to be included in outgoing signed messages for email (S/MIME).
173 SecCmsSignerInfoAddSMIMECaps(SecCmsSignerInfoRef signerinfo
);
177 @abstract Add a SMIMEEncryptionKeyPreferences attribute to the authenticated (i.e. signed) attributes of "signerinfo".
178 @discussion This is expected to be included in outgoing signed messages for email (S/MIME).
181 SecCmsSignerInfoAddSMIMEEncKeyPrefs(SecCmsSignerInfoRef signerinfo
, SecCertificateRef cert
, SecKeychainRef keychainOrArray
);
185 @abstract Add a SMIMEEncryptionKeyPreferences attribute to the authenticated (i.e. signed) attributes of "signerinfo", using the OID prefered by Microsoft.
186 @discussion This is expected to be included in outgoing signed messages for email (S/MIME), if compatibility with Microsoft mail clients is wanted.
189 SecCmsSignerInfoAddMSSMIMEEncKeyPrefs(SecCmsSignerInfoRef signerinfo
, SecCertificateRef cert
, SecKeychainRef keychainOrArray
);
193 @abstract Countersign a signerinfo.
196 SecCmsSignerInfoAddCounterSignature(SecCmsSignerInfoRef signerinfo
,
197 SECOidTag digestalg
, SecIdentityRef identity
);
201 @abstract Add the Apple Codesigning Hash Agility attribute to the authenticated (i.e. signed) attributes of "signerinfo".
202 @discussion This is expected to be included in outgoing Apple code signatures.
205 SecCmsSignerInfoAddAppleCodesigningHashAgility(SecCmsSignerInfoRef signerinfo
, CFDataRef attrValue
);
209 @abstract Add the Apple Codesigning Hash Agility V2 attribute to the authenticated (i.e. signed) attributes of "signerinfo".
210 @discussion This is expected to be included in outgoing Apple code signatures. V2 encodes the hash agility values using DER.
211 The dictionary should have CFNumberRef keys, corresponding to SECOidTags for digest algorithms, and CFDataRef values,
212 corresponding to the digest value for that digest algorithm.
215 SecCmsSignerInfoAddAppleCodesigningHashAgilityV2(SecCmsSignerInfoRef signerinfo
, CFDictionaryRef attrValues
);
218 @function SecCmsSignerInfoAddAppleExpirationTime
219 @abstract Add the expiration time to the authenticated (i.e. signed) attributes of "signerinfo".
220 @discussion This is expected to be included in outgoing signed messages for Asset Receipts but is likely
221 useful in other situations. This should only be added once; a second call will do nothing.
222 @result A result of SECFailure indicates an error adding the attribute.
225 SecCmsSignerInfoAddAppleExpirationTime(SecCmsSignerInfoRef signerinfo
, CFAbsoluteTime t
);
229 @abstract The following needs to be done in the S/MIME layer code after signature of a signerinfo has been verified.
230 @param signerinfo The SecCmsSignerInfo object for which we verified the signature.
231 @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.
234 SecCmsSignerInfoSaveSMIMEProfile(SecCmsSignerInfoRef signerinfo
);
238 @abstract Set cert chain inclusion mode for this signer.
241 SecCmsSignerInfoIncludeCerts(SecCmsSignerInfoRef signerinfo
, SecCmsCertChainMode cm
, SECCertUsage usage
);
243 /*! @functiongroup CMS misc utility functions */
246 Convert a SecCmsVerificationStatus to a human readable string.
249 SecCmsUtilVerificationStatusToString(SecCmsVerificationStatus vs
);
252 @function SecCmsSignerInfoCopyCertFromEncryptionKeyPreference
253 @abstract Copy the certificate specified in the encryption key preference.
254 @param signerinfo The SecCmsSignerInfo object for which we verified the signature.
255 @result The preferred encryption certificate of the user who signed this message, if found.
256 @discussion This function should be called after the signer info has been verified.
258 SecCertificateRef
SecCmsSignerInfoCopyCertFromEncryptionKeyPreference(SecCmsSignerInfoRef signerinfo
);
261 #if defined(__cplusplus)
265 #endif /* _SECURITY_SECCMSSIGNERINFO_H_ */