1/* 2 * Copyright (c) 2004,2011,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 @header SecCmsDecoder.h 26 @Copyright (c) 2004,2011,2014 Apple Inc. All Rights Reserved. 27 28 @availability 10.4 and later 29 @abstract Interfaces of the CMS implementation. 30 @discussion The functions here implement functions for encoding 31 and decoding Cryptographic Message Syntax (CMS) objects 32 as described in rfc3369. 33 */ 34 35#ifndef _SECURITY_SECCMSDECODER_H_ 36#define _SECURITY_SECCMSDECODER_H_ 1 37 38#include <Security/SecCmsBase.h> 39 40 41#if defined(__cplusplus) 42extern "C" { 43#endif 44 45 46/*! @functiongroup Streaming interface */ 47/*! 48 @function 49 @abstract Set up decoding of a BER-encoded CMS message. 50 @param arena An ArenaPool object to use for the resulting message, or NULL if new ArenaPool 51 should be created. 52 @param cb callback function for delivery of inner content inner 53 content will be stored in the message if cb is NULL. 54 @param cb_arg first argument passed to cb when it is called. 55 @param pwfn callback function for getting token password for 56 enveloped data content with a password recipient. 57 @param pwfn_arg first argument passed to pwfn when it is called. 58 @param decrypt_key_cb callback function for getting bulk key 59 for encryptedData content. 60 @param decrypt_key_cb_arg first argument passed to decrypt_key_cb 61 when it is called. 62 @param outDecoder On success will contain a pointer to a newly created SecCmsDecoder. 63 @result A result code. See "SecCmsBase.h" for possible results. 64 @discussion Create a SecCmsDecoder(). If this function returns noErr, the caller must dispose of the returned outDecoder by calling SecCmsDecoderDestroy() or SecCmsDecoderFinish(). 65 @availability 10.4 and later 66 @updated 2004-04-05 67 */ 68extern OSStatus 69SecCmsDecoderCreate(SecArenaPoolRef arena, 70 SecCmsContentCallback cb, void *cb_arg, 71 PK11PasswordFunc pwfn, void *pwfn_arg, 72 SecCmsGetDecryptKeyCallback decrypt_key_cb, void 73 *decrypt_key_cb_arg, 74 SecCmsDecoderRef *outDecoder); 75 76/*! 77 @function 78 @abstract Feed BER-encoded data to decoder. 79 @param decoder Pointer to a SecCmsDecoderContext created with SecCmsDecoderCreate(). 80 @param buf Pointer to bytes to be decoded. 81 @param len number of bytes to decode. 82 @result A result code. See "SecCmsBase.h" for possible results. 83 @discussion If a call to this function fails the caller should call SecCmsDecoderDestroy(). 84 @availability 10.4 and later 85 */ 86extern OSStatus 87SecCmsDecoderUpdate(SecCmsDecoderRef decoder, const void *buf, CFIndex len); 88 89/*! 90 @function 91 @abstract Abort a (presumably failed) decoding process. 92 @param decoder Pointer to a SecCmsDecoderContext created with SecCmsDecoderCreate(). 93 @availability 10.4 and later 94 */ 95extern void 96SecCmsDecoderDestroy(SecCmsDecoderRef decoder); 97 98/*! 99 @function 100 @abstract Mark the end of inner content and finish decoding. 101 @param decoder Pointer to a SecCmsDecoderContext created with SecCmsDecoderCreate(). 102 @param outMessage On success a pointer to a SecCmsMessage containing the decoded message. 103 @result A result code. See "SecCmsBase.h" for possible results. 104 @discussion decoder is no longer valid after this function is called. 105 @availability 10.4 and later 106 */ 107extern OSStatus 108SecCmsDecoderFinish(SecCmsDecoderRef decoder, SecCmsMessageRef *outMessage); 109 110/*! @functiongroup One shot interface */ 111/*! 112 @function 113 @abstract Decode a CMS message from BER encoded data. 114 @discussion This function basically does the same as calling 115 SecCmsDecoderStart(), SecCmsDecoderUpdate() and SecCmsDecoderFinish(). 116 @param DERmessage Pointer to a CSSM_DATA containing the BER encoded cms 117 message to decode. 118 @param cb callback function for delivery of inner content inner 119 content will be stored in the message if cb is NULL. 120 @param cb_arg first argument passed to cb when it is called. 121 @param pwfn callback function for getting token password for enveloped 122 data content with a password recipient. 123 @param pwfn_arg first argument passed to pwfn when it is called. 124 @param decrypt_key_cb callback function for getting bulk key for encryptedData content. 125 @param decrypt_key_cb_arg first argument passed to decrypt_key_cb when it is called. 126 @param outMessage On success a pointer to a SecCmsMessage containing the decoded message. 127 @result A result code. See "SecCmsBase.h" for possible results. 128 @discussion decoder is no longer valid after this function is called. 129 @availability 10.4 and later 130 */ 131extern OSStatus 132SecCmsMessageDecode(const CSSM_DATA *encodedMessage, 133 SecCmsContentCallback cb, void *cb_arg, 134 PK11PasswordFunc pwfn, void *pwfn_arg, 135 SecCmsGetDecryptKeyCallback decrypt_key_cb, void *decrypt_key_cb_arg, 136 SecCmsMessageRef *outMessage); 137 138 139#if defined(__cplusplus) 140} 141#endif 142 143#endif /* _SECURITY_SECCMSDECODER_H_ */ 144