[thirdparty/openssl.git] / doc / crypto / bn.pod

=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);

 BIGNUM *BN_swap(BIGNUM *a, BIGNUM *b);

 int BN_num_bytes(const BIGNUM *a);
 int BN_num_bits(const BIGNUM *a);
 int BN_num_bits_word(BN_ULONG w);

 void BN_set_negative(BIGNUM *a, int n);
 int  BN_is_negative(const BIGNUM *a);

 int BN_add(BIGNUM *r, const BIGNUM *a, const 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_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx);
 int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d,
         BN_CTX *ctx);
 int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
 int BN_nnmod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
 int BN_mod_add(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
         BN_CTX *ctx);
 int BN_mod_sub(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
         BN_CTX *ctx);
 int BN_mod_mul(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
         BN_CTX *ctx);
 int BN_mod_sqr(BIGNUM *ret, BIGNUM *a, 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(const 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);
 const 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);
 int BN_rand_range(BIGNUM *rnd, BIGNUM *range);
 int BN_pseudo_rand_range(BIGNUM *rnd, BIGNUM *range);

 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(const 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);

 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);
 unsigned long BN_BLINDING_get_thread_id(const BN_BLINDING *);
 void BN_BLINDING_set_thread_id(BN_BLINDING *, unsigned long);
 unsigned long BN_BLINDING_get_flags(const BN_BLINDING *);
 void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long);
 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);

=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 SEE ALSO

L<bn_internal(3)|bn_internal(3)>,
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_swap(3)|BN_swap(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)>,
L<BN_BLINDING_new(3)|BN_BLINDING_new(3)>

=cut
Commit	Line	Data
4486d0cd UM	1	=pod
	2
	3	=head1 NAME
	4
4d524e10	5	bn - multiprecision integer arithmetics
4486d0cd UM	6
	7	=head1 SYNOPSIS
	8
	9	#include <openssl/bn.h>
	10
4486d0cd	11	BIGNUM *BN_new(void);
dd8dec69 UM	12	void BN_free(BIGNUM *a);
	13	void BN_init(BIGNUM *);
	14	void BN_clear(BIGNUM *a);
	15	void BN_clear_free(BIGNUM *a);
	16
	17	BN_CTX *BN_CTX_new(void);
	18	void BN_CTX_init(BN_CTX *c);
	19	void BN_CTX_free(BN_CTX *c);
	20
4486d0cd	21	BIGNUM BN_copy(BIGNUM a, const BIGNUM *b);
4486d0cd	22	BIGNUM BN_dup(const BIGNUM a);
dd8dec69	23
78a0c1f1 BM	24	BIGNUM BN_swap(BIGNUM a, BIGNUM *b);
78a0c1f1 BM	25
dd8dec69 UM	26	int BN_num_bytes(const BIGNUM *a);
	27	int BN_num_bits(const BIGNUM *a);
	28	int BN_num_bits_word(BN_ULONG w);
	29
ff22e913 NL	30	void BN_set_negative(BIGNUM *a, int n);
	31	int BN_is_negative(const BIGNUM *a);
	32
78a0c1f1	33	int BN_add(BIGNUM r, const BIGNUM a, const BIGNUM *b);
dd8dec69 UM	34	int BN_sub(BIGNUM r, const BIGNUM a, const BIGNUM *b);
dd8dec69 UM	35	int BN_mul(BIGNUM r, BIGNUM a, BIGNUM b, BN_CTX ctx);
78a0c1f1	36	int BN_sqr(BIGNUM r, BIGNUM a, BN_CTX *ctx);
dd8dec69 UM	37	int BN_div(BIGNUM dv, BIGNUM rem, const BIGNUM a, const BIGNUM d,
dd8dec69 UM	38	BN_CTX *ctx);
dd8dec69	39	int BN_mod(BIGNUM rem, const BIGNUM a, const BIGNUM m, BN_CTX ctx);
78a0c1f1 BM	40	int BN_nnmod(BIGNUM rem, const BIGNUM a, const BIGNUM m, BN_CTX ctx);
	41	int BN_mod_add(BIGNUM ret, BIGNUM a, BIGNUM b, const BIGNUM m,
	42	BN_CTX *ctx);
	43	int BN_mod_sub(BIGNUM ret, BIGNUM a, BIGNUM b, const BIGNUM m,
	44	BN_CTX *ctx);
dd8dec69 UM	45	int BN_mod_mul(BIGNUM ret, BIGNUM a, BIGNUM b, const BIGNUM m,
dd8dec69 UM	46	BN_CTX *ctx);
78a0c1f1	47	int BN_mod_sqr(BIGNUM ret, BIGNUM a, const BIGNUM m, BN_CTX ctx);
dd8dec69 UM	48	int BN_exp(BIGNUM r, BIGNUM a, BIGNUM p, BN_CTX ctx);
	49	int BN_mod_exp(BIGNUM r, BIGNUM a, const BIGNUM *p,
	50	const BIGNUM m, BN_CTX ctx);
	51	int BN_gcd(BIGNUM r, BIGNUM a, BIGNUM b, BN_CTX ctx);
	52
	53	int BN_add_word(BIGNUM *a, BN_ULONG w);
	54	int BN_sub_word(BIGNUM *a, BN_ULONG w);
	55	int BN_mul_word(BIGNUM *a, BN_ULONG w);
	56	BN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w);
7999c65c	57	BN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w);
dd8dec69 UM	58
	59	int BN_cmp(BIGNUM a, BIGNUM b);
	60	int BN_ucmp(BIGNUM a, BIGNUM b);
	61	int BN_is_zero(BIGNUM *a);
	62	int BN_is_one(BIGNUM *a);
	63	int BN_is_word(BIGNUM *a, BN_ULONG w);
	64	int BN_is_odd(BIGNUM *a);
	65
	66	int BN_zero(BIGNUM *a);
	67	int BN_one(BIGNUM *a);
98499135	68	const BIGNUM *BN_value_one(void);
dd8dec69 UM	69	int BN_set_word(BIGNUM *a, unsigned long w);
	70	unsigned long BN_get_word(BIGNUM *a);
	71
4d524e10 UM	72	int BN_rand(BIGNUM *rnd, int bits, int top, int bottom);
4d524e10 UM	73	int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom);
e3068929	74	int BN_rand_range(BIGNUM rnd, BIGNUM range);
983495c4	75	int BN_pseudo_rand_range(BIGNUM rnd, BIGNUM range);
dd8dec69	76
4d524e10 UM	77	BIGNUM BN_generate_prime(BIGNUM ret, int bits,int safe, BIGNUM *add,
	78	BIGNUM rem, void (callback)(int, int, void ), void cb_arg);
	79	int BN_is_prime(const BIGNUM *p, int nchecks,
	80	void (callback)(int, int, void ), BN_CTX ctx, void cb_arg);
dd8dec69 UM	81
	82	int BN_set_bit(BIGNUM *a, int n);
	83	int BN_clear_bit(BIGNUM *a, int n);
	84	int BN_is_bit_set(const BIGNUM *a, int n);
	85	int BN_mask_bits(BIGNUM *a, int n);
	86	int BN_lshift(BIGNUM r, const BIGNUM a, int n);
	87	int BN_lshift1(BIGNUM r, BIGNUM a);
	88	int BN_rshift(BIGNUM r, BIGNUM a, int n);
	89	int BN_rshift1(BIGNUM r, BIGNUM a);
	90
	91	int BN_bn2bin(const BIGNUM a, unsigned char to);
	92	BIGNUM BN_bin2bn(const unsigned char s, int len, BIGNUM *ret);
	93	char BN_bn2hex(const BIGNUM a);
	94	char BN_bn2dec(const BIGNUM a);
	95	int BN_hex2bn(BIGNUM *a, const char str);
	96	int BN_dec2bn(BIGNUM *a, const char str);
dd8dec69	97	int BN_print(BIO fp, const BIGNUM a);
e93f9a32	98	int BN_print_fp(FILE fp, const BIGNUM a);
dd8dec69 UM	99	int BN_bn2mpi(const BIGNUM a, unsigned char to);
	100	BIGNUM BN_mpi2bn(unsigned char s, int len, BIGNUM *ret);
	101
	102	BIGNUM BN_mod_inverse(BIGNUM r, BIGNUM a, const BIGNUM n,
	103	BN_CTX *ctx);
	104
	105	BN_RECP_CTX *BN_RECP_CTX_new(void);
	106	void BN_RECP_CTX_init(BN_RECP_CTX *recp);
	107	void BN_RECP_CTX_free(BN_RECP_CTX *recp);
	108	int BN_RECP_CTX_set(BN_RECP_CTX recp, const BIGNUM m, BN_CTX *ctx);
	109	int BN_mod_mul_reciprocal(BIGNUM r, BIGNUM a, BIGNUM *b,
	110	BN_RECP_CTX recp, BN_CTX ctx);
	111
	112	BN_MONT_CTX *BN_MONT_CTX_new(void);
4486d0cd	113	void BN_MONT_CTX_init(BN_MONT_CTX *ctx);
4486d0cd	114	void BN_MONT_CTX_free(BN_MONT_CTX *mont);
dd8dec69 UM	115	int BN_MONT_CTX_set(BN_MONT_CTX mont, const BIGNUM m, BN_CTX *ctx);
	116	BN_MONT_CTX BN_MONT_CTX_copy(BN_MONT_CTX to, BN_MONT_CTX *from);
	117	int BN_mod_mul_montgomery(BIGNUM r, BIGNUM a, BIGNUM *b,
	118	BN_MONT_CTX mont, BN_CTX ctx);
	119	int BN_from_montgomery(BIGNUM r, BIGNUM a, BN_MONT_CTX *mont,
	120	BN_CTX *ctx);
	121	int BN_to_montgomery(BIGNUM r, BIGNUM a, BN_MONT_CTX *mont,
	122	BN_CTX *ctx);
	123
9ca46ff6 NL	124	BN_BLINDING BN_BLINDING_new(const BIGNUM A, const BIGNUM *Ai,
	125	BIGNUM *mod);
	126	void BN_BLINDING_free(BN_BLINDING *b);
	127	int BN_BLINDING_update(BN_BLINDING b,BN_CTX ctx);
	128	int BN_BLINDING_convert(BIGNUM n, BN_BLINDING b, BN_CTX *ctx);
	129	int BN_BLINDING_invert(BIGNUM n, BN_BLINDING b, BN_CTX *ctx);
	130	int BN_BLINDING_convert_ex(BIGNUM n, BIGNUM r, BN_BLINDING *b,
	131	BN_CTX *ctx);
	132	int BN_BLINDING_invert_ex(BIGNUM n,const BIGNUM r,BN_BLINDING *b,
	133	BN_CTX *ctx);
5f834ab1 GT	134	unsigned long BN_BLINDING_get_thread_id(const BN_BLINDING *);
5f834ab1 GT	135	void BN_BLINDING_set_thread_id(BN_BLINDING *, unsigned long);
9ca46ff6 NL	136	unsigned long BN_BLINDING_get_flags(const BN_BLINDING *);
	137	void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long);
	138	BN_BLINDING BN_BLINDING_create_param(BN_BLINDING b,
	139	const BIGNUM e, BIGNUM m, BN_CTX *ctx,
	140	int (bn_mod_exp)(BIGNUM r, const BIGNUM a, const BIGNUM p,
	141	const BIGNUM m, BN_CTX ctx, BN_MONT_CTX *m_ctx),
	142	BN_MONT_CTX *m_ctx);
4486d0cd UM	143
	144	=head1 DESCRIPTION
	145
dd8dec69 UM	146	This library performs arithmetic operations on integers of arbitrary
	147	size. It was written for use in public key cryptography, such as RSA
	148	and Diffie-Hellman.
	149
	150	It uses dynamic memory allocation for storing its data structures.
	151	That means that there is no limit on the size of the numbers
	152	manipulated by these functions, but return values must always be
	153	checked in case a memory allocation error has occurred.
	154
	155	The basic object in this library is a B<BIGNUM>. It is used to hold a
	156	single large integer. This type should be considered opaque and fields
	157	should not be modified or accessed directly.
	158
bb075f88 RL	159	The creation of B<BIGNUM> objects is described in L<BN_new(3)\|BN_new(3)>;
bb075f88 RL	160	L<BN_add(3)\|BN_add(3)> describes most of the arithmetic operations.
e93f9a32	161	Comparison is described in L<BN_cmp(3)\|BN_cmp(3)>; L<BN_zero(3)\|BN_zero(3)>
bb075f88 RL	162	describes certain assignments, L<BN_rand(3)\|BN_rand(3)> the generation of
	163	random numbers, L<BN_generate_prime(3)\|BN_generate_prime(3)> deals with prime
	164	numbers and L<BN_set_bit(3)\|BN_set_bit(3)> with bit operations. The conversion
	165	of B<BIGNUM>s to external formats is described in L<BN_bn2bin(3)\|BN_bn2bin(3)>.
dd8dec69	166
4486d0cd UM	167	=head1 SEE ALSO
4486d0cd UM	168
775c63fc	169	L<bn_internal(3)\|bn_internal(3)>,
bb075f88 RL	170	L<dh(3)\|dh(3)>, L<err(3)\|err(3)>, L<rand(3)\|rand(3)>, L<rsa(3)\|rsa(3)>,
bb075f88 RL	171	L<BN_new(3)\|BN_new(3)>, L<BN_CTX_new(3)\|BN_CTX_new(3)>,
78a0c1f1	172	L<BN_copy(3)\|BN_copy(3)>, L<BN_swap(3)\|BN_swap(3)>, L<BN_num_bytes(3)\|BN_num_bytes(3)>,
bb075f88 RL	173	L<BN_add(3)\|BN_add(3)>, L<BN_add_word(3)\|BN_add_word(3)>,
	174	L<BN_cmp(3)\|BN_cmp(3)>, L<BN_zero(3)\|BN_zero(3)>, L<BN_rand(3)\|BN_rand(3)>,
	175	L<BN_generate_prime(3)\|BN_generate_prime(3)>, L<BN_set_bit(3)\|BN_set_bit(3)>,
	176	L<BN_bn2bin(3)\|BN_bn2bin(3)>, L<BN_mod_inverse(3)\|BN_mod_inverse(3)>,
	177	L<BN_mod_mul_reciprocal(3)\|BN_mod_mul_reciprocal(3)>,
d753c3f5 NL	178	L<BN_mod_mul_montgomery(3)\|BN_mod_mul_montgomery(3)>,
d753c3f5 NL	179	L<BN_BLINDING_new(3)\|BN_BLINDING_new(3)>
4486d0cd UM	180
4486d0cd UM	181	=cut