Regenerate the manual pages after the OpenSSL update to 0.9.7e.
[dragonfly.git] / secure / lib / libcrypto / man / BN_mod_mul_montgomery.3
CommitLineData
8b0cefbb
JR
1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
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
28.\" double quote, and \*(R" will give a right double quote. | will give a
29.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31.\" expand to `' in nroff, nothing in troff, for use with C<>.
984263bc 32.tr \(*W-|\(bv\*(Tr
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
JR
50.\"
51.\" If the F register is turned on, we'll generate index entries on stderr for
52.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53.\" entries marked with X<> in POD. Of course, you'll have to process the
54.\" output yourself in some meaningful fashion.
55.if \nF \{\
56. de IX
57. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 58..
8b0cefbb
JR
59. nr % 0
60. rr F
984263bc 61.\}
8b0cefbb
JR
62.\"
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
984263bc 66.if n .na
8b0cefbb
JR
67.\"
68.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69.\" Fear. Run. Save yourself. No user-serviceable parts.
70. \" fudge factors for nroff and troff
984263bc 71.if n \{\
8b0cefbb
JR
72. ds #H 0
73. ds #V .8m
74. ds #F .3m
75. ds #[ \f1
76. ds #] \fP
984263bc
MD
77.\}
78.if t \{\
8b0cefbb
JR
79. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80. ds #V .6m
81. ds #F 0
82. ds #[ \&
83. ds #] \&
984263bc 84.\}
8b0cefbb 85. \" simple accents for nroff and troff
984263bc 86.if n \{\
8b0cefbb
JR
87. ds ' \&
88. ds ` \&
89. ds ^ \&
90. ds , \&
91. ds ~ ~
92. ds /
984263bc
MD
93.\}
94.if t \{\
8b0cefbb
JR
95. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 101.\}
8b0cefbb 102. \" troff and (daisy-wheel) nroff accents
984263bc
MD
103.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110.ds ae a\h'-(\w'a'u*4/10)'e
111.ds Ae A\h'-(\w'A'u*4/10)'E
8b0cefbb 112. \" corrections for vroff
984263bc
MD
113.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
8b0cefbb 115. \" for low resolution devices (crt and lpr)
984263bc
MD
116.if \n(.H>23 .if \n(.V>19 \
117\{\
8b0cefbb
JR
118. ds : e
119. ds 8 ss
120. ds o a
121. ds d- d\h'-1'\(ga
122. ds D- D\h'-1'\(hy
123. ds th \o'bp'
124. ds Th \o'LP'
125. ds ae ae
126. ds Ae AE
984263bc
MD
127.\}
128.rm #[ #] #H #V #F C
8b0cefbb
JR
129.\" ========================================================================
130.\"
131.IX Title "BN_mod_mul_montgomery 3"
132.TH BN_mod_mul_montgomery 3 "2004-12-18" "0.9.7e" "OpenSSL"
984263bc
MD
133.SH "NAME"
134BN_mod_mul_montgomery, BN_MONT_CTX_new, BN_MONT_CTX_init,
135BN_MONT_CTX_free, BN_MONT_CTX_set, BN_MONT_CTX_copy,
136BN_from_montgomery, BN_to_montgomery \- Montgomery multiplication
137.SH "SYNOPSIS"
8b0cefbb 138.IX Header "SYNOPSIS"
984263bc
MD
139.Vb 1
140\& #include <openssl/bn.h>
141.Ve
8b0cefbb 142.PP
984263bc
MD
143.Vb 3
144\& BN_MONT_CTX *BN_MONT_CTX_new(void);
145\& void BN_MONT_CTX_init(BN_MONT_CTX *ctx);
146\& void BN_MONT_CTX_free(BN_MONT_CTX *mont);
147.Ve
8b0cefbb 148.PP
984263bc
MD
149.Vb 2
150\& int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx);
151\& BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from);
152.Ve
8b0cefbb 153.PP
984263bc
MD
154.Vb 2
155\& int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b,
156\& BN_MONT_CTX *mont, BN_CTX *ctx);
157.Ve
8b0cefbb 158.PP
984263bc
MD
159.Vb 2
160\& int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,
161\& BN_CTX *ctx);
162.Ve
8b0cefbb 163.PP
984263bc
MD
164.Vb 2
165\& int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,
166\& BN_CTX *ctx);
167.Ve
168.SH "DESCRIPTION"
8b0cefbb 169.IX Header "DESCRIPTION"
984263bc 170These functions implement Montgomery multiplication. They are used
8b0cefbb 171automatically when \fIBN_mod_exp\fR\|(3) is called with suitable input,
984263bc
MD
172but they may be useful when several operations are to be performed
173using the same modulus.
174.PP
8b0cefbb
JR
175\&\fIBN_MONT_CTX_new()\fR allocates and initializes a \fB\s-1BN_MONT_CTX\s0\fR structure.
176\&\fIBN_MONT_CTX_init()\fR initializes an existing uninitialized \fB\s-1BN_MONT_CTX\s0\fR.
984263bc 177.PP
8b0cefbb 178\&\fIBN_MONT_CTX_set()\fR sets up the \fImont\fR structure from the modulus \fIm\fR
984263bc
MD
179by precomputing its inverse and a value R.
180.PP
8b0cefbb 181\&\fIBN_MONT_CTX_copy()\fR copies the \fB\s-1BN_MONT_CTX\s0\fR \fIfrom\fR to \fIto\fR.
984263bc 182.PP
8b0cefbb 183\&\fIBN_MONT_CTX_free()\fR frees the components of the \fB\s-1BN_MONT_CTX\s0\fR, and, if
984263bc
MD
184it was created by \fIBN_MONT_CTX_new()\fR, also the structure itself.
185.PP
8b0cefbb 186\&\fIBN_mod_mul_montgomery()\fR computes Mont(\fIa\fR,\fIb\fR):=\fIa\fR*\fIb\fR*R^\-1 and places
984263bc
MD
187the result in \fIr\fR.
188.PP
8b0cefbb 189\&\fIBN_from_montgomery()\fR performs the Montgomery reduction \fIr\fR = \fIa\fR*R^\-1.
984263bc 190.PP
8b0cefbb 191\&\fIBN_to_montgomery()\fR computes Mont(\fIa\fR,R^2), i.e. \fIa\fR*R.
984263bc
MD
192Note that \fIa\fR must be non-negative and smaller than the modulus.
193.PP
8b0cefbb 194For all functions, \fIctx\fR is a previously allocated \fB\s-1BN_CTX\s0\fR used for
984263bc
MD
195temporary variables.
196.PP
8b0cefbb 197The \fB\s-1BN_MONT_CTX\s0\fR structure is defined as follows:
984263bc
MD
198.PP
199.Vb 10
200\& typedef struct bn_mont_ctx_st
201\& {
202\& int ri; /* number of bits in R */
203\& BIGNUM RR; /* R^2 (used to convert to Montgomery form) */
204\& BIGNUM N; /* The modulus */
205\& BIGNUM Ni; /* R*(1/R mod N) - N*Ni = 1
206\& * (Ni is only stored for bignum algorithm) */
207\& BN_ULONG n0; /* least significant word of Ni */
208\& int flags;
209\& } BN_MONT_CTX;
210.Ve
8b0cefbb
JR
211.PP
212\&\fIBN_to_montgomery()\fR is a macro.
984263bc 213.SH "RETURN VALUES"
8b0cefbb
JR
214.IX Header "RETURN VALUES"
215\&\fIBN_MONT_CTX_new()\fR returns the newly allocated \fB\s-1BN_MONT_CTX\s0\fR, and \s-1NULL\s0
984263bc
MD
216on error.
217.PP
8b0cefbb 218\&\fIBN_MONT_CTX_init()\fR and \fIBN_MONT_CTX_free()\fR have no return values.
984263bc
MD
219.PP
220For the other functions, 1 is returned for success, 0 on error.
8b0cefbb 221The error codes can be obtained by \fIERR_get_error\fR\|(3).
984263bc 222.SH "WARNING"
8b0cefbb 223.IX Header "WARNING"
984263bc
MD
224The inputs must be reduced modulo \fBm\fR, otherwise the result will be
225outside the expected range.
226.SH "SEE ALSO"
8b0cefbb
JR
227.IX Header "SEE ALSO"
228\&\fIbn\fR\|(3), \fIERR_get_error\fR\|(3), \fIBN_add\fR\|(3),
229\&\fIBN_CTX_new\fR\|(3)
984263bc 230.SH "HISTORY"
8b0cefbb
JR
231.IX Header "HISTORY"
232\&\fIBN_MONT_CTX_new()\fR, \fIBN_MONT_CTX_free()\fR, \fIBN_MONT_CTX_set()\fR,
233\&\fIBN_mod_mul_montgomery()\fR, \fIBN_from_montgomery()\fR and \fIBN_to_montgomery()\fR
984263bc
MD
234are available in all versions of SSLeay and OpenSSL.
235.PP
8b0cefbb 236\&\fIBN_MONT_CTX_init()\fR and \fIBN_MONT_CTX_copy()\fR were added in SSLeay 0.9.1b.