Debian Codegraph @

upstream/debian-unstable/man3/OSSL_SELF_TEST_new.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_SELF_TEST_NEW 3SSL"
58 .TH OSSL_SELF_TEST_NEW 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_SELF_TEST_new,
65 OSSL_SELF_TEST_free,
66 OSSL_SELF_TEST_onbegin,
67 OSSL_SELF_TEST_oncorrupt_byte,
68 OSSL_SELF_TEST_onend \- functionality to trigger a callback during a self test
69 .SH SYNOPSIS
70 .IX Header "SYNOPSIS"
71 .Vb 1
72 \& #include <openssl/self_test.h>
73 \&
74 \& OSSL_SELF_TEST *OSSL_SELF_TEST_new(OSSL_CALLBACK *cb, void *cbarg);
75 \& void OSSL_SELF_TEST_free(OSSL_SELF_TEST *st);
76 \&
77 \& void OSSL_SELF_TEST_onbegin(OSSL_SELF_TEST *st, const char *type,
78 \& const char *desc);
79 \& int OSSL_SELF_TEST_oncorrupt_byte(OSSL_SELF_TEST *st, unsigned char *bytes);
80 \& void OSSL_SELF_TEST_onend(OSSL_SELF_TEST *st, int ret);
81 .Ve
82 .SH DESCRIPTION
83 .IX Header "DESCRIPTION"
84 These methods are intended for use by provider implementers, to display
85 diagnostic information during self testing.
86 .PP
87 \&\fBOSSL_SELF_TEST_new()\fR allocates an opaque \fBOSSL_SELF_TEST\fR object that has a
88 callback and callback argument associated with it.
89 .PP
90 The callback \fIcb\fR may be triggered multiple times by a self test to indicate
91 different phases.
92 .PP
93 \&\fBOSSL_SELF_TEST_free()\fR frees the space allocated by \fBOSSL_SELF_TEST_new()\fR.
94 If the argument is NULL, nothing is done.
95 .PP
96 \&\fBOSSL_SELF_TEST_onbegin()\fR may be inserted at the start of a block of self test
97 code. It can be used for diagnostic purposes.
98 If this method is called the callback \fIcb\fR will receive the following
99 \&\fBOSSL_PARAM\fR\|(3) object.
100 .IP """st-phase"" (\fBOSSL_PROV_PARAM_SELF_TEST_PHASE\fR) <UTF8 string>" 4
101 .IX Item """st-phase"" (OSSL_PROV_PARAM_SELF_TEST_PHASE) <UTF8 string>"
102 The value is the string "Start"
103 .PP
104 \&\fBOSSL_SELF_TEST_oncorrupt_byte()\fR may be inserted just after the known answer is
105 calculated, but before the self test compares the result. The first byte in the
106 passed in array of \fIbytes\fR will be corrupted if the callback returns 0,
107 otherwise it leaves the array unaltered. It can be used for failure testing.
108 The \fItype\fR and \fIdesc\fR can be used to identify an individual self test to
109 target for failure testing.
110 If this method is called the callback \fIcb\fR will receive the following
111 \&\fBOSSL_PARAM\fR\|(3) object.
112 .IP """st-phase"" (\fBOSSL_PROV_PARAM_SELF_TEST_PHASE\fR) <UTF8 string>" 4
113 .IX Item """st-phase"" (OSSL_PROV_PARAM_SELF_TEST_PHASE) <UTF8 string>"
114 The value is the string "Corrupt"
115 .PP
116 \&\fBOSSL_SELF_TEST_onend()\fR may be inserted at the end of a block of self test code
117 just before cleanup to indicate if the test passed or failed. It can be used for
118 diagnostic purposes.
119 If this method is called the callback \fIcb\fR will receive the following
120 \&\fBOSSL_PARAM\fR\|(3) object.
121 .IP """st-phase"" (\fBOSSL_PROV_PARAM_SELF_TEST_PHASE\fR) <UTF8 string>" 4
122 .IX Item """st-phase"" (OSSL_PROV_PARAM_SELF_TEST_PHASE) <UTF8 string>"
123 The value of the string is "Pass" if \fIret\fR is non zero, otherwise it has the
124 value "Fail".
125 .PP
126 After the callback \fIcb\fR has been called the values that were set by
127 \&\fBOSSL_SELF_TEST_onbegin()\fR for \fItype\fR and \fIdesc\fR are set to the value "None".
128 .PP
129 If \fBOSSL_SELF_TEST_onbegin()\fR, \fBOSSL_SELF_TEST_oncorrupt_byte()\fR or
130 \&\fBOSSL_SELF_TEST_onend()\fR is called the following additional \fBOSSL_PARAM\fR\|(3) are
131 passed to the callback.
132 .IP """st-type"" (\fBOSSL_PROV_PARAM_SELF_TEST_TYPE\fR) <UTF8 string>" 4
133 .IX Item """st-type"" (OSSL_PROV_PARAM_SELF_TEST_TYPE) <UTF8 string>"
134 The value is setup by the \fItype\fR passed to \fBOSSL_SELF_TEST_onbegin()\fR.
135 This allows the callback to identify the type of test being run.
136 .IP """st-desc"" (\fBOSSL_PROV_PARAM_SELF_TEST_DESC\fR) <UTF8 string>" 4
137 .IX Item """st-desc"" (OSSL_PROV_PARAM_SELF_TEST_DESC) <UTF8 string>"
138 The value is setup by the \fItype\fR passed to \fBOSSL_SELF_TEST_onbegin()\fR.
139 This allows the callback to identify the sub category of the test being run.
140 .SH "RETURN VALUES"
141 .IX Header "RETURN VALUES"
142 \&\fBOSSL_SELF_TEST_new()\fR returns the allocated \fBOSSL_SELF_TEST\fR object, or NULL if
143 it fails.
144 .PP
145 \&\fBOSSL_SELF_TEST_oncorrupt_byte()\fR returns 1 if corruption occurs, otherwise it
146 returns 0.
147 .SH EXAMPLES
148 .IX Header "EXAMPLES"
149 A single self test could be set up in the following way:
150 .PP
151 .Vb 8
152 \& OSSL_SELF_TEST *st = NULL;
153 \& OSSL_CALLBACK *cb;
154 \& void *cbarg;
155 \& int ok = 0;
156 \& unsigned char out[EVP_MAX_MD_SIZE];
157 \& unsigned int out_len = 0;
158 \& EVP_MD_CTX *ctx = EVP_MD_CTX_new();
159 \& EVP_MD *md = EVP_MD_fetch(libctx, t\->algorithm, NULL);
160 \&
161 \& /*
162 \& * Retrieve the callback \- will be NULL if not set by the application via
163 \& * OSSL_SELF_TEST_set_callback().
164 \& */
165 \& OSSL_SELF_TEST_get_callback(libctx, &cb, &cbarg);
166 \&
167 \& st = OSSL_SELF_TEST_new(cb, cb_arg);
168 \&
169 \& /* Trigger the optional callback */
170 \& OSSL_SELF_TEST_onbegin(st, OSSL_SELF_TEST_TYPE_KAT_DIGEST,
171 \& OSSL_SELF_TEST_DESC_MD_SHA2);
172 \&
173 \& if (!EVP_DigestInit_ex(ctx, md, NULL)
174 \& || !EVP_DigestUpdate(ctx, pt, pt_len)
175 \& || !EVP_DigestFinal(ctx, out, &out_len))
176 \& goto err;
177 \&
178 \& /* Optional corruption \- If the application callback returns 0 */
179 \& OSSL_SELF_TEST_oncorrupt_byte(st, out);
180 \&
181 \& if (out_len != t\->expected_len
182 \& || memcmp(out, t\->expected, out_len) != 0)
183 \& goto err;
184 \& ok = 1;
185 \& err:
186 \& OSSL_SELF_TEST_onend(st, ok);
187 \& EVP_MD_free(md);
188 \& EVP_MD_CTX_free(ctx);
189 .Ve
190 .PP
191 Multiple self test's can be set up in a similar way by repeating the pattern of
192 \&\fBOSSL_SELF_TEST_onbegin()\fR, \fBOSSL_SELF_TEST_oncorrupt_byte()\fR, \fBOSSL_SELF_TEST_onend()\fR
193 for each test.
194 .SH "SEE ALSO"
195 .IX Header "SEE ALSO"
196 \&\fBOSSL_SELF_TEST_set_callback\fR\|(3),
197 \&\fBopenssl\-core.h\fR\|(7),
198 \&\fBOSSL_PROVIDER\-FIPS\fR\|(7)
199 .SH HISTORY
200 .IX Header "HISTORY"
201 The functions described here were added in OpenSSL 3.0.
202 .SH COPYRIGHT
203 .IX Header "COPYRIGHT"
204 Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved.
205 .PP
206 Licensed under the Apache License 2.0 (the "License"). You may not use
207 this file except in compliance with the License. You can obtain a copy
208 in the file LICENSE in the source distribution or at
209 <https://www.openssl.org/source/license.html>.