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