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