Allow AES XTS decryption using duplicate keys.
[openssl.git] / doc / internal / man3 / ossl_namemap_new.pod
1 =pod
2
3 =head1 NAME
4
5 ossl_namemap_new, ossl_namemap_free, ossl_namemap_stored,
6 ossl_namemap_add, ossl_namemap_name, ossl_namemap_number
7 - internal number E<lt>-E<gt> name map
8
9 =head1 SYNOPSIS
10
11  #include "internal/cryptlib.h"
12
13  OSSL_NAMEMAP *ossl_namemap_stored(OPENSSL_CTX *libctx);
14
15  OSSL_NAMEMAP *ossl_namemap_new(void);
16  void ossl_namemap_free(OSSL_NAMEMAP *namemap);
17
18  int ossl_namemap_add(OSSL_NAMEMAP *namemap, const char *name);
19  const char *ossl_namemap_name(const OSSL_NAMEMAP *namemap, int number);
20  int ossl_namemap_number(const OSSL_NAMEMAP *namemap, const char *name);
21
22 =head1 DESCRIPTION
23
24 A B<OSSL_NAMEMAP> is a simple number E<lt>-E<gt> name map, which can
25 be used to give any arbitrary name (any string) a unique dynamic
26 identity that is valid throughout the lifetime of the associated
27 library context.
28
29 ossl_namemap_new() and ossl_namemap_free() construct and destruct a
30 new B<OSSL_NAMEMAP>.
31 This is suitable to use when the B<OSSL_NAMEMAP> is embedded in other
32 structures, or should be independent for any reason.
33
34 ossl_namemap_stored() finds or auto-creates the default namemap in the
35 given library context.
36 The returned B<OSSL_NAMEMAP> can't be destructed using
37 ossl_namemap_free().
38
39 ossl_namemap_add() adds a new name to the namemap if it's not already
40 present.
41
42 ossl_namemap_name() finds the name corresponding to the given number.
43
44 ossl_namemap_number() finds the number corresponding to the given
45 name.
46
47 =head1 RETURN VALUES
48
49 ossl_namemap_new() and ossl_namemap_stored() return the pointer to a
50 B<OSSL_NAMEMAP>, or NULL on error.
51
52 ossl_namemap_add() returns the number associated with the added
53 string, or zero on error.
54
55 ossl_namemap_name() returns a pointer to the name corresponding to the
56 given number, or NULL if it's undefined in the given B<OSSL_NAMEMAP>.
57
58 ossl_namemap_number() returns the number corresponding to the given
59 name, or 0 if it's undefined in the given B<OSSL_NAMEMAP>.
60
61 =head1 HISTORY
62
63 The functions described here were all added in OpenSSL 3.0.
64
65 =head1 COPYRIGHT
66
67 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
68
69 Licensed under the Apache License 2.0 (the "License").  You may not use
70 this file except in compliance with the License.  You can obtain a copy
71 in the file LICENSE in the source distribution or at
72 L<https://www.openssl.org/source/license.html>.
73
74 =cut