summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man
diff options
context:
space:
mode:
authorschwarze <>2016-11-02 11:57:56 +0000
committerschwarze <>2016-11-02 11:57:56 +0000
commitcc11de9530a463cf1046e63cc0a8b635aa93cdae (patch)
tree62d26e7f75bb451eba292aad57737306b2f28280 /src/lib/libcrypto/man
parent849e449a83384719b38a7cfdafafc48800004525 (diff)
downloadopenbsd-cc11de9530a463cf1046e63cc0a8b635aa93cdae.tar.gz
openbsd-cc11de9530a463cf1046e63cc0a8b635aa93cdae.tar.bz2
openbsd-cc11de9530a463cf1046e63cc0a8b635aa93cdae.zip
convert DSA and EC manuals from pod to mdoc
Diffstat (limited to 'src/lib/libcrypto/man')
-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
17 files changed, 2658 insertions, 11 deletions
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-12-16 02:24:08 +0000