1/*
2 *  Copyright (c) 2004,2011-2012,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 SecCmsEncoder.h
26    @Copyright (c) 2004,2011-2012,2014 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
41
42#if defined(__cplusplus)
43extern "C" {
44#endif
45
46
47/*! @functiongroup Streaming interface */
48/*!
49    @function
50    @abstract Set up encoding of a CMS message.
51    @param outputfn callback function for delivery of BER-encoded output will
52        not be called if NULL.
53    @param outputarg first argument passed to outputfn when it is called.
54    @param dest If non-NULL, pointer to a CSSM_DATA that will hold the
55        BER-encoded output.
56    @param destpoolp Pool to allocate BER-encoded output in.
57    @param pwfn callback function for getting token password for enveloped
58           data content with a password recipient.
59    @param pwfn_arg first argument passed to pwfn when it is called.
60    @param encrypt_key_cb callback function for getting bulk key for encryptedData content.
61    @param encrypt_key_cb_arg first argument passed to encrypt_key_cb when it is
62        called.
63    @param detached_digestalgs digest algorithms in detached_digests
64    @param detached_digests digests from detached content (one for every element
65        in detached_digestalgs).
66    @result On success a pointer to a SecCmsMessage containing the decoded message
67        is returned. On failure returns NULL. Call PR_GetError() to find out what
68        went wrong in this case.
69    @availability 10.4 and later
70 */
71extern OSStatus
72SecCmsEncoderCreate(SecCmsMessageRef cmsg,
73                    SecCmsContentCallback outputfn, void *outputarg,
74                    CSSM_DATA_PTR dest, SecArenaPoolRef destpoolp,
75                    PK11PasswordFunc pwfn, void *pwfn_arg,
76                    SecCmsGetDecryptKeyCallback encrypt_key_cb, void *encrypt_key_cb_arg,
77                    SECAlgorithmID **detached_digestalgs, CSSM_DATA_PTR *detached_digests,
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    @discussion BER Encode a CMS message, with input being the plaintext message and outBer being the output, stored in arena's pool.
120 */
121extern OSStatus
122SecCmsMessageEncode(SecCmsMessageRef cmsg, const CSSM_DATA *input, SecArenaPoolRef arena,
123                    CSSM_DATA_PTR outBer);
124
125#if defined(__cplusplus)
126}
127#endif
128
129#endif /* _SECURITY_SECCMSENCODER_H_ */
130