Skip to content

Commit 70ff29b

Browse files
committed
secp256k1_context_randomize: document.
I think I summarized it correctly after IRC discussion with gmaxwell and andytoshi; I didn't know it existed :( It's regrettable to expose this level of detail, but users need to know this to make a decision about how to use it. Signed-off-by: Rusty Russell <[email protected]>
1 parent 9d560f9 commit 70ff29b

File tree

1 file changed

+16
-1
lines changed

1 file changed

+16
-1
lines changed

include/secp256k1.h

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -163,6 +163,8 @@ typedef int (*secp256k1_nonce_function)(
163163
*
164164
* Returns: a newly created context object.
165165
* In: flags: which parts of the context to initialize.
166+
*
167+
* See also secp256k1_context_randomize.
166168
*/
167169
SECP256K1_API secp256k1_context* secp256k1_context_create(
168170
unsigned int flags
@@ -543,11 +545,24 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_tweak_mul(
543545
const unsigned char *tweak
544546
) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
545547

546-
/** Updates the context randomization.
548+
/** Updates the context randomization to protect against side-channel leakage.
547549
* Returns: 1: randomization successfully updated
548550
* 0: error
549551
* Args: ctx: pointer to a context object (cannot be NULL)
550552
* In: seed32: pointer to a 32-byte random seed (NULL resets to initial state)
553+
*
554+
* While secp256k1 code is written to be constant-time no matter what secret
555+
* values are, it's possible that a future compiler may output code which isn't,
556+
* and also that the CPU may not emit the same radio frequencies or draw the same
557+
* amount power for all values.
558+
*
559+
* This function provides a seed which is combined into the blinding value: that
560+
* blinding value added before each multiplication (and removed afterwards) so
561+
* that it does not affect function results, but shields against attacks which
562+
* rely on any input-dependent behaviour.
563+
*
564+
* You should call this after secp256k1_context_create or
565+
* secp256k1_context_clone, and may call this repeatedly afterwards.
551566
*/
552567
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_context_randomize(
553568
secp256k1_context* ctx,

0 commit comments

Comments
 (0)