1.\" $OpenBSD: EVP_CIPHER_do_all.3,v 1.3 2024/03/14 23:54:55 tb Exp $
2.\"
3.\" Copyright (c) 2023,2024 Theo Buehler <tb@openbsd.org>
4.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
5.\"
6.\" Permission to use, copy, modify, and distribute this software for any
7.\" purpose with or without fee is hereby granted, provided that the above
8.\" copyright notice and this permission notice appear in all copies.
9.\"
10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17.\"
18.Dd $Mdocdate: March 14 2024 $
19.Dt EVP_CIPHER_DO_ALL 3
20.Os
21.Sh NAME
22.Nm EVP_CIPHER_do_all ,
23.Nm EVP_CIPHER_do_all_sorted ,
24.Nm EVP_MD_do_all ,
25.Nm EVP_MD_do_all_sorted ,
26.Nm OBJ_NAME_do_all ,
27.Nm OBJ_NAME_do_all_sorted
28.Nd iterate over lookup tables for ciphers and digests
29.Sh SYNOPSIS
30.In openssl/evp.h
31.Ft void
32.Fo EVP_CIPHER_do_all
33.Fa "void (*fn)(const EVP_CIPHER *cipher, const char *from,\
34 const char *to, void *arg)"
35.Fa "void *arg"
36.Fc
37.Ft void
38.Fo EVP_CIPHER_do_all_sorted
39.Fa "void (*fn)(const EVP_CIPHER *cipher, const char *from,\
40 const char *to, void *arg)"
41.Fa "void *arg"
42.Fc
43.Ft void
44.Fo EVP_MD_do_all
45.Fa "void (*fn)(const EVP_MD *md, const char *from,\
46 const char *to, void *arg)"
47.Fa "void *arg"
48.Fc
49.Ft void
50.Fo EVP_MD_do_all_sorted
51.Fa "void (*fn)(const EVP_MD *md, const char *from,\
52 const char *to, void *arg)"
53.Fa "void *arg"
54.Fc
55.Bd -literal
56typedef struct {
57        int	    type;
58        int	    alias;
59        const char *name;
60        const char *data;
61} OBJ_NAME;
62.Ed
63.Pp
64.Ft void
65.Fo OBJ_NAME_do_all
66.Fa "int type"
67.Fa "void (*fn)(const OBJ_NAME *obj_name, void *arg)"
68.Fa "void *arg"
69.Fc
70.Ft void
71.Fo OBJ_NAME_do_all_sorted
72.Fa "int type"
73.Fa "void (*fn)(const OBJ_NAME *obj_name, void *arg)"
74.Fa "void *arg"
75.Fc
76.Sh DESCRIPTION
77.Fn EVP_CIPHER_do_all
78calls
79.Fa fn
80on every entry of the global table of cipher names and aliases.
81For a cipher name entry,
82.Fa fn
83is called with a non-NULL
84.Fa cipher ,
85its non-NULL cipher name
86.Fa from ,
87a NULL
88.Fa to ,
89and the
90.Fa arg
91pointer.
92For an alias entry,
93.Fa fn
94is called with a NULL
95.Fa cipher ,
96its alias
97.Fa from ,
98the cipher name that alias points
99.Fa to ,
100and the
101.Fa arg
102pointer.
103.Pp
104.Fn EVP_CIPHER_do_all_sorted
105is similar, except that it processes the cipher names and aliases
106in lexicographic order of their
107.Fa from
108names as determined by
109.Xr strcmp 3 .
110.Pp
111.Fn EVP_MD_do_all
112calls
113.Fa fn
114on every entry of the global table of digest names and aliases.
115For a digest name entry,
116.Fa fn
117is called with a non-NULL
118.Fa md ,
119its non-NULL digest name
120.Fa from ,
121a NULL
122.Fa to ,
123and the
124.Fa arg
125pointer.
126For an alias entry,
127.Fa fn
128is called with a NULL
129.Fa md ,
130its alias
131.Fa from ,
132the digest name that alias points
133.Fa to ,
134and the
135.Fa arg
136pointer.
137.Pp
138.Fn EVP_MD_do_all_sorted
139is similar, except that it processes the digest names and aliases
140in lexicographic order of their
141.Fa from
142names as determined by
143.Xr strcmp 3 .
144.Pp
145.Vt OBJ_NAME
146is an abstraction of the types underlying the lookup tables
147for ciphers and their aliases, and digests and their aliases, respectively.
148For a cipher,
149.Fa type
150is
151.Dv OBJ_NAME_TYPE_CIPHER_METH ,
152.Fa alias
153is 0,
154.Fa name
155is its lookup name and
156.Fa data
157is the
158.Vt EVP_CIPHER
159object it represents, cast to
160.Vt const char * .
161For a cipher alias,
162.Fa type
163is
164.Dv OBJ_NAME_TYPE_CIPHER_METH ,
165.Fa alias
166is
167.Dv OBJ_NAME_ALIAS ,
168.Fa name
169is its lookup name and
170.Fa data
171is the name it aliases.
172Digests representing an
173.Vt EVP_MD
174object and their aliases are represented similarly, except that their type is
175.Dv OBJ_NAME_TYPE_MD_METH .
176.Pp
177.Fn OBJ_NAME_do_all
178calls
179.Fa fn
180on every
181.Fa obj_name
182in the table that has the given
183.Fa type
184(either
185.Dv OBJ_NAME_TYPE_CIPHER_METH
186or
187.Dv OBJ_NAME_TYPE_MD_METH ) ,
188also passing the
189.Fa arg
190pointer.
191.Fn OBJ_NAME_do_all_sorted
192is similar except that it processes the
193.Fa obj_name
194in lexicographic order of their names as determined by
195.Xr strcmp 3 .
196.Sh SEE ALSO
197.Xr evp 3 ,
198.Xr EVP_get_cipherbyname 3 ,
199.Xr EVP_get_digestbyname 3
200.Sh HISTORY
201These functions first appeared in OpenSSL 1.0.0 and have been available since
202.Ox 4.9 .
203.Sh CAVEATS
204.Fn EVP_CIPHER_do_all_sorted ,
205.Fn EVP_MD_do_all_sorted ,
206and
207.Fn OBJ_NAME_do_all_sorted
208cannot report errors.
209In some implementations they need to allocate internally and
210if memory allocation fails they do nothing at all,
211without telling the caller about the problem.
212