OSX/sec/Security/SecCMS.h

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