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  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
  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 OSSL_SELF_TEST_oncorrupt_byte() returns 1 if corruption occurs, otherwise it
 108 returns 0.
 109
 110 =head1 EXAMPLES
 111
 112 A 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
 152 Multiple self test's can be set up in a similar way by repeating the pattern of
 153 OSSL_SELF_TEST_onbegin(), OSSL_SELF_TEST_oncorrupt_byte(), OSSL_SELF_TEST_onend()
 154 for each test.
 155
 156 =head1 SEE ALSO
 157
 158 L<OSSL_SELF_TEST_set_callback(3)>,
 159 L<openssl-core.h(7)>,
 160 L<OSSL_PROVIDER-FIPS(7)>
 161
 162 =head1 HISTORY
 163
 164 The functions described here were added in OpenSSL 3.0.
 165
 166 =head1 COPYRIGHT
 167
 168 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
 169
 170 Licensed under the Apache License 2.0 (the "License").  You may not use
 171 this file except in compliance with the License.  You can obtain a copy
 172 in the file LICENSE in the source distribution or at
 173 L<https://www.openssl.org/source/license.html>.
 174
 175 =cut