]>
Commit | Line | Data |
---|---|---|
fc58fa8b UM |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | BN_mod_mul_montgomery, BN_MONT_CTX_new, BN_MONT_CTX_init, | |
6 | BN_MONT_CTX_free, BN_MONT_CTX_set, BN_MONT_CTX_copy, | |
7 | BN_from_montgomery, BN_to_montgomery - Montgomery multiplication | |
8 | ||
9 | =head1 SYNOPSIS | |
10 | ||
11 | #include <openssl/bn.h> | |
12 | ||
13 | BN_MONT_CTX *BN_MONT_CTX_new(void); | |
fc58fa8b UM |
14 | void BN_MONT_CTX_free(BN_MONT_CTX *mont); |
15 | ||
16 | int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx); | |
17 | BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from); | |
18 | ||
19 | int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b, | |
20 | BN_MONT_CTX *mont, BN_CTX *ctx); | |
21 | ||
22 | int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, | |
23 | BN_CTX *ctx); | |
24 | ||
25 | int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, | |
26 | BN_CTX *ctx); | |
27 | ||
28 | =head1 DESCRIPTION | |
29 | ||
30 | These functions implement Montgomery multiplication. They are used | |
6c2c3e9b | 31 | automatically when L<BN_mod_exp(3)|BN_mod_exp(3)> is called with suitable input, |
38e33cef | 32 | but they may be useful when several operations are to be performed |
fc58fa8b UM |
33 | using the same modulus. |
34 | ||
35 | BN_MONT_CTX_new() allocates and initializes a B<BN_MONT_CTX> structure. | |
fc58fa8b | 36 | |
78a0c1f1 | 37 | BN_MONT_CTX_set() sets up the I<mont> structure from the modulus I<m> |
fc58fa8b UM |
38 | by precomputing its inverse and a value R. |
39 | ||
78a0c1f1 | 40 | BN_MONT_CTX_copy() copies the B<BN_MONT_CTX> I<from> to I<to>. |
fc58fa8b UM |
41 | |
42 | BN_MONT_CTX_free() frees the components of the B<BN_MONT_CTX>, and, if | |
43 | it was created by BN_MONT_CTX_new(), also the structure itself. | |
23a1d5e9 | 44 | If B<mont> is NULL, nothing is done. |
fc58fa8b | 45 | |
78a0c1f1 BM |
46 | BN_mod_mul_montgomery() computes Mont(I<a>,I<b>):=I<a>*I<b>*R^-1 and places |
47 | the result in I<r>. | |
fc58fa8b | 48 | |
78a0c1f1 | 49 | BN_from_montgomery() performs the Montgomery reduction I<r> = I<a>*R^-1. |
fc58fa8b | 50 | |
78a0c1f1 BM |
51 | BN_to_montgomery() computes Mont(I<a>,R^2), i.e. I<a>*R. |
52 | Note that I<a> must be non-negative and smaller than the modulus. | |
fc58fa8b | 53 | |
78a0c1f1 | 54 | For all functions, I<ctx> is a previously allocated B<BN_CTX> used for |
fc58fa8b UM |
55 | temporary variables. |
56 | ||
fc58fa8b UM |
57 | =head1 RETURN VALUES |
58 | ||
59 | BN_MONT_CTX_new() returns the newly allocated B<BN_MONT_CTX>, and NULL | |
60 | on error. | |
61 | ||
e35af275 | 62 | BN_MONT_CTX_free() has no return value. |
fc58fa8b UM |
63 | |
64 | For the other functions, 1 is returned for success, 0 on error. | |
6c2c3e9b | 65 | The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. |
fc58fa8b | 66 | |
06676624 UM |
67 | =head1 WARNING |
68 | ||
69 | The inputs must be reduced modulo B<m>, otherwise the result will be | |
70 | outside the expected range. | |
71 | ||
e35af275 MC |
72 | =head1 REMOVED FUNCTIONALITY |
73 | ||
74 | void BN_MONT_CTX_init(BN_MONT_CTX *c); | |
75 | ||
76 | BN_MONT_CTX_init() is no longer available as of OpenSSL 1.1.0. It was used to | |
77 | initialize an existing uninitialized B<BN_MONT_CTX>. Typically this would be | |
78 | done as follows: | |
79 | ||
80 | BN_MONT_CTX ctx; | |
81 | BN_MONT_CTX_init(&ctx); | |
82 | ||
83 | Instead applications should create a BN_MONT_CTX structure using | |
84 | BN_MONT_CTX_new: | |
85 | ||
86 | BN_MONT_CTX *ctx; | |
87 | ctx = BN_MONT_CTX_new(); | |
88 | if(!ctx) /* handle error */ | |
89 | ... | |
90 | BN_MONT_CTX_free(ctx); | |
91 | ||
fc58fa8b UM |
92 | =head1 SEE ALSO |
93 | ||
6859cf74 | 94 | L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>, |
6c2c3e9b | 95 | L<BN_CTX_new(3)|BN_CTX_new(3)> |
fc58fa8b UM |
96 | |
97 | =head1 HISTORY | |
98 | ||
99 | BN_MONT_CTX_new(), BN_MONT_CTX_free(), BN_MONT_CTX_set(), | |
100 | BN_mod_mul_montgomery(), BN_from_montgomery() and BN_to_montgomery() | |
101 | are available in all versions of SSLeay and OpenSSL. | |
102 | ||
103 | BN_MONT_CTX_init() and BN_MONT_CTX_copy() were added in SSLeay 0.9.1b. | |
e35af275 | 104 | BN_MONT_CTX_init was removed in OpenSSL 1.1.0 |
fc58fa8b UM |
105 | |
106 | =cut |