OSX/libsecurity_smime/lib/SecCMS.h

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