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