From 8dfd330bf11b092a51c64a02cb89085c5c6eb8b5 Mon Sep 17 00:00:00 2001 From: Norman Ashley Date: Thu, 28 Sep 2023 09:52:48 -0400 Subject: [PATCH] Document use of callback functions for secret key thread safe protection and storage. --- src/sig_stfl/sig_stfl.h | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/src/sig_stfl/sig_stfl.h b/src/sig_stfl/sig_stfl.h index 5b865b9f4e..a9bffdfdd8 100644 --- a/src/sig_stfl/sig_stfl.h +++ b/src/sig_stfl/sig_stfl.h @@ -16,6 +16,29 @@ #include +/* + * Developer's Notes: + * Stateful signatures are based on one-time use of a secret key. A pool of secret keys are created for this purpose. + * The state of these keys are tracked to ensure that they are used only once to generate a signature. + * + * As such, product specific environments do play a role in ensuring the safety of the keys. + * Secret keys must be store securely. + * The key index/counter must be updated after each signature generation. + * Secret key must be protected in a thread-save manner. + * + * Application therefore are required to provide environment specific callback functions to + * - store private key + * - lock/unlock private key + * + * See below for details + * OQS_SIG_STFL_SECRET_KEY_SET_lock + * OQS_SIG_STFL_SECRET_KEY_SET_unlock + * OQS_SIG_STFL_SECRET_KEY_SET_mutex + * OQS_SIG_STFL_SECRET_KEY_SET_store_cb + * + */ + + #if defined(__cplusplus) extern "C" { #endif @@ -279,7 +302,7 @@ typedef struct OQS_SIG_STFL_SECRET_KEY { * @return OQS_SUCCESS or OQS_ERROR * Idealy written to secure device */ - OQS_STATUS (*secure_store_scrt_key)(/*const*/ uint8_t *sk_buf, size_t buf_len, void *context); + OQS_STATUS (*secure_store_scrt_key)(uint8_t *sk_buf, size_t buf_len, void *context); /** * Secret Key free internal variant specific data