diff options
author | Dr. Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> | 2020-01-26 22:18:23 +0100 |
---|---|---|
committer | Dr. Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> | 2020-02-07 11:38:02 +0100 |
commit | 30a9d5d1a72149c4eb2b8e5aa83f509344c80232 (patch) | |
tree | c8ae072771a45fa23ad49b0cc0a3ffe740623392 /doc | |
parent | b03de7a9207645c72e22627b10709f15eed211bf (diff) |
RAND_DRBG: add a callback data for entropy and nonce callbacks
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)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/RAND_DRBG_set_callbacks.pod | 31 | ||||
-rw-r--r-- | doc/man3/SSL_CTX_set_ct_validation_callback.pod | 2 |
2 files changed, 30 insertions, 3 deletions
diff --git a/doc/man3/RAND_DRBG_set_callbacks.pod b/doc/man3/RAND_DRBG_set_callbacks.pod index 695c1903e9..c899a1adcb 100644 --- a/doc/man3/RAND_DRBG_set_callbacks.pod +++ b/doc/man3/RAND_DRBG_set_callbacks.pod @@ -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)>, diff --git a/doc/man3/SSL_CTX_set_ct_validation_callback.pod b/doc/man3/SSL_CTX_set_ct_validation_callback.pod index c0a635b9aa..6732ee1135 100644 --- a/doc/man3/SSL_CTX_set_ct_validation_callback.pod +++ b/doc/man3/SSL_CTX_set_ct_validation_callback.pod @@ -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. |