1/*
2 *  Copyright (c) 2004,2008,2010,2013 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 SecCmsSignerInfo.h
26    @Copyright (c) 2004,2008,2010,2013 Apple 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)
44extern "C" {
45#endif
46
47/*!
48    @function
49 */
50extern SecCmsSignerInfoRef
51SecCmsSignerInfoCreate(SecCmsSignedDataRef sigd, SecIdentityRef identity, SECOidTag digestalgtag);
52
53/*!
54    @function
55 */
56extern SecCmsSignerInfoRef
57SecCmsSignerInfoCreateWithSubjKeyID(SecCmsSignedDataRef sigd, const SecAsn1Item *subjKeyID, SecPublicKeyRef pubKey, SecPrivateKeyRef signingKey, SECOidTag digestalgtag);
58
59/*!
60    @function
61 */
62extern SecCmsVerificationStatus
63SecCmsSignerInfoGetVerificationStatus(SecCmsSignerInfoRef signerinfo);
64
65/*!
66    @function
67 */
68extern SECOidData *
69SecCmsSignerInfoGetDigestAlg(SecCmsSignerInfoRef signerinfo);
70
71/*!
72    @function
73 */
74extern SECOidTag
75SecCmsSignerInfoGetDigestAlgTag(SecCmsSignerInfoRef signerinfo);
76
77/*!
78    @function
79 */
80extern CFArrayRef
81SecCmsSignerInfoGetCertList(SecCmsSignerInfoRef signerinfo);
82
83/*!
84    @function
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.
89 */
90extern OSStatus
91SecCmsSignerInfoGetSigningTime(SecCmsSignerInfoRef sinfo, CFAbsoluteTime *stime);
92
93/*!
94    @function
95    @abstract Return the signing cert of a CMS signerInfo.
96    @discussion The certs in the enclosing SignedData must have been imported already.
97 */
98extern SecCertificateRef
99SecCmsSignerInfoGetSigningCertificate(SecCmsSignerInfoRef signerinfo, SecKeychainRef keychainOrArray);
100
101/*!
102    @function
103    @abstract Return the common name of the signer.
104    @param sinfo SignerInfo data for this signer.
105    @discussion Returns a CFStringRef containing the common name of the signer.
106    @result A return value of NULL is an error.
107 */
108extern CF_RETURNS_RETAINED CFStringRef
109SecCmsSignerInfoGetSignerCommonName(SecCmsSignerInfoRef sinfo);
110
111/*!
112    @function
113    @abstract Return the email address of the signer
114    @param sinfo SignerInfo data for this signer.
115    @discussion Returns a CFStringRef containing the name of the signer.
116    @result A return value of NULL is an error.
117 */
118extern CF_RETURNS_RETAINED CFStringRef
119SecCmsSignerInfoGetSignerEmailAddress(SecCmsSignerInfoRef sinfo);
120
121/*!
122    @function
123    @abstract Add the signing time to the authenticated (i.e. signed) attributes of "signerinfo".
124    @discussion This is expected to be included in outgoing signed
125                messages for email (S/MIME) but is likely useful in other situations.
126
127                This should only be added once; a second call will do nothing.
128
129                XXX This will probably just shove the current time into "signerinfo"
130                but it will not actually get signed until the entire item is
131                processed for encoding.  Is this (expected to be small) delay okay?
132 */
133extern OSStatus
134SecCmsSignerInfoAddSigningTime(SecCmsSignerInfoRef signerinfo, CFAbsoluteTime t);
135
136/*!
137    @function
138    @abstract Add a SMIMECapabilities attribute to the authenticated (i.e. signed) attributes of "signerinfo".
139    @discussion This is expected to be included in outgoing signed messages for email (S/MIME).
140 */
141extern OSStatus
142SecCmsSignerInfoAddSMIMECaps(SecCmsSignerInfoRef signerinfo);
143
144/*!
145    @function
146    @abstract Add a SMIMEEncryptionKeyPreferences attribute to the authenticated (i.e. signed) attributes of "signerinfo".
147    @discussion This is expected to be included in outgoing signed messages for email (S/MIME).
148 */
149OSStatus
150SecCmsSignerInfoAddSMIMEEncKeyPrefs(SecCmsSignerInfoRef signerinfo, SecCertificateRef cert, SecKeychainRef keychainOrArray);
151
152/*!
153    @function
154    @abstract Add a SMIMEEncryptionKeyPreferences attribute to the authenticated (i.e. signed) attributes of "signerinfo", using the OID prefered by Microsoft.
155    @discussion This is expected to be included in outgoing signed messages for email (S/MIME), if compatibility with Microsoft mail clients is wanted.
156 */
157OSStatus
158SecCmsSignerInfoAddMSSMIMEEncKeyPrefs(SecCmsSignerInfoRef signerinfo, SecCertificateRef cert, SecKeychainRef keychainOrArray);
159
160/*!
161    @function
162    @abstract Countersign a signerinfo.
163 */
164extern OSStatus
165SecCmsSignerInfoAddCounterSignature(SecCmsSignerInfoRef signerinfo,
166				    SECOidTag digestalg, SecIdentityRef identity);
167
168/*!
169    @function
170    @abstract The following needs to be done in the S/MIME layer code after signature of a signerinfo has been verified.
171    @param signerinfo The SecCmsSignerInfo object for which we verified the signature.
172    @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.
173 */
174extern OSStatus
175SecCmsSignerInfoSaveSMIMEProfile(SecCmsSignerInfoRef signerinfo);
176
177/*!
178    @function
179    @abstract Set cert chain inclusion mode for this signer.
180 */
181extern OSStatus
182SecCmsSignerInfoIncludeCerts(SecCmsSignerInfoRef signerinfo, SecCmsCertChainMode cm, SECCertUsage usage);
183
184/*! @functiongroup CMS misc utility functions */
185/*!
186    @function
187    Convert a SecCmsVerificationStatus to a human readable string.
188 */
189extern const char *
190SecCmsUtilVerificationStatusToString(SecCmsVerificationStatus vs);
191
192
193#if defined(__cplusplus)
194}
195#endif
196
197#endif /* _SECURITY_SECCMSSIGNERINFO_H_ */
198