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