doc/man3/OSSL_SELF_TEST_new.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 OSSL_SELF_TEST_new,
   6 OSSL_SELF_TEST_free,
   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
  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  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);
  22
  23 =head1 DESCRIPTION
  24
  25 These methods are intended for use by provider implementors, to display
  26 diagnostic information during self testing.
  27
  28 OSSL_SELF_TEST_new() allocates an opaque B<OSSL_SELF_TEST> object that has a
  29 callback and callback argument associated with it.
  30
  31 The callback I<cb> may be triggered multiple times by a self test to indicate
  32 different phases.
  33
  34 OSSL_SELF_TEST_free() frees the space allocated by OSSL_SELF_TEST_new().
  35
  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
  39 B<OSSL_PARAM> object.
  40
  41 =over 4
  42
  43 =item "st-phase" (B<OSSL_PROV_PARAM_SELF_TEST_PHASE>) <UTF8 string>
  44
  45 The value is the string "Start"
  46
  47 =back
  48
  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
  56 B<OSSL_PARAM> object.
  57
  58 =over 4
  59
  60 =item "st-phase" (B<OSSL_PROV_PARAM_SELF_TEST_PHASE>) <UTF8 string>
  61
  62 The value is the string "Corrupt"
  63
  64 =back
  65
  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
  68 diagnostic purposes.
  69 If this method is called the callback I<cb> will receive the following
  70 B<OSSL_PARAM> object.
  71
  72 =over 4
  73
  74 =item "st-phase" (B<OSSL_PROV_PARAM_SELF_TEST_PHASE>) <UTF8 string>
  75
  76 The value of the string is "Pass" if I<ret> is non zero, otherwise it has the
  77 value "Fail".
  78
  79 =back
  80
  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".
  83
  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.
  87
  88 =over 4
  89
  90 =item "st-type" (B<OSSL_PROV_PARAM_SELF_TEST_TYPE>) <UTF8 string>
  91
  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.
  94
  95 =item "st-desc" (B<OSSL_PROV_PARAM_SELF_TEST_DESC>) <UTF8 string>
  96
  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.
  99
 100 =back
 101
 102 =head1 RETURN VALUES
 103
 104 OSSL_SELF_TEST_new() returns the allocated B<OSSL_SELF_TEST> object, or NULL if
 105 it fails.
 106
 107 =head1 EXAMPLES
 108
 109 A single self test could be set up in the following way:
 110
 111     OSSL_SELF_TEST *st = NULL;
 112     OSSL_CALLBACK *cb;
 113     void *cbarg;
 114     int ok = 0;
 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);
 119
 120     /*
 121      * Retrieve the callback - will be NULL if not set by the application via
 122      * OSSL_SELF_TEST_set_callback().
 123      */
 124     OSSL_SELF_TEST_get_callback(libctx, &cb, &cbarg);
 125
 126     st = OSSL_SELF_TEST_new(cb, cb_arg);
 127
 128     /* Trigger the optional callback */
 129     OSSL_SELF_TEST_onbegin(st, OSSL_SELF_TEST_TYPE_KAT_DIGEST,
 130                            OSSL_SELF_TEST_DESC_MD_SHA2);
 131
 132     if (!EVP_DigestInit_ex(ctx, md, NULL)
 133         || !EVP_DigestUpdate(ctx, pt, pt_len)
 134         || !EVP_DigestFinal(ctx, out, &out_len))
 135         goto err;
 136
 137     /* Optional corruption - If the application callback returns 0 */
 138     OSSL_SELF_TEST_oncorrupt_byte(st, out);
 139
 140     if (out_len != t->expected_len
 141         || memcmp(out, t->expected, out_len) != 0)
 142         goto err;
 143     ok = 1;
 144   err:
 145     OSSL_SELF_TEST_onend(st, ok);
 146     EVP_MD_free(md);
 147     EVP_MD_CTX_free(ctx);
 148
 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()
 151 for each test.
 152
 153 =head1 SEE ALSO
 154
 155 L<OSSL_SELF_TEST_set_callback(3)>,
 156 L<openssl-core.h(7)>,
 157 L<OSSL_PROVIDER-FIPS(7)>
 158
 159 =head1 HISTORY
 160
 161 The functions described here were added in OpenSSL 3.0.
 162
 163 =head1 COPYRIGHT
 164
 165 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
 166
 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>.
 171
 172 =cut