1  /*
  2   * Copyright (c) 2008-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 SecCMS
 26  */
 27  
 28  #include <CoreFoundation/CoreFoundation.h>
 29  #include <Security/SecIdentity.h>
 30  #include <Security/SecPolicy.h>
 31  #include <Security/SecTrust.h>
 32  
 33  #ifndef _SECURITY_SECCMS_H_
 34  #define _SECURITY_SECCMS_H_
 35  
 36  __BEGIN_DECLS
 37  
 38  extern const void * kSecCMSSignDigest;
 39  extern const void * kSecCMSSignDetached;
 40  extern const void * kSecCMSSignHashAlgorithm;
 41  extern const void * kSecCMSCertChainMode;
 42  extern const void * kSecCMSAdditionalCerts;
 43  extern const void * kSecCMSSignedAttributes;
 44  extern const void * kSecCMSSignDate;
 45  extern const void * kSecCMSAllCerts;
 46  extern const void * kSecCMSHashAgility;
 47  extern const void * kSecCMSHashAgilityV2;
 48  extern const void * kSecCMSExpirationDate;
 49  
 50  extern const void * kSecCMSBulkEncryptionAlgorithm;
 51  extern const void * kSecCMSEncryptionAlgorithmDESCBC;
 52  extern const void * kSecCMSEncryptionAlgorithmAESCBC;
 53  
 54  extern const void * kSecCMSCertChainModeNone;
 55  
 56  extern const void * kSecCMSHashingAlgorithmMD5
 57      __API_DEPRECATED("Disuse this constant in order to upgrade to SHA-1", ios(3.1, 10.0), macos(10.15, 10.15));
 58  extern const void * kSecCMSHashingAlgorithmSHA1;
 59  extern const void * kSecCMSHashingAlgorithmSHA256;
 60  extern const void * kSecCMSHashingAlgorithmSHA384;
 61  extern const void * kSecCMSHashingAlgorithmSHA512;
 62  
 63  /*!
 64  	@function SecCMSVerifyCopyDataAndAttributes
 65      @abstract verify a signed data cms blob.
 66      @param message the cms message to be parsed
 67      @param detached_contents to pass detached contents (optional)
 68      @param policy specifies policy or array thereof should be used (optional).  
 69  	if none is passed the blob will **not** be verified and only 
 70  	the attached contents will be returned.
 71      @param trustref (output/optional) if specified, the trust chain built during 
 72          verification will not be evaluated but returned to the caller to do so.
 73  	@param attached_contents (output/optional) return a copy of the attached 
 74          contents.
 75      @param signed_attributes (output/optional) return a copy of the signed
 76          attributes as a CFDictionary from oids (CFData) to values
 77          (CFArray of CFData).
 78      @result A result code.  See "Security Error Codes" (SecBase.h).
 79          errSecDecode not a CMS message we can parse,
 80          errSecAuthFailed bad signature, or untrusted signer if caller doesn't
 81          ask for trustref,
 82          errSecParam garbage in, garbage out.
 83  */
 84  OSStatus SecCMSVerifyCopyDataAndAttributes(CFDataRef message, CFDataRef detached_contents,
 85      CFTypeRef policy, SecTrustRef *trustref,
 86      CFDataRef *attached_contents, CFDictionaryRef *signed_attributes);
 87  
 88  /*!
 89  	@function SecCMSVerify
 90      @abstract same as SecCMSVerifyCopyDataAndAttributes, for binary compatibility.
 91  */
 92  OSStatus SecCMSVerify(CFDataRef message, CFDataRef detached_contents,
 93      CFTypeRef policy, SecTrustRef *trustref, CFDataRef *attached_contents);
 94  
 95  OSStatus SecCMSVerifySignedData(CFDataRef message, CFDataRef detached_contents,
 96      CFTypeRef policy, SecTrustRef *trustref, CFArrayRef additional_certificates,
 97      CFDataRef *attached_contents, CFDictionaryRef *message_attributes);
 98  
 99  
100  /* Return an array of certificates contained in message, if message is of the
101     type SignedData and has no signers, return NULL otherwise.   Not that if
102     the message is properly formed but has no certificates an empty array will
103     be returned. */
104  CFArrayRef SecCMSCertificatesOnlyMessageCopyCertificates(CFDataRef message);
105  
106  /* Create a degenerate PKCS#7 containing a cert or a CFArray of certs. */
107  CFDataRef SecCMSCreateCertificatesOnlyMessage(CFTypeRef cert_or_array_thereof);
108  CFDataRef SecCMSCreateCertificatesOnlyMessageIAP(SecCertificateRef cert);
109  
110  /*!
111  	@function SecCMSSignDataAndAttributes
112      @abstract create a signed data cms blob.
113      @param identity signer
114      @param data message to be signed
115      @param detached sign detached or not
116  	@param signed_data (output) return signed message.
117      @param signed_attributes (input/optional) signed attributes to insert
118          as a CFDictionary from oids (CFData) to value (CFData).
119      @result A result code.  See "Security Error Codes" (SecBase.h).
120          errSecParam garbage in, garbage out.
121  */
122  OSStatus SecCMSSignDataAndAttributes(SecIdentityRef identity, CFDataRef data, 
123      bool detached, CFMutableDataRef signed_data, CFDictionaryRef signed_attributes);
124  
125  /*!
126  	@function SecCMSSignDigestAndAttributes
127      @abstract create a detached signed data cms blob for a SHA-1 hash.
128      @param identity signer
129      @param digest SHA-1 digest of message to be signed
130  	@param signed_data (output) return signed message.
131      @param signed_attributes (input/optional) signed attributes to insert
132          as a CFDictionary from oids (CFData) to value (CFData).
133      @result A result code.  See "Security Error Codes" (SecBase.h).
134          errSecParam garbage in, garbage out.
135  */
136  OSStatus SecCMSSignDigestAndAttributes(SecIdentityRef identity, CFDataRef digest, 
137      CFMutableDataRef signed_data, CFDictionaryRef signed_attributes);
138  
139  /*!
140  	@function SecCMSCreateSignedData
141      @abstract create a signed data cms blob.
142      @param identity signer
143      @param data SHA-1 digest or message to be signed
144      @param parameters (input/optional) specify algorithm, detached, digest
145      @param signed_attributes (input/optional) signed attributes to insert
146          as a CFDictionary from oids (CFData) to value (CFData).
147      @param signed_data (output) return signed message.
148      @result A result code.  See "Security Error Codes" (SecBase.h).
149          errSecParam garbage in, garbage out.
150  */
151  OSStatus SecCMSCreateSignedData(SecIdentityRef identity, CFDataRef data, 
152      CFDictionaryRef parameters, CFDictionaryRef signed_attributes,
153      CFMutableDataRef signed_data);
154  
155  /*!
156      @function SecCMSCreateEnvelopedData
157      @abstract create a enveloped cms blob for recipients
158      @param recipient_or_cfarray_thereof SecCertificateRef for each recipient
159      @param params CFDictionaryRef with encryption parameters
160      @param data Data to be encrypted
161      @param enveloped_data (output) return enveloped message.
162      @result A result code.  See "Security Error Codes" (SecBase.h).
163          errSecParam garbage in, garbage out.
164  */
165  OSStatus SecCMSCreateEnvelopedData(CFTypeRef recipient_or_cfarray_thereof, 
166      CFDictionaryRef params, CFDataRef data, CFMutableDataRef enveloped_data);
167  
168  /*!
169      @function SecCMSDecryptEnvelopedData
170      @abstract open an enveloped cms blob. expects recipients identity in keychain.
171      @param message Eveloped message
172      @param data (output) return decrypted message.
173      @param recipient (output/optional) return addressed recipient
174      @result A result code.  See "Security Error Codes" (SecBase.h).
175          errSecParam garbage in, garbage out.
176  */
177  OSStatus SecCMSDecryptEnvelopedData(CFDataRef message, 
178      CFMutableDataRef data, SecCertificateRef *recipient);
179  
180  __END_DECLS
181  
182  #endif /* !_SECURITY_SECCMS_H_ */