CMS/SecCmsSignerInfo.h

   1 /*
   2  *  Copyright (c) 2004-2018 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
  27     @availability 10.4 and later
  28     @abstract Interfaces of the CMS implementation.
  29     @discussion The functions here implement functions for encoding
  30                 and decoding Cryptographic Message Syntax (CMS) objects
  31                 as described in rfc3369.
  32  */
  33
  34 #ifndef _SECURITY_SECCMSSIGNERINFO_H_
  35 #define _SECURITY_SECCMSSIGNERINFO_H_  1
  36
  37 #include <Security/SecCmsBase.h>
  38
  39 #include <Security/SecTrust.h>
  40 #include <CoreFoundation/CFDate.h>
  41
  42 __BEGIN_DECLS
  43
  44 #if TARGET_OS_OSX
  45 extern SecCmsSignerInfoRef
  46 SecCmsSignerInfoCreate(SecCmsMessageRef cmsg, SecIdentityRef identity, SECOidTag digestalgtag)
  47     API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(iosmac);
  48
  49 #else // !TARGET_OSX
  50
  51 extern SecCmsSignerInfoRef
  52 SecCmsSignerInfoCreate(SecCmsSignedDataRef sigd, SecIdentityRef identity, SECOidTag digestalgtag)
  53     API_AVAILABLE(ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(iosmac);
  54 #endif // !TARGET_OS_OSX
  55
  56 #if TARGET_OS_OSX
  57 #pragma clang diagnostic push
  58 #pragma clang diagnostic ignored "-Wdeprecated-declarations"
  59 extern SecCmsSignerInfoRef
  60 SecCmsSignerInfoCreateWithSubjKeyID(SecCmsMessageRef cmsg, CSSM_DATA_PTR subjKeyID, SecPublicKeyRef pubKey, SecPrivateKeyRef signingKey, SECOidTag digestalgtag)
  61     API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(iosmac);
  62 #pragma clang diagnostic pop
  63 #else // !TARGET_OS_OSX
  64 extern SecCmsSignerInfoRef
  65 SecCmsSignerInfoCreateWithSubjKeyID(SecCmsSignedDataRef sigd, const SecAsn1Item *subjKeyID, SecPublicKeyRef pubKey, SecPrivateKeyRef signingKey, SECOidTag digestalgtag)
  66     API_AVAILABLE(ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(iosmac);
  67 #endif // !TARGET_OS_OSX
  68
  69 #if TARGET_OS_OSX
  70 /*!
  71      @function
  72      @abstract Destroy a SignerInfo data structure.
  73  */
  74 extern void
  75 SecCmsSignerInfoDestroy(SecCmsSignerInfoRef si)
  76     API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, iosmac);
  77 #endif
  78
  79 /*!
  80     @function
  81  */
  82 extern SecCmsVerificationStatus
  83 SecCmsSignerInfoGetVerificationStatus(SecCmsSignerInfoRef signerinfo);
  84
  85 /*!
  86     @function
  87  */
  88 extern SECOidData *
  89 SecCmsSignerInfoGetDigestAlg(SecCmsSignerInfoRef signerinfo);
  90
  91 /*!
  92     @function
  93  */
  94 extern SECOidTag
  95 SecCmsSignerInfoGetDigestAlgTag(SecCmsSignerInfoRef signerinfo);
  96
  97 /*!
  98     @function
  99  */
 100 extern CFArrayRef
 101 SecCmsSignerInfoGetCertList(SecCmsSignerInfoRef signerinfo);
 102
 103 /*!
 104     @function
 105     @abstract Return the signing time, in UTCTime format, of a CMS signerInfo.
 106     @param sinfo SignerInfo data for this signer.
 107     @discussion Returns a pointer to XXXX (what?)
 108     @result A return value of NULL is an error.
 109  */
 110 extern OSStatus
 111 SecCmsSignerInfoGetSigningTime(SecCmsSignerInfoRef sinfo, CFAbsoluteTime *stime);
 112
 113 /*!
 114      @function
 115      @abstract Return the data in the signed Codesigning Hash Agility attribute.
 116      @param sinfo SignerInfo data for this signer, pointer to a CFDataRef for attribute value
 117      @discussion Returns a CFDataRef containing the value of the attribute
 118      @result A return value of SECFailure is an error.
 119  */
 120 extern OSStatus
 121 SecCmsSignerInfoGetAppleCodesigningHashAgility(SecCmsSignerInfoRef sinfo, CFDataRef *sdata);
 122
 123 /*!
 124      @function
 125      @abstract Return the data in the signed Codesigning Hash Agility V2 attribute.
 126      @param sinfo SignerInfo data for this signer, pointer to a CFDictionaryRef for attribute values
 127      @discussion Returns a CFDictionaryRef containing the values of the attribute. V2 encodes the
 128         hash agility values using DER.
 129      @result A return value of SECFailure is an error.
 130  */
 131 extern OSStatus
 132 SecCmsSignerInfoGetAppleCodesigningHashAgilityV2(SecCmsSignerInfoRef sinfo, CFDictionaryRef *sdict);
 133
 134 /*!
 135      @function SecCmsSignerInfoGetAppleExpirationTime
 136      @abstract Return the expriation time, in CFAbsoluteTime, of a CMS signerInfo.
 137      @param sinfo SignerInfo data for this signer.
 138      @discussion Returns a CFAbsoluteTime
 139      @result A return value of SECFailure is an error.
 140  */
 141 extern OSStatus
 142 SecCmsSignerInfoGetAppleExpirationTime(SecCmsSignerInfoRef sinfo, CFAbsoluteTime *etime);
 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  */
 149 extern SecCertificateRef
 150 SecCmsSignerInfoGetSigningCertificate(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  */
 159 extern CF_RETURNS_RETAINED CFStringRef
 160 SecCmsSignerInfoGetSignerCommonName(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  */
 169 extern CF_RETURNS_RETAINED CFStringRef
 170 SecCmsSignerInfoGetSignerEmailAddress(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  */
 184 extern OSStatus
 185 SecCmsSignerInfoAddSigningTime(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  */
 192 extern OSStatus
 193 SecCmsSignerInfoAddSMIMECaps(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  */
 200 OSStatus
 201 SecCmsSignerInfoAddSMIMEEncKeyPrefs(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  */
 208 OSStatus
 209 SecCmsSignerInfoAddMSSMIMEEncKeyPrefs(SecCmsSignerInfoRef signerinfo, SecCertificateRef cert, SecKeychainRef keychainOrArray);
 210
 211 /*!
 212     @function
 213     @abstract Countersign a signerinfo.
 214  */
 215 extern OSStatus
 216 SecCmsSignerInfoAddCounterSignature(SecCmsSignerInfoRef signerinfo,
 217                                     SECOidTag digestalg, SecIdentityRef identity);
 218
 219 /*!
 220      @function
 221      @abstract Add the Apple Codesigning Hash Agility attribute to the authenticated (i.e. signed) attributes of "signerinfo".
 222      @discussion This is expected to be included in outgoing Apple code signatures.
 223 */
 224 OSStatus
 225 SecCmsSignerInfoAddAppleCodesigningHashAgility(SecCmsSignerInfoRef signerinfo, CFDataRef attrValue);
 226
 227 /*!
 228      @function
 229      @abstract Add the Apple Codesigning Hash Agility V2 attribute to the authenticated (i.e. signed) attributes of "signerinfo".
 230      @discussion This is expected to be included in outgoing Apple code signatures. V2 encodes the hash agility values using DER.
 231      The dictionary should have CFNumberRef keys, corresponding to SECOidTags for digest algorithms, and CFDataRef values,
 232      corresponding to the digest value for that digest algorithm.
 233  */
 234 OSStatus
 235 SecCmsSignerInfoAddAppleCodesigningHashAgilityV2(SecCmsSignerInfoRef signerinfo, CFDictionaryRef attrValues);
 236
 237 /*!
 238      @function SecCmsSignerInfoAddAppleExpirationTime
 239      @abstract Add the expiration time to the authenticated (i.e. signed) attributes of "signerinfo".
 240      @discussion This is expected to be included in outgoing signed messages for Asset Receipts but is likely
 241      useful in other situations. This should only be added once; a second call will do nothing.
 242      @result A result of SECFailure indicates an error adding the attribute.
 243  */
 244 extern OSStatus
 245 SecCmsSignerInfoAddAppleExpirationTime(SecCmsSignerInfoRef signerinfo, CFAbsoluteTime t);
 246
 247 /*!
 248     @function
 249     @abstract The following needs to be done in the S/MIME layer code after signature of a signerinfo has been verified.
 250     @param signerinfo The SecCmsSignerInfo object for which we verified the signature.
 251     @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.
 252  */
 253 extern OSStatus
 254 SecCmsSignerInfoSaveSMIMEProfile(SecCmsSignerInfoRef signerinfo);
 255
 256 /*!
 257     @function
 258     @abstract Set cert chain inclusion mode for this signer.
 259  */
 260 extern OSStatus
 261 SecCmsSignerInfoIncludeCerts(SecCmsSignerInfoRef signerinfo, SecCmsCertChainMode cm, SECCertUsage usage);
 262
 263 /*! @functiongroup CMS misc utility functions */
 264 /*!
 265     @function
 266     Convert a SecCmsVerificationStatus to a human readable string.
 267  */
 268 extern const char *
 269 SecCmsUtilVerificationStatusToString(SecCmsVerificationStatus vs);
 270
 271 /*
 272  * Preference domain and key for the Microsoft ECDSA compatibility flag.
 273  * Default if not present is TRUE, meaning we generate ECDSA-signed messages
 274  * which are compatible with Microsoft Entourage. FALSE means we adhere to
 275  * the spec (RFC 3278 section 2.1.1).
 276  */
 277 #define kMSCompatibilityDomain    "com.apple.security.smime"
 278 #define kMSCompatibilityMode    CFSTR("MSCompatibilityMode")
 279
 280 /*!
 281  @function SecCmsSignerInfoCopyCertFromEncryptionKeyPreference
 282  @abstract Copy the certificate specified in the encryption key preference.
 283  @param signerinfo The SecCmsSignerInfo object for which we verified the signature.
 284  @result The preferred encryption certificate of the user who signed this message, if found.
 285  @discussion This function should be called after the signer info has been verified.
 286  */
 287 SecCertificateRef SecCmsSignerInfoCopyCertFromEncryptionKeyPreference(SecCmsSignerInfoRef signerinfo);
 288
 289 #if TARGET_OS_OSX
 290 /* MARK: Timestamping support */
 291
 292 extern OSStatus
 293 SecCmsSignerInfoVerifyUnAuthAttrs(SecCmsSignerInfoRef signerinfo)
 294     API_AVAILABLE(macos(10.8)) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, iosmac);
 295
 296 extern OSStatus
 297 SecCmsSignerInfoVerifyUnAuthAttrsWithPolicy(SecCmsSignerInfoRef signerinfo,CFTypeRef timeStampPolicy)
 298     API_AVAILABLE(macos(10.8)) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, iosmac);
 299
 300 #pragma clang diagnostic push
 301 #pragma clang diagnostic ignored "-Wdeprecated-declarations"
 302 extern CSSM_DATA *
 303 SecCmsSignerInfoGetEncDigest(SecCmsSignerInfoRef signerinfo)
 304     API_AVAILABLE(macos(10.8)) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, iosmac);
 305 #pragma clang diagnostic pop
 306
 307 extern CFArrayRef
 308 SecCmsSignerInfoGetTimestampCertList(SecCmsSignerInfoRef signerinfo)
 309     API_AVAILABLE(macos(10.8)) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, iosmac);
 310
 311 extern SecCertificateRef
 312 SecCmsSignerInfoGetTimestampSigningCert(SecCmsSignerInfoRef signerinfo)
 313     API_AVAILABLE(macos(10.8)) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, iosmac);
 314
 315 /*!
 316      @function
 317      @abstract Return the timestamp time, in UTCTime format, of a CMS signerInfo.
 318      @param sinfo SignerInfo data for this signer.
 319      @discussion Returns a pointer to XXXX (what?)
 320      @result A return value of NULL is an error.
 321  */
 322 OSStatus
 323 SecCmsSignerInfoGetTimestampTime(SecCmsSignerInfoRef sinfo, CFAbsoluteTime *stime)
 324     API_AVAILABLE(macos(10.8)) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, iosmac);
 325
 326 /*!
 327      @function
 328      @abstract Return the timestamp time, in UTCTime format, of a CMS signerInfo.
 329      @param sinfo SignerInfo data for this signer, timeStampPolicy the policy to verify the timestamp signer
 330      @discussion Returns a pointer to XXXX (what?)
 331      @result A return value of NULL is an error.
 332  */
 333 OSStatus
 334 SecCmsSignerInfoGetTimestampTimeWithPolicy(SecCmsSignerInfoRef sinfo, CFTypeRef timeStampPolicy, CFAbsoluteTime *stime)
 335     API_AVAILABLE(macos(10.8)) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, iosmac);
 336
 337 /*!
 338      @function
 339      @abstract Create a timestamp unsigned attribute with a TimeStampToken.
 340  */
 341 #pragma clang diagnostic push
 342 #pragma clang diagnostic ignored "-Wdeprecated-declarations"
 343 OSStatus
 344 SecCmsSignerInfoAddTimeStamp(SecCmsSignerInfoRef signerinfo, CSSM_DATA *tstoken)
 345     API_AVAILABLE(macos(10.8)) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, iosmac);
 346 #pragma clang diagnostic pop
 347 #endif // TARGET_OS_OSX
 348
 349 __END_DECLS
 350
 351 #endif /* _SECURITY_SECCMSSIGNERINFO_H_ */