summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
Diffstat (limited to 'src')
-rw-r--r--src/lib/libcrypto/doc/DSA_SIG_new.pod38
-rw-r--r--src/lib/libcrypto/doc/DSA_do_sign.pod47
-rw-r--r--src/lib/libcrypto/doc/DSA_dup_DH.pod36
-rw-r--r--src/lib/libcrypto/doc/DSA_generate_key.pod32
-rw-r--r--src/lib/libcrypto/doc/DSA_generate_parameters.pod122
-rw-r--r--src/lib/libcrypto/doc/DSA_get_ex_new_index.pod37
-rw-r--r--src/lib/libcrypto/doc/DSA_new.pod40
-rw-r--r--src/lib/libcrypto/doc/DSA_set_method.pod143
-rw-r--r--src/lib/libcrypto/doc/DSA_sign.pod63
-rw-r--r--src/lib/libcrypto/doc/DSA_size.pod33
-rw-r--r--src/lib/libcrypto/doc/EC_GFp_simple_method.pod60
-rw-r--r--src/lib/libcrypto/doc/EC_GROUP_copy.pod174
-rw-r--r--src/lib/libcrypto/doc/EC_GROUP_new.pod95
-rw-r--r--src/lib/libcrypto/doc/EC_KEY_new.pod115
-rw-r--r--src/lib/libcrypto/doc/EC_POINT_add.pod72
-rw-r--r--src/lib/libcrypto/doc/EC_POINT_new.pod123
-rw-r--r--src/lib/libcrypto/man/DSA_SIG_new.343
-rw-r--r--src/lib/libcrypto/man/DSA_do_sign.368
-rw-r--r--src/lib/libcrypto/man/DSA_dup_DH.341
-rw-r--r--src/lib/libcrypto/man/DSA_generate_key.334
-rw-r--r--src/lib/libcrypto/man/DSA_generate_parameters.3171
-rw-r--r--src/lib/libcrypto/man/DSA_get_ex_new_index.347
-rw-r--r--src/lib/libcrypto/man/DSA_new.346
-rw-r--r--src/lib/libcrypto/man/DSA_set_method.3224
-rw-r--r--src/lib/libcrypto/man/DSA_sign.3122
-rw-r--r--src/lib/libcrypto/man/DSA_size.329
-rw-r--r--src/lib/libcrypto/man/EC_GFp_simple_method.3108
-rw-r--r--src/lib/libcrypto/man/EC_GROUP_copy.3434
-rw-r--r--src/lib/libcrypto/man/EC_GROUP_new.3240
-rw-r--r--src/lib/libcrypto/man/EC_KEY_new.3411
-rw-r--r--src/lib/libcrypto/man/EC_POINT_add.3220
-rw-r--r--src/lib/libcrypto/man/EC_POINT_new.3409
-rw-r--r--src/lib/libcrypto/man/Makefile22
33 files changed, 2658 insertions, 1241 deletions
diff --git a/src/lib/libcrypto/doc/DSA_SIG_new.pod b/src/lib/libcrypto/doc/DSA_SIG_new.pod
deleted file mode 100644
index 77aa649db0..0000000000
--- a/src/lib/libcrypto/doc/DSA_SIG_new.pod
+++ /dev/null
@@ -1,38 +0,0 @@
1=pod
2
3=head1 NAME
4
5DSA_SIG_new, DSA_SIG_free - allocate and free DSA signature objects
6
7=head1 SYNOPSIS
8
9 #include <openssl/dsa.h>
10
11 DSA_SIG *DSA_SIG_new(void);
12
13 void DSA_SIG_free(DSA_SIG *a);
14
15=head1 DESCRIPTION
16
17DSA_SIG_new() allocates and initializes a B<DSA_SIG> structure.
18
19DSA_SIG_free() frees the B<DSA_SIG> structure and its components. The
20values are erased before the memory is returned to the system.
21
22=head1 RETURN VALUES
23
24If the allocation fails, DSA_SIG_new() returns B<NULL> and sets an
25error code that can be obtained by
26L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns a pointer
27to the newly allocated structure.
28
29=head1 SEE ALSO
30
31L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>,
32L<DSA_do_sign(3)|DSA_do_sign(3)>
33
34=head1 HISTORY
35
36DSA_SIG_new() and DSA_SIG_free() were added in OpenSSL 0.9.3.
37
38=cut
diff --git a/src/lib/libcrypto/doc/DSA_do_sign.pod b/src/lib/libcrypto/doc/DSA_do_sign.pod
deleted file mode 100644
index 5dfc733b20..0000000000
--- a/src/lib/libcrypto/doc/DSA_do_sign.pod
+++ /dev/null
@@ -1,47 +0,0 @@
1=pod
2
3=head1 NAME
4
5DSA_do_sign, DSA_do_verify - raw DSA signature operations
6
7=head1 SYNOPSIS
8
9 #include <openssl/dsa.h>
10
11 DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa);
12
13 int DSA_do_verify(const unsigned char *dgst, int dgst_len,
14 DSA_SIG *sig, DSA *dsa);
15
16=head1 DESCRIPTION
17
18DSA_do_sign() computes a digital signature on the B<len> byte message
19digest B<dgst> using the private key B<dsa> and returns it in a
20newly allocated B<DSA_SIG> structure.
21
22L<DSA_sign_setup(3)|DSA_sign_setup(3)> may be used to precompute part
23of the signing operation in case signature generation is
24time-critical.
25
26DSA_do_verify() verifies that the signature B<sig> matches a given
27message digest B<dgst> of size B<len>. B<dsa> is the signer's public
28key.
29
30=head1 RETURN VALUES
31
32DSA_do_sign() returns the signature, NULL on error. DSA_do_verify()
33returns 1 for a valid signature, 0 for an incorrect signature and -1
34on error. The error codes can be obtained by
35L<ERR_get_error(3)|ERR_get_error(3)>.
36
37=head1 SEE ALSO
38
39L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>,
40L<DSA_SIG_new(3)|DSA_SIG_new(3)>,
41L<DSA_sign(3)|DSA_sign(3)>
42
43=head1 HISTORY
44
45DSA_do_sign() and DSA_do_verify() were added in OpenSSL 0.9.3.
46
47=cut
diff --git a/src/lib/libcrypto/doc/DSA_dup_DH.pod b/src/lib/libcrypto/doc/DSA_dup_DH.pod
deleted file mode 100644
index 7f6f0d1115..0000000000
--- a/src/lib/libcrypto/doc/DSA_dup_DH.pod
+++ /dev/null
@@ -1,36 +0,0 @@
1=pod
2
3=head1 NAME
4
5DSA_dup_DH - create a DH structure out of DSA structure
6
7=head1 SYNOPSIS
8
9 #include <openssl/dsa.h>
10
11 DH * DSA_dup_DH(const DSA *r);
12
13=head1 DESCRIPTION
14
15DSA_dup_DH() duplicates DSA parameters/keys as DH parameters/keys. q
16is lost during that conversion, but the resulting DH parameters
17contain its length.
18
19=head1 RETURN VALUE
20
21DSA_dup_DH() returns the new B<DH> structure, and NULL on error. The
22error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
23
24=head1 NOTE
25
26Be careful to avoid small subgroup attacks when using this.
27
28=head1 SEE ALSO
29
30L<dh(3)|dh(3)>, L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>
31
32=head1 HISTORY
33
34DSA_dup_DH() was added in OpenSSL 0.9.4.
35
36=cut
diff --git a/src/lib/libcrypto/doc/DSA_generate_key.pod b/src/lib/libcrypto/doc/DSA_generate_key.pod
deleted file mode 100644
index 069a05767c..0000000000
--- a/src/lib/libcrypto/doc/DSA_generate_key.pod
+++ /dev/null
@@ -1,32 +0,0 @@
1=pod
2
3=head1 NAME
4
5DSA_generate_key - generate DSA key pair
6
7=head1 SYNOPSIS
8
9 #include <openssl/dsa.h>
10
11 int DSA_generate_key(DSA *a);
12
13=head1 DESCRIPTION
14
15DSA_generate_key() expects B<a> to contain DSA parameters. It generates
16a new key pair and stores it in B<a-E<gt>pub_key> and B<a-E<gt>priv_key>.
17
18=head1 RETURN VALUE
19
20DSA_generate_key() returns 1 on success, 0 otherwise.
21The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
22
23=head1 SEE ALSO
24
25L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>,
26L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>
27
28=head1 HISTORY
29
30DSA_generate_key() is available since SSLeay 0.8.
31
32=cut
diff --git a/src/lib/libcrypto/doc/DSA_generate_parameters.pod b/src/lib/libcrypto/doc/DSA_generate_parameters.pod
deleted file mode 100644
index 698b555a0e..0000000000
--- a/src/lib/libcrypto/doc/DSA_generate_parameters.pod
+++ /dev/null
@@ -1,122 +0,0 @@
1=pod
2
3=head1 NAME
4
5DSA_generate_parameters_ex, DSA_generate_parameters - generate DSA parameters
6
7=head1 SYNOPSIS
8
9 #include <openssl/dsa.h>
10
11 int DSA_generate_parameters_ex(DSA *dsa, int bits,
12 const unsigned char *seed,int seed_len,
13 int *counter_ret, unsigned long *h_ret, BN_GENCB *cb);
14
15Deprecated:
16
17 DSA *DSA_generate_parameters(int bits, unsigned char *seed,
18 int seed_len, int *counter_ret, unsigned long *h_ret,
19 void (*callback)(int, int, void *), void *cb_arg);
20
21=head1 DESCRIPTION
22
23DSA_generate_parameters_ex() generates primes p and q and a generator g
24for use in the DSA and stores the result in B<dsa>.
25
26B<bits> is the length of the prime to be generated; the DSS allows a
27maximum of 1024 bits.
28
29If B<seed> is B<NULL> or B<seed_len> E<lt> 20, the primes will be
30generated at random. Otherwise, the seed is used to generate
31them. If the given seed does not yield a prime q, a new random
32seed is chosen and placed at B<seed>.
33
34DSA_generate_parameters_ex() places the iteration count in
35*B<counter_ret> and a counter used for finding a generator in
36*B<h_ret>, unless these are B<NULL>.
37
38A callback function may be used to provide feedback about the progress
39of the key generation. If B<cb> is not B<NULL>, it will be
40called as shown below. For information on the BN_GENCB structure and the
41BN_GENCB_call function discussed below, refer to
42L<BN_generate_prime(3)|BN_generate_prime(3)>.
43
44=over 4
45
46=item *
47
48When a candidate for q is generated, B<BN_GENCB_call(cb, 0, m++)> is called
49(m is 0 for the first candidate).
50
51=item *
52
53When a candidate for q has passed a test by trial division,
54B<BN_GENCB_call(cb, 1, -1)> is called.
55While a candidate for q is tested by Miller-Rabin primality tests,
56B<BN_GENCB_call(cb, 1, i)> is called in the outer loop
57(once for each witness that confirms that the candidate may be prime);
58i is the loop counter (starting at 0).
59
60=item *
61
62When a prime q has been found, B<BN_GENCB_call(cb, 2, 0)> and
63B<BN_GENCB_call(cb, 3, 0)> are called.
64
65=item *
66
67Before a candidate for p (other than the first) is generated and tested,
68B<BN_GENCB_call(cb, 0, counter)> is called.
69
70=item *
71
72When a candidate for p has passed the test by trial division,
73B<BN_GENCB_call(cb, 1, -1)> is called.
74While it is tested by the Miller-Rabin primality test,
75B<BN_GENCB_call(cb, 1, i)> is called in the outer loop
76(once for each witness that confirms that the candidate may be prime).
77i is the loop counter (starting at 0).
78
79=item *
80
81When p has been found, B<BN_GENCB_call(cb, 2, 1)> is called.
82
83=item *
84
85When the generator has been found, B<BN_GENCB_call(cb, 3, 1)> is called.
86
87=back
88
89DSA_generate_parameters() (deprecated) works in much the same way as for DSA_generate_parameters_ex, except that no B<dsa> parameter is passed and
90instead a newly allocated B<DSA> structure is returned. Additionally "old
91style" callbacks are used instead of the newer BN_GENCB based approach.
92Refer to L<BN_generate_prime(3)|BN_generate_prime(3)> for further information.
93
94=head1 RETURN VALUE
95
96DSA_generate_parameters_ex() returns a 1 on success, or 0 otherwise.
97
98DSA_generate_parameters() returns a pointer to the DSA structure, or
99B<NULL> if the parameter generation fails.
100
101The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
102
103=head1 BUGS
104
105Seed lengths E<gt> 20 are not supported.
106
107=head1 SEE ALSO
108
109L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>,
110L<DSA_free(3)|DSA_free(3)>, L<BN_generate_prime(3)|BN_generate_prime(3)>
111
112=head1 HISTORY
113
114DSA_generate_parameters() appeared in SSLeay 0.8. The B<cb_arg>
115argument was added in SSLeay 0.9.0.
116In versions up to OpenSSL 0.9.4, B<callback(1, ...)> was called
117in the inner loop of the Miller-Rabin test whenever it reached the
118squaring step (the parameters to B<callback> did not reveal how many
119witnesses had been tested); since OpenSSL 0.9.5, B<callback(1, ...)>
120is called as in BN_is_prime(3), i.e. once for each witness.
121
122=cut
diff --git a/src/lib/libcrypto/doc/DSA_get_ex_new_index.pod b/src/lib/libcrypto/doc/DSA_get_ex_new_index.pod
deleted file mode 100644
index e2fcabf370..0000000000
--- a/src/lib/libcrypto/doc/DSA_get_ex_new_index.pod
+++ /dev/null
@@ -1,37 +0,0 @@
1=pod
2
3=head1 NAME
4
5DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data - add application
6specific data to DSA structures
7
8=head1 SYNOPSIS
9
10 #include <openssl/dsa.h>
11
12 int DSA_get_ex_new_index(long argl, void *argp,
13 CRYPTO_EX_new *new_func,
14 CRYPTO_EX_dup *dup_func,
15 CRYPTO_EX_free *free_func);
16
17 int DSA_set_ex_data(DSA *d, int idx, void *arg);
18
19 char *DSA_get_ex_data(DSA *d, int idx);
20
21=head1 DESCRIPTION
22
23These functions handle application specific data in DSA
24structures. Their usage is identical to that of
25RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data()
26as described in L<RSA_get_ex_new_index(3)>.
27
28=head1 SEE ALSO
29
30L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, L<dsa(3)|dsa(3)>
31
32=head1 HISTORY
33
34DSA_get_ex_new_index(), DSA_set_ex_data() and DSA_get_ex_data() are
35available since OpenSSL 0.9.5.
36
37=cut
diff --git a/src/lib/libcrypto/doc/DSA_new.pod b/src/lib/libcrypto/doc/DSA_new.pod
deleted file mode 100644
index e1e30b9a07..0000000000
--- a/src/lib/libcrypto/doc/DSA_new.pod
+++ /dev/null
@@ -1,40 +0,0 @@
1=pod
2
3=head1 NAME
4
5DSA_new, DSA_free - allocate and free DSA objects
6
7=head1 SYNOPSIS
8
9 #include <openssl/dsa.h>
10
11 DSA* DSA_new(void);
12
13 void DSA_free(DSA *dsa);
14
15=head1 DESCRIPTION
16
17DSA_new() allocates and initializes a B<DSA> structure. It is equivalent to
18calling DSA_new_method(NULL).
19
20DSA_free() frees the B<DSA> structure and its components. The values are
21erased before the memory is returned to the system.
22
23=head1 RETURN VALUES
24
25If the allocation fails, DSA_new() returns B<NULL> and sets an error
26code that can be obtained by
27L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns a pointer
28to the newly allocated structure.
29
30=head1 SEE ALSO
31
32L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>,
33L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>,
34L<DSA_generate_key(3)|DSA_generate_key(3)>
35
36=head1 HISTORY
37
38DSA_new() and DSA_free() are available in all versions of SSLeay and OpenSSL.
39
40=cut
diff --git a/src/lib/libcrypto/doc/DSA_set_method.pod b/src/lib/libcrypto/doc/DSA_set_method.pod
deleted file mode 100644
index bc57a3e8e2..0000000000
--- a/src/lib/libcrypto/doc/DSA_set_method.pod
+++ /dev/null
@@ -1,143 +0,0 @@
1=pod
2
3=head1 NAME
4
5DSA_set_default_method, DSA_get_default_method,
6DSA_set_method, DSA_new_method, DSA_OpenSSL,
7DSA_set_default_openssl_method, DSA_get_default_openssl_method
8- select DSA method
9
10=head1 SYNOPSIS
11
12 #include <openssl/dsa.h>
13 #include <openssl/engine.h>
14
15 void DSA_set_default_method(const DSA_METHOD *meth);
16
17 const DSA_METHOD *DSA_get_default_method(void);
18
19 int DSA_set_method(DSA *dsa, const DSA_METHOD *meth);
20
21 DSA *DSA_new_method(ENGINE *engine);
22
23 DSA_METHOD *DSA_OpenSSL(void);
24
25=head1 DESCRIPTION
26
27A B<DSA_METHOD> specifies the functions that OpenSSL uses for DSA
28operations. By modifying the method, alternative implementations
29such as hardware accelerators may be used. IMPORTANT: See the NOTES section for
30important information about how these DSA API functions are affected by the use
31of B<ENGINE> API calls.
32
33Initially, the default DSA_METHOD is the OpenSSL internal implementation,
34as returned by DSA_OpenSSL().
35
36DSA_set_default_method() makes B<meth> the default method for all DSA
37structures created later. B<NB>: This is true only whilst no ENGINE has
38been set as a default for DSA, so this function is no longer recommended.
39
40DSA_get_default_method() returns a pointer to the current default
41DSA_METHOD. However, the meaningfulness of this result is dependent on
42whether the ENGINE API is being used, so this function is no longer
43recommended.
44
45DSA_set_method() selects B<meth> to perform all operations using the key
46B<rsa>. This will replace the DSA_METHOD used by the DSA key and if the
47previous method was supplied by an ENGINE, the handle to that ENGINE will
48be released during the change. It is possible to have DSA keys that only
49work with certain DSA_METHOD implementations (eg. from an ENGINE module
50that supports embedded hardware-protected keys), and in such cases
51attempting to change the DSA_METHOD for the key can have unexpected
52results.
53
54DSA_new_method() allocates and initializes a DSA structure so that B<engine>
55will be used for the DSA operations. If B<engine> is NULL, the default engine
56for DSA operations is used, and if no default ENGINE is set, the DSA_METHOD
57controlled by DSA_set_default_method() is used.
58
59=head1 THE DSA_METHOD STRUCTURE
60
61struct
62 {
63 /* name of the implementation */
64 const char *name;
65
66 /* sign */
67 DSA_SIG *(*dsa_do_sign)(const unsigned char *dgst, int dlen,
68 DSA *dsa);
69
70 /* pre-compute k^-1 and r */
71 int (*dsa_sign_setup)(DSA *dsa, BN_CTX *ctx_in, BIGNUM **kinvp,
72 BIGNUM **rp);
73
74 /* verify */
75 int (*dsa_do_verify)(const unsigned char *dgst, int dgst_len,
76 DSA_SIG *sig, DSA *dsa);
77
78 /* compute rr = a1^p1 * a2^p2 mod m (May be NULL for some
79 implementations) */
80 int (*dsa_mod_exp)(DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1,
81 BIGNUM *a2, BIGNUM *p2, BIGNUM *m,
82 BN_CTX *ctx, BN_MONT_CTX *in_mont);
83
84 /* compute r = a ^ p mod m (May be NULL for some implementations) */
85 int (*bn_mod_exp)(DSA *dsa, BIGNUM *r, BIGNUM *a,
86 const BIGNUM *p, const BIGNUM *m,
87 BN_CTX *ctx, BN_MONT_CTX *m_ctx);
88
89 /* called at DSA_new */
90 int (*init)(DSA *DSA);
91
92 /* called at DSA_free */
93 int (*finish)(DSA *DSA);
94
95 int flags;
96
97 char *app_data; /* ?? */
98
99 } DSA_METHOD;
100
101=head1 RETURN VALUES
102
103DSA_OpenSSL() and DSA_get_default_method() return pointers to the respective
104B<DSA_METHOD>s.
105
106DSA_set_method() returns non-zero if the provided B<meth> was successfully set
107as the method for B<dsa> (including unloading the ENGINE handle if the previous
108method was supplied by an ENGINE).
109
110DSA_new_method() returns NULL and sets an error code that can be
111obtained by L<ERR_get_error(3)|ERR_get_error(3)> if the allocation
112fails. Otherwise it returns a pointer to the newly allocated structure.
113
114=head1 NOTES
115
116As of version 0.9.7, DSA_METHOD implementations are grouped together with other
117algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B<ENGINE> modules. If a
118default ENGINE is specified for DSA functionality using an ENGINE API function,
119that will override any DSA defaults set using the DSA API (ie.
120DSA_set_default_method()). For this reason, the ENGINE API is the recommended
121way to control default implementations for use in DSA and other cryptographic
122algorithms.
123
124=head1 SEE ALSO
125
126L<dsa(3)|dsa(3)>, L<DSA_new(3)|DSA_new(3)>
127
128=head1 HISTORY
129
130DSA_set_default_method(), DSA_get_default_method(), DSA_set_method(),
131DSA_new_method() and DSA_OpenSSL() were added in OpenSSL 0.9.4.
132
133DSA_set_default_openssl_method() and DSA_get_default_openssl_method() replaced
134DSA_set_default_method() and DSA_get_default_method() respectively, and
135DSA_set_method() and DSA_new_method() were altered to use B<ENGINE>s rather than
136B<DSA_METHOD>s during development of the engine version of OpenSSL 0.9.6. For
1370.9.7, the handling of defaults in the ENGINE API was restructured so that this
138change was reversed, and behaviour of the other functions resembled more closely
139the previous behaviour. The behaviour of defaults in the ENGINE API now
140transparently overrides the behaviour of defaults in the DSA API without
141requiring changing these function prototypes.
142
143=cut
diff --git a/src/lib/libcrypto/doc/DSA_sign.pod b/src/lib/libcrypto/doc/DSA_sign.pod
deleted file mode 100644
index 4e78a71390..0000000000
--- a/src/lib/libcrypto/doc/DSA_sign.pod
+++ /dev/null
@@ -1,63 +0,0 @@
1=pod
2
3=head1 NAME
4
5DSA_sign, DSA_sign_setup, DSA_verify - DSA signatures
6
7=head1 SYNOPSIS
8
9 #include <openssl/dsa.h>
10
11 int DSA_sign(int type, const unsigned char *dgst, int len,
12 unsigned char *sigret, unsigned int *siglen, DSA *dsa);
13
14 int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp,
15 BIGNUM **rp);
16
17 int DSA_verify(int type, const unsigned char *dgst, int len,
18 unsigned char *sigbuf, int siglen, DSA *dsa);
19
20=head1 DESCRIPTION
21
22DSA_sign() computes a digital signature on the B<len> byte message
23digest B<dgst> using the private key B<dsa> and places its ASN.1 DER
24encoding at B<sigret>. The length of the signature is places in
25*B<siglen>. B<sigret> must point to DSA_size(B<dsa>) bytes of memory.
26
27DSA_sign_setup() may be used to precompute part of the signing
28operation in case signature generation is time-critical. It expects
29B<dsa> to contain DSA parameters. It places the precomputed values
30in newly allocated B<BIGNUM>s at *B<kinvp> and *B<rp>, after freeing
31the old ones unless *B<kinvp> and *B<rp> are NULL. These values may
32be passed to DSA_sign() in B<dsa-E<gt>kinv> and B<dsa-E<gt>r>.
33B<ctx> is a pre-allocated B<BN_CTX> or NULL.
34
35DSA_verify() verifies that the signature B<sigbuf> of size B<siglen>
36matches a given message digest B<dgst> of size B<len>.
37B<dsa> is the signer's public key.
38
39The B<type> parameter is ignored.
40
41=head1 RETURN VALUES
42
43DSA_sign() and DSA_sign_setup() return 1 on success, 0 on error.
44DSA_verify() returns 1 for a valid signature, 0 for an incorrect
45signature and -1 on error. The error codes can be obtained by
46L<ERR_get_error(3)|ERR_get_error(3)>.
47
48=head1 CONFORMING TO
49
50US Federal Information Processing Standard FIPS 186 (Digital Signature
51Standard, DSS), ANSI X9.30
52
53=head1 SEE ALSO
54
55L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>,
56L<DSA_do_sign(3)|DSA_do_sign(3)>
57
58=head1 HISTORY
59
60DSA_sign() and DSA_verify() are available in all versions of SSLeay.
61DSA_sign_setup() was added in SSLeay 0.8.
62
63=cut
diff --git a/src/lib/libcrypto/doc/DSA_size.pod b/src/lib/libcrypto/doc/DSA_size.pod
deleted file mode 100644
index ba4f650361..0000000000
--- a/src/lib/libcrypto/doc/DSA_size.pod
+++ /dev/null
@@ -1,33 +0,0 @@
1=pod
2
3=head1 NAME
4
5DSA_size - get DSA signature size
6
7=head1 SYNOPSIS
8
9 #include <openssl/dsa.h>
10
11 int DSA_size(const DSA *dsa);
12
13=head1 DESCRIPTION
14
15This function returns the size of an ASN.1 encoded DSA signature in
16bytes. It can be used to determine how much memory must be allocated
17for a DSA signature.
18
19B<dsa-E<gt>q> must not be B<NULL>.
20
21=head1 RETURN VALUE
22
23The size in bytes.
24
25=head1 SEE ALSO
26
27L<dsa(3)|dsa(3)>, L<DSA_sign(3)|DSA_sign(3)>
28
29=head1 HISTORY
30
31DSA_size() is available in all versions of SSLeay and OpenSSL.
32
33=cut
diff --git a/src/lib/libcrypto/doc/EC_GFp_simple_method.pod b/src/lib/libcrypto/doc/EC_GFp_simple_method.pod
deleted file mode 100644
index aff20ac175..0000000000
--- a/src/lib/libcrypto/doc/EC_GFp_simple_method.pod
+++ /dev/null
@@ -1,60 +0,0 @@
1=pod
2
3=head1 NAME
4
5EC_GFp_simple_method, EC_GFp_mont_method, EC_GFp_nist_method, EC_GFp_nistp224_method, EC_GFp_nistp256_method, EC_GFp_nistp521_method, EC_GF2m_simple_method, EC_METHOD_get_field_type - Functions for obtaining B<EC_METHOD> objects.
6
7=head1 SYNOPSIS
8
9 #include <openssl/ec.h>
10
11 const EC_METHOD *EC_GFp_simple_method(void);
12 const EC_METHOD *EC_GFp_mont_method(void);
13 const EC_METHOD *EC_GFp_nist_method(void);
14 const EC_METHOD *EC_GFp_nistp224_method(void);
15 const EC_METHOD *EC_GFp_nistp256_method(void);
16 const EC_METHOD *EC_GFp_nistp521_method(void);
17
18 const EC_METHOD *EC_GF2m_simple_method(void);
19
20 int EC_METHOD_get_field_type(const EC_METHOD *meth);
21
22=head1 DESCRIPTION
23
24The Elliptic Curve library provides a number of different implementations through a single common interface.
25When constructing a curve using EC_GROUP_new (see L<EC_GROUP_new(3)|EC_GROUP_new(3)>) an
26implementation method must be provided. The functions described here all return a const pointer to an
27B<EC_METHOD> structure that can be passed to EC_GROUP_NEW. It is important that the correct implementation
28type for the form of curve selected is used.
29
30For F2^m curves there is only one implementation choice, i.e. EC_GF2_simple_method.
31
32For Fp curves the lowest common denominator implementation is the EC_GFp_simple_method implementation. All
33other implementations are based on this one. EC_GFp_mont_method builds on EC_GFp_simple_method but adds the
34use of montgomery multiplication (see L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)>). EC_GFp_nist_method
35offers an implementation optimised for use with NIST recommended curves (NIST curves are available through
36EC_GROUP_new_by_curve_name as described in L<EC_GROUP_new(3)|EC_GROUP_new(3)>).
37
38The functions EC_GFp_nistp224_method, EC_GFp_nistp256_method and EC_GFp_nistp521_method offer 64 bit
39optimised implementations for the NIST P224, P256 and P521 curves respectively. Note, however, that these
40implementations are not available on all platforms.
41
42EC_METHOD_get_field_type identifies what type of field the EC_METHOD structure supports, which will be either
43F2^m or Fp. If the field type is Fp then the value B<NID_X9_62_prime_field> is returned. If the field type is
44F2^m then the value B<NID_X9_62_characteristic_two_field> is returned. These values are defined in the
45obj_mac.h header file.
46
47=head1 RETURN VALUES
48
49All EC_GFp* functions and EC_GF2m_simple_method always return a const pointer to an EC_METHOD structure.
50
51EC_METHOD_get_field_type returns an integer that identifies the type of field the EC_METHOD structure supports.
52
53=head1 SEE ALSO
54
55L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>,
56L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>,
57L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>,
58L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)>
59
60=cut
diff --git a/src/lib/libcrypto/doc/EC_GROUP_copy.pod b/src/lib/libcrypto/doc/EC_GROUP_copy.pod
deleted file mode 100644
index d4896af1d5..0000000000
--- a/src/lib/libcrypto/doc/EC_GROUP_copy.pod
+++ /dev/null
@@ -1,174 +0,0 @@
1=pod
2
3=head1 NAME
4
5EC_GROUP_copy, EC_GROUP_dup, EC_GROUP_method_of, EC_GROUP_set_generator, EC_GROUP_get0_generator, EC_GROUP_get_order, EC_GROUP_get_cofactor, EC_GROUP_set_curve_name, EC_GROUP_get_curve_name, EC_GROUP_set_asn1_flag, EC_GROUP_get_asn1_flag, EC_GROUP_set_point_conversion_form, EC_GROUP_get_point_conversion_form, EC_GROUP_get0_seed, EC_GROUP_get_seed_len, EC_GROUP_set_seed, EC_GROUP_get_degree, EC_GROUP_check, EC_GROUP_check_discriminant, EC_GROUP_cmp, EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis, EC_GROUP_get_pentanomial_basis - Functions for manipulating B<EC_GROUP> objects.
6
7=head1 SYNOPSIS
8
9 #include <openssl/ec.h>
10 #include <openssl/bn.h>
11
12 int EC_GROUP_copy(EC_GROUP *dst, const EC_GROUP *src);
13 EC_GROUP *EC_GROUP_dup(const EC_GROUP *src);
14
15 const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group);
16
17 int EC_GROUP_set_generator(EC_GROUP *group, const EC_POINT *generator, const BIGNUM *order, const BIGNUM *cofactor);
18 const EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group);
19
20 int EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order, BN_CTX *ctx);
21 int EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx);
22
23 void EC_GROUP_set_curve_name(EC_GROUP *group, int nid);
24 int EC_GROUP_get_curve_name(const EC_GROUP *group);
25
26 void EC_GROUP_set_asn1_flag(EC_GROUP *group, int flag);
27 int EC_GROUP_get_asn1_flag(const EC_GROUP *group);
28
29 void EC_GROUP_set_point_conversion_form(EC_GROUP *group, point_conversion_form_t form);
30 point_conversion_form_t EC_GROUP_get_point_conversion_form(const EC_GROUP *);
31
32 unsigned char *EC_GROUP_get0_seed(const EC_GROUP *x);
33 size_t EC_GROUP_get_seed_len(const EC_GROUP *);
34 size_t EC_GROUP_set_seed(EC_GROUP *, const unsigned char *, size_t len);
35
36 int EC_GROUP_get_degree(const EC_GROUP *group);
37
38 int EC_GROUP_check(const EC_GROUP *group, BN_CTX *ctx);
39
40 int EC_GROUP_check_discriminant(const EC_GROUP *group, BN_CTX *ctx);
41
42 int EC_GROUP_cmp(const EC_GROUP *a, const EC_GROUP *b, BN_CTX *ctx);
43
44 int EC_GROUP_get_basis_type(const EC_GROUP *);
45 int EC_GROUP_get_trinomial_basis(const EC_GROUP *, unsigned int *k);
46 int EC_GROUP_get_pentanomial_basis(const EC_GROUP *, unsigned int *k1,
47 unsigned int *k2, unsigned int *k3);
48
49=head1 DESCRIPTION
50
51EC_GROUP_copy copies the curve B<src> into B<dst>. Both B<src> and B<dst> must use the same EC_METHOD.
52
53EC_GROUP_dup creates a new EC_GROUP object and copies the content from B<src> to the newly created
54EC_GROUP object.
55
56EC_GROUP_method_of obtains the EC_METHOD of B<group>.
57
58EC_GROUP_set_generator sets curve paramaters that must be agreed by all participants using the curve. These
59paramaters include the B<generator>, the B<order> and the B<cofactor>. The B<generator> is a well defined point on the
60curve chosen for cryptographic operations. Integers used for point multiplications will be between 0 and
61n-1 where n is the B<order>. The B<order> multipied by the B<cofactor> gives the number of points on the curve.
62
63EC_GROUP_get0_generator returns the generator for the identified B<group>.
64
65The functions EC_GROUP_get_order and EC_GROUP_get_cofactor populate the provided B<order> and B<cofactor> parameters
66with the respective order and cofactors for the B<group>.
67
68The functions EC_GROUP_set_curve_name and EC_GROUP_get_curve_name, set and get the NID for the curve respectively
69(see L<EC_GROUP_new(3)|EC_GROUP_new(3)>). If a curve does not have a NID associated with it, then EC_GROUP_get_curve_name
70will return 0.
71
72The asn1_flag value on a curve is used to determine whether there is a specific ASN1 OID to describe the curve or not.
73If the asn1_flag is 1 then this is a named curve with an associated ASN1 OID. If not then asn1_flag is 0. The functions
74EC_GROUP_get_asn1_flag and EC_GROUP_set_asn1_flag get and set the status of the asn1_flag for the curve. If set then
75the curve_name must also be set.
76
77The point_conversion_form for a curve controls how EC_POINT data is encoded as ASN1 as defined in X9.62 (ECDSA).
78point_conversion_form_t is an enum defined as follows:
79
80 typedef enum {
81 /** the point is encoded as z||x, where the octet z specifies
82 * which solution of the quadratic equation y is */
83 POINT_CONVERSION_COMPRESSED = 2,
84 /** the point is encoded as z||x||y, where z is the octet 0x02 */
85 POINT_CONVERSION_UNCOMPRESSED = 4,
86 /** the point is encoded as z||x||y, where the octet z specifies
87 * which solution of the quadratic equation y is */
88 POINT_CONVERSION_HYBRID = 6
89 } point_conversion_form_t;
90
91
92For POINT_CONVERSION_UNCOMPRESSED the point is encoded as an octet signifying the UNCOMPRESSED form has been used followed by
93the octets for x, followed by the octets for y.
94
95For any given x co-ordinate for a point on a curve it is possible to derive two possible y values. For
96POINT_CONVERSION_COMPRESSED the point is encoded as an octet signifying that the COMPRESSED form has been used AND which of
97the two possible solutions for y has been used, followed by the octets for x.
98
99For POINT_CONVERSION_HYBRID the point is encoded as an octet signifying the HYBRID form has been used AND which of the two
100possible solutions for y has been used, followed by the octets for x, followed by the octets for y.
101
102The functions EC_GROUP_set_point_conversion_form and EC_GROUP_get_point_conversion_form set and get the point_conversion_form
103for the curve respectively.
104
105ANSI X9.62 (ECDSA standard) defines a method of generating the curve parameter b from a random number. This provides advantages
106in that a parameter obtained in this way is highly unlikely to be susceptible to special purpose attacks, or have any trapdoors in it.
107If the seed is present for a curve then the b parameter was generated in a verifiable fashion using that seed. The OpenSSL EC library
108does not use this seed value but does enable you to inspect it using EC_GROUP_get0_seed. This returns a pointer to a memory block
109containing the seed that was used. The length of the memory block can be obtained using EC_GROUP_get_seed_len. A number of the
110builtin curves within the library provide seed values that can be obtained. It is also possible to set a custom seed using
111EC_GROUP_set_seed and passing a pointer to a memory block, along with the length of the seed. Again, the EC library will not use
112this seed value, although it will be preserved in any ASN1 based communications.
113
114EC_GROUP_get_degree gets the degree of the field. For Fp fields this will be the number of bits in p. For F2^m fields this will be
115the value m.
116
117The function EC_GROUP_check_discriminant calculates the discriminant for the curve and verifies that it is valid.
118For a curve defined over Fp the discriminant is given by the formula 4*a^3 + 27*b^2 whilst for F2^m curves the discriminant is
119simply b. In either case for the curve to be valid the discriminant must be non zero.
120
121The function EC_GROUP_check performs a number of checks on a curve to verify that it is valid. Checks performed include
122verifying that the discriminant is non zero; that a generator has been defined; that the generator is on the curve and has
123the correct order.
124
125EC_GROUP_cmp compares B<a> and B<b> to determine whether they represent the same curve or not.
126
127The functions EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis should only be called for curves
128defined over an F2^m field. Addition and multiplication operations within an F2^m field are performed using an irreducible polynomial
129function f(x). This function is either a trinomial of the form:
130
131f(x) = x^m + x^k + 1 with m > k >= 1
132
133or a pentanomial of the form:
134
135f(x) = x^m + x^k3 + x^k2 + x^k1 + 1 with m > k3 > k2 > k1 >= 1
136
137The function EC_GROUP_get_basis_type returns a NID identifying whether a trinomial or pentanomial is in use for the field. The
138function EC_GROUP_get_trinomial_basis must only be called where f(x) is of the trinomial form, and returns the value of B<k>. Similarly
139the function EC_GROUP_get_pentanomial_basis must only be called where f(x) is of the pentanomial form, and returns the values of B<k1>,
140B<k2> and B<k3> respectively.
141
142=head1 RETURN VALUES
143
144The following functions return 1 on success or 0 on error: EC_GROUP_copy, EC_GROUP_set_generator, EC_GROUP_check,
145EC_GROUP_check_discriminant, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis.
146
147EC_GROUP_dup returns a pointer to the duplicated curve, or NULL on error.
148
149EC_GROUP_method_of returns the EC_METHOD implementation in use for the given curve or NULL on error.
150
151EC_GROUP_get0_generator returns the generator for the given curve or NULL on error.
152
153EC_GROUP_get_order, EC_GROUP_get_cofactor, EC_GROUP_get_curve_name, EC_GROUP_get_asn1_flag, EC_GROUP_get_point_conversion_form
154and EC_GROUP_get_degree return the order, cofactor, curve name (NID), ASN1 flag, point_conversion_form and degree for the
155specified curve respectively. If there is no curve name associated with a curve then EC_GROUP_get_curve_name will return 0.
156
157EC_GROUP_get0_seed returns a pointer to the seed that was used to generate the parameter b, or NULL if the seed is not
158specified. EC_GROUP_get_seed_len returns the length of the seed or 0 if the seed is not specified.
159
160EC_GROUP_set_seed returns the length of the seed that has been set. If the supplied seed is NULL, or the supplied seed length is
1610, the return value will be 1. On error 0 is returned.
162
163EC_GROUP_cmp returns 0 if the curves are equal, 1 if they are not equal, or -1 on error.
164
165EC_GROUP_get_basis_type returns the values NID_X9_62_tpBasis or NID_X9_62_ppBasis (as defined in <openssl/obj_mac.h>) for a
166trinomial or pentanomial respectively. Alternatively in the event of an error a 0 is returned.
167
168=head1 SEE ALSO
169
170L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>,
171L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>,
172L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>
173
174=cut
diff --git a/src/lib/libcrypto/doc/EC_GROUP_new.pod b/src/lib/libcrypto/doc/EC_GROUP_new.pod
deleted file mode 100644
index 9ab3566e65..0000000000
--- a/src/lib/libcrypto/doc/EC_GROUP_new.pod
+++ /dev/null
@@ -1,95 +0,0 @@
1=pod
2
3=head1 NAME
4
5EC_GROUP_new, EC_GROUP_free, EC_GROUP_clear_free, EC_GROUP_new_curve_GFp, EC_GROUP_new_curve_GF2m, EC_GROUP_new_by_curve_name, EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m, EC_get_builtin_curves - Functions for creating and destroying B<EC_GROUP> objects.
6
7=head1 SYNOPSIS
8
9 #include <openssl/ec.h>
10 #include <openssl/bn.h>
11
12 EC_GROUP *EC_GROUP_new(const EC_METHOD *meth);
13 void EC_GROUP_free(EC_GROUP *group);
14 void EC_GROUP_clear_free(EC_GROUP *group);
15
16 EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
17 EC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
18 EC_GROUP *EC_GROUP_new_by_curve_name(int nid);
19
20 int EC_GROUP_set_curve_GFp(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
21 int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
22 int EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
23 int EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
24
25 size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems);
26
27=head1 DESCRIPTION
28
29Within the library there are two forms of elliptic curve that are of interest. The first form is those defined over the
30prime field Fp. The elements of Fp are the integers 0 to p-1, where p is a prime number. This gives us a revised
31elliptic curve equation as follows:
32
33y^2 mod p = x^3 +ax + b mod p
34
35The second form is those defined over a binary field F2^m where the elements of the field are integers of length at
36most m bits. For this form the elliptic curve equation is modified to:
37
38y^2 + xy = x^3 + ax^2 + b (where b != 0)
39
40Operations in a binary field are performed relative to an B<irreducible polynomial>. All such curves with OpenSSL
41use a trinomial or a pentanomial for this parameter.
42
43A new curve can be constructed by calling EC_GROUP_new, using the implementation provided by B<meth> (see
44L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>). It is then necessary to call either EC_GROUP_set_curve_GFp or
45EC_GROUP_set_curve_GF2m as appropriate to create a curve defined over Fp or over F2^m respectively.
46
47EC_GROUP_set_curve_GFp sets the curve parameters B<p>, B<a> and B<b> for a curve over Fp stored in B<group>.
48EC_group_get_curve_GFp obtains the previously set curve parameters.
49
50EC_GROUP_set_curve_GF2m sets the equivalent curve parameters for a curve over F2^m. In this case B<p> represents
51the irreducible polynomial - each bit represents a term in the polynomial. Therefore there will either be three
52or five bits set dependent on whether the polynomial is a trinomial or a pentanomial.
53EC_group_get_curve_GF2m obtains the previously set curve parameters.
54
55The functions EC_GROUP_new_curve_GFp and EC_GROUP_new_curve_GF2m are shortcuts for calling EC_GROUP_new and the
56appropriate EC_group_set_curve function. An appropriate default implementation method will be used.
57
58Whilst the library can be used to create any curve using the functions described above, there are also a number of
59predefined curves that are available. In order to obtain a list of all of the predefined curves, call the function
60EC_get_builtin_curves. The parameter B<r> should be an array of EC_builtin_curve structures of size B<nitems>. The function
61will populate the B<r> array with information about the builtin curves. If B<nitems> is less than the total number of
62curves available, then the first B<nitems> curves will be returned. Otherwise the total number of curves will be
63provided. The return value is the total number of curves available (whether that number has been populated in B<r> or
64not). Passing a NULL B<r>, or setting B<nitems> to 0 will do nothing other than return the total number of curves available.
65The EC_builtin_curve structure is defined as follows:
66
67 typedef struct {
68 int nid;
69 const char *comment;
70 } EC_builtin_curve;
71
72Each EC_builtin_curve item has a unique integer id (B<nid>), and a human readable comment string describing the curve.
73
74In order to construct a builtin curve use the function EC_GROUP_new_by_curve_name and provide the B<nid> of the curve to
75be constructed.
76
77EC_GROUP_free frees the memory associated with the EC_GROUP.
78
79EC_GROUP_clear_free destroys any sensitive data held within the EC_GROUP and then frees its memory.
80
81=head1 RETURN VALUES
82
83All EC_GROUP_new* functions return a pointer to the newly constructed group, or NULL on error.
84
85EC_get_builtin_curves returns the number of builtin curves that are available.
86
87EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m return 1 on success or 0 on error.
88
89=head1 SEE ALSO
90
91L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>,
92L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>,
93L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>
94
95=cut
diff --git a/src/lib/libcrypto/doc/EC_KEY_new.pod b/src/lib/libcrypto/doc/EC_KEY_new.pod
deleted file mode 100644
index 02d7bac82c..0000000000
--- a/src/lib/libcrypto/doc/EC_KEY_new.pod
+++ /dev/null
@@ -1,115 +0,0 @@
1=pod
2
3=head1 NAME
4
5EC_KEY_new, EC_KEY_get_flags, EC_KEY_set_flags, EC_KEY_clear_flags, EC_KEY_new_by_curve_name, EC_KEY_free, EC_KEY_copy, EC_KEY_dup, EC_KEY_up_ref, EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key, EC_KEY_set_private_key, EC_KEY_get0_public_key, EC_KEY_set_public_key, EC_KEY_get_enc_flags, EC_KEY_set_enc_flags, EC_KEY_get_conv_form, EC_KEY_set_conv_form, EC_KEY_get_key_method_data, EC_KEY_insert_key_method_data, EC_KEY_set_asn1_flag, EC_KEY_precompute_mult, EC_KEY_generate_key, EC_KEY_check_key, EC_KEY_set_public_key_affine_coordinates - Functions for creating, destroying and manipulating B<EC_KEY> objects.
6
7=head1 SYNOPSIS
8
9 #include <openssl/ec.h>
10 #include <openssl/bn.h>
11
12 EC_KEY *EC_KEY_new(void);
13 int EC_KEY_get_flags(const EC_KEY *key);
14 void EC_KEY_set_flags(EC_KEY *key, int flags);
15 void EC_KEY_clear_flags(EC_KEY *key, int flags);
16 EC_KEY *EC_KEY_new_by_curve_name(int nid);
17 void EC_KEY_free(EC_KEY *key);
18 EC_KEY *EC_KEY_copy(EC_KEY *dst, const EC_KEY *src);
19 EC_KEY *EC_KEY_dup(const EC_KEY *src);
20 int EC_KEY_up_ref(EC_KEY *key);
21 const EC_GROUP *EC_KEY_get0_group(const EC_KEY *key);
22 int EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group);
23 const BIGNUM *EC_KEY_get0_private_key(const EC_KEY *key);
24 int EC_KEY_set_private_key(EC_KEY *key, const BIGNUM *prv);
25 const EC_POINT *EC_KEY_get0_public_key(const EC_KEY *key);
26 int EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub);
27 unsigned int EC_KEY_get_enc_flags(const EC_KEY *key);
28 void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags);
29 point_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key);
30 void EC_KEY_set_conv_form(EC_KEY *eckey, point_conversion_form_t cform);
31 void *EC_KEY_get_key_method_data(EC_KEY *key,
32 void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *));
33 void EC_KEY_insert_key_method_data(EC_KEY *key, void *data,
34 void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *));
35 void EC_KEY_set_asn1_flag(EC_KEY *eckey, int asn1_flag);
36 int EC_KEY_precompute_mult(EC_KEY *key, BN_CTX *ctx);
37 int EC_KEY_generate_key(EC_KEY *key);
38 int EC_KEY_check_key(const EC_KEY *key);
39 int EC_KEY_set_public_key_affine_coordinates(EC_KEY *key, BIGNUM *x, BIGNUM *y);
40
41=head1 DESCRIPTION
42
43An EC_KEY represents a public key and (optionally) an associated private key. A new EC_KEY (with no associated curve) can be constructed by calling EC_KEY_new.
44The reference count for the newly created EC_KEY is initially set to 1. A curve can be associated with the EC_KEY by calling
45EC_KEY_set_group.
46
47Alternatively a new EC_KEY can be constructed by calling EC_KEY_new_by_curve_name and supplying the nid of the associated curve. Refer to L<EC_GROUP_new(3)|EC_GROUP_new(3)> for a description of curve names. This function simply wraps calls to EC_KEY_new and
48EC_GROUP_new_by_curve_name.
49
50Calling EC_KEY_free decrements the reference count for the EC_KEY object, and if it has dropped to zero then frees the memory associated
51with it.
52
53EC_KEY_copy copies the contents of the EC_KEY in B<src> into B<dest>.
54
55EC_KEY_dup creates a new EC_KEY object and copies B<ec_key> into it.
56
57EC_KEY_up_ref increments the reference count associated with the EC_KEY object.
58
59EC_KEY_generate_key generates a new public and private key for the supplied B<eckey> object. B<eckey> must have an EC_GROUP object
60associated with it before calling this function. The private key is a random integer (0 < priv_key < order, where order is the order
61of the EC_GROUP object). The public key is an EC_POINT on the curve calculated by multiplying the generator for the curve by the
62private key.
63
64EC_KEY_check_key performs various sanity checks on the EC_KEY object to confirm that it is valid.
65
66EC_KEY_set_public_key_affine_coordinates sets the public key for B<key> based on its affine co-ordinates, i.e. it constructs an EC_POINT
67object based on the supplied B<x> and B<y> values and sets the public key to be this EC_POINT. It will also performs certain sanity checks
68on the key to confirm that it is valid.
69
70The functions EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key, EC_KEY_set_private_key, EC_KEY_get0_public_key, and EC_KEY_set_public_key get and set the EC_GROUP object, the private key and the EC_POINT public key for the B<key> respectively.
71
72The functions EC_KEY_get_enc_flags and EC_KEY_set_enc_flags get and set the value of the encoding flags for the B<key>. There are two encoding
73flags currently defined - EC_PKEY_NO_PARAMETERS and EC_PKEY_NO_PUBKEY. These flags define the behaviour of how the B<key> is
74converted into ASN1 in a call to i2d_ECPrivateKey. If EC_PKEY_NO_PARAMETERS is set then the public parameters for the curve are not encoded
75along with the private key. If EC_PKEY_NO_PUBKEY is set then the public key is not encoded along with the private key.
76
77The functions EC_KEY_get_conv_form and EC_KEY_set_conv_form get and set the point_conversion_form for the B<key>. For a description
78of point_conversion_forms please refer to L<EC_POINT_new(3)|EC_POINT_new(3)>.
79
80EC_KEY_insert_key_method_data and EC_KEY_get_key_method_data enable the caller to associate arbitrary additional data specific to the
81elliptic curve scheme being used with the EC_KEY object. This data is treated as a "black box" by the ec library. The data to be stored by EC_KEY_insert_key_method_data is provided in the B<data> parameter, which must have associated functions for duplicating, freeing and "clear_freeing" the data item. If a subsequent EC_KEY_get_key_method_data call is issued, the functions for duplicating, freeing and "clear_freeing" the data item must be provided again, and they must be the same as they were when the data item was inserted.
82
83EC_KEY_set_flags sets the flags in the B<flags> parameter on the EC_KEY object. Any flags that are already set are left set. The currently defined standard flags are EC_FLAG_NON_FIPS_ALLOW and EC_FLAG_FIPS_CHECKED. In addition there is the flag EC_FLAG_COFACTOR_ECDH which is specific to ECDH and is defined in ecdh.h. EC_KEY_get_flags returns the current flags that are set for this EC_KEY. EC_KEY_clear_flags clears the flags indicated by the B<flags> parameter. All other flags are left in their existing state.
84
85EC_KEY_set_asn1_flag sets the asn1_flag on the underlying EC_GROUP object (if set). Refer to L<EC_GROUP_copy(3)|EC_GROUP_copy(3)> for further information on the asn1_flag.
86
87EC_KEY_precompute_mult stores multiples of the underlying EC_GROUP generator for faster point multiplication. See also L<EC_POINT_add(3)|EC_POINT_add(3)>.
88
89
90=head1 RETURN VALUES
91
92EC_KEY_new, EC_KEY_new_by_curve_name and EC_KEY_dup return a pointer to the newly created EC_KEY object, or NULL on error.
93
94EC_KEY_get_flags returns the flags associated with the EC_KEY object as an integer.
95
96EC_KEY_copy returns a pointer to the destination key, or NULL on error.
97
98EC_KEY_up_ref, EC_KEY_set_group, EC_KEY_set_private_key, EC_KEY_set_public_key, EC_KEY_precompute_mult, EC_KEY_generate_key, EC_KEY_check_key and EC_KEY_set_public_key_affine_coordinates return 1 on success or 0 on error.
99
100EC_KEY_get0_group returns the EC_GROUP associated with the EC_KEY.
101
102EC_KEY_get0_private_key returns the private key associated with the EC_KEY.
103
104EC_KEY_get_enc_flags returns the value of the current encoding flags for the EC_KEY.
105
106EC_KEY_get_conv_form return the point_conversion_form for the EC_KEY.
107
108
109=head1 SEE ALSO
110
111L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>,
112L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>,
113L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>
114
115=cut
diff --git a/src/lib/libcrypto/doc/EC_POINT_add.pod b/src/lib/libcrypto/doc/EC_POINT_add.pod
deleted file mode 100644
index ae92640843..0000000000
--- a/src/lib/libcrypto/doc/EC_POINT_add.pod
+++ /dev/null
@@ -1,72 +0,0 @@
1=pod
2
3=head1 NAME
4
5EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_is_at_infinity, EC_POINT_is_on_curve, EC_POINT_cmp, EC_POINT_make_affine, EC_POINTs_make_affine, EC_POINTs_mul, EC_POINT_mul, EC_GROUP_precompute_mult, EC_GROUP_have_precompute_mult - Functions for performing mathematical operations and tests on B<EC_POINT> objects.
6
7=head1 SYNOPSIS
8
9 #include <openssl/ec.h>
10 #include <openssl/bn.h>
11
12 int EC_POINT_add(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx);
13 int EC_POINT_dbl(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, BN_CTX *ctx);
14 int EC_POINT_invert(const EC_GROUP *group, EC_POINT *a, BN_CTX *ctx);
15 int EC_POINT_is_at_infinity(const EC_GROUP *group, const EC_POINT *p);
16 int EC_POINT_is_on_curve(const EC_GROUP *group, const EC_POINT *point, BN_CTX *ctx);
17 int EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx);
18 int EC_POINT_make_affine(const EC_GROUP *group, EC_POINT *point, BN_CTX *ctx);
19 int EC_POINTs_make_affine(const EC_GROUP *group, size_t num, EC_POINT *points[], BN_CTX *ctx);
20 int EC_POINTs_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, size_t num, const EC_POINT *p[], const BIGNUM *m[], BN_CTX *ctx);
21 int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, const EC_POINT *q, const BIGNUM *m, BN_CTX *ctx);
22 int EC_GROUP_precompute_mult(EC_GROUP *group, BN_CTX *ctx);
23 int EC_GROUP_have_precompute_mult(const EC_GROUP *group);
24
25
26=head1 DESCRIPTION
27
28EC_POINT_add adds the two points B<a> and B<b> and places the result in B<r>. Similarly EC_POINT_dbl doubles the point B<a> and places the
29result in B<r>. In both cases it is valid for B<r> to be one of B<a> or B<b>.
30
31EC_POINT_invert calculates the inverse of the supplied point B<a>. The result is placed back in B<a>.
32
33The function EC_POINT_is_at_infinity tests whether the supplied point is at infinity or not.
34
35EC_POINT_is_on_curve tests whether the supplied point is on the curve or not.
36
37EC_POINT_cmp compares the two supplied points and tests whether or not they are equal.
38
39The functions EC_POINT_make_affine and EC_POINTs_make_affine force the internal representation of the EC_POINT(s) into the affine
40co-ordinate system. In the case of EC_POINTs_make_affine the value B<num> provides the number of points in the array B<points> to be
41forced.
42
43EC_POINT_mul calculates the value generator * B<n> + B<q> * B<m> and stores the result in B<r>. The value B<n> may be NULL in which case the result is just B<q> * B<m>.
44
45EC_POINTs_mul calculates the value generator * B<n> + B<q[0]> * B<m[0]> + ... + B<q[num-1]> * B<m[num-1]>. As for EC_POINT_mul the value
46B<n> may be NULL.
47
48The function EC_GROUP_precompute_mult stores multiples of the generator for faster point multiplication, whilst
49EC_GROUP_have_precompute_mult tests whether precomputation has already been done. See L<EC_GROUP_copy(3)|EC_GROUP_copy(3)> for information
50about the generator.
51
52
53=head1 RETURN VALUES
54
55The following functions return 1 on success or 0 on error: EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_make_affine,
56EC_POINTs_make_affine, EC_POINTs_make_affine, EC_POINT_mul, EC_POINTs_mul and EC_GROUP_precompute_mult.
57
58EC_POINT_is_at_infinity returns 1 if the point is at infinity, or 0 otherwise.
59
60EC_POINT_is_on_curve returns 1 if the point is on the curve, 0 if not, or -1 on error.
61
62EC_POINT_cmp returns 1 if the points are not equal, 0 if they are, or -1 on error.
63
64EC_GROUP_have_precompute_mult return 1 if a precomputation has been done, or 0 if not.
65
66=head1 SEE ALSO
67
68L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>,
69L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>,
70L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>
71
72=cut
diff --git a/src/lib/libcrypto/doc/EC_POINT_new.pod b/src/lib/libcrypto/doc/EC_POINT_new.pod
deleted file mode 100644
index b41ca0ed0c..0000000000
--- a/src/lib/libcrypto/doc/EC_POINT_new.pod
+++ /dev/null
@@ -1,123 +0,0 @@
1=pod
2
3=head1 NAME
4
5EC_POINT_new, EC_POINT_free, EC_POINT_clear_free, EC_POINT_copy, EC_POINT_dup, EC_POINT_method_of, EC_POINT_set_to_infinity, EC_POINT_set_Jprojective_coordinates, EC_POINT_get_Jprojective_coordinates_GFp, EC_POINT_set_affine_coordinates_GFp, EC_POINT_get_affine_coordinates_GFp, EC_POINT_set_compressed_coordinates_GFp, EC_POINT_set_affine_coordinates_GF2m, EC_POINT_get_affine_coordinates_GF2m, EC_POINT_set_compressed_coordinates_GF2m, EC_POINT_point2oct, EC_POINT_oct2point, EC_POINT_point2bn, EC_POINT_bn2point, EC_POINT_point2hex, EC_POINT_hex2point - Functions for creating, destroying and manipulating B<EC_POINT> objects.
6
7=head1 SYNOPSIS
8
9 #include <openssl/ec.h>
10 #include <openssl/bn.h>
11
12 EC_POINT *EC_POINT_new(const EC_GROUP *group);
13 void EC_POINT_free(EC_POINT *point);
14 void EC_POINT_clear_free(EC_POINT *point);
15 int EC_POINT_copy(EC_POINT *dst, const EC_POINT *src);
16 EC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group);
17 const EC_METHOD *EC_POINT_method_of(const EC_POINT *point);
18 int EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point);
19 int EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group, EC_POINT *p,
20 const BIGNUM *x, const BIGNUM *y, const BIGNUM *z, BN_CTX *ctx);
21 int EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group,
22 const EC_POINT *p, BIGNUM *x, BIGNUM *y, BIGNUM *z, BN_CTX *ctx);
23 int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p,
24 const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx);
25 int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group,
26 const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx);
27 int EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group, EC_POINT *p,
28 const BIGNUM *x, int y_bit, BN_CTX *ctx);
29 int EC_POINT_set_affine_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p,
30 const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx);
31 int EC_POINT_get_affine_coordinates_GF2m(const EC_GROUP *group,
32 const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx);
33 int EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p,
34 const BIGNUM *x, int y_bit, BN_CTX *ctx);
35 size_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p,
36 point_conversion_form_t form,
37 unsigned char *buf, size_t len, BN_CTX *ctx);
38 int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p,
39 const unsigned char *buf, size_t len, BN_CTX *ctx);
40 BIGNUM *EC_POINT_point2bn(const EC_GROUP *, const EC_POINT *,
41 point_conversion_form_t form, BIGNUM *, BN_CTX *);
42 EC_POINT *EC_POINT_bn2point(const EC_GROUP *, const BIGNUM *,
43 EC_POINT *, BN_CTX *);
44 char *EC_POINT_point2hex(const EC_GROUP *, const EC_POINT *,
45 point_conversion_form_t form, BN_CTX *);
46 EC_POINT *EC_POINT_hex2point(const EC_GROUP *, const char *,
47 EC_POINT *, BN_CTX *);
48
49
50=head1 DESCRIPTION
51
52An EC_POINT represents a point on a curve. A new point is constructed by calling the function EC_POINT_new and providing the B<group>
53object that the point relates to.
54
55EC_POINT_free frees the memory associated with the EC_POINT.
56
57EC_POINT_clear_free destroys any sensitive data held within the EC_POINT and then frees its memory.
58
59EC_POINT_copy copies the point B<src> into B<dst>. Both B<src> and B<dst> must use the same EC_METHOD.
60
61EC_POINT_dup creates a new EC_POINT object and copies the content from B<src> to the newly created
62EC_POINT object.
63
64EC_POINT_method_of obtains the EC_METHOD associated with B<point>.
65
66A valid point on a curve is the special point at infinity. A point is set to be at infinity by calling EC_POINT_set_to_infinity.
67
68The affine co-ordinates for a point describe a point in terms of its x and y position. The functions
69EC_POINT_set_affine_coordinates_GFp and EC_POINT_set_affine_coordinates_GF2m set the B<x> and B<y> co-ordinates for the point
70B<p> defined over the curve given in B<group>.
71
72As well as the affine co-ordinates, a point can alternatively be described in terms of its Jacobian
73projective co-ordinates (for Fp curves only). Jacobian projective co-ordinates are expressed as three values x, y and z. Working in
74this co-ordinate system provides more efficient point multiplication operations.
75A mapping exists between Jacobian projective co-ordinates and affine co-ordinates. A Jacobian projective co-ordinate (x, y, z) can be written as an affine co-ordinate as (x/(z^2), y/(z^3)). Conversion to Jacobian projective to affine co-ordinates is simple. The co-ordinate (x, y) is
76mapped to (x, y, 1). To set or get the projective co-ordinates use EC_POINT_set_Jprojective_coordinates_GFp and
77EC_POINT_get_Jprojective_coordinates_GFp respectively.
78
79Points can also be described in terms of their compressed co-ordinates. For a point (x, y), for any given value for x such that the point is
80on the curve there will only ever be two possible values for y. Therefore a point can be set using the EC_POINT_set_compressed_coordinates_GFp
81and EC_POINT_set_compressed_coordinates_GF2m functions where B<x> is the x co-ordinate and B<y_bit> is a value 0 or 1 to identify which of
82the two possible values for y should be used.
83
84In addition EC_POINTs can be converted to and from various external representations. Supported representations are octet strings, BIGNUMs and hexadecimal. The format of the external representation is described by the point_conversion_form. See L<EC_GROUP_copy(3)|EC_GROUP_copy(3)> for
85a description of point_conversion_form. Octet strings are stored in a buffer along with an associated buffer length. A point held in a BIGNUM is calculated by converting the point to an octet string and then converting that octet string into a BIGNUM integer. Points in hexadecimal format are stored in a NULL terminated character string where each character is one of the printable values 0-9 or A-F (or a-f).
86
87The functions EC_POINT_point2oct, EC_POINT_oct2point, EC_POINT_point2bn, EC_POINT_bn2point, EC_POINT_point2hex and EC_POINT_hex2point convert
88from and to EC_POINTs for the formats: octet string, BIGNUM and hexadecimal respectively.
89
90The function EC_POINT_point2oct must be supplied with a buffer long enough to store the octet string. The return value provides the number of
91octets stored. Calling the function with a NULL buffer will not perform the conversion but will still return the required buffer length.
92
93The function EC_POINT_point2hex will allocate sufficient memory to store the hexadecimal string. It is the caller's responsibility to free
94this memory with a subsequent call to free().
95
96=head1 RETURN VALUES
97
98EC_POINT_new and EC_POINT_dup return the newly allocated EC_POINT or NULL on error.
99
100The following functions return 1 on success or 0 on error: EC_POINT_copy, EC_POINT_set_to_infinity, EC_POINT_set_Jprojective_coordinates_GFp,
101EC_POINT_get_Jprojective_coordinates_GFp, EC_POINT_set_affine_coordinates_GFp, EC_POINT_get_affine_coordinates_GFp,
102EC_POINT_set_compressed_coordinates_GFp, EC_POINT_set_affine_coordinates_GF2m, EC_POINT_get_affine_coordinates_GF2m,
103EC_POINT_set_compressed_coordinates_GF2m and EC_POINT_oct2point.
104
105EC_POINT_method_of returns the EC_METHOD associated with the supplied EC_POINT.
106
107EC_POINT_point2oct returns the length of the required buffer, or 0 on error.
108
109EC_POINT_point2bn returns the pointer to the BIGNUM supplied, or NULL on error.
110
111EC_POINT_bn2point returns the pointer to the EC_POINT supplied, or NULL on error.
112
113EC_POINT_point2hex returns a pointer to the hex string, or NULL on error.
114
115EC_POINT_hex2point returns the pointer to the EC_POINT supplied, or NULL on error.
116
117=head1 SEE ALSO
118
119L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>,
120L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>,
121L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>
122
123=cut
diff --git a/src/lib/libcrypto/man/DSA_SIG_new.3 b/src/lib/libcrypto/man/DSA_SIG_new.3
new file mode 100644
index 0000000000..32d21fb782
--- /dev/null
+++ b/src/lib/libcrypto/man/DSA_SIG_new.3
@@ -0,0 +1,43 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt DSA_SIG_NEW 3
3.Os
4.Sh NAME
5.Nm DSA_SIG_new ,
6.Nm DSA_SIG_free
7.Nd allocate and free DSA signature objects
8.Sh SYNOPSIS
9.In openssl/dsa.h
10.Ft DSA_SIG *
11.Fn DSA_SIG_new void
12.Ft void
13.Fo DSA_SIG_free
14.Fa "DSA_SIG *a"
15.Fc
16.Sh DESCRIPTION
17.Fn DSA_SIG_new
18allocates and initializes a
19.Vt DSA_SIG
20structure.
21.Pp
22.Fn DSA_SIG_free
23frees the
24.Vt DSA_SIG
25structure and its components.
26The values are erased before the memory is returned to the system.
27.Sh RETURN VALUES
28If the allocation fails,
29.Fn DSA_SIG_new
30returns
31.Dv NULL
32and sets an error code that can be obtained by
33.Xr ERR_get_error 3 .
34Otherwise it returns a pointer to the newly allocated structure.
35.Sh SEE ALSO
36.Xr dsa 3 ,
37.Xr DSA_do_sign 3 ,
38.Xr ERR_get_error 3
39.Sh HISTORY
40.Fn DSA_SIG_new
41and
42.Fn DSA_SIG_free
43were added in OpenSSL 0.9.3.
diff --git a/src/lib/libcrypto/man/DSA_do_sign.3 b/src/lib/libcrypto/man/DSA_do_sign.3
new file mode 100644
index 0000000000..c61ff925bb
--- /dev/null
+++ b/src/lib/libcrypto/man/DSA_do_sign.3
@@ -0,0 +1,68 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt DSA_DO_SIGN 3
3.Os
4.Sh NAME
5.Nm DSA_do_sign ,
6.Nm DSA_do_verify
7.Nd raw DSA signature operations
8.Sh SYNOPSIS
9.In openssl/dsa.h
10.Ft DSA_SIG *
11.Fo DSA_do_sign
12.Fa "const unsigned char *dgst"
13.Fa "int dlen"
14.Fa "DSA *dsa"
15.Fc
16.Ft int
17.Fo DSA_do_verify
18.Fa "const unsigned char *dgst"
19.Fa "int dgst_len"
20.Fa "DSA_SIG *sig"
21.Fa "DSA *dsa"
22.Fc
23.Sh DESCRIPTION
24.Fn DSA_do_sign
25computes a digital signature on the
26.Fa dlen
27byte message digest
28.Fa dgst
29using the private key
30.Fa dsa
31and returns it in a newly allocated
32.Vt DSA_SIG
33structure.
34.Pp
35.Xr DSA_sign_setup 3
36may be used to precompute part of the signing operation in case
37signature generation is time-critical.
38.Pp
39.Fn DSA_do_verify
40verifies that the signature
41.Fa sig
42matches a given message digest
43.Fa dgst
44of size
45.Fa dgst_len .
46.Fa dsa
47is the signer's public key.
48.Sh RETURN VALUES
49.Fn DSA_do_sign
50returns the signature or
51.Dv NULL
52on error.
53.Fn DSA_do_verify
54returns 1 for a valid signature, 0 for an incorrect signature,
55and -1 on error.
56The error codes can be obtained by
57.Xr ERR_get_error 3 .
58.Sh SEE ALSO
59.Xr dsa 3 ,
60.Xr DSA_SIG_new 3 ,
61.Xr DSA_sign 3 ,
62.Xr ERR_get_error 3 ,
63.Xr rand 3
64.Sh HISTORY
65.Fn DSA_do_sign
66and
67.Fn DSA_do_verify
68were added in OpenSSL 0.9.3.
diff --git a/src/lib/libcrypto/man/DSA_dup_DH.3 b/src/lib/libcrypto/man/DSA_dup_DH.3
new file mode 100644
index 0000000000..c8b7ec60ab
--- /dev/null
+++ b/src/lib/libcrypto/man/DSA_dup_DH.3
@@ -0,0 +1,41 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt DSA_DUP_DH 3
3.Os
4.Sh NAME
5.Nm DSA_dup_DH
6.Nd create a DH structure out of DSA structure
7.Sh SYNOPSIS
8.In openssl/dsa.h
9.Ft DH *
10.Fo DSA_dup_DH
11.Fa "const DSA *r"
12.Fc
13.Sh DESCRIPTION
14.Fn DSA_dup_DH
15duplicates
16.Vt DSA
17parameters/keys as
18.Vt DH
19parameters/keys.
20.Fa r->q
21is lost during that conversion, but the resulting
22.Vt DH
23parameters contain its length.
24.Sh RETURN VALUE
25.Fn DSA_dup_DH
26returns the new
27.Vt DH
28structure or
29.Dv NULL
30on error.
31The error codes can be obtained by
32.Xr ERR_get_error 3 .
33.Sh SEE ALSO
34.Xr dh 3 ,
35.Xr dsa 3 ,
36.Xr ERR_get_error 3
37.Sh HISTORY
38.Fn DSA_dup_DH
39was added in OpenSSL 0.9.4.
40.Sh CAVEATS
41Be careful to avoid small subgroup attacks when using this.
diff --git a/src/lib/libcrypto/man/DSA_generate_key.3 b/src/lib/libcrypto/man/DSA_generate_key.3
new file mode 100644
index 0000000000..cf0872463f
--- /dev/null
+++ b/src/lib/libcrypto/man/DSA_generate_key.3
@@ -0,0 +1,34 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt DSA_GENERATE_KEY 3
3.Os
4.Sh NAME
5.Nm DSA_generate_key
6.Nd generate DSA key pair
7.Sh SYNOPSIS
8.In openssl/dsa.h
9.Ft int
10.Fo DSA_generate_key
11.Fa "DSA *a"
12.Fc
13.Sh DESCRIPTION
14.Fn DSA_generate_key
15expects
16.Fa a
17to contain DSA parameters.
18It generates a new key pair and stores it in
19.Fa a->pub_key
20and
21.Fa a->priv_key .
22.Sh RETURN VALUE
23.Fn DSA_generate_key
24returns 1 on success or 0 otherwise.
25The error codes can be obtained by
26.Xr ERR_get_error 3 .
27.Sh SEE ALSO
28.Xr dsa 3 ,
29.Xr DSA_generate_parameters 3 ,
30.Xr ERR_get_error 3 ,
31.Xr rand 3
32.Sh HISTORY
33.Fn DSA_generate_key
34is available since SSLeay 0.8.
diff --git a/src/lib/libcrypto/man/DSA_generate_parameters.3 b/src/lib/libcrypto/man/DSA_generate_parameters.3
new file mode 100644
index 0000000000..1acb85e77a
--- /dev/null
+++ b/src/lib/libcrypto/man/DSA_generate_parameters.3
@@ -0,0 +1,171 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt DSA_GENERATE_PARAMETERS 3
3.Os
4.Sh NAME
5.Nm DSA_generate_parameters_ex ,
6.Nm DSA_generate_parameters
7.Nd generate DSA parameters
8.Sh SYNOPSIS
9.In openssl/dsa.h
10.Ft int
11.Fo DSA_generate_parameters_ex
12.Fa "DSA *dsa"
13.Fa "int bits"
14.Fa "const unsigned char *seed"
15.Fa "int seed_len"
16.Fa "int *counter_ret"
17.Fa "unsigned long *h_ret"
18.Fa "BN_GENCB *cb"
19.Fc
20.Pp
21Deprecated:
22.Pp
23.Ft DSA *
24.Fo DSA_generate_parameters
25.Fa "int bits"
26.Fa "unsigned char *seed"
27.Fa "int seed_len"
28.Fa "int *counter_ret"
29.Fa "unsigned long *h_ret"
30.Fa "void (*callback)(int, int, void *)"
31.Fa "void *cb_arg"
32.Fc
33.Sh DESCRIPTION
34.Fn DSA_generate_parameters_ex
35generates primes p and q and a generator g for use in the DSA and stores
36the result in
37.Fa dsa .
38.Pp
39.Fa bits
40is the length of the prime to be generated; the DSS allows a maximum of
411024 bits.
42.Pp
43If
44.Fa seed
45is
46.Dv NULL
47or
48.Fa seed_len
49< 20, the primes will be generated at random.
50Otherwise, the seed is used to generate them.
51If the given seed does not yield a prime q, a new random seed is chosen
52and placed at
53.Fa seed .
54.Pp
55.Fn DSA_generate_parameters_ex
56places the iteration count in
57.Pf * Fa counter_ret
58and a counter used for finding a generator in
59.Pf * Fa h_ret ,
60unless these are
61.Dv NULL .
62.Pp
63A callback function may be used to provide feedback about the progress
64of the key generation.
65If
66.Fa cb
67is not
68.Dv NULL ,
69it will be called as shown below.
70For information on the
71.Vt BN_GENCB
72structure, refer to
73.Xr BN_GENCB_call 3 .
74.Bl -bullet
75.It
76When a candidate for q is generated,
77.Fn BN_GENCB_call cb 0 m++
78is called
79.Pf ( Fa m
80is 0 for the first candidate).
81.It
82When a candidate for q has passed a test by trial division,
83.Fn BN_GENCB_call cb 1 -1
84is called.
85While a candidate for q is tested by Miller-Rabin primality tests,
86.Fn BN_GENCB_call cb 1 i
87is called in the outer loop (once for each witness that confirms that
88the candidate may be prime);
89.Fa i
90is the loop counter (starting at 0).
91.It
92When a prime q has been found,
93.Fn BN_GENCB_call cb 2 0
94and
95.Fn BN_GENCB_call cb 3 0
96are called.
97.It
98Before a candidate for p (other than the first) is generated and tested,
99.Fn BN_GENCB_call cb 0 counter
100is called.
101.It
102When a candidate for p has passed the test by trial division,
103.Fn BN_GENCB_call cb 1 -1
104is called.
105While it is tested by the Miller-Rabin primality test,
106.Fn BN_GENCB_call cb 1 i
107is called in the outer loop (once for each witness that confirms that
108the candidate may be prime).
109.Fa i
110is the loop counter (starting at 0).
111.It
112When p has been found,
113.Fn BN_GENCB_call cb 2 1
114is called.
115.It
116When the generator has been found,
117.Fn BN_GENCB_call cb 3 1
118is called.
119.El
120.Pp
121.Fn DSA_generate_parameters
122(deprecated) works in much the same way as for
123.Fn DSA_generate_parameters_ex ,
124except that no
125.Fa dsa
126parameter is passed and instead a newly allocated
127.Vt DSA
128structure is returned.
129Additionally "old style" callbacks are used instead of the newer
130.Vt BN_GENCB
131based approach.
132Refer to
133.Xr BN_generate_prime 3
134for further information.
135.Sh RETURN VALUE
136.Fn DSA_generate_parameters_ex
137returns a 1 on success, or 0 otherwise.
138.Pp
139.Fn DSA_generate_parameters
140returns a pointer to the
141.Vt DSA
142structure, or
143.Dv NULL
144if the parameter generation fails.
145.Pp
146The error codes can be obtained by
147.Xr ERR_get_error 3 .
148.Sh SEE ALSO
149.Xr BN_generate_prime 3 ,
150.Xr dsa 3 ,
151.Xr DSA_free 3 ,
152.Xr ERR_get_error 3 ,
153.Xr rand 3
154.Sh HISTORY
155.Fn DSA_generate_parameters
156appeared in SSLeay 0.8.
157The
158.Fa cb_arg
159argument was added in SSLeay 0.9.0.
160In versions up to OpenSSL 0.9.4,
161.Fn callback 1 ...\&
162was called in the inner loop of the Miller-Rabin test whenever it
163reached the squaring step (the parameters to
164.Fn callback
165did not reveal how many witnesses had been tested); since OpenSSL 0.9.5,
166.Fn callback 1 ...\&
167is called as in
168.Xr BN_is_prime 3 ,
169i.e. once for each witness.
170.Sh BUGS
171Seed lengths > 20 are not supported.
diff --git a/src/lib/libcrypto/man/DSA_get_ex_new_index.3 b/src/lib/libcrypto/man/DSA_get_ex_new_index.3
new file mode 100644
index 0000000000..da2a6ae7aa
--- /dev/null
+++ b/src/lib/libcrypto/man/DSA_get_ex_new_index.3
@@ -0,0 +1,47 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt DSA_GET_EX_NEW_INDEX 3
3.Os
4.Sh NAME
5.Nm DSA_get_ex_new_index ,
6.Nm DSA_set_ex_data ,
7.Nm DSA_get_ex_data
8.Nd add application specific data to DSA structures
9.Sh SYNOPSIS
10.In openssl/dsa.h
11.Ft int
12.Fo DSA_get_ex_new_index
13.Fa "long argl"
14.Fa "void *argp"
15.Fa "CRYPTO_EX_new *new_func"
16.Fa "CRYPTO_EX_dup *dup_func"
17.Fa "CRYPTO_EX_free *free_func"
18.Fc
19.Ft int
20.Fo DSA_set_ex_data
21.Fa "DSA *d"
22.Fa "int idx"
23.Fa "void *arg"
24.Fc
25.Ft char *
26.Fo DSA_get_ex_data
27.Fa "DSA *d"
28.Fa "int idx"
29.Fc
30.Sh DESCRIPTION
31These functions handle application specific data in
32.Vt DSA
33structures.
34Their usage is identical to that of
35.Xr RSA_get_ex_new_index 3 ,
36.Xr RSA_set_ex_data 3 ,
37and
38.Xr RSA_get_ex_data 3 .
39.Sh SEE ALSO
40.Xr dsa 3 ,
41.Xr RSA_get_ex_new_index 3
42.Sh HISTORY
43.Fn DSA_get_ex_new_index ,
44.Fn DSA_set_ex_data ,
45and
46.Fn DSA_get_ex_data
47are available since OpenSSL 0.9.5.
diff --git a/src/lib/libcrypto/man/DSA_new.3 b/src/lib/libcrypto/man/DSA_new.3
new file mode 100644
index 0000000000..0e8e87deed
--- /dev/null
+++ b/src/lib/libcrypto/man/DSA_new.3
@@ -0,0 +1,46 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt DSA_NEW 3
3.Os
4.Sh NAME
5.Nm DSA_new ,
6.Nm DSA_free
7.Nd allocate and free DSA objects
8.Sh SYNOPSIS
9.In openssl/dsa.h
10.Ft DSA*
11.Fn DSA_new void
12.Ft void
13.Fo DSA_free
14.Fa "DSA *dsa"
15.Fc
16.Sh DESCRIPTION
17.Fn DSA_new
18allocates and initializes a
19.Vt DSA
20structure.
21It is equivalent to calling
22.Fn DSA_new_method NULL .
23.Pp
24.Fn DSA_free
25frees the
26.Vt DSA
27structure and its components.
28The values are erased before the memory is returned to the system.
29.Sh RETURN VALUES
30If the allocation fails,
31.Fn DSA_new
32returns
33.Dv NULL
34and sets an error code that can be obtained by
35.Xr ERR_get_error 3 .
36Otherwise it returns a pointer to the newly allocated structure.
37.Sh SEE ALSO
38.Xr dsa 3 ,
39.Xr DSA_generate_key 3 ,
40.Xr DSA_generate_parameters 3 ,
41.Xr ERR_get_error 3
42.Sh HISTORY
43.Fn DSA_new
44and
45.Fn DSA_free
46are available in all versions of SSLeay and OpenSSL.
diff --git a/src/lib/libcrypto/man/DSA_set_method.3 b/src/lib/libcrypto/man/DSA_set_method.3
new file mode 100644
index 0000000000..2ba34ddf94
--- /dev/null
+++ b/src/lib/libcrypto/man/DSA_set_method.3
@@ -0,0 +1,224 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt DSA_SET_METHOD 3
3.Os
4.Sh NAME
5.Nm DSA_set_default_method ,
6.Nm DSA_get_default_method ,
7.Nm DSA_set_method ,
8.Nm DSA_new_method ,
9.Nm DSA_OpenSSL ,
10.Nm DSA_set_default_openssl_method ,
11.Nm DSA_get_default_openssl_method
12.Nd select DSA method
13.Sh SYNOPSIS
14.In openssl/dsa.h
15.In openssl/engine.h
16.Ft void
17.Fo DSA_set_default_method
18.Fa "const DSA_METHOD *meth"
19.Fc
20.Ft const DSA_METHOD *
21.Fn DSA_get_default_method void
22.Ft int
23.Fo DSA_set_method
24.Fa "DSA *dsa"
25.Fa "const DSA_METHOD *meth"
26.Fc
27.Ft DSA *
28.Fo DSA_new_method
29.Fa "ENGINE *engine"
30.Fc
31.Ft DSA_METHOD *
32.Fn DSA_OpenSSL void
33.Sh DESCRIPTION
34A
35.Vt DSA_METHOD
36specifies the functions that OpenSSL uses for DSA operations.
37By modifying the method, alternative implementations such as hardware
38accelerators may be used.
39See the
40.Sx CAVEATS
41section for how these DSA API functions are affected by the use of
42.Xr engine 3
43API calls.
44.Pp
45Initially, the default
46.Vt DSA_METHOD
47is the OpenSSL internal implementation, as returned by
48.Fn DSA_OpenSSL .
49.Pp
50.Fn DSA_set_default_method
51makes
52.Fa meth
53the default method for all
54.Vt DSA
55structures created later.
56.Sy NB :
57This is true only whilst no
58.Vt ENGINE
59has been set as a default for DSA, so this function is no longer
60recommended.
61.Pp
62.Fn DSA_get_default_method
63returns a pointer to the current default
64.Vt DSA_METHOD .
65However, the meaningfulness of this result is dependent on whether the
66.Xr engine 3
67API is being used, so this function is no longer recommended.
68.Pp
69.Fn DSA_set_method
70selects
71.Fa meth
72to perform all operations using the key
73.Fa dsa .
74This will replace the
75.Vt DSA_METHOD
76used by the DSA key and if the previous method was supplied by an
77.Vt ENGINE ,
78the handle to that
79.Vt ENGINE
80will be released during the change.
81It is possible to have DSA keys that only work with certain
82.Vt DSA_METHOD
83implementations (eg. from an
84.Vt ENGINE
85module that supports embedded hardware-protected keys),
86and in such cases attempting to change the
87.Vt DSA_METHOD
88for the key can have unexpected results.
89.Pp
90.Fn DSA_new_method
91allocates and initializes a
92.Vt DSA
93structure so that
94.Fa engine
95will be used for the DSA operations.
96If
97.Fa engine
98is
99.Dv NULL ,
100the default engine for DSA operations is used, and if no
101default
102.Vt ENGINE
103is set, the
104.Vt DSA_METHOD
105controlled by
106.Fn DSA_set_default_method
107is used.
108.Sh THE DSA_METHOD STRUCTURE
109.Bd -literal
110struct
111{
112 /* name of the implementation */
113 const char *name;
114
115 /* sign */
116 DSA_SIG *(*dsa_do_sign)(const unsigned char *dgst, int dlen,
117 DSA *dsa);
118
119 /* pre-compute k^-1 and r */
120 int (*dsa_sign_setup)(DSA *dsa, BN_CTX *ctx_in, BIGNUM **kinvp,
121 BIGNUM **rp);
122
123 /* verify */
124 int (*dsa_do_verify)(const unsigned char *dgst, int dgst_len,
125 DSA_SIG *sig, DSA *dsa);
126
127 /* compute rr = a1^p1 * a2^p2 mod m (May be NULL for some
128 implementations) */
129 int (*dsa_mod_exp)(DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1,
130 BIGNUM *a2, BIGNUM *p2, BIGNUM *m,
131 BN_CTX *ctx, BN_MONT_CTX *in_mont);
132
133 /* compute r = a ^ p mod m (May be NULL for some implementations) */
134 int (*bn_mod_exp)(DSA *dsa, BIGNUM *r, BIGNUM *a,
135 const BIGNUM *p, const BIGNUM *m,
136 BN_CTX *ctx, BN_MONT_CTX *m_ctx);
137
138 /* called at DSA_new */
139 int (*init)(DSA *DSA);
140
141 /* called at DSA_free */
142 int (*finish)(DSA *DSA);
143
144 int flags;
145
146 char *app_data; /* ?? */
147
148} DSA_METHOD;
149.Ed
150.Sh RETURN VALUES
151.Fn DSA_OpenSSL
152and
153.Fn DSA_get_default_method
154return pointers to the respective
155.Vt DSA_METHOD Ns s.
156.Pp
157.Fn DSA_set_method
158returns non-zero if the provided
159.Fa meth
160was successfully set as the method for
161.Fa dsa
162(including unloading the
163.Vt ENGINE
164handle if the previous method was supplied by an
165.Vt ENGINE ) .
166.Pp
167.Fn DSA_new_method
168returns
169.Dv NULL
170and sets an error code that can be obtained by
171.Xr ERR_get_error 3
172if the allocation fails.
173Otherwise it returns a pointer to the newly allocated structure.
174.Sh SEE ALSO
175.Xr dsa 3 ,
176.Xr DSA_new 3
177.Sh HISTORY
178.Fn DSA_set_default_method ,
179.Fn DSA_get_default_method ,
180.Fn DSA_set_method ,
181.Fn DSA_new_method ,
182and
183.Fn DSA_OpenSSL
184were added in OpenSSL 0.9.4.
185.Pp
186.Fn DSA_set_default_openssl_method
187and
188.Fn DSA_get_default_openssl_method
189replaced
190.Fn DSA_set_default_method
191and
192.Fn DSA_get_default_method
193respectively, and
194.Fn DSA_set_method
195and
196.Fn DSA_new_method
197were altered to use
198.Vt ENGINE Ns s
199rather than
200.Vt DSA_METHOD Ns s
201during development of the engine version of OpenSSL 0.9.6.
202For 0.9.7, the handling of defaults in the
203.Xr engine 3
204API was restructured so that this change was reversed, and behaviour
205of the other functions resembled more closely the previous behaviour.
206The behaviour of defaults in the
207.Xr engine 3
208API now transparently overrides the behaviour of defaults in the
209DSA API without requiring changing these function prototypes.
210.Sh CAVEATS
211As of version 0.9.7, DSA_METHOD implementations are grouped together
212with other algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in
213.Vt ENGINE
214modules.
215If a default
216.Vt ENGINE
217is specified for DSA functionality using an
218.Xr engine 3
219API function, that will override any DSA defaults set using the DSA API
220.Pq ie. DSA_set_default_method .
221For this reason, the
222.Xr engine 3
223API is the recommended way to control default implementations for
224use in DSA and other cryptographic algorithms.
diff --git a/src/lib/libcrypto/man/DSA_sign.3 b/src/lib/libcrypto/man/DSA_sign.3
new file mode 100644
index 0000000000..371f1f4555
--- /dev/null
+++ b/src/lib/libcrypto/man/DSA_sign.3
@@ -0,0 +1,122 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt DSA_SIGN 3
3.Os
4.Sh NAME
5.Nm DSA_sign ,
6.Nm DSA_sign_setup ,
7.Nm DSA_verify
8.Nd DSA signatures
9.Sh SYNOPSIS
10.In openssl/dsa.h
11.Ft int
12.Fo DSA_sign
13.Fa "int type"
14.Fa "const unsigned char *dgst"
15.Fa "int len"
16.Fa "unsigned char *sigret"
17.Fa "unsigned int *siglen"
18.Fa "DSA *dsa"
19.Fc
20.Ft int
21.Fo DSA_sign_setup
22.Fa "DSA *dsa"
23.Fa "BN_CTX *ctx"
24.Fa "BIGNUM **kinvp"
25.Fa "BIGNUM **rp"
26.Fc
27.Ft int
28.Fo DSA_verify
29.Fa "int type"
30.Fa "const unsigned char *dgst"
31.Fa "int len"
32.Fa "unsigned char *sigbuf"
33.Fa "int siglen"
34.Fa "DSA *dsa"
35.Fc
36.Sh DESCRIPTION
37.Fn DSA_sign
38computes a digital signature on the
39.Fa len
40byte message digest
41.Fa dgst
42using the private key
43.Fa dsa
44and places its ASN.1 DER encoding at
45.Fa sigret .
46The length of the signature is placed in
47.Pf * Fa siglen .
48.Fa sigret
49must point to
50.Fn DSA_size dsa
51bytes of memory.
52.Pp
53.Fn DSA_sign_setup
54may be used to precompute part of the signing operation in case
55signature generation is time-critical.
56It expects
57.Fa dsa
58to contain DSA parameters.
59It places the precomputed values in newly allocated
60.Vt BIGNUM Ns s
61at
62.Pf * Fa kinvp
63and
64.Pf * Fa rp ,
65after freeing the old ones unless
66.Fa kinvp
67and
68.Fa rp
69are
70.Dv NULL .
71These values may be passed to
72.Fn DSA_sign
73in
74.Fa dsa->kinv
75and
76.Sy dsa->r .
77.Fa ctx
78is a pre-allocated
79.Vt BN_CTX
80or
81.Dv NULL .
82.Pp
83.Fn DSA_verify
84verifies that the signature
85.Fa sigbuf
86of size
87.Fa siglen
88matches a given message digest
89.Fa dgst
90of size
91.Fa len .
92.Fa dsa
93is the signer's public key.
94.Pp
95The
96.Fa type
97parameter is ignored.
98.Sh RETURN VALUES
99.Fn DSA_sign
100and
101.Fn DSA_sign_setup
102return 1 on success or 0 on error.
103.Fn DSA_verify
104returns 1 for a valid signature, 0 for an incorrect signature,
105and -1 on error.
106The error codes can be obtained by
107.Xr ERR_get_error 3 .
108.Sh SEE ALSO
109.Xr dsa 3 ,
110.Xr DSA_do_sign 3 ,
111.Xr ERR_get_error 3 ,
112.Xr rand 3
113.Sh STANDARDS
114US Federal Information Processing Standard FIPS 186 (Digital Signature
115Standard, DSS), ANSI X9.30
116.Sh HISTORY
117.Fn DSA_sign
118and
119.Fn DSA_verify
120are available in all versions of SSLeay.
121.Fn DSA_sign_setup
122was added in SSLeay 0.8.
diff --git a/src/lib/libcrypto/man/DSA_size.3 b/src/lib/libcrypto/man/DSA_size.3
new file mode 100644
index 0000000000..64dce38f7c
--- /dev/null
+++ b/src/lib/libcrypto/man/DSA_size.3
@@ -0,0 +1,29 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt DSA_SIZE 3
3.Os
4.Sh NAME
5.Nm DSA_size
6.Nd get DSA signature size
7.Sh SYNOPSIS
8.In openssl/dsa.h
9.Ft int
10.Fo DSA_size
11.Fa "const DSA *dsa"
12.Fc
13.Sh DESCRIPTION
14This function returns the size of an ASN.1 encoded DSA signature in
15bytes.
16It can be used to determine how much memory must be allocated for a DSA
17signature.
18.Pp
19.Fa dsa->q
20must not be
21.Dv NULL .
22.Sh RETURN VALUE
23The size in bytes.
24.Sh SEE ALSO
25.Xr dsa 3 ,
26.Xr DSA_sign 3
27.Sh HISTORY
28.Fn DSA_size
29is available in all versions of SSLeay and OpenSSL.
diff --git a/src/lib/libcrypto/man/EC_GFp_simple_method.3 b/src/lib/libcrypto/man/EC_GFp_simple_method.3
new file mode 100644
index 0000000000..8f401e85c8
--- /dev/null
+++ b/src/lib/libcrypto/man/EC_GFp_simple_method.3
@@ -0,0 +1,108 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt EC_GFP_SIMPLE_METHOD 3
3.Os
4.Sh NAME
5.Nm EC_GFp_simple_method ,
6.Nm EC_GFp_mont_method ,
7.Nm EC_GFp_nist_method ,
8.Nm EC_GFp_nistp224_method ,
9.Nm EC_GFp_nistp256_method ,
10.Nm EC_GFp_nistp521_method ,
11.Nm EC_GF2m_simple_method ,
12.Nm EC_METHOD_get_field_type
13.Nd obtain EC_METHOD objects
14.Sh SYNOPSIS
15.In openssl/ec.h
16.Ft const EC_METHOD *
17.Fn EC_GFp_simple_method void
18.Ft const EC_METHOD *
19.Fn EC_GFp_mont_method void
20.Ft const EC_METHOD *
21.Fn EC_GFp_nist_method void
22.Ft const EC_METHOD *
23.Fn EC_GFp_nistp224_method void
24.Ft const EC_METHOD *
25.Fn EC_GFp_nistp256_method void
26.Ft const EC_METHOD *
27.Fn EC_GFp_nistp521_method void
28.Ft const EC_METHOD *
29.Fn EC_GF2m_simple_method void
30.Ft int
31.Fo EC_METHOD_get_field_type
32.Fa "const EC_METHOD *meth"
33.Fc
34.Sh DESCRIPTION
35The elliptic curve library provides a number of different
36implementations through a single common interface.
37When constructing a curve using
38.Xr EC_GROUP_new 3 ,
39an implementation method must be provided.
40The functions described here all return a const pointer to an
41.Sy EC_METHOD
42structure that can be passed to
43.Xr EC_GROUP_new .
44It is important that the correct implementation type for the form
45of curve selected is used.
46.Pp
47For F2^m curves there is only one implementation choice,
48.Fn EC_GF2_simple_method .
49.Pp
50For Fp curves the lowest common denominator implementation is the
51.Fn EC_GFp_simple_method
52implementation.
53All other implementations are based on this one.
54.Fn EC_GFp_mont_method
55adds the use of montgomery multiplication (see
56.Xr BN_mod_mul_montgomery 3 ) .
57.Fn EC_GFp_nist_method
58offers an implementation optimised for use with NIST recommended
59curves.
60NIST curves are available through
61.Xr EC_GROUP_new_by_curve_name 3 .
62.Pp
63The functions
64.Fn EC_GFp_nistp224_method ,
65.Fn EC_GFp_nistp256_method ,
66and
67.Fn EC_GFp_nistp521_method
68offer 64 bit optimised implementations for the NIST P224, P256 and
69P521 curves respectively.
70Note, however, that these implementations are not available on all
71platforms.
72.Pp
73.Fn EC_METHOD_get_field_type
74identifies what type of field the
75.Vt EC_METHOD
76structure supports, which will be either F2^m or Fp.
77If the field type is Fp, then the value
78.Dv NID_X9_62_prime_field
79is returned.
80If the field type is F2^m, then the value
81.Dv NID_X9_62_characteristic_two_field
82is returned.
83These values are defined in the
84.In openssl/obj_mac.h
85header file.
86.Sh RETURN VALUES
87All
88.Fn EC_GFp*
89functions and
90.Fn EC_GF2m_simple_method
91always return a const pointer to an
92.Vt EC_METHOD
93structure.
94.Pp
95.Fn EC_METHOD_get_field_type
96returns an integer that identifies the type of field the
97.Vt EC_METHOD
98structure supports.
99.Sh SEE ALSO
100.Xr BN_mod_mul_montgomery 3 ,
101.Xr crypto 3 ,
102.Xr d2i_ECPKParameters 3 ,
103.Xr ec 3 ,
104.Xr EC_GROUP_copy 3 ,
105.Xr EC_GROUP_new 3 ,
106.Xr EC_KEY_new 3 ,
107.Xr EC_POINT_add 3 ,
108.Xr EC_POINT_new 3
diff --git a/src/lib/libcrypto/man/EC_GROUP_copy.3 b/src/lib/libcrypto/man/EC_GROUP_copy.3
new file mode 100644
index 0000000000..61c094700a
--- /dev/null
+++ b/src/lib/libcrypto/man/EC_GROUP_copy.3
@@ -0,0 +1,434 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt EC_GROUP_COPY 3
3.Os
4.Sh NAME
5.Nm EC_GROUP_copy ,
6.Nm EC_GROUP_dup ,
7.Nm EC_GROUP_method_of ,
8.Nm EC_GROUP_set_generator ,
9.Nm EC_GROUP_get0_generator ,
10.Nm EC_GROUP_get_order ,
11.Nm EC_GROUP_get_cofactor ,
12.Nm EC_GROUP_set_curve_name ,
13.Nm EC_GROUP_get_curve_name ,
14.Nm EC_GROUP_set_asn1_flag ,
15.Nm EC_GROUP_get_asn1_flag ,
16.Nm EC_GROUP_set_point_conversion_form ,
17.Nm EC_GROUP_get_point_conversion_form ,
18.Nm EC_GROUP_get0_seed ,
19.Nm EC_GROUP_get_seed_len ,
20.Nm EC_GROUP_set_seed ,
21.Nm EC_GROUP_get_degree ,
22.Nm EC_GROUP_check ,
23.Nm EC_GROUP_check_discriminant ,
24.Nm EC_GROUP_cmp ,
25.Nm EC_GROUP_get_basis_type ,
26.Nm EC_GROUP_get_trinomial_basis ,
27.Nm EC_GROUP_get_pentanomial_basis
28.Nd manipulate EC_GROUP objects
29.Sh SYNOPSIS
30.In openssl/ec.h
31.In openssl/bn.h
32.Ft int
33.Fo EC_GROUP_copy
34.Fa "EC_GROUP *dst"
35.Fa "const EC_GROUP *src"
36.Fc
37.Ft EC_GROUP *
38.Fo EC_GROUP_dup
39.Fa "const EC_GROUP *src"
40.Fc
41.Ft const EC_METHOD *
42.Fo EC_GROUP_method_of
43.Fa "const EC_GROUP *group"
44.Fc
45.Ft int
46.Fo EC_GROUP_set_generator
47.Fa "EC_GROUP *group"
48.Fa "const EC_POINT *generator"
49.Fa "const BIGNUM *order"
50.Fa "const BIGNUM *cofactor"
51.Fc
52.Ft const EC_POINT *
53.Fo EC_GROUP_get0_generator
54.Fa "const EC_GROUP *group"
55.Fc
56.Ft int
57.Fo EC_GROUP_get_order
58.Fa "const EC_GROUP *group"
59.Fa "BIGNUM *order"
60.Fa "BN_CTX *ctx"
61.Fc
62.Ft int
63.Fo EC_GROUP_get_cofactor
64.Fa "const EC_GROUP *group"
65.Fa "BIGNUM *cofactor"
66.Fa "BN_CTX *ctx"
67.Fc
68.Ft void
69.Fo EC_GROUP_set_curve_name
70.Fa "EC_GROUP *group"
71.Fa "int nid"
72.Fc
73.Ft int
74.Fo EC_GROUP_get_curve_name
75.Fa "const EC_GROUP *group"
76.Fc
77.Ft void
78.Fo EC_GROUP_set_asn1_flag
79.Fa "EC_GROUP *group"
80.Fa "int flag"
81.Fc
82.Ft int
83.Fo EC_GROUP_get_asn1_flag
84.Fa "const EC_GROUP *group"
85.Fc
86.Ft void
87.Fo EC_GROUP_set_point_conversion_form
88.Fa "EC_GROUP *group"
89.Fa "point_conversion_form_t form"
90.Fc
91.Ft point_conversion_form_t
92.Fo EC_GROUP_get_point_conversion_form
93.Fa "const EC_GROUP *"
94.Fc
95.Ft unsigned char *
96.Fo EC_GROUP_get0_seed
97.Fa "const EC_GROUP *x"
98.Fc
99.Ft size_t
100.Fo EC_GROUP_get_seed_len
101.Fa "const EC_GROUP *"
102.Fc
103.Ft size_t
104.Fo EC_GROUP_set_seed
105.Fa "EC_GROUP *"
106.Fa "const unsigned char *"
107.Fa "size_t len"
108.Fc
109.Ft int
110.Fo EC_GROUP_get_degree
111.Fa "const EC_GROUP *group"
112.Fc
113.Ft int
114.Fo EC_GROUP_check
115.Fa "const EC_GROUP *group"
116.Fa "BN_CTX *ctx"
117.Fc
118.Ft int
119.Fo EC_GROUP_check_discriminant
120.Fa "const EC_GROUP *group"
121.Fa "BN_CTX *ctx"
122.Fc
123.Ft int
124.Fo EC_GROUP_cmp
125.Fa "const EC_GROUP *a"
126.Fa "const EC_GROUP *b"
127.Fa "BN_CTX *ctx"
128.Fc
129.Ft int
130.Fo EC_GROUP_get_basis_type
131.Fa "const EC_GROUP *"
132.Fc
133.Ft int
134.Fo EC_GROUP_get_trinomial_basis
135.Fa "const EC_GROUP *"
136.Fa "unsigned int *k"
137.Fc
138.Ft int
139.Fo EC_GROUP_get_pentanomial_basis
140.Fa "const EC_GROUP *"
141.Fa "unsigned int *k1"
142.Fa "unsigned int *k2"
143.Fa "unsigned int *k3"
144.Fc
145.Sh DESCRIPTION
146.Fn EC_GROUP_copy
147copies the curve
148.Fa src
149into
150.Fa dst .
151Both
152.Fa src
153and
154.Fa dst
155must use the same
156.Vt EC_METHOD .
157.Pp
158.Fn EC_GROUP_dup
159creates a new
160.Vt EC_GROUP
161object and copies the content from
162.Fa src
163to the newly created
164.Vt EC_GROUP
165object.
166.Pp
167.Fn EC_GROUP_method_of
168obtains the
169.Vt EC_METHOD
170of
171.Fa group .
172.Pp
173.Fn EC_GROUP_set_generator
174sets curve paramaters that must be agreed by all participants using
175the curve.
176These paramaters include the
177.Fa generator ,
178the
179.Fa order
180and the
181.Fa cofactor .
182The
183.Fa generator
184is a well defined point on the curve chosen for cryptographic
185operations.
186Integers used for point multiplications will be between 0 and
187.Fa order No - 1 .
188The
189.Fa order
190multipied by the
191.Fa cofactor
192gives the number of points on the curve.
193.Pp
194.Fn EC_GROUP_get0_generator
195returns the generator for the identified
196.Fa group .
197.Pp
198The functions
199.Fn EC_GROUP_get_order
200and
201.Fn EC_GROUP_get_cofactor
202populate the provided
203.Fa order
204and
205.Fa cofactor
206parameters with the respective order and cofactors for the
207.Fa group .
208.Pp
209The functions
210.Fn EC_GROUP_set_curve_name
211and
212.Fn EC_GROUP_get_curve_name
213set and get the NID for the curve, respectively (see
214.Xr EC_GROUP_new 3 ) .
215If a curve does not have a NID associated with it, then
216.Fn EC_GROUP_get_curve_name
217will return 0.
218.Pp
219The asn1_flag value on a curve is used to determine whether there is a
220specific ASN1 OID to describe the curve or not.
221If the asn1_flag is 1 then this is a named curve with an associated ASN1 OID.
222If not then asn1_flag is 0.
223The functions
224.Fn EC_GROUP_get_asn1_flag
225and
226.Fn EC_GROUP_set_asn1_flag
227get and set the status of the asn1_flag for the curve.
228If set, then the curve_name must also be set.
229.Pp
230The point_conversion_form for a curve controls how
231.Vt EC_POINT
232data is encoded as ASN1 as defined in X9.62 (ECDSA).
233.Vt point_conversion_form_t
234is an enum defined as follows:
235.Bd -literal
236typedef enum {
237 /** the point is encoded as z||x, where the octet z specifies
238 * which solution of the quadratic equation y is */
239 POINT_CONVERSION_COMPRESSED = 2,
240 /** the point is encoded as z||x||y, where z is the octet 0x02 */
241 POINT_CONVERSION_UNCOMPRESSED = 4,
242 /** the point is encoded as z||x||y, where the octet z specifies
243 * which solution of the quadratic equation y is */
244 POINT_CONVERSION_HYBRID = 6
245} point_conversion_form_t;
246.Ed
247.Pp
248For
249.Dv POINT_CONVERSION_UNCOMPRESSED
250the point is encoded as an octet signifying the UNCOMPRESSED form
251has been used followed by the octets for x, followed by the octets
252for y.
253.Pp
254For any given x co-ordinate for a point on a curve it is possible to
255derive two possible y values.
256For
257.Dv POINT_CONVERSION_COMPRESSED
258the point is encoded as an octet signifying that the COMPRESSED
259form has been used AND which of the two possible solutions for y
260has been used, followed by the octets for x.
261.Pp
262For
263.Dv POINT_CONVERSION_HYBRID
264the point is encoded as an octet signifying the HYBRID form has
265been used AND which of the two possible solutions for y has been
266used, followed by the octets for x, followed by the octets for y.
267.Pp
268The functions
269.Fn EC_GROUP_set_point_conversion_form
270and
271.Fn EC_GROUP_get_point_conversion_form
272set and get the point_conversion_form for the curve, respectively.
273.Pp
274ANSI X9.62 (ECDSA standard) defines a method of generating the curve
275parameter b from a random number.
276This provides advantages in that a parameter obtained in this way is
277highly unlikely to be susceptible to special purpose attacks, or have
278any trapdoors in it.
279If the seed is present for a curve then the b parameter was generated in
280a verifiable fashion using that seed.
281The OpenSSL EC library does not use this seed value but does enable you
282to inspect it using
283.Fn EC_GROUP_get0_seed .
284This returns a pointer to a memory block containing the seed that was
285used.
286The length of the memory block can be obtained using
287.Fn EC_GROUP_get_seed_len .
288A number of the builtin curves within the library provide seed values
289that can be obtained.
290It is also possible to set a custom seed using
291.Fn EC_GROUP_set_seed
292and passing a pointer to a memory block, along with the length of
293the seed.
294Again, the EC library will not use this seed value, although it will be
295preserved in any ASN1 based communications.
296.Pp
297.Fn EC_GROUP_get_degree
298gets the degree of the field.
299For Fp fields this will be the number of bits in p.
300For F2^m fields this will be the value m.
301.Pp
302The function
303.Fn EC_GROUP_check_discriminant
304calculates the discriminant for the curve and verifies that it is
305valid.
306For a curve defined over Fp the discriminant is given by the formula
3074*a^3 + 27*b^2 whilst for F2^m curves the discriminant is simply b.
308In either case for the curve to be valid the discriminant must be
309non-zero.
310.Pp
311The function
312.Fn EC_GROUP_check
313performs a number of checks on a curve to verify that it is valid.
314Checks performed include verifying that the discriminant is non zero;
315that a generator has been defined; that the generator is on the curve
316and has the correct order.
317.Pp
318.Fn EC_GROUP_cmp
319compares
320.Fa a
321and
322.Fa b
323to determine whether they represent the same curve or not.
324.Pp
325The functions
326.Fn EC_GROUP_get_basis_type ,
327.Fn EC_GROUP_get_trinomial_basis ,
328and
329.Fn EC_GROUP_get_pentanomial_basis
330should only be called for curves defined over an F2^m field.
331Addition and multiplication operations within an F2^m field are
332performed using an irreducible polynomial function f(x).
333This function is either a trinomial of the form:
334.Pp
335.Dl f(x) = x^m + x^k + 1 with m > k >= 1
336.Pp
337or a pentanomial of the form:
338.Pp
339.Dl f(x) = x^m + x^k3 + x^k2 + x^k1 + 1 with m > k3 > k2 > k1 >= 1
340.Pp
341The function
342.Fn EC_GROUP_get_basis_type
343returns a NID identifying whether a trinomial or pentanomial is in
344use for the field.
345The function
346.Fn EC_GROUP_get_trinomial_basis
347must only be called where f(x) is of the trinomial form, and returns
348the value of
349.Fa k .
350Similarly, the function
351.Fn EC_GROUP_get_pentanomial_basis
352must only be called where f(x) is of the pentanomial form, and
353returns the values of
354.Fa k1 ,
355.Fa k2 ,
356and
357.Fa k3 .
358.Sh RETURN VALUES
359The following functions return 1 on success or 0 on error:
360.Fn EC_GROUP_copy ,
361.Fn EC_GROUP_set_generator ,
362.Fn EC_GROUP_check ,
363.Fn EC_GROUP_check_discriminant ,
364.Fn EC_GROUP_get_trinomial_basis ,
365and
366.Fn EC_GROUP_get_pentanomial_basis .
367.Pp
368.Fn EC_GROUP_dup
369returns a pointer to the duplicated curve or
370.Dv NULL
371on error.
372.Pp
373.Fn EC_GROUP_method_of
374returns the
375.Vt EC_METHOD
376implementation in use for the given curve or
377.Dv NULL
378on error.
379.Pp
380.Fn EC_GROUP_get0_generator
381returns the generator for the given curve or
382.Dv NULL
383on error.
384.Pp
385.Fn EC_GROUP_get_order ,
386.Fn EC_GROUP_get_cofactor ,
387.Fn EC_GROUP_get_curve_name ,
388.Fn EC_GROUP_get_asn1_flag ,
389.Fn EC_GROUP_get_point_conversion_form ,
390and
391.Fn EC_GROUP_get_degree
392return the order, cofactor, curve name (NID), ASN1 flag,
393point_conversion_form and degree for the specified curve, respectively.
394If there is no curve name associated with a curve then
395.Fn EC_GROUP_get_curve_name
396returns 0.
397.Pp
398.Fn EC_GROUP_get0_seed
399returns a pointer to the seed that was used to generate the parameter
400b, or
401.Dv NULL
402if the seed is not specified.
403.Fn EC_GROUP_get_seed_len
404returns the length of the seed or 0 if the seed is not specified.
405.Pp
406.Fn EC_GROUP_set_seed
407returns the length of the seed that has been set.
408If the supplied seed is
409.Dv NULL
410or the supplied seed length is 0, the return value will be 1.
411On error 0 is returned.
412.Pp
413.Fn EC_GROUP_cmp
414returns 0 if the curves are equal, 1 if they are not equal,
415or -1 on error.
416.Pp
417.Fn EC_GROUP_get_basis_type
418returns the values
419.Dv NID_X9_62_tpBasis
420or
421.Dv NID_X9_62_ppBasis
422as defined in
423.In openssl/obj_mac.h
424for a trinomial or pentanomial, respectively.
425Alternatively in the event of an error a 0 is returned.
426.Sh SEE ALSO
427.Xr crypto 3 ,
428.Xr d2i_ECPKParameters 3 ,
429.Xr ec 3 ,
430.Xr EC_GFp_simple_method 3 ,
431.Xr EC_GROUP_new 3 ,
432.Xr EC_KEY_new 3 ,
433.Xr EC_POINT_add 3 ,
434.Xr EC_POINT_new 3
diff --git a/src/lib/libcrypto/man/EC_GROUP_new.3 b/src/lib/libcrypto/man/EC_GROUP_new.3
new file mode 100644
index 0000000000..00690dfc07
--- /dev/null
+++ b/src/lib/libcrypto/man/EC_GROUP_new.3
@@ -0,0 +1,240 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt EC_GROUP_NEW 3
3.Os
4.Sh NAME
5.Nm EC_GROUP_new ,
6.Nm EC_GROUP_free ,
7.Nm EC_GROUP_clear_free ,
8.Nm EC_GROUP_new_curve_GFp ,
9.Nm EC_GROUP_new_curve_GF2m ,
10.Nm EC_GROUP_new_by_curve_name ,
11.Nm EC_GROUP_set_curve_GFp ,
12.Nm EC_GROUP_get_curve_GFp ,
13.Nm EC_GROUP_set_curve_GF2m ,
14.Nm EC_GROUP_get_curve_GF2m ,
15.Nm EC_get_builtin_curves
16.Nd create and destroy EC_GROUP objects
17.Sh SYNOPSIS
18.In openssl/ec.h
19.In openssl/bn.h
20.Ft EC_GROUP *
21.Fo EC_GROUP_new
22.Fa "const EC_METHOD *meth"
23.Fc
24.Ft void
25.Fo EC_GROUP_free
26.Fa "EC_GROUP *group"
27.Fc
28.Ft void
29.Fo EC_GROUP_clear_free
30.Fa "EC_GROUP *group"
31.Fc
32.Ft EC_GROUP *
33.Fo EC_GROUP_new_curve_GFp
34.Fa "const BIGNUM *p"
35.Fa "const BIGNUM *a"
36.Fa "const BIGNUM *b"
37.Fa "BN_CTX *ctx"
38.Fc
39.Ft EC_GROUP *
40.Fo EC_GROUP_new_curve_GF2m
41.Fa "const BIGNUM *p"
42.Fa "const BIGNUM *a"
43.Fa "const BIGNUM *b"
44.Fa "BN_CTX *ctx"
45.Fc
46.Ft EC_GROUP *
47.Fo EC_GROUP_new_by_curve_name
48.Fa "int nid"
49.Fc
50.Ft int
51.Fo EC_GROUP_set_curve_GFp
52.Fa "EC_GROUP *group"
53.Fa "const BIGNUM *p"
54.Fa "const BIGNUM *a"
55.Fa "const BIGNUM *b"
56.Fa "BN_CTX *ctx"
57.Fc
58.Ft int
59.Fo EC_GROUP_get_curve_GFp
60.Fa "const EC_GROUP *group"
61.Fa "BIGNUM *p"
62.Fa "BIGNUM *a"
63.Fa "BIGNUM *b"
64.Fa "BN_CTX *ctx"
65.Fc
66.Ft int
67.Fo EC_GROUP_set_curve_GF2m
68.Fa "EC_GROUP *group"
69.Fa "const BIGNUM *p"
70.Fa "const BIGNUM *a"
71.Fa "const BIGNUM *b"
72.Fa "BN_CTX *ctx"
73.Fc
74.Ft int
75.Fo EC_GROUP_get_curve_GF2m
76.Fa "const EC_GROUP *group"
77.Fa "BIGNUM *p"
78.Fa "BIGNUM *a"
79.Fa "BIGNUM *b"
80.Fa "BN_CTX *ctx"
81.Fc
82.Ft size_t
83.Fo EC_get_builtin_curves
84.Fa "EC_builtin_curve *r"
85.Fa "size_t nitems"
86.Fc
87.Sh DESCRIPTION
88Within the library there are two forms of elliptic curves that are of
89interest.
90The first form is those defined over the prime field Fp.
91The elements of Fp are the integers 0 to p-1, where
92.Fa p
93is a prime number.
94This gives us a revised elliptic curve equation as follows:
95.Pp
96.Dl y^2 mod p = x^3 +ax + b mod p
97.Pp
98The second form is those defined over a binary field F2^m where the
99elements of the field are integers of length at most m bits.
100For this form the elliptic curve equation is modified to:
101.Pp
102.Dl y^2 + xy = x^3 + ax^2 + b (where b != 0)
103.Pp
104Operations in a binary field are performed relative to an irreducible
105polynomial.
106All such curves with OpenSSL use a trinomial or a pentanomial for this
107parameter.
108.Pp
109A new curve can be constructed by calling
110.Fn EC_GROUP_new ,
111using the implementation provided by
112.Fa meth
113(see
114.Xr EC_GFp_simple_method 3 ) .
115It is then necessary to call either
116.Fn EC_GROUP_set_curve_GFp
117or
118.Fn EC_GROUP_set_curve_GF2m
119as appropriate to create a curve defined over Fp or over F2^m, respectively.
120.Pp
121.Fn EC_GROUP_set_curve_GFp
122sets the curve parameters
123.Fa p ,
124.Fa a ,
125and
126.Fa b
127for a curve over Fp stored in
128.Fa group .
129.Fn EC_group_get_curve_GFp
130obtains the previously set curve parameters.
131.Pp
132.Fn EC_GROUP_set_curve_GF2m
133sets the equivalent curve parameters for a curve over F2^m.
134In this case
135.Fa p
136represents the irreducible polynomial - each bit represents a term in
137the polynomial.
138Therefore there will either be three or five bits set dependent on
139whether the polynomial is a trinomial or a pentanomial.
140.Fn EC_group_get_curve_GF2m
141obtains the previously set curve parameters.
142.Pp
143The functions
144.Fn EC_GROUP_new_curve_GFp
145and
146.Fn EC_GROUP_new_curve_GF2m
147are shortcuts for calling
148.Fn EC_GROUP_new
149and the appropriate
150.Fn EC_GROUP_set_curve_*
151function.
152An appropriate default implementation method will be used.
153.Pp
154Whilst the library can be used to create any curve using the functions
155described above, there are also a number of predefined curves that are
156available.
157In order to obtain a list of all of the predefined curves, call the
158function
159.Fn EC_get_builtin_curves .
160The parameter
161.Fa r
162should be an array of
163.Vt EC_builtin_cure
164structures of size
165.Fa nitems .
166The function will populate the
167.Fa r
168array with information about the builtin curves.
169If
170.Fa nitems
171is less than the total number of curves available, then the first
172.Fa nitems
173curves will be returned.
174Otherwise the total number of curves will be provided.
175The return value is the total number of curves available (whether that
176number has been populated in
177.Fa r
178or not).
179Passing a
180.Dv NULL
181.Fa r ,
182or setting
183.Fa nitems
184to 0, will do nothing other than return the total number of curves
185available.
186The
187.Vt EC_builtin_curve
188structure is defined as follows:
189.Bd -literal
190typedef struct {
191 int nid;
192 const char *comment;
193} EC_builtin_curve;
194.Ed
195.Pp
196Each
197.Vt EC_builtin_curve
198item has a unique integer id
199.Pq Fa nid
200and a human readable comment string describing the curve.
201.Pp
202In order to construct a builtin curve use the function
203.Fn EC_GROUP_new_by_curve_name
204and provide the
205.Fa nid
206of the curve to be constructed.
207.Pp
208.Fn EC_GROUP_free
209frees the memory associated with the
210.Vt EC_GROUP .
211.Pp
212.Fn EC_GROUP_clear_free
213destroys any sensitive data held within the
214.Vt EC_GROUP
215and then frees its memory.
216.Sh RETURN VALUES
217All
218.Fn EC_GROUP_new*
219functions return a pointer to the newly constructed group or
220.Dv NULL
221on error.
222.Pp
223.Fn EC_get_builtin_curves
224returns the number of builtin curves that are available.
225.Pp
226.Fn EC_GROUP_set_curve_GFp ,
227.Fn EC_GROUP_get_curve_GFp ,
228.Fn EC_GROUP_set_curve_GF2m ,
229and
230.Fn EC_GROUP_get_curve_GF2m
231return 1 on success or 0 on error.
232.Sh SEE ALSO
233.Xr crypto 3 ,
234.Xr d2i_ECPKParameters 3 ,
235.Xr ec 3 ,
236.Xr EC_GFp_simple_method 3 ,
237.Xr EC_GROUP_copy 3 ,
238.Xr EC_KEY_new 3 ,
239.Xr EC_POINT_add 3 ,
240.Xr EC_POINT_new 3
diff --git a/src/lib/libcrypto/man/EC_KEY_new.3 b/src/lib/libcrypto/man/EC_KEY_new.3
new file mode 100644
index 0000000000..dcc55fa973
--- /dev/null
+++ b/src/lib/libcrypto/man/EC_KEY_new.3
@@ -0,0 +1,411 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt EC_KEY_NEW 3
3.Os
4.Sh NAME
5.Nm EC_KEY_new ,
6.Nm EC_KEY_get_flags ,
7.Nm EC_KEY_set_flags ,
8.Nm EC_KEY_clear_flags ,
9.Nm EC_KEY_new_by_curve_name ,
10.Nm EC_KEY_free ,
11.Nm EC_KEY_copy ,
12.Nm EC_KEY_dup ,
13.Nm EC_KEY_up_ref ,
14.Nm EC_KEY_get0_group ,
15.Nm EC_KEY_set_group ,
16.Nm EC_KEY_get0_private_key ,
17.Nm EC_KEY_set_private_key ,
18.Nm EC_KEY_get0_public_key ,
19.Nm EC_KEY_set_public_key ,
20.Nm EC_KEY_get_enc_flags ,
21.Nm EC_KEY_set_enc_flags ,
22.Nm EC_KEY_get_conv_form ,
23.Nm EC_KEY_set_conv_form ,
24.Nm EC_KEY_get_key_method_data ,
25.Nm EC_KEY_insert_key_method_data ,
26.Nm EC_KEY_set_asn1_flag ,
27.Nm EC_KEY_precompute_mult ,
28.Nm EC_KEY_generate_key ,
29.Nm EC_KEY_check_key ,
30.Nm EC_KEY_set_public_key_affine_coordinates
31.Nd create, destroy and manipulate EC_KEY objects
32.Sh SYNOPSIS
33.In openssl/ec.h
34.In openssl/bn.h
35.Ft EC_KEY *
36.Fn EC_KEY_new void
37.Ft int
38.Fo EC_KEY_get_flags
39.Fa "const EC_KEY *key"
40.Fc
41.Ft void
42.Fo EC_KEY_set_flags
43.Fa "EC_KEY *key"
44.Fa "int flags"
45.Fc
46.Ft void
47.Fo EC_KEY_clear_flags
48.Fa "EC_KEY *key"
49.Fa "int flags"
50.Fc
51.Ft EC_KEY *
52.Fo EC_KEY_new_by_curve_name
53.Fa "int nid"
54.Fc
55.Ft void
56.Fo EC_KEY_free
57.Fa "EC_KEY *key"
58.Fc
59.Ft EC_KEY *
60.Fo EC_KEY_copy
61.Fa "EC_KEY *dst"
62.Fa "const EC_KEY *src"
63.Fc
64.Ft EC_KEY *
65.Fo EC_KEY_dup
66.Fa "const EC_KEY *src"
67.Fc
68.Ft int
69.Fo EC_KEY_up_ref
70.Fa "EC_KEY *key"
71.Fc
72.Ft const EC_GROUP *
73.Fo EC_KEY_get0_group
74.Fa "const EC_KEY *key"
75.Fc
76.Ft int
77.Fo EC_KEY_set_group
78.Fa "EC_KEY *key"
79.Fa "const EC_GROUP *group"
80.Fc
81.Ft const BIGNUM *
82.Fo EC_KEY_get0_private_key
83.Fa "const EC_KEY *key"
84.Fc
85.Ft int
86.Fo EC_KEY_set_private_key
87.Fa "EC_KEY *key"
88.Fa "const BIGNUM *prv"
89.Fc
90.Ft const EC_POINT *
91.Fo EC_KEY_get0_public_key
92.Fa "const EC_KEY *key"
93.Fc
94.Ft int
95.Fo EC_KEY_set_public_key
96.Fa "EC_KEY *key"
97.Fa "const EC_POINT *pub"
98.Fc
99.Ft unsigned int
100.Fo EC_KEY_get_enc_flags
101.Fa "const EC_KEY *key"
102.Fc
103.Ft void
104.Fo EC_KEY_set_enc_flags
105.Fa "EC_KEY *key"
106.Fa "unsigned int flags"
107.Fc
108.Ft point_conversion_form_t
109.Fo EC_KEY_get_conv_form
110.Fa "const EC_KEY *key"
111.Fc
112.Ft void
113.Fo EC_KEY_set_conv_form
114.Fa "EC_KEY *key"
115.Fa "point_conversion_form_t cform"
116.Fc
117.Ft void *
118.Fo EC_KEY_get_key_method_data
119.Fa "EC_KEY *key"
120.Fa "void *(*dup_func)(void *)"
121.Fa "void (*free_func)(void *)"
122.Fa "void (*clear_free_func)(void *)"
123.Fc
124.Ft void
125.Fo EC_KEY_insert_key_method_data
126.Fa "EC_KEY *key"
127.Fa "void *data"
128.Fa "void *(*dup_func)(void *)"
129.Fa "void (*free_func)(void *)"
130.Fa "void (*clear_free_func)(void *)"
131.Fc
132.Ft void
133.Fo EC_KEY_set_asn1_flag
134.Fa "EC_KEY *key"
135.Fa "int asn1_flag"
136.Fc
137.Ft int
138.Fo EC_KEY_precompute_mult
139.Fa "EC_KEY *key"
140.Fa "BN_CTX *ctx"
141.Fc
142.Ft int
143.Fo EC_KEY_generate_key
144.Fa "EC_KEY *key"
145.Fc
146.Ft int
147.Fo EC_KEY_check_key
148.Fa "const EC_KEY *key"
149.Fc
150.Ft int
151.Fo EC_KEY_set_public_key_affine_coordinates
152.Fa "EC_KEY *key"
153.Fa "BIGNUM *x"
154.Fa "BIGNUM *y"
155.Fc
156.Sh DESCRIPTION
157An
158.Vt EC_KEY
159represents a public key and (optionally) an associated private key.
160A new
161.Vt EC_KEY
162(with no associated curve) can be constructed by calling
163.Fn EC_KEY_new .
164The reference count for the newly created
165.Vt EC_KEY
166is initially set to 1.
167A curve can be associated with the
168.Vt EC_KEY
169by calling
170.Fn EC_KEY_set_group .
171.Pp
172Alternatively a new
173.Vt EC_KEY
174can be constructed by calling
175.Fn EC_KEY_new_by_curve_name
176and supplying the
177.Fa nid
178of the associated curve.
179Refer to
180.Xr EC_GROUP_new 3
181for a description of curve names.
182This function simply wraps calls to
183.Fn EC_KEY_new
184and
185.Fn EC_GROUP_new_by_curve_name .
186.Pp
187Calling
188.Fn EC_KEY_free
189decrements the reference count for the
190.Vt EC_KEY
191object, and if it has dropped to zero, then frees the memory associated
192with it.
193.Pp
194.Fn EC_KEY_copy
195copies the contents of the
196.Vt EC_KEY
197in
198.Fa src
199into
200.Fa dst .
201.Pp
202.Fn EC_KEY_dup
203creates a new
204.Vt EC_KEY
205object and copies
206.Fa src
207into it.
208.Pp
209.Fn EC_KEY_up_ref
210increments the reference count associated with the
211.Vt EC_KEY
212object.
213.Pp
214.Fn EC_KEY_generate_key
215generates a new public and private key for the supplied
216.Fa key
217object.
218.Fa key
219must have an
220.Vt EC_GROUP
221object associated with it before calling this function.
222The private key is a random integer (0 < priv_key < order, where order
223is the order of the
224.Vt EC_GROUP
225object).
226The public key is an
227.Vt EC_POINT
228on the curve calculated by multiplying the generator for the curve
229by the private key.
230.Pp
231.Fn EC_KEY_check_key
232performs various sanity checks on the
233.Vt EC_KEY
234object to confirm that it is valid.
235.Pp
236.Fn EC_KEY_set_public_key_affine_coordinates
237sets the public key for
238.Fa key
239based on its affine coordinates, i.e. it constructs an
240.Vt EC_POINT
241object based on the supplied
242.Fa x
243and
244.Fa y
245values and sets the public key to be this
246.Vt EC_POINT .
247It also performs certain sanity checks on the key to confirm that
248it is valid.
249.Pp
250The functions
251.Fn EC_KEY_get0_group ,
252.Fn EC_KEY_set_group ,
253.Fn EC_KEY_get0_private_key ,
254.Fn EC_KEY_set_private_key ,
255.Fn EC_KEY_get0_public_key ,
256and
257.Fn EC_KEY_set_public_key
258get and set the
259.Vt EC_GROUP
260object, the private key and the
261.Vt EC_POINT
262public key for the
263.Fa key ,
264respectively.
265.Pp
266The functions
267.Fn EC_KEY_get_enc_flags
268and
269.Fn EC_KEY_set_enc_flags
270get and set the value of the encoding flags for the
271.Fa key .
272There are two encoding flags currently defined:
273.Dv EC_PKEY_NO_PARAMETERS
274and
275.Dv EC_PKEY_NO_PUBKEY .
276These flags define the behaviour of how the
277.Fa key
278is converted into ASN1 in a call to
279.Fn i2d_ECPrivateKey .
280If
281.Dv EC_PKEY_NO_PARAMETERS
282is set then the public parameters for the curve
283are not encoded along with the private key.
284If
285.Dv EC_PKEY_NO_PUBKEY
286is set then the public key is not encoded along with the private
287key.
288.Pp
289The functions
290.Fn EC_KEY_get_conv_form
291and
292.Fn EC_KEY_set_conv_form
293get and set the point_conversion_form for the
294.Fa key .
295For a description of point_conversion_forms please refer to
296.Xr EC_POINT_new 3 .
297.Pp
298.Fn EC_KEY_insert_key_method_data
299and
300.Fn EC_KEY_get_key_method_data
301enable the caller to associate arbitrary additional data specific
302to the elliptic curve scheme being used with the
303.Vt EC_KEY
304object.
305This data is treated as a "black box" by the ec library.
306The data to be stored by
307.Fn EC_KEY_insert_key_method_data
308is provided in the
309.Fa data
310parameter, which must have associated functions for duplicating, freeing
311and "clear_freeing" the data item.
312If a subsequent
313.Fn EC_KEY_get_key_method_data
314call is issued, the functions for duplicating, freeing and
315"clear_freeing" the data item must be provided again, and they must
316be the same as they were when the data item was inserted.
317.Pp
318.Fn EC_KEY_set_flags
319sets the flags in the
320.Fa flags
321parameter on the
322.Vt EC_KEY
323object.
324Any flags that are already set are left set.
325The currently defined standard flags are
326.Dv EC_FLAG_NON_FIPS_ALLOW
327and
328.Dv EC_FLAG_FIPS_CHECKED .
329In addition there is the flag
330.Dv EC_FLAG_COFACTOR_ECDH
331which is specific to ECDH and is defined in
332.In openssl/ecdh.h .
333.Fn EC_KEY_get_flags
334returns the current flags that are set for this
335.Vt EC_KEY .
336.Fn EC_KEY_clear_flags
337clears the flags indicated by the
338.Fa flags
339parameter.
340All other flags are left in their existing state.
341.Pp
342.Fn EC_KEY_set_asn1_flag
343sets the asn1_flag on the underlying
344.Vt EC_GROUP
345object (if set).
346Refer to
347.Xr EC_GROUP_copy 3
348for further information on the asn1_flag.
349.Pp
350.Fn EC_KEY_precompute_mult
351stores multiples of the underlying
352.Vt EC_GROUP
353generator for faster point multiplication.
354See also
355.Xr EC_POINT_add 3 .
356.Sh RETURN VALUES
357.Fn EC_KEY_new ,
358.Fn EC_KEY_new_by_curve_name ,
359and
360.Fn EC_KEY_dup
361return a pointer to the newly created
362.Vt EC_KEY object or
363.Dv NULL
364on error.
365.Pp
366.Fn EC_KEY_get_flags
367returns the flags associated with the
368.Vt EC_KEY object.
369.Pp
370.Fn EC_KEY_copy
371returns a pointer to the destination key or
372.Dv NULL
373on error.
374.Pp
375.Fn EC_KEY_up_ref ,
376.Fn EC_KEY_set_group ,
377.Fn EC_KEY_set_private_key ,
378.Fn EC_KEY_set_public_key ,
379.Fn EC_KEY_precompute_mult ,
380.Fn EC_KEY_generate_key ,
381.Fn EC_KEY_check_key ,
382and
383.Fn EC_KEY_set_public_key_affine_coordinates
384return 1 on success or 0 on error.
385.Pp
386.Fn EC_KEY_get0_group
387returns the
388.Vt EC_GROUP
389associated with the
390.Vt EC_KEY .
391.Pp
392.Fn EC_KEY_get0_private_key
393returns the private key associated with the
394.Vt EC_KEY .
395.Pp
396.Fn EC_KEY_get_enc_flags
397returns the value of the current encoding flags for the
398.Vt EC_KEY .
399.Pp
400.Fn EC_KEY_get_conv_form
401returns the point_conversion_form for the
402.Vt EC_KEY .
403.Sh SEE ALSO
404.Xr crypto 3 ,
405.Xr d2i_ECPKParameters 3 ,
406.Xr ec 3 ,
407.Xr EC_GFp_simple_method 3 ,
408.Xr EC_GROUP_copy 3 ,
409.Xr EC_GROUP_new 3 ,
410.Xr EC_POINT_add 3 ,
411.Xr EC_POINT_new 3
diff --git a/src/lib/libcrypto/man/EC_POINT_add.3 b/src/lib/libcrypto/man/EC_POINT_add.3
new file mode 100644
index 0000000000..b8e3290952
--- /dev/null
+++ b/src/lib/libcrypto/man/EC_POINT_add.3
@@ -0,0 +1,220 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt EC_POINT_ADD 3
3.Os
4.Sh NAME
5.Nm EC_POINT_add ,
6.Nm EC_POINT_dbl ,
7.Nm EC_POINT_invert ,
8.Nm EC_POINT_is_at_infinity ,
9.Nm EC_POINT_is_on_curve ,
10.Nm EC_POINT_cmp ,
11.Nm EC_POINT_make_affine ,
12.Nm EC_POINTs_make_affine ,
13.Nm EC_POINTs_mul ,
14.Nm EC_POINT_mul ,
15.Nm EC_GROUP_precompute_mult ,
16.Nm EC_GROUP_have_precompute_mult
17.Nd perform mathematical operations and tests on EC_POINT objects
18.Sh SYNOPSIS
19.In openssl/ec.h
20.In openssl/bn.h
21.Ft int
22.Fo EC_POINT_add
23.Fa "const EC_GROUP *group"
24.Fa "EC_POINT *r"
25.Fa "const EC_POINT *a"
26.Fa "const EC_POINT *b"
27.Fa "BN_CTX *ctx"
28.Fc
29.Ft int
30.Fo EC_POINT_dbl
31.Fa "const EC_GROUP *group"
32.Fa "EC_POINT *r"
33.Fa "const EC_POINT *a"
34.Fa "BN_CTX *ctx"
35.Fc
36.Ft int
37.Fo EC_POINT_invert
38.Fa "const EC_GROUP *group"
39.Fa "EC_POINT *a"
40.Fa "BN_CTX *ctx"
41.Fc
42.Ft int
43.Fo EC_POINT_is_at_infinity
44.Fa "const EC_GROUP *group"
45.Fa "const EC_POINT *p"
46.Fc
47.Ft int
48.Fo EC_POINT_is_on_curve
49.Fa "const EC_GROUP *group"
50.Fa "const EC_POINT *point"
51.Fa "BN_CTX *ctx"
52.Fc
53.Ft int
54.Fo EC_POINT_cmp
55.Fa "const EC_GROUP *group"
56.Fa "const EC_POINT *a"
57.Fa "const EC_POINT *b"
58.Fa "BN_CTX *ctx"
59.Fc
60.Ft int
61.Fo EC_POINT_make_affine
62.Fa "const EC_GROUP *group"
63.Fa "EC_POINT *point"
64.Fa "BN_CTX *ctx"
65.Fc
66.Ft int
67.Fo EC_POINTs_make_affine
68.Fa "const EC_GROUP *group"
69.Fa "size_t num"
70.Fa "EC_POINT *points[]"
71.Fa "BN_CTX *ctx"
72.Fc
73.Ft int
74.Fo EC_POINTs_mul
75.Fa "const EC_GROUP *group"
76.Fa "EC_POINT *r"
77.Fa "const BIGNUM *n"
78.Fa "size_t num"
79.Fa "const EC_POINT *p[]"
80.Fa "const BIGNUM *m[]"
81.Fa "BN_CTX *ctx"
82.Fc
83.Ft int
84.Fo EC_POINT_mul
85.Fa "const EC_GROUP *group"
86.Fa "EC_POINT *r"
87.Fa "const BIGNUM *n"
88.Fa "const EC_POINT *q"
89.Fa "const BIGNUM *m"
90.Fa "BN_CTX *ctx"
91.Fc
92.Ft int
93.Fo EC_GROUP_precompute_mult
94.Fa "EC_GROUP *group"
95.Fa "BN_CTX *ctx"
96.Fc
97.Ft int
98.Fo EC_GROUP_have_precompute_mult
99.Fa "const EC_GROUP *group"
100.Fc
101.Sh DESCRIPTION
102.Fn EC_POINT_add
103adds the two points
104.Fa a
105and
106.Fa b
107and places the result in
108.Fa r .
109Similarly
110.Fn EC_POINT_dbl
111doubles the point
112.Fa a
113and places the result in
114.Fa r .
115In both cases it is valid for
116.Fa r
117to be one of
118.Fa a
119or
120.Fa b .
121.Pp
122.Fn EC_POINT_invert
123calculates the inverse of the supplied point
124.Fa a .
125The result is placed back in
126.Fa a .
127.Pp
128The function
129.Fn EC_POINT_is_at_infinity
130tests whether the supplied point is at infinity or not.
131.Pp
132.Fn EC_POINT_is_on_curve
133tests whether the supplied point is on the curve or not.
134.Pp
135.Fn EC_POINT_cmp
136compares the two supplied points and tests whether or not they are
137equal.
138.Pp
139The functions
140.Fn EC_POINT_make_affine
141and
142.Fn EC_POINTs_make_affine
143force the internal representation of the
144.Vt EC_POINT Ns (s)
145into the affine coordinate system.
146In the case of
147.Fn EC_POINTs_make_affine ,
148the value
149.Fa num
150provides the number of points in the array
151.Fa points
152to be forced.
153.Pp
154.Fn EC_POINT_mul
155calculates the value
156.Pp
157.D1 generator * n + q * m
158.Pp
159and stores the result in
160.Fa r .
161The value
162.Fa n
163may be
164.Dv NULL ,
165in which case the result is just q * m.
166.Pp
167.Fn EC_POINTs_mul
168calculates the value
169.Pp
170.Dl generator * n + q[0] * m[0] + ... + q[num-1] * m[num-1]
171.Pp
172As for
173.Fn EC_POINT_mul ,
174the value
175.Fa n
176may be
177.Dv NULL .
178.Pp
179The function
180.Fn EC_GROUP_precompute_mult
181stores multiples of the generator for faster point multiplication,
182whilst
183.Fn EC_GROUP_have_precompute_mult
184tests whether precomputation has already been done.
185See
186.Xr EC_GROUP_copy 3
187for information about the generator.
188.Sh RETURN VALUES
189The following functions return 1 on success or 0 on error:
190.Fn EC_POINT_add ,
191.Fn EC_POINT_dbl ,
192.Fn EC_POINT_invert ,
193.Fn EC_POINT_make_affine ,
194.Fn EC_POINTs_make_affine ,
195.Fn EC_POINTs_make_affine ,
196.Fn EC_POINT_mul ,
197.Fn EC_POINTs_mul ,
198and
199.Fn EC_GROUP_precompute_mult .
200.Pp
201.Fn EC_POINT_is_at_infinity
202returns 1 if the point is at infinity or 0 otherwise.
203.Pp
204.Fn EC_POINT_is_on_curve
205returns 1 if the point is on the curve, 0 if not, or -1 on error.
206.Pp
207.Fn EC_POINT_cmp
208returns 1 if the points are not equal, 0 if they are, or -1 on error.
209.Pp
210.Fn EC_GROUP_have_precompute_mult
211returns 1 if a precomputation has been done or 0 if not.
212.Sh SEE ALSO
213.Xr crypto 3 ,
214.Xr d2i_ECPKParameters 3 ,
215.Xr ec 3 ,
216.Xr EC_GFp_simple_method 3 ,
217.Xr EC_GROUP_copy 3 ,
218.Xr EC_GROUP_new 3 ,
219.Xr EC_KEY_new 3 ,
220.Xr EC_POINT_new 3
diff --git a/src/lib/libcrypto/man/EC_POINT_new.3 b/src/lib/libcrypto/man/EC_POINT_new.3
new file mode 100644
index 0000000000..cd0dcaf986
--- /dev/null
+++ b/src/lib/libcrypto/man/EC_POINT_new.3
@@ -0,0 +1,409 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt EC_POINT_NEW 3
3.Os
4.Sh NAME
5.Nm EC_POINT_new ,
6.Nm EC_POINT_free ,
7.Nm EC_POINT_clear_free ,
8.Nm EC_POINT_copy ,
9.Nm EC_POINT_dup ,
10.Nm EC_POINT_method_of ,
11.Nm EC_POINT_set_to_infinity ,
12.Nm EC_POINT_set_Jprojective_coordinates ,
13.Nm EC_POINT_get_Jprojective_coordinates_GFp ,
14.Nm EC_POINT_set_affine_coordinates_GFp ,
15.Nm EC_POINT_get_affine_coordinates_GFp ,
16.Nm EC_POINT_set_compressed_coordinates_GFp ,
17.Nm EC_POINT_set_affine_coordinates_GF2m ,
18.Nm EC_POINT_get_affine_coordinates_GF2m ,
19.Nm EC_POINT_set_compressed_coordinates_GF2m ,
20.Nm EC_POINT_point2oct ,
21.Nm EC_POINT_oct2point ,
22.Nm EC_POINT_point2bn ,
23.Nm EC_POINT_bn2point ,
24.Nm EC_POINT_point2hex ,
25.Nm EC_POINT_hex2point
26.Nd create, destroy, and manipulate EC_POINT objects
27.Sh SYNOPSIS
28.In openssl/ec.h
29.In openssl/bn.h
30.Ft EC_POINT *
31.Fo EC_POINT_new
32.Fa "const EC_GROUP *group"
33.Fc
34.Ft void
35.Fo EC_POINT_free
36.Fa "EC_POINT *point"
37.Fc
38.Ft void
39.Fo EC_POINT_clear_free
40.Fa "EC_POINT *point"
41.Fc
42.Ft int
43.Fo EC_POINT_copy
44.Fa "EC_POINT *dst"
45.Fa "const EC_POINT *src"
46.Fc
47.Ft EC_POINT *
48.Fo EC_POINT_dup
49.Fa "const EC_POINT *src"
50.Fa "const EC_GROUP *group"
51.Fc
52.Ft const EC_METHOD *
53.Fo EC_POINT_method_of
54.Fa "const EC_POINT *point"
55.Fc
56.Ft int
57.Fo EC_POINT_set_to_infinity
58.Fa "const EC_GROUP *group"
59.Fa "EC_POINT *point"
60.Fc
61.Ft int
62.Fo EC_POINT_set_Jprojective_coordinates_GFp
63.Fa "const EC_GROUP *group"
64.Fa "EC_POINT *p"
65.Fa "const BIGNUM *x"
66.Fa "const BIGNUM *y"
67.Fa "const BIGNUM *z"
68.Fa "BN_CTX *ctx"
69.Fc
70.Ft int
71.Fo EC_POINT_get_Jprojective_coordinates_GFp
72.Fa "const EC_GROUP *group"
73.Fa "const EC_POINT *p"
74.Fa "BIGNUM *x"
75.Fa "BIGNUM *y"
76.Fa "BIGNUM *z"
77.Fa "BN_CTX *ctx"
78.Fc
79.Ft int
80.Fo EC_POINT_set_affine_coordinates_GFp
81.Fa "const EC_GROUP *group"
82.Fa "EC_POINT *p"
83.Fa "const BIGNUM *x"
84.Fa "const BIGNUM *y"
85.Fa "BN_CTX *ctx"
86.Fc
87.Ft int
88.Fo EC_POINT_get_affine_coordinates_GFp
89.Fa "const EC_GROUP *group"
90.Fa "const EC_POINT *p"
91.Fa "BIGNUM *x"
92.Fa "BIGNUM *y"
93.Fa "BN_CTX *ctx"
94.Fc
95.Ft int
96.Fo EC_POINT_set_compressed_coordinates_GFp
97.Fa "const EC_GROUP *group"
98.Fa "EC_POINT *p"
99.Fa "const BIGNUM *x"
100.Fa "int y_bit"
101.Fa "BN_CTX *ctx"
102.Fc
103.Ft int
104.Fo EC_POINT_set_affine_coordinates_GF2m
105.Fa "const EC_GROUP *group"
106.Fa "EC_POINT *p"
107.Fa "const BIGNUM *x"
108.Fa "const BIGNUM *y"
109.Fa "BN_CTX *ctx"
110.Fc
111.Ft int
112.Fo EC_POINT_get_affine_coordinates_GF2m
113.Fa "const EC_GROUP *group"
114.Fa "const EC_POINT *p"
115.Fa "BIGNUM *x"
116.Fa "BIGNUM *y"
117.Fa "BN_CTX *ctx"
118.Fc
119.Ft int
120.Fo EC_POINT_set_compressed_coordinates_GF2m
121.Fa "const EC_GROUP *group"
122.Fa "EC_POINT *p"
123.Fa "const BIGNUM *x"
124.Fa "int y_bit"
125.Fa "BN_CTX *ctx"
126.Fc
127.Ft size_t
128.Fo EC_POINT_point2oct
129.Fa "const EC_GROUP *group"
130.Fa "const EC_POINT *p"
131.Fa "point_conversion_form_t form"
132.Fa "unsigned char *buf"
133.Fa "size_t len"
134.Fa "BN_CTX *ctx"
135.Fc
136.Ft int
137.Fo EC_POINT_oct2point
138.Fa "const EC_GROUP *group"
139.Fa "EC_POINT *p"
140.Fa "const unsigned char *buf"
141.Fa "size_t len"
142.Fa "BN_CTX *ctx"
143.Fc
144.Ft BIGNUM *
145.Fo EC_POINT_point2bn
146.Fa "const EC_GROUP *"
147.Fa "const EC_POINT *"
148.Fa "point_conversion_form_t form"
149.Fa "BIGNUM *"
150.Fa "BN_CTX *"
151.Fc
152.Ft EC_POINT *
153.Fo EC_POINT_bn2point
154.Fa "const EC_GROUP *"
155.Fa "const BIGNUM *"
156.Fa "EC_POINT *"
157.Fa "BN_CTX *"
158.Fc
159.Ft char *
160.Fo EC_POINT_point2hex
161.Fa "const EC_GROUP *"
162.Fa "const EC_POINT *"
163.Fa "point_conversion_form_t form"
164.Fa "BN_CTX *"
165.Fc
166.Ft EC_POINT *
167.Fo EC_POINT_hex2point
168.Fa "const EC_GROUP *"
169.Fa "const char *"
170.Fa "EC_POINT *"
171.Fa "BN_CTX *"
172.Fc
173.Sh DESCRIPTION
174An
175.Vt EC_POINT
176represents a point on a curve.
177A new point is constructed by calling the function
178.Fn EC_POINT_new
179and providing the
180.Fa group
181object that the point relates to.
182.Pp
183.Fn EC_POINT_free
184frees the memory associated with the
185.Vt EC_POINT .
186.Pp
187.Fn EC_POINT_clear_free
188destroys any sensitive data held within the
189.Vt EC_POINT
190and then frees its memory.
191.Pp
192.Fn EC_POINT_copy
193copies the point
194.Fa src
195into
196.Fa dst .
197Both
198.Fa src
199and
200.Fa dst
201must use the same
202.Vt EC_METHOD .
203.Pp
204.Fn EC_POINT_dup
205creates a new
206.Vt EC_POINT
207object and copies the content from
208.Fa src
209to the newly created
210.Vt EC_POINT
211object.
212.Pp
213.Fn EC_POINT_method_of
214obtains the
215.Vt EC_METHOD
216associated with
217.Fa point .
218.Pp
219A valid point on a curve is the special point at infinity.
220A point is set to be at infinity by calling
221.Fn EC_POINT_set_to_infinity .
222.Pp
223The affine coordinates for a point describe a point in terms of its
224.Fa x
225and
226.Fa y
227position.
228The functions
229.Fn EC_POINT_set_affine_coordinates_GFp
230and
231.Fn EC_POINT_set_affine_coordinates_GF2m
232set the
233.Fa x
234and
235.Fa y
236coordinates for the point
237.Fa p
238defined over the curve given in
239.Fa group .
240.Pp
241As well as the affine coordinates, a point can alternatively be
242described in terms of its Jacobian projective coordinates (for Fp
243curves only).
244Jacobian projective coordinates are expressed as three values
245.Fa x ,
246.Fa y ,
247and
248.Fa z .
249Working in this coordinate system provides more efficient point
250multiplication operations.
251A mapping exists between Jacobian projective coordinates and affine
252coordinates.
253A Jacobian projective coordinate
254.Pq Fa x , y , z
255can be written as an affine coordinate as
256.Pp
257.Dl (x/(z^2), y/(z^3)) .
258.Pp
259Conversion to Jacobian projective to affine coordinates is simple.
260The coordinate
261.Pq Fa x , y
262is mapped to
263.Pq Fa x , y , No 1 .
264To set or get the projective coordinates use
265.Fn EC_POINT_set_Jprojective_coordinates_GFp
266and
267.Fn EC_POINT_get_Jprojective_coordinates_GFp ,
268respectively.
269.Pp
270Points can also be described in terms of their compressed coordinates.
271For a point
272.Pq Fa x , y ,
273for any given value for
274.Fa x
275such that the point is on the curve, there will only ever be two
276possible values for
277.Fa y .
278Therefore a point can be set using the
279.Fn EC_POINT_set_compressed_coordinates_GFp
280and
281.Fn EC_POINT_set_compressed_coordinates_GF2m
282functions where
283.Fa x
284is the x coordinate and
285.Fa y_bit
286is a value 0 or 1 to identify which of the two possible values for y
287should be used.
288.Pp
289In addition
290.Vt EC_POINT Ns s
291can be converted to and from various external representations.
292Supported representations are octet strings,
293.Vt BIGNUM Ns s ,
294and hexadecimal.
295The format of the external representation is described by the
296point_conversion_form.
297See
298.Xr EC_GROUP_copy 3
299for a description of point_conversion_form.
300Octet strings are stored in a buffer along with an associated buffer
301length.
302A point held in a
303.Vt BIGNUM
304is calculated by converting the point to an octet string and then
305converting that octet string into a
306.Vt BIGNUM
307integer.
308Points in hexadecimal format are stored in a NUL terminated character
309string where each character is one of the printable values 0-9 or A-F
310(or a-f).
311.Pp
312The functions
313.Fn EC_POINT_point2oct ,
314.Fn EC_POINT_oct2point ,
315.Fn EC_POINT_point2bn ,
316.Fn EC_POINT_bn2point ,
317.Fn EC_POINT_point2hex ,
318and
319.Fn EC_POINT_hex2point
320convert from and to
321.Vt EC_POINT Ns s
322for the formats octet string,
323.Vt BIGNUM ,
324and hexadecimal, respectively.
325.Pp
326The function
327.Fn EC_POINT_point2oct
328must be supplied with a
329.Fa buf
330long enough to store the octet string.
331The return value provides the number of octets stored.
332Calling the function with a
333.Dv NULL
334.Fa buf
335will not perform the conversion but will still return the required
336buffer length.
337.Pp
338The function
339.Fn EC_POINT_point2hex
340will allocate sufficient memory to store the hexadecimal string.
341It is the caller's responsibility to free this memory with a subsequent
342call to
343.Xr free 3 .
344.Sh RETURN VALUES
345.Fn EC_POINT_new
346and
347.Fn EC_POINT_dup
348return the newly allocated
349.Vt EC_POINT
350or
351.Dv NULL
352on error.
353.Pp
354The following functions return 1 on success or 0 on error:
355.Fn EC_POINT_copy ,
356.Fn EC_POINT_set_to_infinity ,
357.Fn EC_POINT_set_Jprojective_coordinates_GFp ,
358.Fn EC_POINT_get_Jprojective_coordinates_GFp ,
359.Fn EC_POINT_set_affine_coordinates_GFp ,
360.Fn EC_POINT_get_affine_coordinates_GFp ,
361.Fn EC_POINT_set_compressed_coordinates_GFp ,
362.Fn EC_POINT_set_affine_coordinates_GF2m ,
363.Fn EC_POINT_get_affine_coordinates_GF2m ,
364.Fn EC_POINT_set_compressed_coordinates_GF2m ,
365and
366.Fn EC_POINT_oct2point .
367.Pp
368.Fn EC_POINT_method_of
369returns the
370.Vt EC_METHOD
371associated with the supplied
372.Vt EC_POINT .
373.Pp
374.Fn EC_POINT_point2oct
375returns the length of the required buffer, or 0 on error.
376.Pp
377.Fn EC_POINT_point2bn
378returns the pointer to the
379.Vt BIGNUM
380supplied or
381.Vt NULL
382on error.
383.Pp
384.Fn EC_POINT_bn2point
385returns the pointer to the
386.Vt EC_POINT
387supplied or
388.Dv NULL
389on error.
390.Pp
391.Fn EC_POINT_point2hex
392returns a pointer to the hex string or
393.Dv NULL
394on error.
395.Pp
396.Fn EC_POINT_hex2point
397returns the pointer to the
398.Vt EC_POINT supplied or
399.Dv NULL
400on error.
401.Sh SEE ALSO
402.Xr crypto 3 ,
403.Xr d2i_ECPKParameters 3 ,
404.Xr ec 3 ,
405.Xr EC_GFp_simple_method 3 ,
406.Xr EC_GROUP_copy 3 ,
407.Xr EC_GROUP_new 3 ,
408.Xr EC_KEY_new 3 ,
409.Xr EC_POINT_add 3
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index a40bb39167..f676472ff6 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
1# $OpenBSD: Makefile,v 1.35 2016/11/02 09:11:53 schwarze Exp $ 1# $OpenBSD: Makefile,v 1.36 2016/11/02 11:57:56 schwarze Exp $
2 2
3.include <bsd.own.mk> # for NOMAN 3.include <bsd.own.mk> # for NOMAN
4 4
@@ -63,16 +63,6 @@ MAN= \
63 DH_new.3 \ 63 DH_new.3 \
64 DH_set_method.3 \ 64 DH_set_method.3 \
65 DH_size.3 \ 65 DH_size.3 \
66 ECDSA_SIG_new.3 \
67 EVP_AEAD_CTX_init.3 \
68 UI_new.3 \
69 bn_dump.3 \
70 crypto.3 \
71 d2i_PKCS8PrivateKey_bio.3 \
72 des_read_pw.3 \
73 lh_new.3 \
74
75GENMAN= \
76 DSA_SIG_new.3 \ 66 DSA_SIG_new.3 \
77 DSA_do_sign.3 \ 67 DSA_do_sign.3 \
78 DSA_dup_DH.3 \ 68 DSA_dup_DH.3 \
@@ -89,6 +79,16 @@ GENMAN= \
89 EC_KEY_new.3 \ 79 EC_KEY_new.3 \
90 EC_POINT_add.3 \ 80 EC_POINT_add.3 \
91 EC_POINT_new.3 \ 81 EC_POINT_new.3 \
82 ECDSA_SIG_new.3 \
83 EVP_AEAD_CTX_init.3 \
84 UI_new.3 \
85 bn_dump.3 \
86 crypto.3 \
87 d2i_PKCS8PrivateKey_bio.3 \
88 des_read_pw.3 \
89 lh_new.3 \
90
91GENMAN= \
92 ERR.3 \ 92 ERR.3 \
93 ERR_GET_LIB.3 \ 93 ERR_GET_LIB.3 \
94 ERR_clear_error.3 \ 94 ERR_clear_error.3 \
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-03-21 19:48:01 +0000