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