SecCmsEncoder.h
1 /* 2 * Copyright (c) 2004-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 SecCmsEncoder.h 26 27 @availability 10.4 and later 28 @abstract CMS message encoding 29 @discussion The functions here implement functions for encoding 30 Cryptographic Message Syntax (CMS) objects as described 31 in rfc3369. 32 A SecCmsEncoder object is used to encode CMS messages into BER. 33 */ 34 35 #ifndef _SECURITY_SECCMSENCODER_H_ 36 #define _SECURITY_SECCMSENCODER_H_ 1 37 38 #include <Security/SecCmsBase.h> 39 #include <CoreFoundation/CFData.h> 40 41 42 __BEGIN_DECLS 43 44 /*! @functiongroup Streaming interface */ 45 46 #if TARGET_OS_OSX 47 /*! 48 @function 49 @abstract Set up encoding of a CMS message. 50 @param outputfn callback function for delivery of BER-encoded output will 51 not be called if NULL. 52 @param outputarg first argument passed to outputfn when it is called. 53 @param dest If non-NULL, pointer to a CSSM_DATA that will hold the 54 BER-encoded output. 55 @param destpoolp Pool to allocate BER-encoded output in. 56 @param pwfn callback function for getting token password for enveloped 57 data content with a password recipient. 58 @param pwfn_arg first argument passed to pwfn when it is called. 59 @param encrypt_key_cb callback function for getting bulk key for encryptedData content. 60 @param encrypt_key_cb_arg first argument passed to encrypt_key_cb when it is 61 called. 62 @param detached_digestalgs digest algorithms in detached_digests 63 @param detached_digests digests from detached content (one for every element 64 in detached_digestalgs). 65 @result On success a pointer to a SecCmsMessage containing the decoded message 66 is returned. On failure returns NULL. Call PR_GetError() to find out what 67 went wrong in this case. 68 @availability 10.4 through 10.7 69 */ 70 #pragma clang diagnostic push 71 #pragma clang diagnostic ignored "-Wdeprecated-declarations" 72 extern OSStatus 73 SecCmsEncoderCreate(SecCmsMessageRef cmsg, 74 SecCmsContentCallback outputfn, void *outputarg, 75 CSSM_DATA_PTR dest, SecArenaPoolRef destpoolp, 76 PK11PasswordFunc pwfn, void *pwfn_arg, 77 SecCmsGetDecryptKeyCallback encrypt_key_cb, void *encrypt_key_cb_arg, 78 SECAlgorithmID **detached_digestalgs, CSSM_DATA_PTR *detached_digests, 79 SecCmsEncoderRef *outEncoder) 80 API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(macCatalyst); 81 #pragma clang diagnostic pop 82 #else // !TARGET_OS_OSX 83 /*! 84 @function 85 @abstract Set up encoding of a CMS message. 86 @param cmsg The SecCmsMessageRef to be encoded. 87 @param outputfn callback function for delivery of BER-encoded output will 88 not be called if NULL. 89 @param outputarg first argument passed to outputfn when it is called. 90 @param outBer If non-NULL, a CFMutableDataRef to which the 91 BER-encoded output will be appended. 92 @param pwfn callback function for getting token password for enveloped 93 data content with a password recipient. 94 @param pwfn_arg first argument passed to pwfn when it is called. 95 @param encrypt_key_cb callback function for getting bulk key for encryptedData content. 96 @param encrypt_key_cb_arg first argument passed to encrypt_key_cb when it is 97 called. 98 @result On success a pointer to a SecCmsMessage containing the decoded message 99 is returned. On failure returns NULL. Call PR_GetError() to find out what 100 went wrong in this case. 101 @availability 10.4 and later 102 */ 103 extern OSStatus 104 SecCmsEncoderCreate(SecCmsMessageRef cmsg, 105 SecCmsContentCallback outputfn, void *outputarg, 106 CFMutableDataRef outBer, 107 PK11PasswordFunc pwfn, void *pwfn_arg, 108 SecCmsGetDecryptKeyCallback encrypt_key_cb, void *encrypt_key_cb_arg, 109 SecCmsEncoderRef *outEncoder) 110 API_AVAILABLE(ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(macCatalyst); 111 #endif // !TARGET_OS_OSX 112 113 /*! 114 @function 115 @abstract Take content data delivery from the user 116 @param encoder encoder context 117 @param data content data 118 @param len length of content data 119 @result On success 0 is returned. On failure returns non zero. Call 120 PR_GetError() to find out what went wrong in this case. 121 @availability 10.4 and later 122 */ 123 extern OSStatus 124 SecCmsEncoderUpdate(SecCmsEncoderRef encoder, const void *data, CFIndex len); 125 126 /*! 127 @function 128 @abstract Abort a (presumably failed) encoding process. 129 @param encoder Pointer to a SecCmsEncoderContext created with SecCmsEncoderCreate(). 130 @availability 10.4 and later 131 */ 132 extern void 133 SecCmsEncoderDestroy(SecCmsEncoderRef encoder); 134 135 /*! 136 @function 137 @abstract Signal the end of data. 138 @discussion Walks down the chain of encoders and the finishes them from the 139 innermost out. 140 @param encoder Pointer to a SecCmsEncoder created with SecCmsEncoderCreate(). 141 @result On success 0 is returned. On failure returns non zero. Call 142 PR_GetError() to find out what went wrong in this case. 143 @availability 10.4 and later 144 */ 145 extern OSStatus 146 SecCmsEncoderFinish(SecCmsEncoderRef encoder); 147 148 /*! @functiongroup One shot interface */ 149 #if TARGET_OS_OSX 150 /*! 151 @function 152 @abstract BER Encode a CMS message. 153 @discussion BER Encode a CMS message, with input being the plaintext message and outBer being the output, stored in arena's pool. 154 */ 155 #pragma clang diagnostic push 156 #pragma clang diagnostic ignored "-Wdeprecated-declarations" 157 extern OSStatus 158 SecCmsMessageEncode(SecCmsMessageRef cmsg, const CSSM_DATA *input, SecArenaPoolRef arena, 159 CSSM_DATA_PTR outBer) 160 API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(macCatalyst); 161 #pragma clang diagnostic pop 162 #else // !TARGET_OS_OSX 163 /*! 164 @function 165 @abstract BER Encode a CMS message. 166 @param cmsg The SecCmsMessageRef to be encoded. 167 @param input The inner content of the message. 168 @param outBer A CFMutableDataRef to which the 169 BER-encoded output will be appended. 170 @discussion BER Encode a CMS message, with input being the plaintext message and outBer being the output, stored in arena's pool. 171 */ 172 extern OSStatus 173 SecCmsMessageEncode(SecCmsMessageRef cmsg, const SecAsn1Item *input, 174 CFMutableDataRef outBer) 175 API_AVAILABLE(ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(macCatalyst); 176 #endif // !TARGET_OS_OSX 177 178 __END_DECLS 179 180 #endif /* _SECURITY_SECCMSENCODER_H_ */