1=pod
2
3=head1 NAME
4
5OSSL_SELF_TEST_new,
6OSSL_SELF_TEST_free,
7OSSL_SELF_TEST_onbegin,
8OSSL_SELF_TEST_oncorrupt_byte,
9OSSL_SELF_TEST_onend - functionality to trigger a callback during a self test
10
11=head1 SYNOPSIS
12
13 #include <openssl/self_test.h>
14
15 OSSL_SELF_TEST *OSSL_SELF_TEST_new(OSSL_CALLBACK *cb, void *cbarg);
16 void OSSL_SELF_TEST_free(OSSL_SELF_TEST *st);
17
18 void OSSL_SELF_TEST_onbegin(OSSL_SELF_TEST *st, const char *type,
19                             const char *desc);
20 int OSSL_SELF_TEST_oncorrupt_byte(OSSL_SELF_TEST *st, unsigned char *bytes);
21 void OSSL_SELF_TEST_onend(OSSL_SELF_TEST *st, int ret);
22
23=head1 DESCRIPTION
24
25These methods are intended for use by provider implementers, to display
26diagnostic information during self testing.
27
28OSSL_SELF_TEST_new() allocates an opaque B<OSSL_SELF_TEST> object that has a
29callback and callback argument associated with it.
30
31The callback I<cb> may be triggered multiple times by a self test to indicate
32different phases.
33
34OSSL_SELF_TEST_free() frees the space allocated by OSSL_SELF_TEST_new().
35If the argument is NULL, nothing is done.
36
37OSSL_SELF_TEST_onbegin() may be inserted at the start of a block of self test
38code. It can be used for diagnostic purposes.
39If this method is called the callback I<cb> will receive the following
40L<OSSL_PARAM(3)> object.
41
42=over 4
43
44=item "st-phase" (B<OSSL_PROV_PARAM_SELF_TEST_PHASE>) <UTF8 string>
45
46The value is the string "Start"
47
48=back
49
50OSSL_SELF_TEST_oncorrupt_byte() may be inserted just after the known answer is
51calculated, but before the self test compares the result. The first byte in the
52passed in array of I<bytes> will be corrupted if the callback returns 0,
53otherwise it leaves the array unaltered. It can be used for failure testing.
54The I<type> and I<desc> can be used to identify an individual self test to
55target for failure testing.
56If this method is called the callback I<cb> will receive the following
57L<OSSL_PARAM(3)> object.
58
59=over 4
60
61=item "st-phase" (B<OSSL_PROV_PARAM_SELF_TEST_PHASE>) <UTF8 string>
62
63The value is the string "Corrupt"
64
65=back
66
67OSSL_SELF_TEST_onend() may be inserted at the end of a block of self test code
68just before cleanup to indicate if the test passed or failed. It can be used for
69diagnostic purposes.
70If this method is called the callback I<cb> will receive the following
71L<OSSL_PARAM(3)> object.
72
73=over 4
74
75=item "st-phase" (B<OSSL_PROV_PARAM_SELF_TEST_PHASE>) <UTF8 string>
76
77The value of the string is "Pass" if I<ret> is non zero, otherwise it has the
78value "Fail".
79
80=back
81
82After the callback I<cb> has been called the values that were set by
83OSSL_SELF_TEST_onbegin() for I<type> and I<desc> are set to the value "None".
84
85If OSSL_SELF_TEST_onbegin(), OSSL_SELF_TEST_oncorrupt_byte() or
86OSSL_SELF_TEST_onend() is called the following additional L<OSSL_PARAM(3)> are
87passed to the callback.
88
89=over 4
90
91=item "st-type" (B<OSSL_PROV_PARAM_SELF_TEST_TYPE>) <UTF8 string>
92
93The value is setup by the I<type> passed to OSSL_SELF_TEST_onbegin().
94This allows the callback to identify the type of test being run.
95
96=item "st-desc" (B<OSSL_PROV_PARAM_SELF_TEST_DESC>) <UTF8 string>
97
98The value is setup by the I<type> passed to OSSL_SELF_TEST_onbegin().
99This allows the callback to identify the sub category of the test being run.
100
101=back
102
103=head1 RETURN VALUES
104
105OSSL_SELF_TEST_new() returns the allocated B<OSSL_SELF_TEST> object, or NULL if
106it fails.
107
108OSSL_SELF_TEST_oncorrupt_byte() returns 1 if corruption occurs, otherwise it
109returns 0.
110
111=head1 EXAMPLES
112
113A single self test could be set up in the following way:
114
115    OSSL_SELF_TEST *st = NULL;
116    OSSL_CALLBACK *cb;
117    void *cbarg;
118    int ok = 0;
119    unsigned char out[EVP_MAX_MD_SIZE];
120    unsigned int out_len = 0;
121    EVP_MD_CTX *ctx = EVP_MD_CTX_new();
122    EVP_MD *md = EVP_MD_fetch(libctx, t->algorithm, NULL);
123
124    /*
125     * Retrieve the callback - will be NULL if not set by the application via
126     * OSSL_SELF_TEST_set_callback().
127     */
128    OSSL_SELF_TEST_get_callback(libctx, &cb, &cbarg);
129
130    st = OSSL_SELF_TEST_new(cb, cb_arg);
131
132    /* Trigger the optional callback */
133    OSSL_SELF_TEST_onbegin(st, OSSL_SELF_TEST_TYPE_KAT_DIGEST,
134                           OSSL_SELF_TEST_DESC_MD_SHA2);
135
136    if (!EVP_DigestInit_ex(ctx, md, NULL)
137        || !EVP_DigestUpdate(ctx, pt, pt_len)
138        || !EVP_DigestFinal(ctx, out, &out_len))
139        goto err;
140
141    /* Optional corruption - If the application callback returns 0 */
142    OSSL_SELF_TEST_oncorrupt_byte(st, out);
143
144    if (out_len != t->expected_len
145        || memcmp(out, t->expected, out_len) != 0)
146        goto err;
147    ok = 1;
148  err:
149    OSSL_SELF_TEST_onend(st, ok);
150    EVP_MD_free(md);
151    EVP_MD_CTX_free(ctx);
152
153Multiple self test's can be set up in a similar way by repeating the pattern of
154OSSL_SELF_TEST_onbegin(), OSSL_SELF_TEST_oncorrupt_byte(), OSSL_SELF_TEST_onend()
155for each test.
156
157=head1 SEE ALSO
158
159L<OSSL_SELF_TEST_set_callback(3)>,
160L<openssl-core.h(7)>,
161L<OSSL_PROVIDER-FIPS(7)>
162
163=head1 HISTORY
164
165The functions described here were added in OpenSSL 3.0.
166
167=head1 COPYRIGHT
168
169Copyright 2020-2024 The OpenSSL Project Authors. All Rights Reserved.
170
171Licensed under the Apache License 2.0 (the "License").  You may not use
172this file except in compliance with the License.  You can obtain a copy
173in the file LICENSE in the source distribution or at
174L<https://www.openssl.org/source/license.html>.
175
176=cut
177