1*b077aed3SPierre Pronchery=pod 2*b077aed3SPierre Pronchery 3*b077aed3SPierre Pronchery=head1 NAME 4*b077aed3SPierre Pronchery 5*b077aed3SPierre Proncheryossl_namemap_new, ossl_namemap_free, ossl_namemap_stored, ossl_namemap_empty, 6*b077aed3SPierre Proncheryossl_namemap_add_name, ossl_namemap_add_name_n, ossl_namemap_add_names, 7*b077aed3SPierre Proncheryossl_namemap_name2num, ossl_namemap_name2num_n, 8*b077aed3SPierre Proncheryossl_namemap_doall_names 9*b077aed3SPierre Pronchery- internal number E<lt>-E<gt> name map 10*b077aed3SPierre Pronchery 11*b077aed3SPierre Pronchery=head1 SYNOPSIS 12*b077aed3SPierre Pronchery 13*b077aed3SPierre Pronchery #include "internal/cryptlib.h" 14*b077aed3SPierre Pronchery 15*b077aed3SPierre Pronchery OSSL_NAMEMAP *ossl_namemap_stored(OSSL_LIB_CTX *libctx); 16*b077aed3SPierre Pronchery 17*b077aed3SPierre Pronchery OSSL_NAMEMAP *ossl_namemap_new(void); 18*b077aed3SPierre Pronchery void ossl_namemap_free(OSSL_NAMEMAP *namemap); 19*b077aed3SPierre Pronchery int ossl_namemap_empty(OSSL_NAMEMAP *namemap); 20*b077aed3SPierre Pronchery 21*b077aed3SPierre Pronchery int ossl_namemap_add_name(OSSL_NAMEMAP *namemap, int number, const char *name); 22*b077aed3SPierre Pronchery int ossl_namemap_add_name_n(OSSL_NAMEMAP *namemap, int number, 23*b077aed3SPierre Pronchery const char *name, size_t name_len); 24*b077aed3SPierre Pronchery 25*b077aed3SPierre Pronchery int ossl_namemap_name2num(const OSSL_NAMEMAP *namemap, const char *name); 26*b077aed3SPierre Pronchery int ossl_namemap_name2num_n(const OSSL_NAMEMAP *namemap, 27*b077aed3SPierre Pronchery const char *name, size_t name_len); 28*b077aed3SPierre Pronchery int ossl_namemap_doall_names(const OSSL_NAMEMAP *namemap, int number, 29*b077aed3SPierre Pronchery void (*fn)(const char *name, void *data), 30*b077aed3SPierre Pronchery void *data); 31*b077aed3SPierre Pronchery 32*b077aed3SPierre Pronchery int ossl_namemap_add_names(OSSL_NAMEMAP *namemap, int number, 33*b077aed3SPierre Pronchery const char *names, const char separator); 34*b077aed3SPierre Pronchery 35*b077aed3SPierre Pronchery=head1 DESCRIPTION 36*b077aed3SPierre Pronchery 37*b077aed3SPierre ProncheryA B<OSSL_NAMEMAP> is a one-to-many number E<lt>-E<gt> names map, which 38*b077aed3SPierre Proncherycan be used to give any arbitrary set of names (any string) a unique 39*b077aed3SPierre Proncherydynamic identity that is valid throughout the lifetime of the associated 40*b077aed3SPierre Proncherylibrary context. 41*b077aed3SPierre Pronchery 42*b077aed3SPierre Proncheryossl_namemap_new() and ossl_namemap_free() construct and destruct a 43*b077aed3SPierre Proncherynew B<OSSL_NAMEMAP>. 44*b077aed3SPierre ProncheryThis is suitable to use when the B<OSSL_NAMEMAP> is embedded in other 45*b077aed3SPierre Proncherystructures, or should be independent for any reason. 46*b077aed3SPierre Pronchery 47*b077aed3SPierre Proncheryossl_namemap_empty() checks if the given B<OSSL_NAMEMAP> is empty or 48*b077aed3SPierre Proncherynot. 49*b077aed3SPierre Pronchery 50*b077aed3SPierre Proncheryossl_namemap_stored() finds or auto-creates the default namemap in the 51*b077aed3SPierre Proncherygiven library context. 52*b077aed3SPierre ProncheryThe returned B<OSSL_NAMEMAP> can't be destructed using 53*b077aed3SPierre Proncheryossl_namemap_free(). 54*b077aed3SPierre Pronchery 55*b077aed3SPierre Proncheryossl_namemap_add_name() adds a new name to the namemap if it's not already 56*b077aed3SPierre Proncherypresent. 57*b077aed3SPierre ProncheryIf the given I<number> is zero, a new number will be allocated to 58*b077aed3SPierre Proncheryidentify this I<name>. 59*b077aed3SPierre ProncheryIf the given I<number> is nonzero, the I<name> is added to the set of 60*b077aed3SPierre Proncherynames already associated with that number. 61*b077aed3SPierre Pronchery 62*b077aed3SPierre Proncheryossl_namemap_name2num() finds the number corresponding to the given 63*b077aed3SPierre ProncheryI<name>. 64*b077aed3SPierre Pronchery 65*b077aed3SPierre Proncheryossl_namemap_add_name_n() and ossl_namemap_name2num_n() do the same thing 66*b077aed3SPierre Proncheryas ossl_namemap_add_name() and ossl_namemap_name2num(), but take a string 67*b077aed3SPierre Proncherylength I<name_len> as well, allowing the caller to use a fragment of 68*b077aed3SPierre Proncherya string as a name. 69*b077aed3SPierre Pronchery 70*b077aed3SPierre Proncheryossl_namemap_doall_names() walks through all names associated with 71*b077aed3SPierre ProncheryI<number> in the given I<namemap> and calls the function I<fn> for 72*b077aed3SPierre Proncheryeach of them. 73*b077aed3SPierre ProncheryI<fn> is also passed the I<data> argument, which allows any caller to 74*b077aed3SPierre Proncherypass extra data for that function to use. 75*b077aed3SPierre Pronchery 76*b077aed3SPierre Proncheryossl_namemap_add_names() divides up a set of names given in I<names>, 77*b077aed3SPierre Proncheryseparated by I<separator>, and adds each to the I<namemap>, all with 78*b077aed3SPierre Proncherythe same number. If some of them already exist in the I<namemap>, 79*b077aed3SPierre Proncherythey must all have the same associated number, which will be adopted 80*b077aed3SPierre Proncheryfor any name that doesn't exist yet. 81*b077aed3SPierre Pronchery 82*b077aed3SPierre Pronchery=head1 RETURN VALUES 83*b077aed3SPierre Pronchery 84*b077aed3SPierre Proncheryossl_namemap_new() and ossl_namemap_stored() return the pointer to a 85*b077aed3SPierre ProncheryB<OSSL_NAMEMAP>, or NULL on error. 86*b077aed3SPierre Pronchery 87*b077aed3SPierre Proncheryossl_namemap_empty() returns 1 if the B<OSSL_NAMEMAP> is NULL or 88*b077aed3SPierre Proncheryempty, 0 if it's not empty, or -1 on internal error (such as inability 89*b077aed3SPierre Proncheryto lock). 90*b077aed3SPierre Pronchery 91*b077aed3SPierre Proncheryossl_namemap_add_name() and ossl_namemap_add_name_n() return the number 92*b077aed3SPierre Proncheryassociated with the added string, or zero on error. 93*b077aed3SPierre Pronchery 94*b077aed3SPierre Proncheryossl_namemap_num2names() returns a pointer to a NULL-terminated list of 95*b077aed3SPierre Proncherypointers to the names corresponding to the given number, or NULL if 96*b077aed3SPierre Proncheryit's undefined in the given B<OSSL_NAMEMAP>. 97*b077aed3SPierre Pronchery 98*b077aed3SPierre Proncheryossl_namemap_name2num() and ossl_namemap_name2num_n() return the number 99*b077aed3SPierre Proncherycorresponding to the given name, or 0 if it's undefined in the given 100*b077aed3SPierre ProncheryB<OSSL_NAMEMAP>. 101*b077aed3SPierre Pronchery 102*b077aed3SPierre Proncheryossl_namemap_doall_names() returns 1 if the callback was called for all names. A 103*b077aed3SPierre Proncheryreturn value of 0 means that the callback was not called for any names. 104*b077aed3SPierre Pronchery 105*b077aed3SPierre Proncheryossl_namemap_add_names() returns the number associated with the added 106*b077aed3SPierre Proncherynames, or zero on error. 107*b077aed3SPierre Pronchery 108*b077aed3SPierre Pronchery=head1 NOTES 109*b077aed3SPierre Pronchery 110*b077aed3SPierre ProncheryThe result from ossl_namemap_num2names() isn't thread safe, other threads 111*b077aed3SPierre Proncherydealing with the same namemap may cause the list of names to change 112*b077aed3SPierre Proncherylocation. 113*b077aed3SPierre ProncheryIt is therefore strongly recommended to only use the result in code 114*b077aed3SPierre Proncheryguarded by a thread lock. 115*b077aed3SPierre Pronchery 116*b077aed3SPierre Pronchery=head1 HISTORY 117*b077aed3SPierre Pronchery 118*b077aed3SPierre ProncheryThe functions described here were all added in OpenSSL 3.0. 119*b077aed3SPierre Pronchery 120*b077aed3SPierre Pronchery=head1 COPYRIGHT 121*b077aed3SPierre Pronchery 122*b077aed3SPierre ProncheryCopyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. 123*b077aed3SPierre Pronchery 124*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 125*b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 126*b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 127*b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 128*b077aed3SPierre Pronchery 129*b077aed3SPierre Pronchery=cut 130