5 ossl_namemap_new, ossl_namemap_free, ossl_namemap_stored,
6 ossl_namemap_add, ossl_namemap_add_n,
7 ossl_namemap_name2num, ossl_namemap_name2num_n,
8 ossl_namemap_doall_names
9 - internal number E<lt>-E<gt> name map
13 #include "internal/cryptlib.h"
15 OSSL_NAMEMAP *ossl_namemap_stored(OPENSSL_CTX *libctx);
17 OSSL_NAMEMAP *ossl_namemap_new(void);
18 void ossl_namemap_free(OSSL_NAMEMAP *namemap);
20 int ossl_namemap_add(OSSL_NAMEMAP *namemap, int number, const char *name);
21 int ossl_namemap_add_n(OSSL_NAMEMAP *namemap, int number,
22 const char *name, size_t name_len);
24 int ossl_namemap_name2num(const OSSL_NAMEMAP *namemap, const char *name);
25 int ossl_namemap_name2num_n(const OSSL_NAMEMAP *namemap,
26 const char *name, size_t name_len);
27 void ossl_namemap_doall_names(const OSSL_NAMEMAP *namemap, int number,
28 void (*fn)(const char *name, void *data),
33 A B<OSSL_NAMEMAP> is a one-to-many number E<lt>-E<gt> names map, which
34 can be used to give any arbitrary set of names (any string) a unique
35 dynamic identity that is valid throughout the lifetime of the associated
38 ossl_namemap_new() and ossl_namemap_free() construct and destruct a
40 This is suitable to use when the B<OSSL_NAMEMAP> is embedded in other
41 structures, or should be independent for any reason.
43 ossl_namemap_stored() finds or auto-creates the default namemap in the
44 given library context.
45 The returned B<OSSL_NAMEMAP> can't be destructed using
48 ossl_namemap_add() adds a new name to the namemap if it's not already
50 If the given I<number> is zero, a new number will be allocated to
51 identify this I<name>.
52 If the given I<number> is nonzero, the I<name> is added to the set of
53 names already associated with that number.
55 ossl_namemap_name2num() finds the number corresponding to the given
58 ossl_namemap_add_n() and ossl_namemap_name2num_n() do the same thing
59 as ossl_namemap_add() and ossl_namemap_name2num(), but take a string
60 length I<name_len> as well, allowing the caller to use a fragment of
64 ossl_namemap_doall_names() walks through all names associated with
65 I<number> in the given I<namemap> and calls the function I<fn> for
67 I<fn> is also passed the I<data> argument, which allows any caller to
68 pass extra data for that function to use.
72 ossl_namemap_new() and ossl_namemap_stored() return the pointer to a
73 B<OSSL_NAMEMAP>, or NULL on error.
75 ossl_namemap_add() and ossl_namemap_add_n() return the number associated
76 with the added string, or zero on error.
78 ossl_namemap_num2names() returns a pointer to a NULL-terminated list of
79 pointers to the names corresponding to the given number, or NULL if
80 it's undefined in the given B<OSSL_NAMEMAP>.
82 ossl_namemap_name2num() and ossl_namemap_name2num_n() return the number
83 corresponding to the given name, or 0 if it's undefined in the given
88 The result from ossl_namemap_num2names() isn't thread safe, other threads
89 dealing with the same namemap may cause the list of names to change
91 It is therefore strongly recommended to only use the result in code
92 guarded by a thread lock.
96 The functions described here were all added in OpenSSL 3.0.
100 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
102 Licensed under the Apache License 2.0 (the "License"). You may not use
103 this file except in compliance with the License. You can obtain a copy
104 in the file LICENSE in the source distribution or at
105 L<https://www.openssl.org/source/license.html>.