Debian Codegraph @

upstream/debian-unstable/man3/OSSL_ALGORITHM.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OSSL_ALGORITHM 3SSL"
58 .TH OSSL_ALGORITHM 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 OSSL_ALGORITHM \- OpenSSL Core type to define a fetchable algorithm
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& #include <openssl/core.h>
69 \&
70 \& typedef struct ossl_algorithm_st OSSL_ALGORITHM;
71 \& struct ossl_algorithm_st {
72 \& const char *algorithm_names; /* key */
73 \& const char *property_definition; /* key */
74 \& const OSSL_DISPATCH *implementation;
75 \& const char *algorithm_description;
76 \& };
77 .Ve
78 .SH DESCRIPTION
79 .IX Header "DESCRIPTION"
80 The \fBOSSL_ALGORITHM\fR type is a \fIpublic structure\fR that describes an
81 algorithm that a \fBprovider\fR\|(7) provides. Arrays of this type are returned
82 by providers on demand from the OpenSSL libraries to describe what
83 algorithms the providers provide implementations of, and with what
84 properties.
85 .PP
86 Arrays of this type must be terminated with a tuple where \fIalgorithm_names\fR
87 is NULL.
88 .PP
89 This type of array is typically returned by the provider's operation querying
90 function, further described in "Provider Functions" in \fBprovider\-base\fR\|(7).
91 .SS "\fBOSSL_ALGORITHM\fP fields"
92 .IX Subsection "OSSL_ALGORITHM fields"
93 .IP \fIalgorithm_names\fR 4
94 .IX Item "algorithm_names"
95 This string is a colon separated set of names / identities, and is used by
96 the appropriate fetching functionality (such as \fBEVP_CIPHER_fetch\fR\|(3),
97 \&\fBEVP_MD_fetch\fR\|(3), etc) to find the desired algorithm.
98 .Sp
99 Multiple names / identities allow a specific algorithm implementation to be
100 fetched multiple ways. For example, the RSA algorithm has the following
101 known identities:
102 .RS 4
103 .IP \(bu 4
104 \&\f(CW\*(C`RSA\*(C'\fR
105 .IP \(bu 4
106 \&\f(CW\*(C`rsaEncryption\*(C'\fR
107 .Sp
108 This is the name of the algorithm's OBJECT IDENTIFIER (OID), as given by the
109 PKCS#1 RFC's ASN.1 module <https://www.rfc-editor.org/rfc/rfc8017#appendix-C>
110 .IP \(bu 4
111 \&\f(CW1.2.840.113549.1.1.1\fR
112 .Sp
113 This is the OID itself for \f(CW\*(C`rsaEncryption\*(C'\fR, in canonical decimal text form.
114 .RE
115 .RS 4
116 .Sp
117 The resulting \fIalgorithm_names\fR string would look like this:
118 .Sp
119 .Vb 1
120 \& "RSA:rsaEncryption:1.2.840.113549.1.1.1"
121 .Ve
122 .Sp
123 The OpenSSL libraries use the first of the algorithm names as the main
124 or canonical name, on a per algorithm implementation basis.
125 .Sp
126 See the notes "On the subject of algorithm names" below for a more in
127 depth discussion on \fIalgorithm_names\fR and how that may interact with
128 applications and libraries, including OpenSSL's.
129 .RE
130 .IP \fIproperty_definition\fR 4
131 .IX Item "property_definition"
132 This string defines a set of properties associated with a particular
133 algorithm implementation, and is used by the appropriate fetching
134 functionality (such as \fBEVP_CIPHER_fetch\fR\|(3), \fBEVP_MD_fetch\fR\|(3), etc) for
135 a finer grained lookup of an algorithm implementation, which is useful in
136 case multiple implementations of the same algorithm are available.
137 .Sp
138 See \fBproperty\fR\|(7) for a further description of the contents of this
139 string.
140 .IP \fIimplementation\fR 4
141 .IX Item "implementation"
142 Pointer to an \fBOSSL_DISPATCH\fR\|(3) array, containing pointers to the
143 functions of a particular algorithm implementation.
144 .IP \fIalgorithm_description\fR 4
145 .IX Item "algorithm_description"
146 A string with a short human-readable description of the algorithm.
147 .SH NOTES
148 .IX Header "NOTES"
149 .SS "On the subject of algorithm names"
150 .IX Subsection "On the subject of algorithm names"
151 Providers may find the need to register ASN.1 OIDs for algorithms using
152 \&\fBOBJ_create\fR\|(3) (via the \fBcore_obj_create\fR upcall described in
153 \&\fBprovider\-base\fR\|(7), because some application or library \-\- possibly still
154 the OpenSSL libraries, even \-\- use NIDs to look up algorithms.
155 .PP
156 In that scenario, you must make sure that the corresponding \fBOSSL_ALGORITHM\fR's
157 \&\fIalgorithm_names\fR includes both the short and the long name.
158 .PP
159 Most of the time, registering ASN.1 OIDs like this shouldn't be necessary,
160 and applications and libraries are encouraged to use \fBOBJ_obj2txt\fR\|(3) to
161 get a text representation of the OID, which may be a long or short name for
162 OIDs that are registered, or the OID itself in canonical decimal text form
163 if not (or if \fBOBJ_obj2txt\fR\|(3) is called with \fIno_name\fR = 1).
164 .PP
165 It's recommended to make sure that the corresponding \fBOSSL_ALGORITHM\fR's
166 \&\fIalgorithm_names\fR include known names as well as the OID itself in
167 canonical decimal text form. That should cover all scenarios.
168 .SH "SEE ALSO"
169 .IX Header "SEE ALSO"
170 \&\fBcrypto\fR\|(7), \fBprovider\-base\fR\|(7), \fBopenssl\-core.h\fR\|(7),
171 \&\fBopenssl\-core_dispatch.h\fR\|(7), \fBOSSL_DISPATCH\fR\|(3)
172 .SH HISTORY
173 .IX Header "HISTORY"
174 \&\fBOSSL_ALGORITHM\fR was added in OpenSSL 3.0
175 .SH COPYRIGHT
176 .IX Header "COPYRIGHT"
177 Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.
178 .PP
179 Licensed under the Apache License 2.0 (the "License"). You may not use
180 this file except in compliance with the License. You can obtain a copy
181 in the file LICENSE in the source distribution or at
182 <https://www.openssl.org/source/license.html>.