Debian Codegraph @

upstream/debian-unstable/man3/CMS_EnvelopedData_create.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "CMS_ENVELOPEDDATA_CREATE 3SSL"
58 .TH CMS_ENVELOPEDDATA_CREATE 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 CMS_EnvelopedData_create_ex, CMS_EnvelopedData_create,
65 CMS_AuthEnvelopedData_create, CMS_AuthEnvelopedData_create_ex
66 \&\- Create CMS envelope
67 .SH SYNOPSIS
68 .IX Header "SYNOPSIS"
69 .Vb 1
70 \& #include <openssl/cms.h>
71 \&
72 \& CMS_ContentInfo *
73 \& CMS_EnvelopedData_create_ex(const EVP_CIPHER *cipher, OSSL_LIB_CTX *libctx,
74 \& const char *propq);
75 \& CMS_ContentInfo *CMS_EnvelopedData_create(const EVP_CIPHER *cipher);
76 \&
77 \& CMS_ContentInfo *
78 \& CMS_AuthEnvelopedData_create_ex(const EVP_CIPHER *cipher, OSSL_LIB_CTX *libctx,
79 \& const char *propq);
80 \& CMS_ContentInfo *CMS_AuthEnvelopedData_create(const EVP_CIPHER *cipher);
81 .Ve
82 .SH DESCRIPTION
83 .IX Header "DESCRIPTION"
84 \&\fBCMS_EnvelopedData_create_ex()\fR creates a \fBCMS_ContentInfo\fR structure
85 with a type \fBNID_pkcs7_enveloped\fR. \fIcipher\fR is the symmetric cipher to use.
86 The library context \fIlibctx\fR and the property query \fIpropq\fR are used when
87 retrieving algorithms from providers.
88 .PP
89 \&\fBCMS_AuthEnvelopedData_create_ex()\fR creates a \fBCMS_ContentInfo\fR
90 structure with a type \fBNID_id_smime_ct_authEnvelopedData\fR. \fBcipher\fR is the
91 symmetric AEAD cipher to use. Currently only AES variants with GCM mode are
92 supported. The library context \fIlibctx\fR and the property query \fIpropq\fR are
93 used when retrieving algorithms from providers.
94 .PP
95 The algorithm passed in the \fIcipher\fR parameter must support ASN1 encoding of
96 its parameters.
97 .PP
98 The recipients can be added later using \fBCMS_add1_recipient_cert\fR\|(3) or
99 \&\fBCMS_add0_recipient_key\fR\|(3).
100 .PP
101 The \fBCMS_ContentInfo\fR structure needs to be finalized using \fBCMS_final\fR\|(3)
102 and then freed using \fBCMS_ContentInfo_free\fR\|(3).
103 .PP
104 \&\fBCMS_EnvelopedData_create()\fR and \fBCMS_AuthEnvelopedData_create()\fR are similar to
105 \&\fBCMS_EnvelopedData_create_ex()\fR and \fBCMS_AuthEnvelopedData_create_ex()\fR
106 but use default values of NULL for
107 the library context \fIlibctx\fR and the property query \fIpropq\fR.
108 .SH NOTES
109 .IX Header "NOTES"
110 Although \fBCMS_EnvelopedData_create_ex()\fR, and \fBCMS_EnvelopedData_create()\fR,
111 \&\fBCMS_AuthEnvelopedData_create_ex()\fR, and \fBCMS_AuthEnvelopedData_create()\fR allocate
112 a new \fBCMS_ContentInfo\fR structure, they are not usually used in applications.
113 The wrappers \fBCMS_encrypt\fR\|(3) and \fBCMS_decrypt\fR\|(3) are often used instead.
114 .SH "RETURN VALUES"
115 .IX Header "RETURN VALUES"
116 If the allocation fails, \fBCMS_EnvelopedData_create_ex()\fR,
117 \&\fBCMS_EnvelopedData_create()\fR, \fBCMS_AuthEnvelopedData_create_ex()\fR,
118 \&\fBCMS_AuthEnvelopedData_create()\fR, \fBCMS_AuthEnvelopedData_create()\fR,
119 and \fBCMS_AuthEnvelopedData_create_ex()\fR return NULL and set an
120 error code that can be obtained by \fBERR_get_error\fR\|(3).
121 Otherwise, they return a pointer to the newly allocated structure.
122 .SH "SEE ALSO"
123 .IX Header "SEE ALSO"
124 \&\fBERR_get_error\fR\|(3), \fBCMS_encrypt\fR\|(3), \fBCMS_decrypt\fR\|(3), \fBCMS_final\fR\|(3),
125 \&\fBCMS_sign_ex\fR\|(3), \fBCMS_encrypt_ex\fR\|(3)
126 .SH HISTORY
127 .IX Header "HISTORY"
128 The \fBCMS_EnvelopedData_create_ex()\fR method was added in OpenSSL 3.0.
129 .PP
130 \&\fBCMS_AuthEnvelopedData_create()\fR and \fBCMS_AuthEnvelopedData_create_ex()\fR
131 were added in OpenSSL 3.5.
132 .SH COPYRIGHT
133 .IX Header "COPYRIGHT"
134 Copyright 2020\-2025 The OpenSSL Project Authors. All Rights Reserved.
135 .PP
136 Licensed under the Apache License 2.0 (the "License"). You may not use
137 this file except in compliance with the License. You can obtain a copy
138 in the file LICENSE in the source distribution or at
139 <https://www.openssl.org/source/license.html>.