OSSL_SELF_TEST_NEW(3SSL)

📦
version 4.0.3 · 13 versions
, in ubuntu stonking

✨ OSSL_SELF_TEST_new — the whole self-test callback glow-up ✨

okay bestie, this one's from the 3SSL manual, and it's literally the toolkit for making a self test ✨talk✨ to your app while it's running. provider implementer girlies, this one's for you 💅

🌸 NAME 🌸

OSSL_SELF_TEST_new, OSSL_SELF_TEST_free, OSSL_SELF_TEST_onbegin, OSSL_SELF_TEST_oncorrupt_byte, OSSL_SELF_TEST_onend — the whole girl squad of functions that let you trigger a callback during a self test. it's giving "diagnostic commentary, live" 👑

🎀 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);
int OSSL_SELF_TEST_oncorrupt_byte(OSSL_SELF_TEST *st, unsigned char *bytes);
void OSSL_SELF_TEST_onend(OSSL_SELF_TEST *st, int ret);

💖 DESCRIPTION 💖

so these methods are for provider implementers, okay? not random civilians. the whole point is to display diagnostic information while self testing is happening. it's the backstage pass to the self test's whole vibe 🦋

OSSL_SELF_TEST_new() allocates an opaque OSSL_SELF_TEST object, and that object has a callback plus a callback argument associated with it. match made in heaven fr fr 🫶

the callback cb may be triggered multiple times by a self test, to indicate different phases. she's popular. she gets called a lot. 💅

OSSL_SELF_TEST_free() frees the space allocated by OSSL_SELF_TEST_new(). and if the argument is NULL? nothing is done. no notes, she just ignores it, iconic 🎀

🌈 OSSL_SELF_TEST_onbegin()

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 cb will receive the following OSSL_PARAM(3) object 👇

  • "st-phase" (OSSL_PROV_PARAM_SELF_TEST_PHASE) <UTF8 string> — the value is the string "Start"

🌈 OSSL_SELF_TEST_oncorrupt_byte()

OSSL_SELF_TEST_oncorrupt_byte() may be inserted just after the known answer is calculated, but before the self test compares the result. here's the tea: the first byte in the passed in array of bytes will be corrupted if the callback returns 0, otherwise it leaves the array unaltered 😭 (yes, she's supposed to break things — it's for failure testing.)

the type and desc can be used to identify an individual self test to target for failure testing. pinpoint accuracy, queen 🎯

if this method is called, the callback cb will receive the following OSSL_PARAM(3) object👇

  • "st-phase" (OSSL_PROV_PARAM_SELF_TEST_PHASE) <UTF8 string> — the value is the string "Corrupt"

🌈 OSSL_SELF_TEST_onend()

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. can be used for diagnostic purposes. if this method is called, the callback cb will receive the following OSSL_PARAM(3) object 👇

  • "st-phase" (OSSL_PROV_PARAM_SELF_TEST_PHASE) <UTF8 string> — the value of the string is "Pass" if ret is non zero, otherwise it has the value "Fail"

after the callback cb has been called, the values that were set by OSSL_SELF_TEST_onbegin() for type and desc are set to the value "None". she resets. closure, we love to see it 💜

🧚 the extra params when you call onbegin / oncorrupt_byte / onend

if OSSL_SELF_TEST_onbegin(), OSSL_SELF_TEST_oncorrupt_byte() or OSSL_SELF_TEST_onend() is called, the following additional OSSL_PARAM(3) are passed to the callback 👇

  • "st-type" (OSSL_PROV_PARAM_SELF_TEST_TYPE) <UTF8 string> — the value is setup by the type passed to OSSL_SELF_TEST_onbegin(). this allows the callback to identify the type of test being run.
  • "st-desc" (OSSL_PROV_PARAM_SELF_TEST_DESC) <UTF8 string> — the value is setup by the type passed to OSSL_SELF_TEST_onbegin(). this allows the callback to identify the sub category of the test being run.

💀 RETURN VALUES 💀

  • OSSL_SELF_TEST_new() returns the allocated OSSL_SELF_TEST object, or NULL if it fails. (she failed. it happens. 🙈)
  • OSSL_SELF_TEST_oncorrupt_byte() returns 1 if corruption occurs, otherwise it returns 0.

🔥 EXAMPLES 🔥

a single self test could be set up in the following way, bestie:

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 — just repeat the pattern of OSSL_SELF_TEST_onbegin(), OSSL_SELF_TEST_oncorrupt_byte(), OSSL_SELF_TEST_onend() for each test. rinse and repeat, no cap 🌸

🫶 SEE ALSO 🫶

OSSL_SELF_TEST_set_callback(3), openssl-core.h(7), OSSL_PROVIDER-FIPS(7)

👑 HISTORY 👑

the functions described here were added in OpenSSL 3.0.

Copyright 2020-2024 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 <https://www.openssl.org/source/license.html>.

⚠️ real talk bestie: that license line is not a vibe, it's a rule. use her correctly or don't use her at all 💅

and that's the whole page!! mwah 💋 this was version 4.0.3, dated 2026-09-29, straight outta the OSSL_SELF_TEST_NEW(3SSL) manual. go forth and self test, icon 🦋✨

📦 where this page comes from