1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
|
.\" $OpenBSD: EVP_CIPHER_CTX_init.3,v 1.4 2024/12/06 15:01:01 schwarze Exp $
.\" full merge up to:
.\" OpenSSL EVP_EncryptInit.pod 0874d7f2 Oct 11 13:13:47 2022 +0100
.\"
.\" This file is a derived work.
.\" The changes are covered by the following Copyright and license:
.\"
.\" Copyright (c) 2018, 2019, 2023 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>
.\" and Richard Levitte <levitte@openssl.org>.
.\" Copyright (c) 2000-2001, 2015 The OpenSSL Project.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in
.\" the documentation and/or other materials provided with the
.\" distribution.
.\"
.\" 3. All advertising materials mentioning features or use of this
.\" software must display the following acknowledgment:
.\" "This product includes software developed by the OpenSSL Project
.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
.\"
.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
.\" endorse or promote products derived from this software without
.\" prior written permission. For written permission, please contact
.\" openssl-core@openssl.org.
.\"
.\" 5. Products derived from this software may not be called "OpenSSL"
.\" nor may "OpenSSL" appear in their names without prior written
.\" permission of the OpenSSL Project.
.\"
.\" 6. Redistributions of any form whatsoever must retain the following
.\" acknowledgment:
.\" "This product includes software developed by the OpenSSL Project
.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: December 6 2024 $
.Dt EVP_CIPHER_CTX_INIT 3
.Os
.Sh NAME
.Nm EVP_CIPHER_CTX_init ,
.Nm EVP_CIPHER_CTX_cleanup ,
.Nm EVP_Cipher
.Nd obsolete EVP cipher functions
.Sh SYNOPSIS
.In openssl/evp.h
.Ft int
.Fo EVP_CIPHER_CTX_init
.Fa "EVP_CIPHER_CTX *ctx"
.Fc
.Ft int
.Fo EVP_CIPHER_CTX_cleanup
.Fa "EVP_CIPHER_CTX *ctx"
.Fc
.Ft int
.Fo EVP_Cipher
.Fa "EVP_CIPHER_CTX *ctx"
.Fa "unsigned char *out"
.Fa "const unsigned char *in"
.Fa "unsigned int in_len"
.Fc
.Sh DESCRIPTION
.Fn EVP_CIPHER_CTX_init
is a deprecated function that could be used to clear a cipher context
on the stack before
.Vt EVP_CIPHER_CTX
was made opaque.
Calling it on a cipher context just returned from
.Xr EVP_CIPHER_CTX_new 3
has no effect.
Calling it on a cipher context that was already used may leak memory
with older versions of the library.
Instead, use
.Xr EVP_CIPHER_CTX_reset 3
or
.Xr EVP_CIPHER_CTX_free 3 .
.Pp
.Fn EVP_CIPHER_CTX_cleanup
is a deprecated alias for
.Xr EVP_CIPHER_CTX_reset 3 .
It clears all information from
.Fa ctx
and frees all allocated memory associated with it, except the
.Fa ctx
object itself.
.Pp
.Fn EVP_Cipher
exposes implementation details of the functions
.Xr EVP_CipherUpdate 3
and
.Xr EVP_CipherFinal 3
that should never have become part of the public API.
.Pp
If the flag
.Dv EVP_CIPH_FLAG_CUSTOM_CIPHER
is set for the cipher used by
.Fa ctx ,
behaviour depends on
.Fa in .
If that argument is
.Dv NULL
and
.Fa in_len
is 0, behaviour is similar to
.Xr EVP_CipherFinal 3 ;
if
.Fa in_len
is not 0, behaviour is undefined.
If
.Fa in
is not
.Dv NULL ,
behaviour is similar to
.Xr EVP_CipherUpdate 3 .
In both cases, the exceptions to the similarity are that arguments
and return values differ.
.Pp
If the flag
.Dv EVP_CIPH_FLAG_CUSTOM_CIPHER
is not set for the cipher used by
.Fa ctx ,
it encrypts or decrypts aligned blocks of data
whose lengths match the cipher block size.
It requires that the previous encryption or decryption operation
using the same
.Fa ctx ,
if there was any, ended exactly on a block boundary and that
.Fa in_len
is an integer multiple of the cipher block size.
If either of these conditions is violated,
.Fn EVP_Cipher
silently produces incorrect results.
For that reason, using the function
.Xr EVP_CipherUpdate 3
instead is strongly recommended.
The latter can safely handle partial blocks, and even if
.Fa in_len
actually is a multiple of the cipher block size for all calls,
the overhead incurred by using
.Xr EVP_CipherUpdate 3
is minimal.
.Sh RETURN VALUES
.Fn EVP_CIPHER_CTX_init
always returns 1.
.Pp
.Fn EVP_CIPHER_CTX_cleanup
returns 1 for success or 0 for failure.
.Pp
With
.Dv EVP_CIPH_FLAG_CUSTOM_CIPHER ,
.Fn EVP_Cipher
returns the number of bytes written to
.Fa out
for success or \-1 for failure.
Without
.Dv EVP_CIPH_FLAG_CUSTOM_CIPHER ,
it returns 1 for success or 0 for failure.
.Sh SEE ALSO
.Xr evp 3 ,
.Xr EVP_EncryptInit 3
.Sh HISTORY
.Fn EVP_Cipher
first appeared in SSLeay 0.6.5.
.Fn EVP_CIPHER_CTX_cleanup
first appeared in SSLeay 0.8.0.
.Fn EVP_CIPHER_CTX_init
first appeared in SSLeay 0.9.0.
All these functions have been available since
.Ox 2.4 .
.Sh CAVEATS
Checking the return value of
.Fn EVP_Cipher
requires unusual caution: zero signals success if
.Dv EVP_CIPH_FLAG_CUSTOM_CIPHER
is set or failure otherwise.
|
