diff options
Diffstat (limited to 'linux-x86/include/openssl/bn.h')
-rw-r--r-- | linux-x86/include/openssl/bn.h | 45 |
1 files changed, 31 insertions, 14 deletions
diff --git a/linux-x86/include/openssl/bn.h b/linux-x86/include/openssl/bn.h index d9491a9..0361645 100644 --- a/linux-x86/include/openssl/bn.h +++ b/linux-x86/include/openssl/bn.h @@ -136,7 +136,16 @@ extern "C" { // BN provides support for working with arbitrary sized integers. For example, // although the largest integer supported by the compiler might be 64 bits, BN -// will allow you to work with numbers until you run out of memory. +// will allow you to work with much larger numbers. +// +// This library is developed for use inside BoringSSL, and uses implementation +// strategies that may not be ideal for other applications. Non-cryptographic +// uses should use a more general-purpose integer library, especially if +// performance-sensitive. +// +// Many functions in BN scale quadratically or higher in the bit length of their +// input. Callers at this layer are assumed to have capped input sizes within +// their performance tolerances. // BN_ULONG is the native word size when working with big integers. @@ -151,14 +160,12 @@ extern "C" { typedef uint64_t BN_ULONG; #define BN_BITS2 64 #define BN_DEC_FMT1 "%" PRIu64 -#define BN_DEC_FMT2 "%019" PRIu64 #define BN_HEX_FMT1 "%" PRIx64 #define BN_HEX_FMT2 "%016" PRIx64 #elif defined(OPENSSL_32_BIT) typedef uint32_t BN_ULONG; #define BN_BITS2 32 #define BN_DEC_FMT1 "%" PRIu32 -#define BN_DEC_FMT2 "%09" PRIu32 #define BN_HEX_FMT1 "%" PRIx32 #define BN_HEX_FMT2 "%08" PRIx32 #else @@ -205,6 +212,10 @@ OPENSSL_EXPORT unsigned BN_num_bits(const BIGNUM *bn); // BN_num_bytes returns the minimum number of bytes needed to represent the // absolute value of |bn|. +// +// While |size_t| is the preferred type for byte counts, callers can assume that +// |BIGNUM|s are bounded such that this value, and its corresponding bit count, +// will always fit in |int|. OPENSSL_EXPORT unsigned BN_num_bytes(const BIGNUM *bn); // BN_zero sets |bn| to zero. @@ -280,6 +291,10 @@ OPENSSL_EXPORT int BN_hex2bn(BIGNUM **outp, const char *in); // BN_bn2dec returns an allocated string that contains a NUL-terminated, // decimal representation of |bn|. If |bn| is negative, the first char in the // resulting string will be '-'. Returns NULL on allocation failure. +// +// Converting an arbitrarily large integer to decimal is quadratic in the bit +// length of |a|. This function assumes the caller has capped the input within +// performance tolerances. OPENSSL_EXPORT char *BN_bn2dec(const BIGNUM *a); // BN_dec2bn parses the leading decimal number from |in|, which may be @@ -288,6 +303,10 @@ OPENSSL_EXPORT char *BN_bn2dec(const BIGNUM *a); // decimal number and stores it in |*outp|. If |*outp| is NULL then it // allocates a new BIGNUM and updates |*outp|. It returns the number of bytes // of |in| processed or zero on error. +// +// Converting an arbitrarily large integer to decimal is quadratic in the bit +// length of |a|. This function assumes the caller has capped the input within +// performance tolerances. OPENSSL_EXPORT int BN_dec2bn(BIGNUM **outp, const char *in); // BN_asc2bn acts like |BN_dec2bn| or |BN_hex2bn| depending on whether |in| @@ -681,6 +700,9 @@ OPENSSL_EXPORT void BN_GENCB_set(BN_GENCB *callback, // the callback, or 1 if |callback| is NULL. OPENSSL_EXPORT int BN_GENCB_call(BN_GENCB *callback, int event, int n); +// BN_GENCB_get_arg returns |callback->arg|. +OPENSSL_EXPORT void *BN_GENCB_get_arg(const BN_GENCB *callback); + // BN_generate_prime_ex sets |ret| to a prime number of |bits| length. If safe // is non-zero then the prime will be such that (ret-1)/2 is also a prime. // (This is needed for Diffie-Hellman groups to ensure that the only subgroups @@ -810,8 +832,9 @@ OPENSSL_EXPORT BIGNUM *BN_mod_inverse(BIGNUM *out, const BIGNUM *a, // Note this function may incorrectly report |a| has no inverse if the random // blinding value has no inverse. It should only be used when |n| has few // non-invertible elements, such as an RSA modulus. -int BN_mod_inverse_blinded(BIGNUM *out, int *out_no_inverse, const BIGNUM *a, - const BN_MONT_CTX *mont, BN_CTX *ctx); +OPENSSL_EXPORT int BN_mod_inverse_blinded(BIGNUM *out, int *out_no_inverse, + const BIGNUM *a, + const BN_MONT_CTX *mont, BN_CTX *ctx); // BN_mod_inverse_odd sets |out| equal to |a|^-1, mod |n|. |a| must be // non-negative and must be less than |n|. |n| must be odd. This function @@ -849,15 +872,6 @@ OPENSSL_EXPORT void BN_MONT_CTX_free(BN_MONT_CTX *mont); OPENSSL_EXPORT BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, const BN_MONT_CTX *from); -// BN_MONT_CTX_set_locked takes |lock| and checks whether |*pmont| is NULL. If -// so, it creates a new |BN_MONT_CTX| and sets the modulus for it to |mod|. It -// then stores it as |*pmont|. It returns one on success and zero on error. Note -// this function assumes |mod| is public. -// -// If |*pmont| is already non-NULL then it does nothing and returns one. -int BN_MONT_CTX_set_locked(BN_MONT_CTX **pmont, CRYPTO_MUTEX *lock, - const BIGNUM *mod, BN_CTX *bn_ctx); - // BN_to_montgomery sets |ret| equal to |a| in the Montgomery domain. |a| is // assumed to be in the range [0, n), where |n| is the Montgomery modulus. It // returns one on success or zero on error. @@ -964,6 +978,9 @@ OPENSSL_EXPORT int BN_bn2binpad(const BIGNUM *in, uint8_t *out, int len); // conservative.) #define BN_prime_checks BN_prime_checks_for_validation +// BN_secure_new calls |BN_new|. +OPENSSL_EXPORT BIGNUM *BN_secure_new(void); + // Private functions |