Latest update.

doc/man3/OSSL_SELF_TEST_new.pod

@@ -0,0 +1,172 @@
+=pod
+
+=head1 NAME
+
+OSSL_SELF_TEST_new,
+OSSL_SELF_TEST_free,
+OSSL_SELF_TEST_onbegin,
+OSSL_SELF_TEST_oncorrupt_byte,
+OSSL_SELF_TEST_onend - functionality to trigger a callback during a self test
+
+=head1 SYNOPSIS
+
+ #include <openssl/self_test.h>
+
+ OSSL_SELF_TEST *OSSL_SELF_TEST_new(OSSL_CALLBACK *cb, void *cbarg);
+ void OSSL_SELF_TEST_free(OSSL_SELF_TEST *st);
+
+ void OSSL_SELF_TEST_onbegin(OSSL_SELF_TEST *st, const char *type,
+                             const char *desc);
+ void OSSL_SELF_TEST_oncorrupt_byte(OSSL_SELF_TEST *st, unsigned char *bytes);
+ void OSSL_SELF_TEST_onend(OSSL_SELF_TEST *st, int ret);
+
+=head1 DESCRIPTION
+
+These methods are intended for use by provider implementors, to display
+diagnostic information during self testing.
+
+OSSL_SELF_TEST_new() allocates an opaque B<OSSL_SELF_TEST> object that has a
+callback and callback argument associated with it.
+
+The callback I<cb> may be triggered multiple times by a self test to indicate
+different phases.
+
+OSSL_SELF_TEST_free() frees the space allocated by OSSL_SELF_TEST_new().
+
+OSSL_SELF_TEST_onbegin() may be inserted at the start of a block of self test
+code. It can be used for diagnostic purposes.
+If this method is called the callback I<cb> will receive the following
+B<OSSL_PARAM> object.
+
+=over 4
+
+=item "st-phase" (B<OSSL_PROV_PARAM_SELF_TEST_PHASE>) <UTF8 string>
+
+The value is the string "Start"
+
+=back
+
+OSSL_SELF_TEST_oncorrupt_byte() may be inserted just after the known answer is
+calculated, but before the self test compares the result. The first byte in the
+passed in array of I<bytes> will be corrupted if the callback returns 0,
+otherwise it leaves the array unaltered. It can be used for failure testing.
+The I<type> and I<desc> can be used to identify an individual self test to
+target for failure testing.
+If this method is called the callback I<cb> will receive the following
+B<OSSL_PARAM> object.
+
+=over 4
+
+=item "st-phase" (B<OSSL_PROV_PARAM_SELF_TEST_PHASE>) <UTF8 string>
+
+The value is the string "Corrupt"
+
+=back
+
+OSSL_SELF_TEST_onend() may be inserted at the end of a block of self test code
+just before cleanup to indicate if the test passed or failed. It can be used for
+diagnostic purposes.
+If this method is called the callback I<cb> will receive the following
+B<OSSL_PARAM> object.
+
+=over 4
+
+=item "st-phase" (B<OSSL_PROV_PARAM_SELF_TEST_PHASE>) <UTF8 string>
+
+The value of the string is "Pass" if I<ret> is non zero, otherwise it has the
+value "Fail".
+
+=back
+
+After the callback I<cb> has been called the values that were set by
+OSSL_SELF_TEST_onbegin() for I<type> and I<desc> are set to the value "None".
+
+If OSSL_SELF_TEST_onbegin(), OSSL_SELF_TEST_oncorrupt_byte() or
+OSSL_SELF_TEST_onend() is called the following additional B<OSSL_PARAM> are
+passed to the callback.
+
+=over 4
+
+=item "st-type" (B<OSSL_PROV_PARAM_SELF_TEST_TYPE>) <UTF8 string>
+
+The value is setup by the I<type> passed to OSSL_SELF_TEST_onbegin().
+This allows the callback to identify the type of test being run.
+
+=item "st-desc" (B<OSSL_PROV_PARAM_SELF_TEST_DESC>) <UTF8 string>
+
+The value is setup by the I<type> passed to OSSL_SELF_TEST_onbegin().
+This allows the callback to identify the sub category of the test being run.
+
+=back
+
+=head1 RETURN VALUES
+
+OSSL_SELF_TEST_new() returns the allocated B<OSSL_SELF_TEST> object, or NULL if
+it fails.
+
+=head1 EXAMPLES
+
+A single self test could be set up in the following way:
+
+    OSSL_SELF_TEST *st = NULL;
+    OSSL_CALLBACK *cb;
+    void *cbarg;
+    int ok = 0;
+    unsigned char out[EVP_MAX_MD_SIZE];
+    unsigned int out_len = 0;
+    EVP_MD_CTX *ctx = EVP_MD_CTX_new();
+    EVP_MD *md = EVP_MD_fetch(libctx, t->algorithm, NULL);
+
+    /*
+     * Retrieve the callback - will be NULL if not set by the application via
+     * OSSL_SELF_TEST_set_callback().
+     */
+    OSSL_SELF_TEST_get_callback(libctx, &cb, &cbarg);
+
+    st = OSSL_SELF_TEST_new(cb, cb_arg);
+
+    /* Trigger the optional callback */
+    OSSL_SELF_TEST_onbegin(st, OSSL_SELF_TEST_TYPE_KAT_DIGEST,
+                           OSSL_SELF_TEST_DESC_MD_SHA2);
+
+    if (!EVP_DigestInit_ex(ctx, md, NULL)
+        || !EVP_DigestUpdate(ctx, pt, pt_len)
+        || !EVP_DigestFinal(ctx, out, &out_len))
+        goto err;
+    
+    /* Optional corruption - If the application callback returns 0 */
+    OSSL_SELF_TEST_oncorrupt_byte(st, out);
+
+    if (out_len != t->expected_len
+        || memcmp(out, t->expected, out_len) != 0)
+        goto err;
+    ok = 1;
+  err:
+    OSSL_SELF_TEST_onend(st, ok);
+    EVP_MD_free(md);
+    EVP_MD_CTX_free(ctx);
+
+Multiple self test's can be set up in a similar way by repeating the pattern of
+OSSL_SELF_TEST_onbegin(), OSSL_SELF_TEST_oncorrupt_byte(), OSSL_SELF_TEST_onend()
+for each test.
+
+=head1 SEE ALSO
+
+L<OSSL_SELF_TEST_set_callback(3)>,
+L<openssl-core.h(7)>,
+L<OSSL_PROVIDER-FIPS(7)>
+
+=head1 HISTORY
+
+The functions described here were added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut