OSSL_SELF_TEST_onbegin(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(3)
37       object.
38
39       "st-phase" (OSSL_PROV_PARAM_SELF_TEST_PHASE) <UTF8 string>
40           The value is the string "Start"
41
42       OSSL_SELF_TEST_oncorrupt_byte() may be inserted just after the known
43       answer is calculated, but before the self test compares the result. The
44       first byte in the passed in array of bytes will be corrupted if the
45       callback returns 0, otherwise it leaves the array unaltered. It can be
46       used for failure testing.  The type and desc can be used to identify an
47       individual self test to target for failure testing.  If this method is
48       called the callback cb will receive the following OSSL_PARAM(3) object.
49
50       "st-phase" (OSSL_PROV_PARAM_SELF_TEST_PHASE) <UTF8 string>
51           The value is the string "Corrupt"
52
53       OSSL_SELF_TEST_onend() may be inserted at the end of a block of self
54       test code just before cleanup to indicate if the test passed or failed.
55       It can be used for diagnostic purposes.  If this method is called the
56       callback cb will receive the following OSSL_PARAM(3) object.
57
58       "st-phase" (OSSL_PROV_PARAM_SELF_TEST_PHASE) <UTF8 string>
59           The value of the string is "Pass" if ret is non zero, otherwise it
60           has the value "Fail".
61
62       After the callback cb has been called the values that were set by
63       OSSL_SELF_TEST_onbegin() for type and desc are set to the value "None".
64
65       If OSSL_SELF_TEST_onbegin(), OSSL_SELF_TEST_oncorrupt_byte() or
66       OSSL_SELF_TEST_onend() is called the following additional OSSL_PARAM(3)
67       are passed to the callback.
68
69       "st-type" (OSSL_PROV_PARAM_SELF_TEST_TYPE) <UTF8 string>
70           The value is setup by the type passed to OSSL_SELF_TEST_onbegin().
71           This allows the callback to identify the type of test being run.
72
73       "st-desc" (OSSL_PROV_PARAM_SELF_TEST_DESC) <UTF8 string>
74           The value is setup by the type passed to OSSL_SELF_TEST_onbegin().
75           This allows the callback to identify the sub category of the test
76           being run.
77

RETURN VALUES

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

EXAMPLES

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

HISTORY

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

COPYRIGHT

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