Upgrade to OpenSSL 0.9.8h.
[dragonfly.git] / secure / lib / libcrypto / man / BN_mod_mul_montgomery.3
CommitLineData
aac4ff6f 1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
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
aac4ff6f
PA
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<>.
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 62.\"
aac4ff6f
PA
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
66.if n .na
67.\"
8b0cefbb
JR
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"
aac4ff6f 132.TH BN_mod_mul_montgomery 3 "2008-09-06" "0.9.8h" "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>
aac4ff6f
PA
141.Ve
142.PP
143.Vb 3
984263bc
MD
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);
aac4ff6f
PA
147.Ve
148.PP
149.Vb 2
984263bc
MD
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);
aac4ff6f
PA
152.Ve
153.PP
154.Vb 2
984263bc
MD
155\& int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b,
156\& BN_MONT_CTX *mont, BN_CTX *ctx);
aac4ff6f
PA
157.Ve
158.PP
159.Vb 2
984263bc
MD
160\& int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,
161\& BN_CTX *ctx);
aac4ff6f
PA
162.Ve
163.PP
164.Vb 2
984263bc
MD
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 */
aac4ff6f 205\& BIGNUM Ni; /* R*(1/R mod N) - N*Ni = 1
984263bc
MD
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.