7 OSSL_SELF_TEST_onbegin,
8 OSSL_SELF_TEST_oncorrupt_byte,
9 OSSL_SELF_TEST_onend - functionality to trigger a callback during a self test
13 #include <openssl/self_test.h>
15 OSSL_SELF_TEST *OSSL_SELF_TEST_new(OSSL_CALLBACK *cb, void *cbarg);
16 void OSSL_SELF_TEST_free(OSSL_SELF_TEST *st);
18 void OSSL_SELF_TEST_onbegin(OSSL_SELF_TEST *st, const char *type,
20 void OSSL_SELF_TEST_oncorrupt_byte(OSSL_SELF_TEST *st, unsigned char *bytes);
21 void OSSL_SELF_TEST_onend(OSSL_SELF_TEST *st, int ret);
25 These methods are intended for use by provider implementors, to display
26 diagnostic information during self testing.
28 OSSL_SELF_TEST_new() allocates an opaque B<OSSL_SELF_TEST> object that has a
29 callback and callback argument associated with it.
31 The callback I<cb> may be triggered multiple times by a self test to indicate
34 OSSL_SELF_TEST_free() frees the space allocated by OSSL_SELF_TEST_new().
36 OSSL_SELF_TEST_onbegin() may be inserted at the start of a block of self test
37 code. It can be used for diagnostic purposes.
38 If this method is called the callback I<cb> will receive the following
43 =item "st-phase" (B<OSSL_PROV_PARAM_SELF_TEST_PHASE>) <UTF8 string>
45 The value is the string "Start"
49 OSSL_SELF_TEST_oncorrupt_byte() may be inserted just after the known answer is
50 calculated, but before the self test compares the result. The first byte in the
51 passed in array of I<bytes> will be corrupted if the callback returns 0,
52 otherwise it leaves the array unaltered. It can be used for failure testing.
53 The I<type> and I<desc> can be used to identify an individual self test to
54 target for failure testing.
55 If this method is called the callback I<cb> will receive the following
60 =item "st-phase" (B<OSSL_PROV_PARAM_SELF_TEST_PHASE>) <UTF8 string>
62 The value is the string "Corrupt"
66 OSSL_SELF_TEST_onend() may be inserted at the end of a block of self test code
67 just before cleanup to indicate if the test passed or failed. It can be used for
69 If this method is called the callback I<cb> will receive the following
74 =item "st-phase" (B<OSSL_PROV_PARAM_SELF_TEST_PHASE>) <UTF8 string>
76 The value of the string is "Pass" if I<ret> is non zero, otherwise it has the
81 After the callback I<cb> has been called the values that were set by
82 OSSL_SELF_TEST_onbegin() for I<type> and I<desc> are set to the value "None".
84 If OSSL_SELF_TEST_onbegin(), OSSL_SELF_TEST_oncorrupt_byte() or
85 OSSL_SELF_TEST_onend() is called the following additional B<OSSL_PARAM> are
86 passed to the callback.
90 =item "st-type" (B<OSSL_PROV_PARAM_SELF_TEST_TYPE>) <UTF8 string>
92 The value is setup by the I<type> passed to OSSL_SELF_TEST_onbegin().
93 This allows the callback to identify the type of test being run.
95 =item "st-desc" (B<OSSL_PROV_PARAM_SELF_TEST_DESC>) <UTF8 string>
97 The value is setup by the I<type> passed to OSSL_SELF_TEST_onbegin().
98 This allows the callback to identify the sub category of the test being run.
104 OSSL_SELF_TEST_new() returns the allocated B<OSSL_SELF_TEST> object, or NULL if
109 A single self test could be set up in the following way:
111 OSSL_SELF_TEST *st = NULL;
115 unsigned char out[EVP_MAX_MD_SIZE];
116 unsigned int out_len = 0;
117 EVP_MD_CTX *ctx = EVP_MD_CTX_new();
118 EVP_MD *md = EVP_MD_fetch(libctx, t->algorithm, NULL);
121 * Retrieve the callback - will be NULL if not set by the application via
122 * OSSL_SELF_TEST_set_callback().
124 OSSL_SELF_TEST_get_callback(libctx, &cb, &cbarg);
126 st = OSSL_SELF_TEST_new(cb, cb_arg);
128 /* Trigger the optional callback */
129 OSSL_SELF_TEST_onbegin(st, OSSL_SELF_TEST_TYPE_KAT_DIGEST,
130 OSSL_SELF_TEST_DESC_MD_SHA2);
132 if (!EVP_DigestInit_ex(ctx, md, NULL)
133 || !EVP_DigestUpdate(ctx, pt, pt_len)
134 || !EVP_DigestFinal(ctx, out, &out_len))
137 /* Optional corruption - If the application callback returns 0 */
138 OSSL_SELF_TEST_oncorrupt_byte(st, out);
140 if (out_len != t->expected_len
141 || memcmp(out, t->expected, out_len) != 0)
145 OSSL_SELF_TEST_onend(st, ok);
147 EVP_MD_CTX_free(ctx);
149 Multiple self test's can be set up in a similar way by repeating the pattern of
150 OSSL_SELF_TEST_onbegin(), OSSL_SELF_TEST_oncorrupt_byte(), OSSL_SELF_TEST_onend()
155 L<OSSL_SELF_TEST_set_callback(3)>,
156 L<openssl-core.h(7)>,
157 L<OSSL_PROVIDER-FIPS(7)>
161 The functions described here were added in OpenSSL 3.0.
165 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
167 Licensed under the Apache License 2.0 (the "License"). You may not use
168 this file except in compliance with the License. You can obtain a copy
169 in the file LICENSE in the source distribution or at
170 L<https://www.openssl.org/source/license.html>.