OSSL_SELF_TEST_oncorrupt_byte(3ossl)

1OSSL_SELF_TEST_NEW(3ossl)           OpenSSL          OSSL_SELF_TEST_NEW(3ossl)
2
3
4

NAME

6       OSSL_SELF_TEST_new, OSSL_SELF_TEST_free, OSSL_SELF_TEST_onbegin,
7       OSSL_SELF_TEST_oncorrupt_byte, OSSL_SELF_TEST_onend - functionality to
8       trigger a callback during a self test
9

SYNOPSIS

11        #include <openssl/self_test.h>
12
13        OSSL_SELF_TEST *OSSL_SELF_TEST_new(OSSL_CALLBACK *cb, void *cbarg);
14        void OSSL_SELF_TEST_free(OSSL_SELF_TEST *st);
15
16        void OSSL_SELF_TEST_onbegin(OSSL_SELF_TEST *st, const char *type,
17                                    const char *desc);
18        int OSSL_SELF_TEST_oncorrupt_byte(OSSL_SELF_TEST *st, unsigned char *bytes);
19        void OSSL_SELF_TEST_onend(OSSL_SELF_TEST *st, int ret);
20

DESCRIPTION

22       These methods are intended for use by provider implementors, to display
23       diagnostic information during self testing.
24
25       OSSL_SELF_TEST_new() allocates an opaque OSSL_SELF_TEST object that has
26       a callback and callback argument associated with it.
27
28       The callback cb may be triggered multiple times by a self test to
29       indicate different phases.
30
31       OSSL_SELF_TEST_free() frees the space allocated by
32       OSSL_SELF_TEST_new().
33
34       OSSL_SELF_TEST_onbegin() may be inserted at the start of a block of
35       self test code. It can be used for diagnostic purposes.  If this method
36       is called the callback cb will receive the following OSSL_PARAM object.
37
38       "st-phase" (OSSL_PROV_PARAM_SELF_TEST_PHASE) <UTF8 string>
39           The value is the string "Start"
40
41       OSSL_SELF_TEST_oncorrupt_byte() may be inserted just after the known
42       answer is calculated, but before the self test compares the result. The
43       first byte in the passed in array of bytes will be corrupted if the
44       callback returns 0, otherwise it leaves the array unaltered. It can be
45       used for failure testing.  The type and desc can be used to identify an
46       individual self test to target for failure testing.  If this method is
47       called the callback cb will receive the following OSSL_PARAM object.
48
49       "st-phase" (OSSL_PROV_PARAM_SELF_TEST_PHASE) <UTF8 string>
50           The value is the string "Corrupt"
51
52       OSSL_SELF_TEST_onend() may be inserted at the end of a block of self
53       test code just before cleanup to indicate if the test passed or failed.
54       It can be used for diagnostic purposes.  If this method is called the
55       callback cb will receive the following OSSL_PARAM object.
56
57       "st-phase" (OSSL_PROV_PARAM_SELF_TEST_PHASE) <UTF8 string>
58           The value of the string is "Pass" if ret is non zero, otherwise it
59           has the value "Fail".
60
61       After the callback cb has been called the values that were set by
62       OSSL_SELF_TEST_onbegin() for type and desc are set to the value "None".
63
64       If OSSL_SELF_TEST_onbegin(), OSSL_SELF_TEST_oncorrupt_byte() or
65       OSSL_SELF_TEST_onend() is called the following additional OSSL_PARAM
66       are passed to the callback.
67
68       "st-type" (OSSL_PROV_PARAM_SELF_TEST_TYPE) <UTF8 string>
69           The value is setup by the type passed to OSSL_SELF_TEST_onbegin().
70           This allows the callback to identify the type of test being run.
71
72       "st-desc" (OSSL_PROV_PARAM_SELF_TEST_DESC) <UTF8 string>
73           The value is setup by the type passed to OSSL_SELF_TEST_onbegin().
74           This allows the callback to identify the sub category of the test
75           being run.
76

RETURN VALUES

78       OSSL_SELF_TEST_new() returns the allocated OSSL_SELF_TEST object, or
79       NULL if it fails.
80
81       OSSL_SELF_TEST_oncorrupt_byte() returns 1 if corruption occurs,
82       otherwise it returns 0.
83

EXAMPLES

85       A single self test could be set up in the following way:
86
87           OSSL_SELF_TEST *st = NULL;
88           OSSL_CALLBACK *cb;
89           void *cbarg;
90           int ok = 0;
91           unsigned char out[EVP_MAX_MD_SIZE];
92           unsigned int out_len = 0;
93           EVP_MD_CTX *ctx = EVP_MD_CTX_new();
94           EVP_MD *md = EVP_MD_fetch(libctx, t->algorithm, NULL);
95
96           /*
97            * Retrieve the callback - will be NULL if not set by the application via
98            * OSSL_SELF_TEST_set_callback().
99            */
100           OSSL_SELF_TEST_get_callback(libctx, &cb, &cbarg);
101
102           st = OSSL_SELF_TEST_new(cb, cb_arg);
103
104           /* Trigger the optional callback */
105           OSSL_SELF_TEST_onbegin(st, OSSL_SELF_TEST_TYPE_KAT_DIGEST,
106                                  OSSL_SELF_TEST_DESC_MD_SHA2);
107
108           if (!EVP_DigestInit_ex(ctx, md, NULL)
109               || !EVP_DigestUpdate(ctx, pt, pt_len)
110               || !EVP_DigestFinal(ctx, out, &out_len))
111               goto err;
112
113           /* Optional corruption - If the application callback returns 0 */
114           OSSL_SELF_TEST_oncorrupt_byte(st, out);
115
116           if (out_len != t->expected_len
117               || memcmp(out, t->expected, out_len) != 0)
118               goto err;
119           ok = 1;
120         err:
121           OSSL_SELF_TEST_onend(st, ok);
122           EVP_MD_free(md);
123           EVP_MD_CTX_free(ctx);
124
125       Multiple self test's can be set up in a similar way by repeating the
126       pattern of OSSL_SELF_TEST_onbegin(), OSSL_SELF_TEST_oncorrupt_byte(),
127       OSSL_SELF_TEST_onend() for each test.
128

HISTORY

134       The functions described here were added in OpenSSL 3.0.
135

COPYRIGHT

137       Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
138
139       Licensed under the Apache License 2.0 (the "License").  You may not use
140       this file except in compliance with the License.  You can obtain a copy
141       in the file LICENSE in the source distribution or at
142       <https://www.openssl.org/source/license.html>.
143
144
145
1463.0.5                             2022-11-01         OSSL_SELF_TEST_NEW(3ossl)