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