CMS/SecCmsSignedData.h

   1 /*
   2  *  Copyright (c) 2004-2018 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 SecCmsSignedData.h
  26
  27     @availability 10.4 and later
  28     @abstract Interfaces of the CMS implementation.
  29     @discussion The functions here implement functions for encoding
  30                 and decoding Cryptographic Message Syntax (CMS) objects
  31                 as described in rfc3369.
  32  */
  33
  34 #ifndef _SECURITY_SECCMSSIGNEDDATA_H_
  35 #define _SECURITY_SECCMSSIGNEDDATA_H_  1
  36
  37 #include <Security/SecCmsBase.h>
  38 #include <Security/SecTrust.h>
  39
  40 __BEGIN_DECLS
  41
  42 /*!
  43     @function
  44     @abstract Create a new SecCmsSignedData object.
  45     @param cmsg Pointer to a SecCmsMessage in which this SecCmsSignedData
  46         should be created.
  47  */
  48 extern SecCmsSignedDataRef
  49 SecCmsSignedDataCreate(SecCmsMessageRef cmsg);
  50
  51 /*!
  52     @function
  53  */
  54 extern void
  55 SecCmsSignedDataDestroy(SecCmsSignedDataRef sigd);
  56
  57 /*!
  58     @function
  59     @abstract Retrieve the SignedData's signer list.
  60  */
  61 extern SecCmsSignerInfoRef *
  62 SecCmsSignedDataGetSignerInfos(SecCmsSignedDataRef sigd);
  63
  64 /*!
  65     @function
  66  */
  67 extern int
  68 SecCmsSignedDataSignerInfoCount(SecCmsSignedDataRef sigd);
  69
  70 /*!
  71     @function
  72  */
  73 extern SecCmsSignerInfoRef
  74 SecCmsSignedDataGetSignerInfo(SecCmsSignedDataRef sigd, int i);
  75
  76 /*!
  77     @function
  78     @abstract Retrieve the SignedData's digest algorithm list.
  79  */
  80 #pragma clang diagnostic push
  81 #pragma clang diagnostic ignored "-Wdeprecated-declarations"
  82 extern SECAlgorithmID **
  83 SecCmsSignedDataGetDigestAlgs(SecCmsSignedDataRef sigd);
  84 #pragma clang diagnostic pop
  85
  86 /*!
  87     @function
  88     @abstract Return pointer to this signedData's contentinfo.
  89  */
  90 extern SecCmsContentInfoRef
  91 SecCmsSignedDataGetContentInfo(SecCmsSignedDataRef sigd);
  92
  93 /*!
  94     @function
  95     @discussion XXX Should be obsoleted.
  96  */
  97 extern OSStatus
  98 SecCmsSignedDataImportCerts(SecCmsSignedDataRef sigd, SecKeychainRef keychain,
  99                                 SECCertUsage certusage, Boolean keepcerts);
 100
 101 /*!
 102     @function
 103     @abstract See if we have digests in place.
 104  */
 105 extern Boolean
 106 SecCmsSignedDataHasDigests(SecCmsSignedDataRef sigd);
 107
 108 /*!
 109     @function
 110     @abstract Check the signatures.
 111     @discussion The digests were either calculated during decoding (and are stored in the
 112                 signedData itself) or set after decoding using SecCmsSignedDataSetDigests.
 113
 114                 The verification checks if the signing cert is valid and has a trusted chain
 115                 for the purpose specified by "policies".
 116
 117                 If trustRef is NULL the cert chain is verified and the VerificationStatus is set accordingly.
 118                 Otherwise a SecTrust object is returned for the caller to evaluate using SecTrustEvaluate().
 119  */
 120 extern OSStatus
 121 SecCmsSignedDataVerifySignerInfo(SecCmsSignedDataRef sigd, int i, SecKeychainRef keychainOrArray,
 122                                  CFTypeRef policies, SecTrustRef *trustRef);
 123
 124 /*!
 125     @function
 126     @abstract Verify the certs in a certs-only message.
 127 */
 128 extern OSStatus
 129 SecCmsSignedDataVerifyCertsOnly(SecCmsSignedDataRef sigd,
 130                                   SecKeychainRef keychainOrArray,
 131                                   CFTypeRef policies);
 132
 133 /*!
 134     @function
 135  */
 136 extern OSStatus
 137 SecCmsSignedDataAddCertList(SecCmsSignedDataRef sigd, CFArrayRef certlist);
 138
 139 /*!
 140     @function
 141     @abstract Add cert and its entire chain to the set of certs.
 142  */
 143 extern OSStatus
 144 SecCmsSignedDataAddCertChain(SecCmsSignedDataRef sigd, SecCertificateRef cert);
 145
 146 /*!
 147     @function
 148  */
 149 extern OSStatus
 150 SecCmsSignedDataAddCertificate(SecCmsSignedDataRef sigd, SecCertificateRef cert);
 151
 152 /*!
 153     @function
 154  */
 155 extern Boolean
 156 SecCmsSignedDataContainsCertsOrCrls(SecCmsSignedDataRef sigd);
 157
 158
 159 #if TARGET_OS_OSX
 160 /*!
 161      @function
 162      @abstract Retrieve the SignedData's certificate list.
 163  */
 164 #pragma clang diagnostic push
 165 #pragma clang diagnostic ignored "-Wdeprecated-declarations"
 166 extern CSSM_DATA_PTR *
 167 SecCmsSignedDataGetCertificateList(SecCmsSignedDataRef sigd)
 168     API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(macCatalyst);
 169 #pragma clang diagnostic pop
 170 #else // !TARGET_OS_OSX
 171 /*!
 172     @function
 173     @abstract Retrieve the SignedData's certificate list.
 174  */
 175 extern SecAsn1Item * *
 176 SecCmsSignedDataGetCertificateList(SecCmsSignedDataRef sigd)
 177     API_AVAILABLE(ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(macCatalyst);
 178 #endif // !TARGET_OS_OSX
 179
 180 /*!
 181     @function
 182     @abstract Create a certs-only SignedData.
 183     @param cert Base certificate that will be included
 184     @param include_chain If true, include the complete cert chain for cert.
 185     @discussion More certs and chains can be added via AddCertificate and AddCertChain.
 186     @result An error results in a return value of NULL and an error set.
 187  */
 188 extern SecCmsSignedDataRef
 189 SecCmsSignedDataCreateCertsOnly(SecCmsMessageRef cmsg, SecCertificateRef cert, Boolean include_chain);
 190
 191 #if TARGET_OS_IPHONE
 192 /*!
 193         @function
 194     @abstract Finalize the digests in digestContext and apply them to sigd.
 195     @param sigd A SecCmsSignedDataRef for which the digests have been calculated
 196     @param digestContext A digestContext created with SecCmsDigestContextStartMultiple.
 197         @result The digest will have been applied to sigd.  After this call completes sigd is ready to accept
 198         SecCmsSignedDataVerifySignerInfo() calls.  The caller should still destroy digestContext with a SecCmsDigestContextDestroy() call.
 199
 200  */
 201 extern OSStatus SecCmsSignedDataSetDigestContext(SecCmsSignedDataRef sigd,
 202                                                                                                  SecCmsDigestContextRef digestContext)
 203      API_AVAILABLE(ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(macos, macCatalyst);
 204 #endif
 205
 206 #if TARGET_OS_OSX
 207 extern OSStatus
 208 SecCmsSignedDataAddSignerInfo(SecCmsSignedDataRef sigd,
 209                               SecCmsSignerInfoRef signerinfo);
 210
 211 #pragma clang diagnostic push
 212 #pragma clang diagnostic ignored "-Wdeprecated-declarations"
 213 extern OSStatus
 214 SecCmsSignedDataSetDigests(SecCmsSignedDataRef sigd,
 215                            SECAlgorithmID **digestalgs,
 216                            CSSM_DATA_PTR *digests)
 217     API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(macCatalyst);
 218 #pragma clang diagnostic pop
 219 #endif
 220
 221 __END_DECLS
 222
 223 #endif /* _SECURITY_SECCMSSIGNEDDATA_H_ */