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