38e33cef15
New function BN_pseudo_rand(). Use BN_prime_checks_size(BN_num_bits(w)) rounds of Miller-Rabin when generating DSA primes (why not use BN_is_prime()?)
181 lines
6.8 KiB
Text
181 lines
6.8 KiB
Text
=pod
|
|
|
|
=head1 NAME
|
|
|
|
bn - Multiprecision integer arithmetics
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include <openssl/bn.h>
|
|
|
|
BIGNUM *BN_new(void);
|
|
void BN_free(BIGNUM *a);
|
|
void BN_init(BIGNUM *);
|
|
void BN_clear(BIGNUM *a);
|
|
void BN_clear_free(BIGNUM *a);
|
|
|
|
BN_CTX *BN_CTX_new(void);
|
|
void BN_CTX_init(BN_CTX *c);
|
|
void BN_CTX_free(BN_CTX *c);
|
|
|
|
BIGNUM *BN_copy(BIGNUM *a, const BIGNUM *b);
|
|
BIGNUM *BN_dup(const BIGNUM *a);
|
|
|
|
int BN_num_bytes(const BIGNUM *a);
|
|
int BN_num_bits(const BIGNUM *a);
|
|
int BN_num_bits_word(BN_ULONG w);
|
|
|
|
int BN_add(BIGNUM *r, BIGNUM *a, BIGNUM *b);
|
|
int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);
|
|
int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
|
|
int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d,
|
|
BN_CTX *ctx);
|
|
int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx);
|
|
int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
|
|
int BN_mod_mul(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
|
|
BN_CTX *ctx);
|
|
int BN_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BN_CTX *ctx);
|
|
int BN_mod_exp(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
|
|
const BIGNUM *m, BN_CTX *ctx);
|
|
int BN_gcd(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
|
|
|
|
int BN_add_word(BIGNUM *a, BN_ULONG w);
|
|
int BN_sub_word(BIGNUM *a, BN_ULONG w);
|
|
int BN_mul_word(BIGNUM *a, BN_ULONG w);
|
|
BN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w);
|
|
BN_ULONG BN_mod_word(BIGNUM *a, BN_ULONG w);
|
|
|
|
int BN_cmp(BIGNUM *a, BIGNUM *b);
|
|
int BN_ucmp(BIGNUM *a, BIGNUM *b);
|
|
int BN_is_zero(BIGNUM *a);
|
|
int BN_is_one(BIGNUM *a);
|
|
int BN_is_word(BIGNUM *a, BN_ULONG w);
|
|
int BN_is_odd(BIGNUM *a);
|
|
|
|
int BN_zero(BIGNUM *a);
|
|
int BN_one(BIGNUM *a);
|
|
BIGNUM *BN_value_one(void);
|
|
int BN_set_word(BIGNUM *a, unsigned long w);
|
|
unsigned long BN_get_word(BIGNUM *a);
|
|
|
|
int BN_rand(BIGNUM *rnd, int bits, int top,int bottom);
|
|
int BN_pseudo_rand(BIGNUM *rnd, int bits, int top,int bottom);
|
|
|
|
BIGNUM *BN_generate_prime(BIGNUM *ret,int bits,int safe,BIGNUM *add,
|
|
BIGNUM *rem,void (*callback)(int,int,void *),void *cb_arg);
|
|
int BN_is_prime(BIGNUM *p,int nchecks,void (*callback)(int,int,void *),
|
|
BN_CTX *ctx,void *cb_arg);
|
|
|
|
int BN_set_bit(BIGNUM *a, int n);
|
|
int BN_clear_bit(BIGNUM *a, int n);
|
|
int BN_is_bit_set(const BIGNUM *a, int n);
|
|
int BN_mask_bits(BIGNUM *a, int n);
|
|
int BN_lshift(BIGNUM *r, const BIGNUM *a, int n);
|
|
int BN_lshift1(BIGNUM *r, BIGNUM *a);
|
|
int BN_rshift(BIGNUM *r, BIGNUM *a, int n);
|
|
int BN_rshift1(BIGNUM *r, BIGNUM *a);
|
|
|
|
int BN_bn2bin(const BIGNUM *a, unsigned char *to);
|
|
BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret);
|
|
char *BN_bn2hex(const BIGNUM *a);
|
|
char *BN_bn2dec(const BIGNUM *a);
|
|
int BN_hex2bn(BIGNUM **a, const char *str);
|
|
int BN_dec2bn(BIGNUM **a, const char *str);
|
|
int BN_print(BIO *fp, const BIGNUM *a);
|
|
int BN_print_fp(FILE *fp, const BIGNUM *a);
|
|
int BN_bn2mpi(const BIGNUM *a, unsigned char *to);
|
|
BIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret);
|
|
|
|
BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n,
|
|
BN_CTX *ctx);
|
|
|
|
BN_RECP_CTX *BN_RECP_CTX_new(void);
|
|
void BN_RECP_CTX_init(BN_RECP_CTX *recp);
|
|
void BN_RECP_CTX_free(BN_RECP_CTX *recp);
|
|
int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx);
|
|
int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *a, BIGNUM *b,
|
|
BN_RECP_CTX *recp, BN_CTX *ctx);
|
|
|
|
BN_MONT_CTX *BN_MONT_CTX_new(void);
|
|
void BN_MONT_CTX_init(BN_MONT_CTX *ctx);
|
|
void BN_MONT_CTX_free(BN_MONT_CTX *mont);
|
|
int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx);
|
|
BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from);
|
|
int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b,
|
|
BN_MONT_CTX *mont, BN_CTX *ctx);
|
|
int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,
|
|
BN_CTX *ctx);
|
|
int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,
|
|
BN_CTX *ctx);
|
|
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
This library performs arithmetic operations on integers of arbitrary
|
|
size. It was written for use in public key cryptography, such as RSA
|
|
and Diffie-Hellman.
|
|
|
|
It uses dynamic memory allocation for storing its data structures.
|
|
That means that there is no limit on the size of the numbers
|
|
manipulated by these functions, but return values must always be
|
|
checked in case a memory allocation error has occurred.
|
|
|
|
The basic object in this library is a B<BIGNUM>. It is used to hold a
|
|
single large integer. This type should be considered opaque and fields
|
|
should not be modified or accessed directly.
|
|
|
|
The creation of B<BIGNUM> objects is described in L<BN_new(3)|BN_new(3)>;
|
|
L<BN_add(3)|BN_add(3)> describes most of the arithmetic operations.
|
|
Comparison is described in L<BN_cmp(3)|BN_cmp(3)>; L<BN_zero(3)|BN_zero(3)>
|
|
describes certain assignments, L<BN_rand(3)|BN_rand(3)> the generation of
|
|
random numbers, L<BN_generate_prime(3)|BN_generate_prime(3)> deals with prime
|
|
numbers and L<BN_set_bit(3)|BN_set_bit(3)> with bit operations. The conversion
|
|
of B<BIGNUM>s to external formats is described in L<BN_bn2bin(3)|BN_bn2bin(3)>.
|
|
|
|
=head1 INTERNALS
|
|
|
|
The following description is based on the SSLeay documentation:
|
|
|
|
typedef struct bignum_st
|
|
{
|
|
int top; /* Index of last used d. */
|
|
BN_ULONG *d; /* Pointer to an array of 'BITS2' bit chunks. */
|
|
int max; /* Size of the d array. */
|
|
int neg;
|
|
} BIGNUM;
|
|
|
|
The big number is stored in B<d>, a malloc()ed array of B<BN_ULONG>s.
|
|
A B<BN_ULONG> can be either 16, 32 or 64 bits in size, depending on
|
|
the 'number of bits' specified in bn.h.
|
|
|
|
B<max> is the size of the B<d> array that has been allocated. B<top>
|
|
is the 'last' entry being used, so for a value of 4, bn.d[0]=4 and
|
|
bn.top=1. B<neg> is 1 if the number is negative. When a BIGNUM is
|
|
'0', the B<d> field can be NULL and B<top> == 0. Various routines in
|
|
this library require the use of temporary B<BIGNUM> variables during
|
|
their execution. Since dynamic memory allocation to create B<BIGNUM>s
|
|
is rather expensive when used in conjunction with repeated subroutine
|
|
calls, the B<BN_CTX> structure is used. This structure contains
|
|
B<BN_CTX_NUM> B<BIGNUM>s. B<BN_CTX_NUM> is the maximum number of
|
|
temporary B<BIGNUM>s any publicly exported function will use.
|
|
|
|
#define BN_CTX_NUM 12
|
|
typedef struct bignum_ctx
|
|
{
|
|
int tos; /* top of stack */
|
|
BIGNUM *bn[BN_CTX_NUM]; /* The variables */
|
|
} BN_CTX;
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>,
|
|
L<BN_new(3)|BN_new(3)>, L<BN_CTX_new(3)|BN_CTX_new(3)>,
|
|
L<BN_copy(3)|BN_copy(3)>, L<BN_num_bytes(3)|BN_num_bytes(3)>,
|
|
L<BN_add(3)|BN_add(3)>, L<BN_add_word(3)|BN_add_word(3)>,
|
|
L<BN_cmp(3)|BN_cmp(3)>, L<BN_zero(3)|BN_zero(3)>, L<BN_rand(3)|BN_rand(3)>,
|
|
L<BN_generate_prime(3)|BN_generate_prime(3)>, L<BN_set_bit(3)|BN_set_bit(3)>,
|
|
L<BN_bn2bin(3)|BN_bn2bin(3)>, L<BN_mod_inverse(3)|BN_mod_inverse(3)>,
|
|
L<BN_mod_mul_reciprocal(3)|BN_mod_mul_reciprocal(3)>,
|
|
L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)>
|
|
|
|
=cut
|