BN_BLINDING_NEW(3SSL)

📦
version 4.0.3 · 13 versions
, in ubuntu stonking

✨ BN_BLINDING_NEW ✨

okay bestie so this is a page from the OpenSSL manual, and it's filed under 3SSL which is the section for the library functions, not the commands. it's all about the blinding gang — a whole little friend group of BIGNUM-adjacent functions that keep your modular exponentiation from getting side-channel'd, which is iconic of them fr fr 💅

🌸 NAME 🌸

BN_BLINDING_new, BN_BLINDING_free, BN_BLINDING_update, BN_BLINDING_convert, BN_BLINDING_invert, BN_BLINDING_convert_ex, BN_BLINDING_invert_ex, BN_BLINDING_is_current_thread, BN_BLINDING_set_current_thread, BN_BLINDING_lock, BN_BLINDING_unlock, BN_BLINDING_get_flags, BN_BLINDING_set_flags, BN_BLINDING_create_param — blinding related BIGNUM functions 🦋

✨ SYNOPSIS ✨

bestie, here's the whole cast list in their natural habitat, copy-pasted exactly because we do not mess with signatures:

#include <openssl/bn.h>

BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai,
                             BIGNUM *mod);
void BN_BLINDING_free(BN_BLINDING *b);
int BN_BLINDING_update(BN_BLINDING *b, BN_CTX *ctx);
int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b,
                           BN_CTX *ctx);
int BN_BLINDING_invert_ex(BIGNUM *n, const BIGNUM *r, BN_BLINDING *b,
                          BN_CTX *ctx);
int BN_BLINDING_is_current_thread(BN_BLINDING *b);
void BN_BLINDING_set_current_thread(BN_BLINDING *b);
int BN_BLINDING_lock(BN_BLINDING *b);
int BN_BLINDING_unlock(BN_BLINDING *b);
unsigned long BN_BLINDING_get_flags(const BN_BLINDING *b);
void BN_BLINDING_set_flags(BN_BLINDING *b, unsigned long flags);
BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b,
                                      const BIGNUM *e, BIGNUM *m, BN_CTX *ctx,
                                      int (*bn_mod_exp)(BIGNUM *r,
                                                        const BIGNUM *a,
                                                        const BIGNUM *p,
                                                        const BIGNUM *m,
                                                        BN_CTX *ctx,
                                                        BN_MONT_CTX *m_ctx),
                                      BN_MONT_CTX *m_ctx);

👑 DESCRIPTION 👑

let's go function by function, no skips, no cuts, we're doing the full tour 💖

  • BN_BLINDING_new() — allocates a brand new BN_BLINDING structure and copies the A and Ai values into the freshly created BN_BLINDING object. new object, who dis ✨
  • BN_BLINDING_free() — frees the BN_BLINDING structure. and if b is NULL, literally nothing happens. no drama, no segfault, just vibes 🫶
  • BN_BLINDING_update() — updates the BN_BLINDING parameters by squaring the A and Ai, or — after a specific number of uses and if the necessary parameters are set — by re-creating the blinding parameters. glow-up round two ✨
  • BN_BLINDING_convert_ex() — multiplies n with the blinding factor A. if r is not NULL, a copy of the inverse blinding factor Ai gets returned in r. and bestie, that is super useful when an RSA object is shared across several threads, iykyk 🧵
  • BN_BLINDING_invert_ex() — multiplies n with the inverse blinding factor Ai. if r is not NULL, it'll be used as the inverse blinding.
  • BN_BLINDING_convert() and BN_BLINDING_invert() — these two are wrapper functions for BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex() with r set to NULL. the low-effort besties of the group 💅
  • BN_BLINDING_is_current_thread() — returns whether the BN_BLINDING structure is owned by the current thread. the whole point is to help users provide proper locking if they need it for multi-threaded use. main character checking if it's their turn 🔥
  • BN_BLINDING_set_current_thread() — sets the current thread as the owner of the BN_BLINDING structure. claiming your man, so to speak.
  • BN_BLINDING_lock() — locks the BN_BLINDING structure. 🔒
  • BN_BLINDING_unlock() — unlocks the BN_BLINDING structure. 🔓
  • BN_BLINDING_get_flags() — returns the BN_BLINDING flags. currently there are two supported flags: BN_BLINDING_NO_UPDATE and BN_BLINDING_NO_RECREATE. BN_BLINDING_NO_UPDATE inhibits the automatic update of the BN_BLINDING parameters after each use, and BN_BLINDING_NO_RECREATE inhibits the automatic re-creation of the BN_BLINDING parameters after a fixed number of uses — and that number is currently 32. in newly allocated BN_BLINDING objects, no flags are set. blank slate energy 🌈
  • BN_BLINDING_set_flags() — sets the BN_BLINDING parameters flags.
  • BN_BLINDING_create_param() — creates new BN_BLINDING parameters using the exponent e and the modulus m. bn_mod_exp and m_ctx can be used to pass special functions for exponentiation — normally BN_mod_exp_mont() and BN_MONT_CTX. fancy custom hooks, obsessed 💜

🎀 RETURN VALUES 🎀

okay so here's what every function hands back, and bestie we do not skip a single one:

  • BN_BLINDING_new() — returns the newly allocated BN_BLINDING structure, or NULL in case of an error. 😭
  • BN_BLINDING_update(), BN_BLINDING_convert(), BN_BLINDING_invert(), BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex() — return 1 on success and 0 if an error occurred. classic.
  • BN_BLINDING_is_current_thread() — returns 1 if the current thread owns the BN_BLINDING object, 0 otherwise.
  • BN_BLINDING_set_current_thread() — doesn't return anything. it's giving void, periodt.
  • BN_BLINDING_lock(), BN_BLINDING_unlock() — return 1 if the operation succeeded, or 0 on error.
  • BN_BLINDING_get_flags() — returns the currently set BN_BLINDING flags, which is an unsigned long value.
  • BN_BLINDING_create_param() — returns the newly created BN_BLINDING parameters, or NULL on error.

🦋 HISTORY 🦋

a lil lore drop: BN_BLINDING_thread_id() was first introduced in OpenSSL 1.0.0, and it deprecates BN_BLINDING_set_thread_id() and BN_BLINDING_get_thread_id(). old names, we don't know them anymore 💅

Copyright 2005-2017 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>.

and that's the whole page bestie, slayed ✨ this was version 4.0.3, dated 2026-09-29, and yes that's the BN_BLINDING_NEW page out of 3SSL — go forth and blind responsibly 🫶💖🎀

📦 where this page comes from