libsecurity_smime/lib/SecCmsSignerInfo.h

   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)
  44 extern "C" {
  45 #endif
  46
  47 /*!
  48     @function
  49  */
  50 extern SecCmsSignerInfoRef
  51 SecCmsSignerInfoCreate(SecCmsSignedDataRef sigd, SecIdentityRef identity, SECOidTag digestalgtag);
  52
  53 /*!
  54     @function
  55  */
  56 extern SecCmsSignerInfoRef
  57 SecCmsSignerInfoCreateWithSubjKeyID(SecCmsSignedDataRef sigd, const SecAsn1Item *subjKeyID, SecPublicKeyRef pubKey, SecPrivateKeyRef signingKey, SECOidTag digestalgtag);
  58
  59 /*!
  60     @function
  61  */
  62 extern SecCmsVerificationStatus
  63 SecCmsSignerInfoGetVerificationStatus(SecCmsSignerInfoRef signerinfo);
  64
  65 /*!
  66     @function
  67  */
  68 extern SECOidData *
  69 SecCmsSignerInfoGetDigestAlg(SecCmsSignerInfoRef signerinfo);
  70
  71 /*!
  72     @function
  73  */
  74 extern SECOidTag
  75 SecCmsSignerInfoGetDigestAlgTag(SecCmsSignerInfoRef signerinfo);
  76
  77 /*!
  78     @function
  79  */
  80 extern CFArrayRef
  81 SecCmsSignerInfoGetCertList(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  */
  90 extern OSStatus
  91 SecCmsSignerInfoGetSigningTime(SecCmsSignerInfoRef sinfo, CFAbsoluteTime *stime);
  92
  93 /*!
  94      @function
  95      @abstract Return the data in the signed Codesigning Hash Agility attribute.
  96      @param sinfo SignerInfo data for this signer, pointer to a CFDataRef for attribute value
  97      @discussion Returns a CFDataRef containing the value of the attribute
  98      @result A return value of SECFailure is an error.
  99  */
 100 extern OSStatus
 101 SecCmsSignerInfoGetAppleCodesigningHashAgility(SecCmsSignerInfoRef sinfo, CFDataRef *sdata);
 102
 103 /*!
 104      @function
 105      @abstract Return the data in the signed Codesigning Hash Agility V2 attribute.
 106      @param sinfo SignerInfo data for this signer, pointer to a CFDictionaryRef for attribute values
 107      @discussion Returns a CFDictionaryRef containing the values of the attribute. V2 encodes the
 108         hash agility values using DER.
 109      @result A return value of SECFailure is an error.
 110  */
 111 extern OSStatus
 112 SecCmsSignerInfoGetAppleCodesigningHashAgilityV2(SecCmsSignerInfoRef sinfo, CFDictionaryRef *sdict);
 113
 114 /*!
 115     @function
 116     @abstract Return the signing cert of a CMS signerInfo.
 117     @discussion The certs in the enclosing SignedData must have been imported already.
 118  */
 119 extern SecCertificateRef
 120 SecCmsSignerInfoGetSigningCertificate(SecCmsSignerInfoRef signerinfo, SecKeychainRef keychainOrArray);
 121
 122 /*!
 123     @function
 124     @abstract Return the common name of the signer.
 125     @param sinfo SignerInfo data for this signer.
 126     @discussion Returns a CFStringRef containing the common name of the signer.
 127     @result A return value of NULL is an error.
 128  */
 129 extern CF_RETURNS_RETAINED CFStringRef
 130 SecCmsSignerInfoGetSignerCommonName(SecCmsSignerInfoRef sinfo);
 131
 132 /*!
 133     @function
 134     @abstract Return the email address of the signer
 135     @param sinfo SignerInfo data for this signer.
 136     @discussion Returns a CFStringRef containing the name of the signer.
 137     @result A return value of NULL is an error.
 138  */
 139 extern CF_RETURNS_RETAINED CFStringRef
 140 SecCmsSignerInfoGetSignerEmailAddress(SecCmsSignerInfoRef sinfo);
 141
 142 /*!
 143     @function
 144     @abstract Add the signing time to the authenticated (i.e. signed) attributes of "signerinfo".
 145     @discussion This is expected to be included in outgoing signed
 146                 messages for email (S/MIME) but is likely useful in other situations.
 147
 148                 This should only be added once; a second call will do nothing.
 149
 150                 XXX This will probably just shove the current time into "signerinfo"
 151                 but it will not actually get signed until the entire item is
 152                 processed for encoding.  Is this (expected to be small) delay okay?
 153  */
 154 extern OSStatus
 155 SecCmsSignerInfoAddSigningTime(SecCmsSignerInfoRef signerinfo, CFAbsoluteTime t);
 156
 157 /*!
 158     @function
 159     @abstract Add a SMIMECapabilities attribute to the authenticated (i.e. signed) attributes of "signerinfo".
 160     @discussion This is expected to be included in outgoing signed messages for email (S/MIME).
 161  */
 162 extern OSStatus
 163 SecCmsSignerInfoAddSMIMECaps(SecCmsSignerInfoRef signerinfo);
 164
 165 /*!
 166     @function
 167     @abstract Add a SMIMEEncryptionKeyPreferences attribute to the authenticated (i.e. signed) attributes of "signerinfo".
 168     @discussion This is expected to be included in outgoing signed messages for email (S/MIME).
 169  */
 170 OSStatus
 171 SecCmsSignerInfoAddSMIMEEncKeyPrefs(SecCmsSignerInfoRef signerinfo, SecCertificateRef cert, SecKeychainRef keychainOrArray);
 172
 173 /*!
 174     @function
 175     @abstract Add a SMIMEEncryptionKeyPreferences attribute to the authenticated (i.e. signed) attributes of "signerinfo", using the OID prefered by Microsoft.
 176     @discussion This is expected to be included in outgoing signed messages for email (S/MIME), if compatibility with Microsoft mail clients is wanted.
 177  */
 178 OSStatus
 179 SecCmsSignerInfoAddMSSMIMEEncKeyPrefs(SecCmsSignerInfoRef signerinfo, SecCertificateRef cert, SecKeychainRef keychainOrArray);
 180
 181 /*!
 182     @function
 183     @abstract Countersign a signerinfo.
 184  */
 185 extern OSStatus
 186 SecCmsSignerInfoAddCounterSignature(SecCmsSignerInfoRef signerinfo,
 187                                     SECOidTag digestalg, SecIdentityRef identity);
 188
 189 /*!
 190      @function
 191      @abstract Add the Apple Codesigning Hash Agility attribute to the authenticated (i.e. signed) attributes of "signerinfo".
 192      @discussion This is expected to be included in outgoing Apple code signatures.
 193 */
 194 OSStatus
 195 SecCmsSignerInfoAddAppleCodesigningHashAgility(SecCmsSignerInfoRef signerinfo, CFDataRef attrValue);
 196
 197 /*!
 198      @function
 199      @abstract Add the Apple Codesigning Hash Agility V2 attribute to the authenticated (i.e. signed) attributes of "signerinfo".
 200      @discussion This is expected to be included in outgoing Apple code signatures. V2 encodes the hash agility values using DER.
 201      The dictionary should have CFNumberRef keys, corresponding to SECOidTags for digest algorithms, and CFDataRef values,
 202      corresponding to the digest value for that digest algorithm.
 203  */
 204 OSStatus
 205 SecCmsSignerInfoAddAppleCodesigningHashAgilityV2(SecCmsSignerInfoRef signerinfo, CFDictionaryRef attrValues);
 206
 207 /*!
 208     @function
 209     @abstract The following needs to be done in the S/MIME layer code after signature of a signerinfo has been verified.
 210     @param signerinfo The SecCmsSignerInfo object for which we verified the signature.
 211     @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.
 212  */
 213 extern OSStatus
 214 SecCmsSignerInfoSaveSMIMEProfile(SecCmsSignerInfoRef signerinfo);
 215
 216 /*!
 217     @function
 218     @abstract Set cert chain inclusion mode for this signer.
 219  */
 220 extern OSStatus
 221 SecCmsSignerInfoIncludeCerts(SecCmsSignerInfoRef signerinfo, SecCmsCertChainMode cm, SECCertUsage usage);
 222
 223 /*! @functiongroup CMS misc utility functions */
 224 /*!
 225     @function
 226     Convert a SecCmsVerificationStatus to a human readable string.
 227  */
 228 extern const char *
 229 SecCmsUtilVerificationStatusToString(SecCmsVerificationStatus vs);
 230
 231 /*!
 232  @function SecCmsSignerInfoCopyCertFromEncryptionKeyPreference
 233  @abstract Copy the certificate specified in the encryption key preference.
 234  @param signerinfo The SecCmsSignerInfo object for which we verified the signature.
 235  @result The preferred encryption certificate of the user who signed this message, if found.
 236  @discussion This function should be called after the signer info has been verified.
 237  */
 238 SecCertificateRef SecCmsSignerInfoCopyCertFromEncryptionKeyPreference(SecCmsSignerInfoRef signerinfo);
 239
 240
 241 #if defined(__cplusplus)
 242 }
 243 #endif
 244
 245 #endif /* _SECURITY_SECCMSSIGNERINFO_H_ */