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