| blob | 7f8cffd8817d7dfd133e4371778367af4b35a5df |
1 .\" $OpenBSD: PKCS7_new.3,v 1.2 2016/12/25 22:15:10 schwarze Exp $
2 .\"
3 .\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
4 .\"
5 .\" Permission to use, copy, modify, and distribute this software for any
6 .\" purpose with or without fee is hereby granted, provided that the above
7 .\" copyright notice and this permission notice appear in all copies.
8 .\"
9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16 .\"
17 .Dd $Mdocdate: December 25 2016 $
18 .Dt PKCS7_NEW 3
19 .Os
20 .Sh NAME
21 .Nm PKCS7_new ,
22 .Nm PKCS7_free ,
23 .Nm PKCS7_SIGNED_new ,
24 .Nm PKCS7_SIGNED_free ,
25 .Nm PKCS7_ENVELOPE_new ,
26 .Nm PKCS7_ENVELOPE_free ,
27 .Nm PKCS7_SIGN_ENVELOPE_new ,
28 .Nm PKCS7_SIGN_ENVELOPE_free ,
29 .Nm PKCS7_DIGEST_new ,
30 .Nm PKCS7_DIGEST_free ,
31 .Nm PKCS7_ENCRYPT_new ,
32 .Nm PKCS7_ENCRYPT_free ,
33 .Nm PKCS7_ENC_CONTENT_new ,
34 .Nm PKCS7_ENC_CONTENT_free ,
35 .Nm PKCS7_SIGNER_INFO_new ,
36 .Nm PKCS7_SIGNER_INFO_free ,
37 .Nm PKCS7_RECIP_INFO_new ,
38 .Nm PKCS7_RECIP_INFO_free ,
39 .Nm PKCS7_ISSUER_AND_SERIAL_new ,
40 .Nm PKCS7_ISSUER_AND_SERIAL_free
41 .Nd PKCS#7 data structures
42 .Sh SYNOPSIS
43 .In openssl/pkcs7.h
44 .Ft PKCS7 *
45 .Fn PKCS7_new void
46 .Ft void
47 .Fn PKCS7_free "PKCS7 *p7"
48 .Ft PKCS7_SIGNED *
49 .Fn PKCS7_SIGNED_new void
50 .Ft void
51 .Fn PKCS7_SIGNED_free "PKCS7_SIGNED *signed"
52 .Ft PKCS7_ENVELOPE *
53 .Fn PKCS7_ENVELOPE_new void
54 .Ft void
55 .Fn PKCS7_ENVELOPE_free "PKCS7_ENVELOPE *envelope"
56 .Ft PKCS7_SIGN_ENVELOPE *
57 .Fn PKCS7_SIGN_ENVELOPE_new void
58 .Ft void
59 .Fn PKCS7_SIGN_ENVELOPE_free "PKCS7_SIGN_ENVELOPE *signed_envelope"
60 .Ft PKCS7_DIGEST *
61 .Fn PKCS7_DIGEST_new void
62 .Ft void
63 .Fn PKCS7_DIGEST_free "PKCS7_DIGEST *digested"
64 .Ft PKCS7_ENCRYPT *
65 .Fn PKCS7_ENCRYPT_new void
66 .Ft void
67 .Fn PKCS7_ENCRYPT_free "PKCS7_ENCRYPT *encrypted"
68 .Ft PKCS7_ENC_CONTENT *
69 .Fn PKCS7_ENC_CONTENT_new void
70 .Ft void
71 .Fn PKCS7_ENC_CONTENT_free "PKCS7_ENC_CONTENT *content"
72 .Ft PKCS7_SIGNER_INFO *
73 .Fn PKCS7_SIGNER_INFO_new void
74 .Ft void
75 .Fn PKCS7_SIGNER_INFO_free "PKCS7_SIGNER_INFO *signer"
76 .Ft PKCS7_RECIP_INFO *
77 .Fn PKCS7_RECIP_INFO_new void
78 .Ft void
79 .Fn PKCS7_RECIP_INFO_free "PKCS7_RECIP_INFO *recip"
80 .Ft PKCS7_ISSUER_AND_SERIAL *
81 .Fn PKCS7_ISSUER_AND_SERIAL_new void
82 .Ft void
83 .Fn PKCS7_ISSUER_AND_SERIAL_free "PKCS7_ISSUER_AND_SERIAL *cert"
84 .Sh DESCRIPTION
85 PKCS#7 is an ASN.1-based format for transmitting data that has
86 cryptography applied to it, in particular signed and encrypted data.
87 .Pp
88 .Fn PKCS7_new
89 allocates and initializes an empty
90 .Vt PKCS7
91 object, representing an ASN.1
92 .Vt ContentInfo
93 structure defined in RFC 2315 section 7.
94 It is the top-level data structure able to hold any kind of content
95 that can be transmitted using PKCS#7.
96 It can be used recursively in
97 .Vt PKCS7_SIGNED
98 and
99 .Vt PKCS7_DIGEST
100 objects.
101 .Fn PKCS7_free
102 frees
103 .Fa p7 .
104 .Pp
105 .Fn PKCS7_SIGNED_new
106 allocates and initializes an empty
107 .Vt PKCS7_SIGNED
108 object, representing an ASN.1
109 .Vt SignedData
110 structure defined in RFC 2315 section 9.
111 It can be used inside
112 .Vt PKCS7
113 objects and holds any kind of content together with signatures by
114 zero or more signers and information about the signing algorithm
115 and certificates used.
116 .Fn PKCS7_SIGNED_free
117 frees
118 .Fa signed .
119 .Pp
120 .Fn PKCS7_ENVELOPE_new
121 allocates and initializes an empty
122 .Vt PKCS7_ENVELOPE
123 object, representing an ASN.1
124 .Vt EnvelopedData
125 structure defined in RFC 2315 section 10.
126 It can be used inside
127 .Vt PKCS7
128 objects and holds any kind of encrypted content together with
129 content-encryption keys for one or more recipients.
130 .Fn PKCS7_ENVELOPE_free
131 frees
132 .Fa envelope .
133 .Pp
134 .Fn PKCS7_SIGN_ENVELOPE_new
135 allocates and initializes an empty
136 .Vt PKCS7_SIGN_ENVELOPE
137 object, representing an ASN.1
138 .Vt SignedAndEnvelopedData
139 structure defined in RFC 2315 section 11.
140 It can be used inside
141 .Vt PKCS7
142 objects and holds any kind of encrypted content together with
143 signatures by one or more signers, information about the signing
144 algorithm and certificates used, and content-encryption keys for
145 one or more recipients.
146 .Fn PKCS7_SIGN_ENVELOPE_free
147 frees
148 .Fa signed_envelope .
149 .Pp
150 .Fn PKCS7_DIGEST_new
151 allocates and initializes an empty
152 .Vt PKCS7_DIGEST
153 object, representing an ASN.1
154 .Vt DigestedData
155 structure defined in RFC 2315 section 12.
156 It can be used inside
157 .Vt PKCS7
158 objects and holds any kind of content together with a message digest
159 for checking its integrity and information about the algorithm used.
160 .Fn PKCS7_DIGEST_free
161 frees
162 .Fa digested .
163 .Pp
164 .Fn PKCS7_ENCRYPT_new
165 allocates and initializes an empty
166 .Vt PKCS7_ENCRYPT
167 object, representing an ASN.1
168 .Vt EncryptedData
169 structure defined in RFC 2315 section 13.
170 It can be used inside
171 .Vt PKCS7
172 objects and holds any kind of encrypted content.
173 Keys are not included and need to be communicated separately.
174 .Fn PKCS7_ENCRYPT_free
175 frees
176 .Fa encrypted .
177 .Pp
178 .Fn PKCS7_ENC_CONTENT_new
179 allocates and initializes an empty
180 .Vt PKCS7_ENC_CONTENT
181 object, representing an ASN.1
182 .Vt EncryptedContentInfo
183 structure defined in RFC 2315 section 10.1.
184 It can be used inside
185 .Vt PKCS7_ENVELOPE ,
186 .Vt PKCS7_SIGN_ENVELOPE ,
187 and
188 .Vt PKCS7_ENCRYPT
189 objects and holds encrypted content together with information about
190 the encryption algorithm used.
191 .Fn PKCS7_ENC_CONTENT_free
192 frees
193 .Fa content .
194 .Pp
195 .Fn PKCS7_SIGNER_INFO_new
196 allocates and initializes an empty
197 .Vt PKCS7_SIGNER_INFO
198 object, representing an ASN.1
199 .Vt SignerInfo
200 structure defined in RFC 2315 section 9.2.
201 It can be used inside
202 .Vt PKCS7_SIGNED
203 and
204 .Vt PKCS7_SIGN_ENVELOPE
205 objects and holds a signature together with information about the
206 signer and the algorithms used.
207 .Fn PKCS7_SIGNER_INFO_free
208 frees
209 .Fa signer .
210 .Pp
211 .Fn PKCS7_RECIP_INFO_new
212 allocates and initializes an empty
213 .Vt PKCS7_RECIP_INFO
214 object, representing an ASN.1
215 .Vt RecipientInfo
216 structure defined in RFC 2315 section 10.2.
217 It can be used inside
218 .Vt PKCS7_ENVELOPE
219 and
220 .Vt PKCS7_SIGN_ENVELOPE
221 objects and holds a content-encryption key together with information
222 about the intended recipient and the key encryption algorithm used.
223 .Fn PKCS7_RECIP_INFO_free
224 frees
225 .Fa recip .
226 .Pp
227 .Fn PKCS7_ISSUER_AND_SERIAL_new
228 allocates and initializes an empty
229 .Vt PKCS7_ISSUER_AND_SERIAL
230 object, representing an ASN.1
231 .Vt IssuerAndSerialNumber
232 structure defined in RFC 2315 section 6.7.
233 It can be used inside
234 .Vt PKCS7_SIGNER_INFO
235 and
236 .Vt PKCS7_RECIP_INFO
237 objects and identifies a certificate by holding the distinguished
238 name of the certificate issuer and an issuer-specific certificate
239 serial number.
240 .Fn PKCS7_ISSUER_AND_SERIAL_free
241 frees
242 .Fa cert .
243 .Sh SEE ALSO
244 .Xr i2d_PKCS7_bio_stream 3 ,
245 .Xr PEM_read_PKCS7 3 ,
246 .Xr PEM_write_bio_PKCS7_stream 3 ,
247 .Xr PKCS7_decrypt 3 ,
248 .Xr PKCS7_encrypt 3 ,
249 .Xr PKCS7_sign 3 ,
250 .Xr PKCS7_sign_add_signer 3 ,
251 .Xr PKCS7_verify 3 ,
252 .Xr SMIME_read_PKCS7 3 ,
253 .Xr SMIME_write_PKCS7 3
254 .Sh STANDARDS
255 RFC 2315: PKCS #7: Cryptographic Message Syntax Version 1.5