summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/doc
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/doc')
-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
16 files changed, 0 insertions, 1230 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