Update build for OpenSSL-0.9.8j upgrade.
[dragonfly.git] / secure / lib / libcrypto / man / bn.3
CommitLineData
e257b235 1.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
8b0cefbb
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sh \" Subsection heading
984263bc
MD
6.br
7.if t .Sp
8.ne 5
9.PP
10\fB\\$1\fR
11.PP
12..
8b0cefbb 13.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
14.if t .sp .5v
15.if n .sp
16..
8b0cefbb 17.de Vb \" Begin verbatim text
984263bc
MD
18.ft CW
19.nf
20.ne \\$1
21..
8b0cefbb 22.de Ve \" End verbatim text
984263bc 23.ft R
984263bc
MD
24.fi
25..
8b0cefbb
JR
26.\" Set up some character translations and predefined strings. \*(-- will
27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
e257b235
PA
28.\" double quote, and \*(R" will give a right double quote. \*(C+ will
29.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
30.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
31.\" nothing in troff, for use with C<>.
32.tr \(*W-
8b0cefbb 33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 34.ie n \{\
8b0cefbb
JR
35. ds -- \(*W-
36. ds PI pi
37. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39. ds L" ""
40. ds R" ""
41. ds C` ""
42. ds C' ""
984263bc
MD
43'br\}
44.el\{\
8b0cefbb
JR
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
984263bc 49'br\}
8b0cefbb 50.\"
e257b235
PA
51.\" Escape single quotes in literal strings from groff's Unicode transform.
52.ie \n(.g .ds Aq \(aq
53.el .ds Aq '
54.\"
8b0cefbb
JR
55.\" If the F register is turned on, we'll generate index entries on stderr for
56.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
57.\" entries marked with X<> in POD. Of course, you'll have to process the
58.\" output yourself in some meaningful fashion.
e257b235 59.ie \nF \{\
8b0cefbb
JR
60. de IX
61. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 62..
8b0cefbb
JR
63. nr % 0
64. rr F
984263bc 65.\}
e257b235
PA
66.el \{\
67. de IX
68..
69.\}
aac4ff6f 70.\"
8b0cefbb
JR
71.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
72.\" Fear. Run. Save yourself. No user-serviceable parts.
73. \" fudge factors for nroff and troff
984263bc 74.if n \{\
8b0cefbb
JR
75. ds #H 0
76. ds #V .8m
77. ds #F .3m
78. ds #[ \f1
79. ds #] \fP
984263bc
MD
80.\}
81.if t \{\
8b0cefbb
JR
82. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
83. ds #V .6m
84. ds #F 0
85. ds #[ \&
86. ds #] \&
984263bc 87.\}
8b0cefbb 88. \" simple accents for nroff and troff
984263bc 89.if n \{\
8b0cefbb
JR
90. ds ' \&
91. ds ` \&
92. ds ^ \&
93. ds , \&
94. ds ~ ~
95. ds /
984263bc
MD
96.\}
97.if t \{\
8b0cefbb
JR
98. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
99. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
100. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
101. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
102. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
103. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 104.\}
8b0cefbb 105. \" troff and (daisy-wheel) nroff accents
984263bc
MD
106.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
107.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
108.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
109.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
110.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
111.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
112.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
113.ds ae a\h'-(\w'a'u*4/10)'e
114.ds Ae A\h'-(\w'A'u*4/10)'E
8b0cefbb 115. \" corrections for vroff
984263bc
MD
116.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
117.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
8b0cefbb 118. \" for low resolution devices (crt and lpr)
984263bc
MD
119.if \n(.H>23 .if \n(.V>19 \
120\{\
8b0cefbb
JR
121. ds : e
122. ds 8 ss
123. ds o a
124. ds d- d\h'-1'\(ga
125. ds D- D\h'-1'\(hy
126. ds th \o'bp'
127. ds Th \o'LP'
128. ds ae ae
129. ds Ae AE
984263bc
MD
130.\}
131.rm #[ #] #H #V #F C
8b0cefbb
JR
132.\" ========================================================================
133.\"
134.IX Title "bn 3"
e257b235
PA
135.TH bn 3 "2009-01-11" "0.9.8j" "OpenSSL"
136.\" For nroff, turn off justification. Always turn off hyphenation; it makes
137.\" way too many mistakes in technical documents.
138.if n .ad l
139.nh
984263bc
MD
140.SH "NAME"
141bn \- multiprecision integer arithmetics
142.SH "SYNOPSIS"
8b0cefbb 143.IX Header "SYNOPSIS"
984263bc
MD
144.Vb 1
145\& #include <openssl/bn.h>
e257b235 146\&
984263bc
MD
147\& BIGNUM *BN_new(void);
148\& void BN_free(BIGNUM *a);
149\& void BN_init(BIGNUM *);
150\& void BN_clear(BIGNUM *a);
151\& void BN_clear_free(BIGNUM *a);
e257b235 152\&
984263bc
MD
153\& BN_CTX *BN_CTX_new(void);
154\& void BN_CTX_init(BN_CTX *c);
155\& void BN_CTX_free(BN_CTX *c);
e257b235 156\&
984263bc
MD
157\& BIGNUM *BN_copy(BIGNUM *a, const BIGNUM *b);
158\& BIGNUM *BN_dup(const BIGNUM *a);
e257b235 159\&
984263bc 160\& BIGNUM *BN_swap(BIGNUM *a, BIGNUM *b);
e257b235 161\&
984263bc
MD
162\& int BN_num_bytes(const BIGNUM *a);
163\& int BN_num_bits(const BIGNUM *a);
164\& int BN_num_bits_word(BN_ULONG w);
e257b235 165\&
a561f9ff
SS
166\& void BN_set_negative(BIGNUM *a, int n);
167\& int BN_is_negative(const BIGNUM *a);
e257b235 168\&
984263bc
MD
169\& int BN_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);
170\& int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);
171\& int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
172\& int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx);
173\& int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d,
174\& BN_CTX *ctx);
175\& int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
176\& int BN_nnmod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
177\& int BN_mod_add(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
178\& BN_CTX *ctx);
179\& int BN_mod_sub(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
180\& BN_CTX *ctx);
181\& int BN_mod_mul(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
182\& BN_CTX *ctx);
183\& int BN_mod_sqr(BIGNUM *ret, BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
184\& int BN_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BN_CTX *ctx);
185\& int BN_mod_exp(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
186\& const BIGNUM *m, BN_CTX *ctx);
187\& int BN_gcd(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
e257b235 188\&
984263bc
MD
189\& int BN_add_word(BIGNUM *a, BN_ULONG w);
190\& int BN_sub_word(BIGNUM *a, BN_ULONG w);
191\& int BN_mul_word(BIGNUM *a, BN_ULONG w);
192\& BN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w);
193\& BN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w);
e257b235 194\&
984263bc
MD
195\& int BN_cmp(BIGNUM *a, BIGNUM *b);
196\& int BN_ucmp(BIGNUM *a, BIGNUM *b);
197\& int BN_is_zero(BIGNUM *a);
198\& int BN_is_one(BIGNUM *a);
199\& int BN_is_word(BIGNUM *a, BN_ULONG w);
200\& int BN_is_odd(BIGNUM *a);
e257b235 201\&
984263bc
MD
202\& int BN_zero(BIGNUM *a);
203\& int BN_one(BIGNUM *a);
204\& const BIGNUM *BN_value_one(void);
205\& int BN_set_word(BIGNUM *a, unsigned long w);
206\& unsigned long BN_get_word(BIGNUM *a);
e257b235 207\&
984263bc
MD
208\& int BN_rand(BIGNUM *rnd, int bits, int top, int bottom);
209\& int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom);
210\& int BN_rand_range(BIGNUM *rnd, BIGNUM *range);
211\& int BN_pseudo_rand_range(BIGNUM *rnd, BIGNUM *range);
e257b235 212\&
984263bc
MD
213\& BIGNUM *BN_generate_prime(BIGNUM *ret, int bits,int safe, BIGNUM *add,
214\& BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg);
215\& int BN_is_prime(const BIGNUM *p, int nchecks,
216\& void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg);
e257b235 217\&
984263bc
MD
218\& int BN_set_bit(BIGNUM *a, int n);
219\& int BN_clear_bit(BIGNUM *a, int n);
220\& int BN_is_bit_set(const BIGNUM *a, int n);
221\& int BN_mask_bits(BIGNUM *a, int n);
222\& int BN_lshift(BIGNUM *r, const BIGNUM *a, int n);
223\& int BN_lshift1(BIGNUM *r, BIGNUM *a);
224\& int BN_rshift(BIGNUM *r, BIGNUM *a, int n);
225\& int BN_rshift1(BIGNUM *r, BIGNUM *a);
e257b235 226\&
984263bc
MD
227\& int BN_bn2bin(const BIGNUM *a, unsigned char *to);
228\& BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret);
229\& char *BN_bn2hex(const BIGNUM *a);
230\& char *BN_bn2dec(const BIGNUM *a);
231\& int BN_hex2bn(BIGNUM **a, const char *str);
232\& int BN_dec2bn(BIGNUM **a, const char *str);
233\& int BN_print(BIO *fp, const BIGNUM *a);
234\& int BN_print_fp(FILE *fp, const BIGNUM *a);
235\& int BN_bn2mpi(const BIGNUM *a, unsigned char *to);
236\& BIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret);
e257b235 237\&
984263bc
MD
238\& BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n,
239\& BN_CTX *ctx);
e257b235 240\&
984263bc
MD
241\& BN_RECP_CTX *BN_RECP_CTX_new(void);
242\& void BN_RECP_CTX_init(BN_RECP_CTX *recp);
243\& void BN_RECP_CTX_free(BN_RECP_CTX *recp);
244\& int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx);
245\& int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *a, BIGNUM *b,
246\& BN_RECP_CTX *recp, BN_CTX *ctx);
e257b235 247\&
984263bc
MD
248\& BN_MONT_CTX *BN_MONT_CTX_new(void);
249\& void BN_MONT_CTX_init(BN_MONT_CTX *ctx);
250\& void BN_MONT_CTX_free(BN_MONT_CTX *mont);
251\& int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx);
252\& BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from);
253\& int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b,
254\& BN_MONT_CTX *mont, BN_CTX *ctx);
255\& int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,
256\& BN_CTX *ctx);
257\& int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,
258\& BN_CTX *ctx);
e257b235 259\&
a561f9ff
SS
260\& BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai,
261\& BIGNUM *mod);
262\& void BN_BLINDING_free(BN_BLINDING *b);
263\& int BN_BLINDING_update(BN_BLINDING *b,BN_CTX *ctx);
264\& int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
265\& int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
266\& int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b,
267\& BN_CTX *ctx);
268\& int BN_BLINDING_invert_ex(BIGNUM *n,const BIGNUM *r,BN_BLINDING *b,
269\& BN_CTX *ctx);
270\& unsigned long BN_BLINDING_get_thread_id(const BN_BLINDING *);
271\& void BN_BLINDING_set_thread_id(BN_BLINDING *, unsigned long);
272\& unsigned long BN_BLINDING_get_flags(const BN_BLINDING *);
273\& void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long);
274\& BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b,
275\& const BIGNUM *e, BIGNUM *m, BN_CTX *ctx,
276\& int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p,
277\& const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx),
278\& BN_MONT_CTX *m_ctx);
279.Ve
984263bc 280.SH "DESCRIPTION"
8b0cefbb 281.IX Header "DESCRIPTION"
984263bc 282This library performs arithmetic operations on integers of arbitrary
8b0cefbb 283size. It was written for use in public key cryptography, such as \s-1RSA\s0
e257b235 284and Diffie-Hellman.
984263bc
MD
285.PP
286It uses dynamic memory allocation for storing its data structures.
287That means that there is no limit on the size of the numbers
288manipulated by these functions, but return values must always be
289checked in case a memory allocation error has occurred.
290.PP
8b0cefbb 291The basic object in this library is a \fB\s-1BIGNUM\s0\fR. It is used to hold a
984263bc
MD
292single large integer. This type should be considered opaque and fields
293should not be modified or accessed directly.
294.PP
8b0cefbb
JR
295The creation of \fB\s-1BIGNUM\s0\fR objects is described in \fIBN_new\fR\|(3);
296\&\fIBN_add\fR\|(3) describes most of the arithmetic operations.
297Comparison is described in \fIBN_cmp\fR\|(3); \fIBN_zero\fR\|(3)
298describes certain assignments, \fIBN_rand\fR\|(3) the generation of
299random numbers, \fIBN_generate_prime\fR\|(3) deals with prime
300numbers and \fIBN_set_bit\fR\|(3) with bit operations. The conversion
301of \fB\s-1BIGNUM\s0\fRs to external formats is described in \fIBN_bn2bin\fR\|(3).
984263bc 302.SH "SEE ALSO"
74dab6c2 303.IX Header "SEE ALSO"
8b0cefbb
JR
304\&\fIbn_internal\fR\|(3),
305\&\fIdh\fR\|(3), \fIerr\fR\|(3), \fIrand\fR\|(3), \fIrsa\fR\|(3),
306\&\fIBN_new\fR\|(3), \fIBN_CTX_new\fR\|(3),
307\&\fIBN_copy\fR\|(3), \fIBN_swap\fR\|(3), \fIBN_num_bytes\fR\|(3),
308\&\fIBN_add\fR\|(3), \fIBN_add_word\fR\|(3),
309\&\fIBN_cmp\fR\|(3), \fIBN_zero\fR\|(3), \fIBN_rand\fR\|(3),
310\&\fIBN_generate_prime\fR\|(3), \fIBN_set_bit\fR\|(3),
311\&\fIBN_bn2bin\fR\|(3), \fIBN_mod_inverse\fR\|(3),
312\&\fIBN_mod_mul_reciprocal\fR\|(3),
a561f9ff
SS
313\&\fIBN_mod_mul_montgomery\fR\|(3),
314\&\fIBN_BLINDING_new\fR\|(3)