From 24e78a11838b5b911fc4a003f68b779f8b42e6f6 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Sun, 11 Dec 2016 14:22:43 +0000 Subject: Distribute the text of ec(3) to the individual EC manuals where it belongs. Make sure EC_GROUP_new(3) points to all EC manuals and all EC manuals point back to EC_GROUP_new(3), and add some other useful links as well. Change all links to ec(3) to point to EC_GROUP_new(3) instead. --- src/lib/libcrypto/man/ECDSA_SIG_new.3 | 9 +++- src/lib/libcrypto/man/EC_GFp_simple_method.3 | 10 ++-- src/lib/libcrypto/man/EC_GROUP_copy.3 | 10 ++-- src/lib/libcrypto/man/EC_GROUP_new.3 | 19 +++++-- src/lib/libcrypto/man/EC_KEY_new.3 | 17 ++++-- src/lib/libcrypto/man/EC_POINT_add.3 | 10 ++-- src/lib/libcrypto/man/EC_POINT_new.3 | 10 ++-- src/lib/libcrypto/man/Makefile | 3 +- src/lib/libcrypto/man/crypto.3 | 4 +- src/lib/libcrypto/man/d2i_ECPKParameters.3 | 8 +-- src/lib/libcrypto/man/ec.3 | 77 ---------------------------- 11 files changed, 70 insertions(+), 107 deletions(-) delete mode 100644 src/lib/libcrypto/man/ec.3 diff --git a/src/lib/libcrypto/man/ECDSA_SIG_new.3 b/src/lib/libcrypto/man/ECDSA_SIG_new.3 index 6275ae398e..c0dbb18fc0 100644 --- a/src/lib/libcrypto/man/ECDSA_SIG_new.3 +++ b/src/lib/libcrypto/man/ECDSA_SIG_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: ECDSA_SIG_new.3,v 1.6 2016/12/11 12:21:48 schwarze Exp $ +.\" $OpenBSD: ECDSA_SIG_new.3,v 1.7 2016/12/11 14:22:43 schwarze Exp $ .\" OpenSSL e6390aca Jul 21 10:06:03 2015 -0400 .\" .\" This file was written by Nils Larsch . @@ -198,6 +198,10 @@ Most applications should use the higher level EVP interface such as or .Xr EVP_DigestVerifyInit 3 instead. +Creation of the required +.Vt EC_KEY +objects is described in +.Xr EC_KEY_new 3 . .Pp The .Vt ECDSA_SIG @@ -454,7 +458,10 @@ if (ret == -1) { } .Ed .Sh SEE ALSO +.Xr d2i_ECPKParameters 3 , .Xr DSA_new 3 , +.Xr EC_GROUP_new 3 , +.Xr EC_KEY_new 3 , .Xr EVP_DigestSignInit 3 , .Xr EVP_DigestVerifyInit 3 , .Xr RSA_new 3 diff --git a/src/lib/libcrypto/man/EC_GFp_simple_method.3 b/src/lib/libcrypto/man/EC_GFp_simple_method.3 index d2f0d76bce..7f08e707f5 100644 --- a/src/lib/libcrypto/man/EC_GFp_simple_method.3 +++ b/src/lib/libcrypto/man/EC_GFp_simple_method.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: EC_GFp_simple_method.3,v 1.5 2016/12/06 14:54:55 schwarze Exp $ +.\" $OpenBSD: EC_GFp_simple_method.3,v 1.6 2016/12/11 14:22:43 schwarze Exp $ .\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 .\" .\" This file was written by Matt Caswell . @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: December 6 2016 $ +.Dd $Mdocdate: December 11 2016 $ .Dt EC_GFP_SIMPLE_METHOD 3 .Os .Sh NAME @@ -84,6 +84,11 @@ .Sh DESCRIPTION The elliptic curve library provides a number of different implementations through a single common interface. +Each implementation is optimised for different scenarios. +An implementation is represented by an +.Vt EC_METHOD +structure. +.Pp When constructing a curve using .Xr EC_GROUP_new 3 , an implementation method must be provided. @@ -149,7 +154,6 @@ structure supports. .Sh SEE ALSO .Xr BN_mod_mul_montgomery 3 , .Xr d2i_ECPKParameters 3 , -.Xr ec 3 , .Xr EC_GROUP_copy 3 , .Xr EC_GROUP_new 3 , .Xr EC_KEY_new 3 , diff --git a/src/lib/libcrypto/man/EC_GROUP_copy.3 b/src/lib/libcrypto/man/EC_GROUP_copy.3 index 7d778c1e32..d857a21929 100644 --- a/src/lib/libcrypto/man/EC_GROUP_copy.3 +++ b/src/lib/libcrypto/man/EC_GROUP_copy.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: EC_GROUP_copy.3,v 1.6 2016/12/06 14:54:55 schwarze Exp $ +.\" $OpenBSD: EC_GROUP_copy.3,v 1.7 2016/12/11 14:22:43 schwarze Exp $ .\" OpenSSL aafbe1cc Jun 12 23:42:08 2013 +0100 .\" .\" This file was written by Matt Caswell . @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: December 6 2016 $ +.Dd $Mdocdate: December 11 2016 $ .Dt EC_GROUP_COPY 3 .Os .Sh NAME @@ -193,6 +193,11 @@ .Fa "unsigned int *k3" .Fc .Sh DESCRIPTION +These functions operate on +.Vt EC_GROUP +objects created by the functions described in +.Xr EC_GROUP_new 3 . +.Pp .Fn EC_GROUP_copy copies the curve .Fa src @@ -475,7 +480,6 @@ for a trinomial or pentanomial, respectively. Alternatively in the event of an error a 0 is returned. .Sh SEE ALSO .Xr d2i_ECPKParameters 3 , -.Xr ec 3 , .Xr EC_GFp_simple_method 3 , .Xr EC_GROUP_new 3 , .Xr EC_KEY_new 3 , diff --git a/src/lib/libcrypto/man/EC_GROUP_new.3 b/src/lib/libcrypto/man/EC_GROUP_new.3 index 27916744dd..f1227da759 100644 --- a/src/lib/libcrypto/man/EC_GROUP_new.3 +++ b/src/lib/libcrypto/man/EC_GROUP_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: EC_GROUP_new.3,v 1.5 2016/12/06 14:54:55 schwarze Exp $ +.\" $OpenBSD: EC_GROUP_new.3,v 1.6 2016/12/11 14:22:43 schwarze Exp $ .\" OpenSSL 9b86974e Mon Aug 17 15:21:33 2015 -0400 .\" .\" This file was written by Matt Caswell . @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: December 6 2016 $ +.Dd $Mdocdate: December 11 2016 $ .Dt EC_GROUP_NEW 3 .Os .Sh NAME @@ -135,6 +135,12 @@ .Fa "size_t nitems" .Fc .Sh DESCRIPTION +The EC library provides functions for performing operations on +elliptic curves over finite fields. +In general, an elliptic curve satisfies an equation of the form: +.Pp +.Dl y^2 = x^3 + ax + b +.Pp Within the library there are two forms of elliptic curves that are of interest. The first form is those defined over the prime field Fp. @@ -143,7 +149,7 @@ The elements of Fp are the integers 0 to p-1, where is a prime number. This gives us a revised elliptic curve equation as follows: .Pp -.Dl y^2 mod p = x^3 +ax + b mod p +.Dl y^2 mod p = x^3 + ax + b mod p .Pp The second form is those defined over a binary field F2^m where the elements of the field are integers of length at most m bits. @@ -156,6 +162,9 @@ polynomial. All such curves with OpenSSL use a trinomial or a pentanomial for this parameter. .Pp +An +.Vt EC_GROUP +structure is used to represent the definition of an elliptic curve. A new curve can be constructed by calling .Fn EC_GROUP_new , using the implementation provided by @@ -291,9 +300,9 @@ and return 1 on success or 0 on error. .Sh SEE ALSO .Xr d2i_ECPKParameters 3 , -.Xr ec 3 , .Xr EC_GFp_simple_method 3 , .Xr EC_GROUP_copy 3 , .Xr EC_KEY_new 3 , .Xr EC_POINT_add 3 , -.Xr EC_POINT_new 3 +.Xr EC_POINT_new 3 , +.Xr ECDSA_SIG_new 3 diff --git a/src/lib/libcrypto/man/EC_KEY_new.3 b/src/lib/libcrypto/man/EC_KEY_new.3 index fecb718a2b..742be773ee 100644 --- a/src/lib/libcrypto/man/EC_KEY_new.3 +++ b/src/lib/libcrypto/man/EC_KEY_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: EC_KEY_new.3,v 1.7 2016/12/06 14:54:55 schwarze Exp $ +.\" $OpenBSD: EC_KEY_new.3,v 1.8 2016/12/11 14:22:43 schwarze Exp $ .\" OpenSSL d900a015 Oct 8 14:40:42 2015 +0200 .\" .\" This file was written by Matt Caswell . @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: December 6 2016 $ +.Dd $Mdocdate: December 11 2016 $ .Dt EC_KEY_NEW 3 .Os .Sh NAME @@ -221,6 +221,15 @@ An .Vt EC_KEY represents a public key and (optionally) an associated private key. +The public key is a point on a curve represented by an +.Vt EC_POINT , +see +.Xr EC_POINT_new 3 . +The private key is simply a +.Vt BIGNUM , +see +.Xr BN_new 3 . +.Pp A new .Vt EC_KEY (with no associated curve) can be constructed by calling @@ -510,9 +519,9 @@ returns the point_conversion_form for the .Vt EC_KEY . .Sh SEE ALSO .Xr d2i_ECPKParameters 3 , -.Xr ec 3 , .Xr EC_GFp_simple_method 3 , .Xr EC_GROUP_copy 3 , .Xr EC_GROUP_new 3 , .Xr EC_POINT_add 3 , -.Xr EC_POINT_new 3 +.Xr EC_POINT_new 3 , +.Xr ECDSA_SIG_new 3 diff --git a/src/lib/libcrypto/man/EC_POINT_add.3 b/src/lib/libcrypto/man/EC_POINT_add.3 index 74de2fa01c..dd3d58056a 100644 --- a/src/lib/libcrypto/man/EC_POINT_add.3 +++ b/src/lib/libcrypto/man/EC_POINT_add.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: EC_POINT_add.3,v 1.5 2016/12/06 14:54:55 schwarze Exp $ +.\" $OpenBSD: EC_POINT_add.3,v 1.6 2016/12/11 14:22:43 schwarze Exp $ .\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 .\" .\" This file was written by Matt Caswell . @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: December 6 2016 $ +.Dd $Mdocdate: December 11 2016 $ .Dt EC_POINT_ADD 3 .Os .Sh NAME @@ -149,6 +149,11 @@ .Fa "const EC_GROUP *group" .Fc .Sh DESCRIPTION +These functions operate on +.Vt EC_POINT +objects created by +.Xr EC_POINT_new 3 . +.Pp .Fn EC_POINT_add adds the two points .Fa a @@ -261,7 +266,6 @@ returns 1 if the points are not equal, 0 if they are, or -1 on error. returns 1 if a precomputation has been done or 0 if not. .Sh SEE ALSO .Xr d2i_ECPKParameters 3 , -.Xr ec 3 , .Xr EC_GFp_simple_method 3 , .Xr EC_GROUP_copy 3 , .Xr EC_GROUP_new 3 , diff --git a/src/lib/libcrypto/man/EC_POINT_new.3 b/src/lib/libcrypto/man/EC_POINT_new.3 index 235c8d69bc..1e09208ffa 100644 --- a/src/lib/libcrypto/man/EC_POINT_new.3 +++ b/src/lib/libcrypto/man/EC_POINT_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: EC_POINT_new.3,v 1.5 2016/12/06 14:54:55 schwarze Exp $ +.\" $OpenBSD: EC_POINT_new.3,v 1.6 2016/12/11 14:22:43 schwarze Exp $ .\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 .\" .\" This file was written by Matt Caswell . @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: December 6 2016 $ +.Dd $Mdocdate: December 11 2016 $ .Dt EC_POINT_NEW 3 .Os .Sh NAME @@ -224,6 +224,11 @@ An .Vt EC_POINT represents a point on a curve. +A curve is represented by an +.Vt EC_GROUP +object created by the functions described in +.Xr EC_GROUP_new 3 . +.Pp A new point is constructed by calling the function .Fn EC_POINT_new and providing the @@ -460,7 +465,6 @@ returns the pointer to the on error. .Sh SEE ALSO .Xr d2i_ECPKParameters 3 , -.Xr ec 3 , .Xr EC_GFp_simple_method 3 , .Xr EC_GROUP_copy 3 , .Xr EC_GROUP_new 3 , diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index 82d313af96..4d23082d1f 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.72 2016/12/11 12:52:28 schwarze Exp $ +# $OpenBSD: Makefile,v 1.73 2016/12/11 14:22:43 schwarze Exp $ .include @@ -213,7 +213,6 @@ MAN= \ d2i_X509_REQ.3 \ d2i_X509_SIG.3 \ des_read_pw.3 \ - ec.3 \ engine.3 \ evp.3 \ i2d_PKCS7_bio_stream.3 \ diff --git a/src/lib/libcrypto/man/crypto.3 b/src/lib/libcrypto/man/crypto.3 index 4acd876375..b176b48b36 100644 --- a/src/lib/libcrypto/man/crypto.3 +++ b/src/lib/libcrypto/man/crypto.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: crypto.3,v 1.12 2016/12/11 12:21:48 schwarze Exp $ +.\" $OpenBSD: crypto.3,v 1.13 2016/12/11 14:22:43 schwarze Exp $ .\" OpenSSL a9c85cea Nov 11 09:33:55 2016 +0100 .\" .\" This file was written by Ulf Moeller and @@ -127,7 +127,7 @@ thread support, see include .Xr BIO_f_buffer 3 , .Xr BN_new 3 , -.Xr ec 3 , +.Xr EC_GROUP_new 3 , .Xr lh_new 3 . .Pp Some of the newer functions follow a naming convention using the numbers diff --git a/src/lib/libcrypto/man/d2i_ECPKParameters.3 b/src/lib/libcrypto/man/d2i_ECPKParameters.3 index 02f3c5c39b..edecdee67c 100644 --- a/src/lib/libcrypto/man/d2i_ECPKParameters.3 +++ b/src/lib/libcrypto/man/d2i_ECPKParameters.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: d2i_ECPKParameters.3,v 1.6 2016/12/06 14:54:55 schwarze Exp $ +.\" $OpenBSD: d2i_ECPKParameters.3,v 1.7 2016/12/11 14:22:43 schwarze Exp $ .\" OpenSSL 05ea606a May 20 20:52:46 2016 -0400 .\" .\" This file was written by Matt Caswell . @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: December 6 2016 $ +.Dd $Mdocdate: December 11 2016 $ .Dt D2I_ECPKPARAMETERS 3 .Os .Sh NAME @@ -378,10 +378,10 @@ and return 1 for success or 0 if an error occurs. .Sh SEE ALSO .Xr d2i_X509 3 , -.Xr ec 3 , .Xr EC_GFp_simple_method 3 , .Xr EC_GROUP_copy 3 , .Xr EC_GROUP_new 3 , .Xr EC_KEY_new 3 , .Xr EC_POINT_add 3 , -.Xr EC_POINT_new 3 +.Xr EC_POINT_new 3 , +.Xr ECDSA_SIG_new 3 diff --git a/src/lib/libcrypto/man/ec.3 b/src/lib/libcrypto/man/ec.3 deleted file mode 100644 index b3e0c8697e..0000000000 --- a/src/lib/libcrypto/man/ec.3 +++ /dev/null @@ -1,77 +0,0 @@ -.\" $OpenBSD: ec.3,v 1.4 2016/12/08 21:48:50 jmc Exp $ -.\" -.Dd $Mdocdate: December 8 2016 $ -.Dt EC 3 -.Os -.Sh NAME -.Nm ec -.Nd Elliptic Curve functions -.Sh SYNOPSIS -.In openssl/ec.h -.Sh DESCRIPTION -This library provides an extensive set of functions for performing -operations on elliptic curves over finite fields. -In general an elliptic curve is one with an equation of the form: -.Pp -.Dl y^2 = x^3 + ax + b -.Pp -An -.Vt EC_GROUP -structure is used to represent the definition of an elliptic curve. -Points on a curve are stored using an -.Vt EC_POINT -structure. -An -.Vt EC_KEY -is used to hold a private/public key pair, where a private key is simply a -.Vt BIGNUM -and a public key is a point on a curve represented by an -.Vt EC_POINT . -.Pp -The library contains a number of alternative implementations of the -different functions. -Each implementation is optimised for different scenarios. -No matter which implementation is being used, the interface remains the -same. -The library handles calling the correct implementation when an interface -function is invoked. -An implementation is represented by an -.Vt EC_METHOD -structure. -.Pp -The creation and destruction of -.Vt EC_GROUP -objects is described in -.Xr EC_GROUP_new 3 . -Functions for manipulating -.Vt EC_GROUP -objects are described in -.Xr EC_GROUP_copy 3 . -.Pp -Functions for creating, destroying and manipulating -.Vt EC_POINT -objects are explained in -.Xr EC_POINT_new 3 , -whilst functions for performing mathematical operations and tests on -.Vt EC_POINT Ns s -are covered in -.Xr EC_POINT_add 3 . -.Pp -For working with private and public keys refer to -.Xr EC_KEY_new 3 . -Implementations are covered in -.Xr EC_GFp_simple_method 3 . -.Pp -For information on encoding and decoding curve parameters to and -from ASN.1 see -.Xr d2i_ECPKParameters 3 . -.Sh SEE ALSO -.Xr crypto 3 , -.Xr d2i_ECPKParameters 3 , -.Xr EC_GFp_simple_method 3 , -.Xr EC_GROUP_copy 3 , -.Xr EC_GROUP_new 3 , -.Xr EC_KEY_new 3 , -.Xr EC_POINT_add 3 , -.Xr EC_POINT_new 3 , -.Xr EVP_PKEY_CTX_set_ec_paramgen_curve_nid 3 -- cgit v1.2.3-55-g6feb