Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)

Standard preamble:
========================================================================
..

..

.. Set up some character translations and predefined strings. \*(-- will
give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
double quote, and \*(R" will give a right double quote. \*(C+ will
give a nicer C++. Capital omega is used to do unbreakable dashes and
therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
nothing in troff, for use with C<>.
.tr \(*W- . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.

If the F register is turned on, we'll generate index entries on stderr for
titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
entries marked with X<> in POD. Of course, you'll have to process the
output yourself in some meaningful fashion.

Avoid warning from groff about undefined register 'F'.
.. .nr rF 0 . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF
Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] .\} . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents . \" corrections for vroff . \" for low resolution devices (crt and lpr) \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} ========================================================================

Title "bn_internal 3" For nroff, turn off justification. Always turn off hyphenation; it makes
way too many mistakes in technical documents.
bn_mul_words, bn_mul_add_words, bn_sqr_words, bn_div_words, bn_add_words, bn_sub_words, bn_mul_comba4, bn_mul_comba8, bn_sqr_comba4, bn_sqr_comba8, bn_cmp_words, bn_mul_normal, bn_mul_low_normal, bn_mul_recursive, bn_mul_part_recursive, bn_mul_low_recursive, bn_mul_high, bn_sqr_normal, bn_sqr_recursive, bn_expand, bn_wexpand, bn_expand2, bn_fix_top, bn_check_top, bn_print, bn_dump, bn_set_max, bn_set_high, bn_set_low - BIGNUM library internal functions Header "SYNOPSIS" .Vb 1 #include <openssl/bn.h> \& BN_ULONG bn_mul_words(BN_ULONG *rp, BN_ULONG *ap, int num, BN_ULONG w); BN_ULONG bn_mul_add_words(BN_ULONG *rp, BN_ULONG *ap, int num, BN_ULONG w); void bn_sqr_words(BN_ULONG *rp, BN_ULONG *ap, int num); BN_ULONG bn_div_words(BN_ULONG h, BN_ULONG l, BN_ULONG d); BN_ULONG bn_add_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp, int num); BN_ULONG bn_sub_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp, int num); \& void bn_mul_comba4(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b); void bn_mul_comba8(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b); void bn_sqr_comba4(BN_ULONG *r, BN_ULONG *a); void bn_sqr_comba8(BN_ULONG *r, BN_ULONG *a); \& int bn_cmp_words(BN_ULONG *a, BN_ULONG *b, int n); \& void bn_mul_normal(BN_ULONG *r, BN_ULONG *a, int na, BN_ULONG *b, int nb); void bn_mul_low_normal(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n); void bn_mul_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n2, int dna,int dnb,BN_ULONG *tmp); void bn_mul_part_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n, int tna,int tnb, BN_ULONG *tmp); void bn_mul_low_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n2, BN_ULONG *tmp); void bn_mul_high(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, BN_ULONG *l, int n2, BN_ULONG *tmp); \& void bn_sqr_normal(BN_ULONG *r, BN_ULONG *a, int n, BN_ULONG *tmp); void bn_sqr_recursive(BN_ULONG *r, BN_ULONG *a, int n2, BN_ULONG *tmp); \& void mul(BN_ULONG r, BN_ULONG a, BN_ULONG w, BN_ULONG c); void mul_add(BN_ULONG r, BN_ULONG a, BN_ULONG w, BN_ULONG c); void sqr(BN_ULONG r0, BN_ULONG r1, BN_ULONG a); \& BIGNUM *bn_expand(BIGNUM *a, int bits); BIGNUM *bn_wexpand(BIGNUM *a, int n); BIGNUM *bn_expand2(BIGNUM *a, int n); void bn_fix_top(BIGNUM *a); \& void bn_check_top(BIGNUM *a); void bn_print(BIGNUM *a); void bn_dump(BN_ULONG *d, int n); void bn_set_max(BIGNUM *a); void bn_set_high(BIGNUM *r, BIGNUM *a, int n); void bn_set_low(BIGNUM *r, BIGNUM *a, int n); .Ve Header "DESCRIPTION" This page documents the internal functions used by the OpenSSL \fB\s-1BIGNUM\s0 implementation. They are described here to facilitate debugging and extending the library. They are not to be used by applications. Subsection "The BIGNUM structure" .Vb 1 typedef struct bignum_st BIGNUM; \& struct bignum_st { BN_ULONG *d; /* Pointer to an array of \*(AqBN_BITS2\*(Aq bit chunks. */ int top; /* Index of last used d +1. */ /* The next are internal book keeping for bn_expand. */ int dmax; /* Size of the d array. */ int neg; /* one if the number is negative */ int flags; }; .Ve

The integer value is stored in d, a malloc()ed array of words (\s-1BN_ULONG\s0), least significant word first. A \s-1BN_ULONG\s0 can be either 16, 32 or 64 bits in size, depending on the 'number of bits' (\s-1BITS2\s0) specified in \f(CW\*(C`openssl/bn.h\*(C'.

\fBdmax is the size of the d array that has been allocated. top is the number of words being used, so for a value of 4, bn.d[0]=4 and bn.top=1. neg is 1 if the number is negative. When a \s-1BIGNUM\s0 is \fB0, the d field can be \s-1NULL\s0 and top == 0.

\fBflags is a bit field of flags which are defined in \*(C`openssl/bn.h\*(C'. The flags begin with \s-1BN_FLG_\s0. The macros BN_set_flags(b,n) and BN_get_flags(b,n) exist to enable or fetch flag(s) n from \s-1BIGNUM\s0 structure b.

Various routines in this library require the use of temporary \fB\s-1BIGNUM\s0 variables during their execution. Since dynamic memory allocation to create \s-1BIGNUM\s0s is rather expensive when used in conjunction with repeated subroutine calls, the \s-1BN_CTX\s0 structure is used. This structure contains \s-1BN_CTX_NUM\s0 \s-1BIGNUM\s0s, see \fIBN_CTX_start\|(3).

Subsection "Low-level arithmetic operations" These functions are implemented in C and for several platforms in assembly language:

bn_mul_words(rp, ap, num, w) operates on the num word arrays rp and ap. It computes ap * w, places the result in rp, and returns the high word (carry).

bn_mul_add_words(rp, ap, num, w) operates on the num word arrays rp and ap. It computes ap * w + rp, places the result in rp, and returns the high word (carry).

bn_sqr_words(rp, ap, n) operates on the num word array \fBap and the 2*num word array ap. It computes ap * ap word-wise, and places the low and high bytes of the result in rp.

bn_div_words(h, l, d) divides the two word number (h,l) by d and returns the result.

bn_add_words(rp, ap, bp, num) operates on the num word arrays ap, bp and rp. It computes ap + bp, places the result in rp, and returns the high word (carry).

bn_sub_words(rp, ap, bp, num) operates on the num word arrays ap, bp and rp. It computes ap - bp, places the result in rp, and returns the carry (1 if bp > ap, 0 otherwise).

bn_mul_comba4(r, a, b) operates on the 4 word arrays a and \fBb and the 8 word array r. It computes a*b and places the result in r.

bn_mul_comba8(r, a, b) operates on the 8 word arrays a and \fBb and the 16 word array r. It computes a*b and places the result in r.

bn_sqr_comba4(r, a, b) operates on the 4 word arrays a and \fBb and the 8 word array r.

bn_sqr_comba8(r, a, b) operates on the 8 word arrays a and \fBb and the 16 word array r.

The following functions are implemented in C:

bn_cmp_words(a, b, n) operates on the n word arrays a and b. It returns 1, 0 and -1 if a is greater than, equal and less than b.

bn_mul_normal(r, a, na, b, nb) operates on the na word array a, the nb word array b and the na+nb word array r. It computes a*b and places the result in r.

bn_mul_low_normal(r, a, b, n) operates on the n word arrays r, a and b. It computes the n low words of \fBa*b and places the result in r.

bn_mul_recursive(r, a, b, n2, dna, dnb, t) operates on the word arrays a and b of length n2+dna and n2+dnb (dna and dnb are currently allowed to be 0 or negative) and the 2*n2 word arrays r and t. n2 must be a power of 2. It computes \fBa*b and places the result in r.

bn_mul_part_recursive(r, a, b, n, tna, tnb, tmp) operates on the word arrays a and b of length n+tna and \fBn+tnb and the 4*n word arrays r and tmp.

bn_mul_low_recursive(r, a, b, n2, tmp) operates on the \fBn2 word arrays r and tmp and the n2/2 word arrays a and b.

bn_mul_high(r, a, b, l, n2, tmp) operates on the \fBn2 word arrays r, a, b and l (?) and the 3*n2 word array tmp.

\fIBN_mul() calls bn_mul_normal(), or an optimized implementation if the factors have the same size: bn_mul_comba8() is used if they are 8 words long, bn_mul_recursive() if they are larger than \fB\s-1BN_MULL_SIZE_NORMAL\s0 and the size is an exact multiple of the word size, and bn_mul_part_recursive() for others that are larger than \fB\s-1BN_MULL_SIZE_NORMAL\s0.

bn_sqr_normal(r, a, n, tmp) operates on the n word array \fBa and the 2*n word arrays tmp and r.

The implementations use the following macros which, depending on the architecture, may use \*(L"long long\*(R" C operations or inline assembler. They are defined in \*(C`bn_lcl.h\*(C'.

mul(r, a, w, c) computes w*a+c and places the low word of the result in r and the high word in c.

mul_add(r, a, w, c) computes w*a+r+c and places the low word of the result in r and the high word in c.

sqr(r0, r1, a) computes a*a and places the low word of the result in r0 and the high word in r1.

Subsection "Size changes" \fIbn_expand() ensures that b has enough space for a bits bit number. bn_wexpand() ensures that b has enough space for an \fBn word number. If the number has to be expanded, both macros call bn_expand2(), which allocates a new d array and copies the data. They return \s-1NULL\s0 on error, b otherwise.

The bn_fix_top() macro reduces a->top to point to the most significant non-zero word plus one when a has shrunk.

Subsection "Debugging" \fIbn_check_top() verifies that \*(C`((a)->top >= 0 && (a)->top <= (a)->dmax)\*(C'. A violation will cause the program to abort.

\fIbn_print() prints a to stderr. bn_dump() prints n words at d (in reverse order, i.e. most significant word first) to stderr.

\fIbn_set_max() makes a a static number with a dmax of its current size. This is used by bn_set_low() and bn_set_high() to make r a read-only \fB\s-1BIGNUM\s0 that contains the n low or high words of a.

If \s-1BN_DEBUG\s0 is not defined, bn_check_top(), bn_print(), bn_dump() and bn_set_max() are defined as empty macros.

Header "SEE ALSO" \fIbn\|(3)