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