OSX/libsecurity_smime/lib/SecCmsSignerInfo.h

   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 #include <CoreFoundation/CFDate.h>
  42
  43
  44 #if defined(__cplusplus)
  45 extern "C" {
  46 #endif
  47
  48 /*!
  49     @function
  50  */
  51 extern SecCmsSignerInfoRef
  52 SecCmsSignerInfoCreate(SecCmsMessageRef cmsg, SecIdentityRef identity, SECOidTag digestalgtag);
  53
  54 /*!
  55     @function
  56  */
  57 extern SecCmsSignerInfoRef
  58 SecCmsSignerInfoCreateWithSubjKeyID(SecCmsMessageRef cmsg, CSSM_DATA_PTR subjKeyID, SecPublicKeyRef pubKey, SecPrivateKeyRef signingKey, SECOidTag digestalgtag) DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
  59
  60 /*!
  61     @function
  62     @abstract Destroy a SignerInfo data structure.
  63  */
  64 extern void
  65 SecCmsSignerInfoDestroy(SecCmsSignerInfoRef si);
  66
  67 /*!
  68     @function
  69  */
  70 extern SecCmsVerificationStatus
  71 SecCmsSignerInfoGetVerificationStatus(SecCmsSignerInfoRef signerinfo);
  72
  73 /*!
  74     @function
  75  */
  76 extern OSStatus
  77 SecCmsSignerInfoVerifyUnAuthAttrs(SecCmsSignerInfoRef signerinfo);
  78
  79 /*!
  80     @function
  81  */
  82 extern OSStatus
  83 SecCmsSignerInfoVerifyUnAuthAttrsWithPolicy(SecCmsSignerInfoRef signerinfo,CFTypeRef timeStampPolicy);
  84
  85 /*!
  86     @function
  87  */
  88 extern CSSM_DATA *
  89 SecCmsSignerInfoGetEncDigest(SecCmsSignerInfoRef signerinfo) DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
  90
  91 /*!
  92     @function
  93  */
  94 extern SECOidData *
  95 SecCmsSignerInfoGetDigestAlg(SecCmsSignerInfoRef signerinfo);
  96
  97 /*!
  98     @function
  99  */
 100 extern SECOidTag
 101 SecCmsSignerInfoGetDigestAlgTag(SecCmsSignerInfoRef signerinfo);
 102
 103 /*!
 104     @function
 105  */
 106 extern CFArrayRef
 107 SecCmsSignerInfoGetCertList(SecCmsSignerInfoRef signerinfo);
 108
 109 /*!
 110     @function
 111  */
 112 extern CFArrayRef
 113 SecCmsSignerInfoGetTimestampCertList(SecCmsSignerInfoRef signerinfo);
 114
 115 /*!
 116  @function
 117  */
 118 extern SecCertificateRef
 119 SecCmsSignerInfoGetTimestampSigningCert(SecCmsSignerInfoRef signerinfo);
 120
 121 /*!
 122     @function
 123     @abstract Return the signing time, in UTCTime format, of a CMS signerInfo.
 124     @param sinfo SignerInfo data for this signer.
 125     @discussion Returns a pointer to XXXX (what?)
 126     @result A return value of NULL is an error.
 127  */
 128 extern OSStatus
 129 SecCmsSignerInfoGetSigningTime(SecCmsSignerInfoRef sinfo, CFAbsoluteTime *stime);
 130
 131 /*!
 132     @function
 133     @abstract Return the timestamp time, in UTCTime format, of a CMS signerInfo.
 134     @param sinfo SignerInfo data for this signer.
 135     @discussion Returns a pointer to XXXX (what?)
 136     @result A return value of NULL is an error.
 137  */
 138 OSStatus
 139 SecCmsSignerInfoGetTimestampTime(SecCmsSignerInfoRef sinfo, CFAbsoluteTime *stime);
 140
 141 /*!
 142     @function
 143     @abstract Return the timestamp time, in UTCTime format, of a CMS signerInfo.
 144     @param sinfo SignerInfo data for this signer, timeStampPolicy the policy to verify the timestamp signer
 145     @discussion Returns a pointer to XXXX (what?)
 146     @result A return value of NULL is an error.
 147  */
 148 OSStatus
 149 SecCmsSignerInfoGetTimestampTimeWithPolicy(SecCmsSignerInfoRef sinfo, CFTypeRef timeStampPolicy, CFAbsoluteTime *stime);
 150
 151 /*!
 152     @function
 153     @abstract Return the data in the signed Codesigning Hash Agility attribute.
 154     @param sinfo SignerInfo data for this signer, pointer to a CFDataRef for attribute value
 155     @discussion Returns a CFDataRef containing the value of the attribute
 156     @result A return value of SECFailure is an error.
 157  */
 158 OSStatus
 159 SecCmsSignerInfoGetAppleCodesigningHashAgility(SecCmsSignerInfoRef sinfo, CFDataRef *sdata);
 160
 161 /*!
 162      @function
 163      @abstract Return the data in the signed Codesigning Hash Agility V2 attribute.
 164      @param sinfo SignerInfo data for this signer, pointer to a CFDictionaryRef for attribute values
 165      @discussion Returns a CFDictionaryRef containing the values of the attribute. V2 encodes the hash
 166         agility values using DER.
 167      @result A return value of SECFailure is an error.
 168  */
 169 extern OSStatus
 170 SecCmsSignerInfoGetAppleCodesigningHashAgilityV2(SecCmsSignerInfoRef sinfo, CFDictionaryRef *sdict);
 171
 172 /*!
 173      @function SecCmsSignerInfoGetAppleExpirationTime
 174      @abstract Return the expriation time, in CFAbsoluteTime, of a CMS signerInfo.
 175      @param sinfo SignerInfo data for this signer.
 176      @discussion Returns a CFAbsoluteTime
 177      @result A return value of SECFailure is an error.
 178  */
 179 extern OSStatus
 180 SecCmsSignerInfoGetAppleExpirationTime(SecCmsSignerInfoRef sinfo, CFAbsoluteTime *etime);
 181
 182 /*!
 183     @function
 184     @abstract Return the signing cert of a CMS signerInfo.
 185     @discussion The certs in the enclosing SignedData must have been imported already.
 186  */
 187 extern SecCertificateRef
 188 SecCmsSignerInfoGetSigningCertificate(SecCmsSignerInfoRef signerinfo, SecKeychainRef keychainOrArray);
 189
 190 /*!
 191     @function
 192     @abstract Return the common name of the signer.
 193     @param sinfo SignerInfo data for this signer.
 194     @discussion Returns a CFStringRef containing the common name of the signer.
 195     @result A return value of NULL is an error.
 196  */
 197 extern CFStringRef
 198 SecCmsSignerInfoGetSignerCommonName(SecCmsSignerInfoRef sinfo);
 199
 200 /*!
 201     @function
 202     @abstract Return the email address of the signer
 203     @param sinfo SignerInfo data for this signer.
 204     @discussion Returns a CFStringRef containing the name of the signer.
 205     @result A return value of NULL is an error.
 206  */
 207 extern CFStringRef
 208 SecCmsSignerInfoGetSignerEmailAddress(SecCmsSignerInfoRef sinfo);
 209
 210 /*!
 211     @function
 212     @abstract Add the signing time to the authenticated (i.e. signed) attributes of "signerinfo".
 213     @discussion This is expected to be included in outgoing signed
 214                 messages for email (S/MIME) but is likely useful in other situations.
 215
 216                 This should only be added once; a second call will do nothing.
 217
 218                 XXX This will probably just shove the current time into "signerinfo"
 219                 but it will not actually get signed until the entire item is
 220                 processed for encoding.  Is this (expected to be small) delay okay?
 221  */
 222 extern OSStatus
 223 SecCmsSignerInfoAddSigningTime(SecCmsSignerInfoRef signerinfo, CFAbsoluteTime t);
 224
 225 /*!
 226     @function
 227     @abstract Add a SMIMECapabilities attribute to the authenticated (i.e. signed) attributes of "signerinfo".
 228     @discussion This is expected to be included in outgoing signed messages for email (S/MIME).
 229  */
 230 extern OSStatus
 231 SecCmsSignerInfoAddSMIMECaps(SecCmsSignerInfoRef signerinfo);
 232
 233 /*!
 234     @function
 235     @abstract Add a SMIMEEncryptionKeyPreferences attribute to the authenticated (i.e. signed) attributes of "signerinfo".
 236     @discussion This is expected to be included in outgoing signed messages for email (S/MIME).
 237  */
 238 OSStatus
 239 SecCmsSignerInfoAddSMIMEEncKeyPrefs(SecCmsSignerInfoRef signerinfo, SecCertificateRef cert, SecKeychainRef keychainOrArray);
 240
 241 /*!
 242     @function
 243     @abstract Add a SMIMEEncryptionKeyPreferences attribute to the authenticated (i.e. signed) attributes of "signerinfo", using the OID prefered by Microsoft.
 244     @discussion This is expected to be included in outgoing signed messages for email (S/MIME), if compatibility with Microsoft mail clients is wanted.
 245  */
 246 OSStatus
 247 SecCmsSignerInfoAddMSSMIMEEncKeyPrefs(SecCmsSignerInfoRef signerinfo, SecCertificateRef cert, SecKeychainRef keychainOrArray);
 248
 249 /*!
 250     @function
 251     @abstract Create a timestamp unsigned attribute with a TimeStampToken.
 252  */
 253 OSStatus
 254 SecCmsSignerInfoAddTimeStamp(SecCmsSignerInfoRef signerinfo, CSSM_DATA *tstoken) DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 255
 256 /*!
 257     @function
 258     @abstract Countersign a signerinfo.
 259  */
 260 extern OSStatus
 261 SecCmsSignerInfoAddCounterSignature(SecCmsSignerInfoRef signerinfo,
 262                                     SECOidTag digestalg, SecIdentityRef identity);
 263
 264 /*!
 265      @function
 266      @abstract Add the Apple Codesigning Hash Agility attribute to the authenticated (i.e. signed) attributes of "signerinfo".
 267      @discussion This is expected to be included in outgoing Apple code signatures.
 268  */
 269  OSStatus
 270  SecCmsSignerInfoAddAppleCodesigningHashAgility(SecCmsSignerInfoRef signerinfo, CFDataRef attrValue);
 271
 272 /*!
 273      @function
 274      @abstract Add the Apple Codesigning Hash Agility V2 attribute to the authenticated (i.e. signed) attributes of "signerinfo".
 275      @discussion This is expected to be included in outgoing Apple code signatures. V2 encodes the hash agility values using DER.
 276      The dictionary should have CFNumberRef keys, corresponding to SECOidTags for digest algorithms, and CFDataRef values,
 277      corresponding to the digest value for that digest algorithm.
 278  */
 279 OSStatus
 280 SecCmsSignerInfoAddAppleCodesigningHashAgilityV2(SecCmsSignerInfoRef signerinfo, CFDictionaryRef attrValues);
 281
 282 /*!
 283      @function SecCmsSignerInfoAddAppleExpirationTime
 284      @abstract Add the expiration time to the authenticated (i.e. signed) attributes of "signerinfo".
 285      @discussion This is expected to be included in outgoing signed messages for Asset Receipts but is likely
 286      useful in other situations. This should only be added once; a second call will do nothing.
 287      @result A result of SECFailure indicates an error adding the attribute.
 288  */
 289 extern OSStatus
 290 SecCmsSignerInfoAddAppleExpirationTime(SecCmsSignerInfoRef signerinfo, CFAbsoluteTime t);
 291
 292 /*!
 293     @function
 294     @abstract The following needs to be done in the S/MIME layer code after signature of a signerinfo has been verified.
 295     @param signerinfo The SecCmsSignerInfo object for which we verified the signature.
 296     @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.
 297  */
 298 extern OSStatus
 299 SecCmsSignerInfoSaveSMIMEProfile(SecCmsSignerInfoRef signerinfo);
 300
 301 /*!
 302     @function
 303     @abstract Set cert chain inclusion mode for this signer.
 304  */
 305 extern OSStatus
 306 SecCmsSignerInfoIncludeCerts(SecCmsSignerInfoRef signerinfo, SecCmsCertChainMode cm, SECCertUsage usage);
 307
 308 /*! @functiongroup CMS misc utility functions */
 309 /*!
 310     @function
 311     Convert a SecCmsVerificationStatus to a human readable string.
 312  */
 313 extern const char *
 314 SecCmsUtilVerificationStatusToString(SecCmsVerificationStatus vs);
 315
 316 /*
 317  * Preference domain and key for the Microsoft ECDSA compatibility flag.
 318  * Default if not present is TRUE, meaning we generate ECDSA-signed messages
 319  * which are compatible with Microsoft Entourage. FALSE means we adhere to
 320  * the spec (RFC 3278 section 2.1.1).
 321  */
 322 #define kMSCompatibilityDomain  "com.apple.security.smime"
 323 #define kMSCompatibilityMode    CFSTR("MSCompatibilityMode")
 324
 325 /*!
 326  @function SecCmsSignerInfoCopyCertFromEncryptionKeyPreference
 327  @abstract Copy the certificate specified in the encryption key preference.
 328  @param signerinfo The SecCmsSignerInfo object for which we verified the signature.
 329  @result The preferred encryption certificate of the user who signed this message, if found.
 330  @discussion This function should be called after the signer info has been verified.
 331  */
 332 SecCertificateRef SecCmsSignerInfoCopyCertFromEncryptionKeyPreference(SecCmsSignerInfoRef signerinfo);
 333
 334 #if defined(__cplusplus)
 335 }
 336 #endif
 337
 338 #endif /* _SECURITY_SECCMSSIGNERINFO_H_ */