RAND_DRBG: add a callback data for entropy and nonce callbacks
authorDr. Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
Sun, 26 Jan 2020 21:18:23 +0000 (22:18 +0100)
committerDr. Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
Fri, 7 Feb 2020 10:38:02 +0000 (11:38 +0100)
The callback data allows passing context specific data from the
application of the DRBG to to the entropy callbacks.
This a rather specialized feature which is useful for implementing
known answer tests (KATs) or deterministic signatures (RFC6979),
which require passing a specified entropy and nonce for instantiating
the DRBG.

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/10950)

crypto/rand/drbg_lib.c
crypto/rand/rand_local.h
doc/man3/RAND_DRBG_set_callbacks.pod
doc/man3/SSL_CTX_set_ct_validation_callback.pod
include/openssl/rand_drbg.h
util/libcrypto.num

index a695a5f..029cc6e 100644 (file)
@@ -304,6 +304,34 @@ void rand_drbg_cleanup_nonce(RAND_DRBG *drbg,
     OPENSSL_clear_free(out, outlen);
 }
 
+/*
+ * Set the |drbg|'s callback data pointer for the entropy and nonce callbacks
+ *
+ * The ownership of the context data remains with the caller,
+ * i.e., it is the caller's responsibility to keep it available as long
+ * as it is need by the callbacks and free it after use.
+ *
+ * Setting the callback data is allowed only if the drbg has not been
+ * initialized yet. Otherwise, the operation will fail.
+ *
+ * Returns 1 on success, 0 on failure.
+ */
+int RAND_DRBG_set_callback_data(RAND_DRBG *drbg, void *data)
+{
+    if (drbg->state != DRBG_UNINITIALISED
+        || drbg->parent != NULL)
+        return 0;
+
+    drbg->callback_data = data;
+    return 1;
+}
+
+/* Retrieve the callback data pointer */
+void *RAND_DRBG_get_callback_data(RAND_DRBG *drbg)
+{
+    return drbg->callback_data;
+}
+
 /*
  * Set/initialize |drbg| to be of type |type|, with optional |flags|.
  *
index c0ba3ba..ce16892 100644 (file)
@@ -328,6 +328,8 @@ struct rand_drbg_st {
     RAND_DRBG_cleanup_entropy_fn cleanup_entropy;
     RAND_DRBG_get_nonce_fn get_nonce;
     RAND_DRBG_cleanup_nonce_fn cleanup_nonce;
+
+    void *callback_data;
 };
 
 /* The global RAND method, and the global buffer and DRBG instance. */
index 695c190..c899a1a 100644 (file)
@@ -3,6 +3,8 @@
 =head1 NAME
 
 RAND_DRBG_set_callbacks,
+RAND_DRBG_set_callback_data,
+RAND_DRBG_get_callback_data,
 RAND_DRBG_get_entropy_fn,
 RAND_DRBG_cleanup_entropy_fn,
 RAND_DRBG_get_nonce_fn,
@@ -20,6 +22,9 @@ RAND_DRBG_cleanup_nonce_fn
                              RAND_DRBG_get_nonce_fn get_nonce,
                              RAND_DRBG_cleanup_nonce_fn cleanup_nonce);
 
+ int RAND_DRBG_set_callback_data(RAND_DRBG *drbg, void *ctx);
+
+ void *RAND_DRBG_get_callback_data(RAND_DRBG *drbg);
 
 =head2 Callback Functions
 
@@ -53,7 +58,16 @@ the nonce when reseeding the given B<drbg>.
 The callback functions are implemented and provided by the caller.
 Their parameter lists need to match the function prototypes above.
 
-Setting the callbacks is allowed only if the DRBG has not been initialized yet.
+RAND_DRBG_set_callback_data() can be used to store a pointer to some context
+specific data, which can subsequently be retrieved by the entropy and nonce
+callbacks using RAND_DRBG_get_callback_data().
+The ownership of the context data remains with the caller, i.e., it is the
+caller's responsibility to keep it available as long as it is need by the
+callbacks and free it after use.
+For more information about the the callback data see the NOTES section.
+
+Setting the callbacks or the callback data is allowed only if the DRBG has
+not been initialized yet.
 Otherwise, the operation will fail.
 To change the settings for one of the three shared DRBGs it is necessary to call
 RAND_DRBG_uninstantiate() first.
@@ -95,7 +109,12 @@ setting them to NULL.
 
 =head1 RETURN VALUES
 
-RAND_DRBG_set_callbacks() return 1 on success, and 0 on failure
+RAND_DRBG_set_callbacks() returns 1 on success, and 0 on failure.
+
+RAND_DRBG_set_callback_data() returns 1 on success, and 0 on failure.
+
+RAND_DRBG_get_callback_data() returns the pointer to the callback data,
+which is NULL if none has been set previously.
 
 =head1 NOTES
 
@@ -121,6 +140,14 @@ In this case the DRBG will automatically request an extra amount of entropy
 utilize for the nonce, following the recommendations of [NIST SP 800-90A Rev. 1],
 section 8.6.7.
 
+The callback data a rather specialized feature, because in general the
+random sources don't (and in fact, they must not) depend on any state provided
+by the DRBG.
+There are however exceptional cases where this feature is useful, most notably
+for implementing known answer tests (KATs) or deterministic signatures like
+those specified in RFC6979, which require passing a specified entropy and nonce
+for instantiating the DRBG.
+
 =head1 SEE ALSO
 
 L<RAND_DRBG_new(3)>,
index c0a635b..6732ee1 100644 (file)
@@ -69,7 +69,7 @@ sufficient to allow the connection to continue.
 The TLS handshake is aborted if the verification mode is not B<SSL_VERIFY_NONE>
 and the callback returns a non-positive result.
 
-An arbitrary callback context argument, B<arg>, can be passed in when setting
+An arbitrary callback data argument, B<arg>, can be passed in when setting
 the callback.
 This will be passed to the callback whenever it is invoked.
 Ownership of this context remains with the caller.
index e9857ec..6d8368d 100644 (file)
@@ -150,6 +150,10 @@ int RAND_DRBG_set_callbacks(RAND_DRBG *drbg,
                             RAND_DRBG_cleanup_nonce_fn cleanup_nonce);
 
 
+int RAND_DRBG_set_callback_data(RAND_DRBG *drbg, void *data);
+
+void *RAND_DRBG_get_callback_data(RAND_DRBG *drbg);
+
 # ifdef  __cplusplus
 }
 # endif
index dc6515c..777db89 100644 (file)
@@ -4918,3 +4918,5 @@ PKCS8_pkey_add1_attr_by_OBJ             ? 3_0_0   EXIST::FUNCTION:
 EVP_PKEY_private_check                  ?      3_0_0   EXIST::FUNCTION:
 EVP_PKEY_pairwise_check                 ?      3_0_0   EXIST::FUNCTION:
 ASN1_item_verify_ctx                    ?      3_0_0   EXIST::FUNCTION:
+RAND_DRBG_set_callback_data             ?      3_0_0   EXIST::FUNCTION:
+RAND_DRBG_get_callback_data             ?      3_0_0   EXIST::FUNCTION: