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 signing cert of a CMS signerInfo.
 106     @discussion The certs in the enclosing SignedData must have been imported already.
 107  */
 108 extern SecCertificateRef
 109 SecCmsSignerInfoGetSigningCertificate(SecCmsSignerInfoRef signerinfo, SecKeychainRef keychainOrArray);
 110
 111 /*!
 112     @function
 113     @abstract Return the common name of the signer.
 114     @param sinfo SignerInfo data for this signer.
 115     @discussion Returns a CFStringRef containing the common name of the signer.
 116     @result A return value of NULL is an error.
 117  */
 118 extern CF_RETURNS_RETAINED CFStringRef
 119 SecCmsSignerInfoGetSignerCommonName(SecCmsSignerInfoRef sinfo);
 120
 121 /*!
 122     @function
 123     @abstract Return the email address of the signer
 124     @param sinfo SignerInfo data for this signer.
 125     @discussion Returns a CFStringRef containing the name of the signer.
 126     @result A return value of NULL is an error.
 127  */
 128 extern CF_RETURNS_RETAINED CFStringRef
 129 SecCmsSignerInfoGetSignerEmailAddress(SecCmsSignerInfoRef sinfo);
 130
 131 /*!
 132     @function
 133     @abstract Add the signing time to the authenticated (i.e. signed) attributes of "signerinfo".
 134     @discussion This is expected to be included in outgoing signed
 135                 messages for email (S/MIME) but is likely useful in other situations.
 136
 137                 This should only be added once; a second call will do nothing.
 138
 139                 XXX This will probably just shove the current time into "signerinfo"
 140                 but it will not actually get signed until the entire item is
 141                 processed for encoding.  Is this (expected to be small) delay okay?
 142  */
 143 extern OSStatus
 144 SecCmsSignerInfoAddSigningTime(SecCmsSignerInfoRef signerinfo, CFAbsoluteTime t);
 145
 146 /*!
 147     @function
 148     @abstract Add a SMIMECapabilities attribute to the authenticated (i.e. signed) attributes of "signerinfo".
 149     @discussion This is expected to be included in outgoing signed messages for email (S/MIME).
 150  */
 151 extern OSStatus
 152 SecCmsSignerInfoAddSMIMECaps(SecCmsSignerInfoRef signerinfo);
 153
 154 /*!
 155     @function
 156     @abstract Add a SMIMEEncryptionKeyPreferences attribute to the authenticated (i.e. signed) attributes of "signerinfo".
 157     @discussion This is expected to be included in outgoing signed messages for email (S/MIME).
 158  */
 159 OSStatus
 160 SecCmsSignerInfoAddSMIMEEncKeyPrefs(SecCmsSignerInfoRef signerinfo, SecCertificateRef cert, SecKeychainRef keychainOrArray);
 161
 162 /*!
 163     @function
 164     @abstract Add a SMIMEEncryptionKeyPreferences attribute to the authenticated (i.e. signed) attributes of "signerinfo", using the OID prefered by Microsoft.
 165     @discussion This is expected to be included in outgoing signed messages for email (S/MIME), if compatibility with Microsoft mail clients is wanted.
 166  */
 167 OSStatus
 168 SecCmsSignerInfoAddMSSMIMEEncKeyPrefs(SecCmsSignerInfoRef signerinfo, SecCertificateRef cert, SecKeychainRef keychainOrArray);
 169
 170 /*!
 171     @function
 172     @abstract Countersign a signerinfo.
 173  */
 174 extern OSStatus
 175 SecCmsSignerInfoAddCounterSignature(SecCmsSignerInfoRef signerinfo,
 176                                     SECOidTag digestalg, SecIdentityRef identity);
 177
 178 /*!
 179      @function
 180      @abstract Add the Apple Codesigning Hash Agility attribute to the authenticated (i.e. signed) attributes of "signerinfo".
 181      @discussion This is expected to be included in outgoing signed Apple code signatures.
 182 */
 183 OSStatus
 184 SecCmsSignerInfoAddAppleCodesigningHashAgility(SecCmsSignerInfoRef signerinfo, CFDataRef attrValue);
 185
 186 /*!
 187     @function
 188     @abstract The following needs to be done in the S/MIME layer code after signature of a signerinfo has been verified.
 189     @param signerinfo The SecCmsSignerInfo object for which we verified the signature.
 190     @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.
 191  */
 192 extern OSStatus
 193 SecCmsSignerInfoSaveSMIMEProfile(SecCmsSignerInfoRef signerinfo);
 194
 195 /*!
 196     @function
 197     @abstract Set cert chain inclusion mode for this signer.
 198  */
 199 extern OSStatus
 200 SecCmsSignerInfoIncludeCerts(SecCmsSignerInfoRef signerinfo, SecCmsCertChainMode cm, SECCertUsage usage);
 201
 202 /*! @functiongroup CMS misc utility functions */
 203 /*!
 204     @function
 205     Convert a SecCmsVerificationStatus to a human readable string.
 206  */
 207 extern const char *
 208 SecCmsUtilVerificationStatusToString(SecCmsVerificationStatus vs);
 209
 210
 211 #if defined(__cplusplus)
 212 }
 213 #endif
 214
 215 #endif /* _SECURITY_SECCMSSIGNERINFO_H_ */