1/*
2 *  Copyright (c) 2004,2008,2010 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    @Copyright (c) 2004,2008,2010 Apple Inc. All Rights Reserved.
27
28    @availability 10.4 and later
29    @abstract CMS message encoding
30    @discussion The functions here implement functions for encoding
31                Cryptographic Message Syntax (CMS) objects as described
32                in rfc3369.
33                A SecCmsEncoder object is used to encode CMS messages into BER.
34 */
35
36#ifndef _SECURITY_SECCMSENCODER_H_
37#define _SECURITY_SECCMSENCODER_H_  1
38
39#include <Security/SecCmsBase.h>
40#include <CoreFoundation/CFData.h>
41
42
43#if defined(__cplusplus)
44extern "C" {
45#endif
46
47
48/*! @functiongroup Streaming interface */
49/*!
50    @function
51    @abstract Set up encoding of a CMS message.
52	@param cmsg The SecCmsMessageRef to be encoded.
53    @param outputfn callback function for delivery of BER-encoded output will
54        not be called if NULL.
55    @param outputarg first argument passed to outputfn when it is called.
56    @param dest If non-NULL, a CFMutableDataRef to which the
57        BER-encoded output will be appended.
58    @param pwfn callback function for getting token password for enveloped
59           data content with a password recipient.
60    @param pwfn_arg first argument passed to pwfn when it is called.
61    @param encrypt_key_cb callback function for getting bulk key for encryptedData content.
62    @param encrypt_key_cb_arg first argument passed to encrypt_key_cb when it is
63        called.
64    @param detached_digestalgs digest algorithms in detached_digests
65    @param detached_digests digests from detached content (one for every element
66        in detached_digestalgs).
67    @result On success a pointer to a SecCmsMessage containing the decoded message
68        is returned. On failure returns NULL. Call PR_GetError() to find out what
69        went wrong in this case.
70    @availability 10.4 and later
71 */
72extern OSStatus
73SecCmsEncoderCreate(SecCmsMessageRef cmsg,
74                    SecCmsContentCallback outputfn, void *outputarg,
75                    CFMutableDataRef outBer,
76                    PK11PasswordFunc pwfn, void *pwfn_arg,
77                    SecCmsGetDecryptKeyCallback encrypt_key_cb, void *encrypt_key_cb_arg,
78                    SecCmsEncoderRef *outEncoder);
79
80/*!
81    @function
82    @abstract Take content data delivery from the user
83    @param encoder encoder context
84    @param data content data
85    @param len length of content data
86    @result On success 0 is returned. On failure returns non zero. Call
87        PR_GetError() to find out what went wrong in this case.
88    @availability 10.4 and later
89 */
90extern OSStatus
91SecCmsEncoderUpdate(SecCmsEncoderRef encoder, const void *data, CFIndex len);
92
93/*!
94    @function
95    @abstract Abort a (presumably failed) encoding process.
96    @param encoder Pointer to a SecCmsEncoderContext created with SecCmsEncoderCreate().
97    @availability 10.4 and later
98 */
99extern void
100SecCmsEncoderDestroy(SecCmsEncoderRef encoder);
101
102/*!
103    @function
104    @abstract Signal the end of data.
105    @discussion Walks down the chain of encoders and the finishes them from the
106        innermost out.
107    @param encoder Pointer to a SecCmsEncoder created with SecCmsEncoderCreate().
108    @result On success 0 is returned. On failure returns non zero. Call
109        PR_GetError() to find out what went wrong in this case.
110    @availability 10.4 and later
111 */
112extern OSStatus
113SecCmsEncoderFinish(SecCmsEncoderRef encoder);
114
115/*! @functiongroup One shot interface */
116/*!
117    @function
118    @abstract BER Encode a CMS message.
119	@param cmsg The SecCmsMessageRef to be encoded.
120	@param input The inner content of the message.
121    @param outBer A CFMutableDataRef to which the
122        BER-encoded output will be appended.
123    @discussion BER Encode a CMS message, with input being the plaintext message and outBer being the output, stored in arena's pool.
124 */
125extern OSStatus
126SecCmsMessageEncode(SecCmsMessageRef cmsg, const SecAsn1Item *input,
127                    CFMutableDataRef outBer);
128
129
130#if defined(__cplusplus)
131}
132#endif
133
134#endif /* _SECURITY_SECCMSENCODER_H_ */
135