From 90c573eba184fe31184d14ce10367f810fa1d417 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Wed, 2 Nov 2016 11:57:56 +0000 Subject: convert DSA and EC manuals from pod to mdoc --- src/lib/libcrypto/man/DSA_SIG_new.3 | 43 +++ src/lib/libcrypto/man/DSA_do_sign.3 | 68 ++++ src/lib/libcrypto/man/DSA_dup_DH.3 | 41 +++ src/lib/libcrypto/man/DSA_generate_key.3 | 34 ++ src/lib/libcrypto/man/DSA_generate_parameters.3 | 171 ++++++++++ src/lib/libcrypto/man/DSA_get_ex_new_index.3 | 47 +++ src/lib/libcrypto/man/DSA_new.3 | 46 +++ src/lib/libcrypto/man/DSA_set_method.3 | 224 ++++++++++++ src/lib/libcrypto/man/DSA_sign.3 | 122 +++++++ src/lib/libcrypto/man/DSA_size.3 | 29 ++ src/lib/libcrypto/man/EC_GFp_simple_method.3 | 108 ++++++ src/lib/libcrypto/man/EC_GROUP_copy.3 | 434 ++++++++++++++++++++++++ src/lib/libcrypto/man/EC_GROUP_new.3 | 240 +++++++++++++ src/lib/libcrypto/man/EC_KEY_new.3 | 411 ++++++++++++++++++++++ src/lib/libcrypto/man/EC_POINT_add.3 | 220 ++++++++++++ src/lib/libcrypto/man/EC_POINT_new.3 | 409 ++++++++++++++++++++++ src/lib/libcrypto/man/Makefile | 22 +- 17 files changed, 2658 insertions(+), 11 deletions(-) create mode 100644 src/lib/libcrypto/man/DSA_SIG_new.3 create mode 100644 src/lib/libcrypto/man/DSA_do_sign.3 create mode 100644 src/lib/libcrypto/man/DSA_dup_DH.3 create mode 100644 src/lib/libcrypto/man/DSA_generate_key.3 create mode 100644 src/lib/libcrypto/man/DSA_generate_parameters.3 create mode 100644 src/lib/libcrypto/man/DSA_get_ex_new_index.3 create mode 100644 src/lib/libcrypto/man/DSA_new.3 create mode 100644 src/lib/libcrypto/man/DSA_set_method.3 create mode 100644 src/lib/libcrypto/man/DSA_sign.3 create mode 100644 src/lib/libcrypto/man/DSA_size.3 create mode 100644 src/lib/libcrypto/man/EC_GFp_simple_method.3 create mode 100644 src/lib/libcrypto/man/EC_GROUP_copy.3 create mode 100644 src/lib/libcrypto/man/EC_GROUP_new.3 create mode 100644 src/lib/libcrypto/man/EC_KEY_new.3 create mode 100644 src/lib/libcrypto/man/EC_POINT_add.3 create mode 100644 src/lib/libcrypto/man/EC_POINT_new.3 (limited to 'src/lib/libcrypto/man') 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 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt DSA_SIG_NEW 3 +.Os +.Sh NAME +.Nm DSA_SIG_new , +.Nm DSA_SIG_free +.Nd allocate and free DSA signature objects +.Sh SYNOPSIS +.In openssl/dsa.h +.Ft DSA_SIG * +.Fn DSA_SIG_new void +.Ft void +.Fo DSA_SIG_free +.Fa "DSA_SIG *a" +.Fc +.Sh DESCRIPTION +.Fn DSA_SIG_new +allocates and initializes a +.Vt DSA_SIG +structure. +.Pp +.Fn DSA_SIG_free +frees the +.Vt DSA_SIG +structure and its components. +The values are erased before the memory is returned to the system. +.Sh RETURN VALUES +If the allocation fails, +.Fn DSA_SIG_new +returns +.Dv NULL +and sets an error code that can be obtained by +.Xr ERR_get_error 3 . +Otherwise it returns a pointer to the newly allocated structure. +.Sh SEE ALSO +.Xr dsa 3 , +.Xr DSA_do_sign 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn DSA_SIG_new +and +.Fn DSA_SIG_free +were 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 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt DSA_DO_SIGN 3 +.Os +.Sh NAME +.Nm DSA_do_sign , +.Nm DSA_do_verify +.Nd raw DSA signature operations +.Sh SYNOPSIS +.In openssl/dsa.h +.Ft DSA_SIG * +.Fo DSA_do_sign +.Fa "const unsigned char *dgst" +.Fa "int dlen" +.Fa "DSA *dsa" +.Fc +.Ft int +.Fo DSA_do_verify +.Fa "const unsigned char *dgst" +.Fa "int dgst_len" +.Fa "DSA_SIG *sig" +.Fa "DSA *dsa" +.Fc +.Sh DESCRIPTION +.Fn DSA_do_sign +computes a digital signature on the +.Fa dlen +byte message digest +.Fa dgst +using the private key +.Fa dsa +and returns it in a newly allocated +.Vt DSA_SIG +structure. +.Pp +.Xr DSA_sign_setup 3 +may be used to precompute part of the signing operation in case +signature generation is time-critical. +.Pp +.Fn DSA_do_verify +verifies that the signature +.Fa sig +matches a given message digest +.Fa dgst +of size +.Fa dgst_len . +.Fa dsa +is the signer's public key. +.Sh RETURN VALUES +.Fn DSA_do_sign +returns the signature or +.Dv NULL +on error. +.Fn DSA_do_verify +returns 1 for a valid signature, 0 for an incorrect signature, +and -1 on error. +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr dsa 3 , +.Xr DSA_SIG_new 3 , +.Xr DSA_sign 3 , +.Xr ERR_get_error 3 , +.Xr rand 3 +.Sh HISTORY +.Fn DSA_do_sign +and +.Fn DSA_do_verify +were 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 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt DSA_DUP_DH 3 +.Os +.Sh NAME +.Nm DSA_dup_DH +.Nd create a DH structure out of DSA structure +.Sh SYNOPSIS +.In openssl/dsa.h +.Ft DH * +.Fo DSA_dup_DH +.Fa "const DSA *r" +.Fc +.Sh DESCRIPTION +.Fn DSA_dup_DH +duplicates +.Vt DSA +parameters/keys as +.Vt DH +parameters/keys. +.Fa r->q +is lost during that conversion, but the resulting +.Vt DH +parameters contain its length. +.Sh RETURN VALUE +.Fn DSA_dup_DH +returns the new +.Vt DH +structure or +.Dv NULL +on error. +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr dh 3 , +.Xr dsa 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn DSA_dup_DH +was added in OpenSSL 0.9.4. +.Sh CAVEATS +Be 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 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt DSA_GENERATE_KEY 3 +.Os +.Sh NAME +.Nm DSA_generate_key +.Nd generate DSA key pair +.Sh SYNOPSIS +.In openssl/dsa.h +.Ft int +.Fo DSA_generate_key +.Fa "DSA *a" +.Fc +.Sh DESCRIPTION +.Fn DSA_generate_key +expects +.Fa a +to contain DSA parameters. +It generates a new key pair and stores it in +.Fa a->pub_key +and +.Fa a->priv_key . +.Sh RETURN VALUE +.Fn DSA_generate_key +returns 1 on success or 0 otherwise. +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr dsa 3 , +.Xr DSA_generate_parameters 3 , +.Xr ERR_get_error 3 , +.Xr rand 3 +.Sh HISTORY +.Fn DSA_generate_key +is 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 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt DSA_GENERATE_PARAMETERS 3 +.Os +.Sh NAME +.Nm DSA_generate_parameters_ex , +.Nm DSA_generate_parameters +.Nd generate DSA parameters +.Sh SYNOPSIS +.In openssl/dsa.h +.Ft int +.Fo DSA_generate_parameters_ex +.Fa "DSA *dsa" +.Fa "int bits" +.Fa "const unsigned char *seed" +.Fa "int seed_len" +.Fa "int *counter_ret" +.Fa "unsigned long *h_ret" +.Fa "BN_GENCB *cb" +.Fc +.Pp +Deprecated: +.Pp +.Ft DSA * +.Fo DSA_generate_parameters +.Fa "int bits" +.Fa "unsigned char *seed" +.Fa "int seed_len" +.Fa "int *counter_ret" +.Fa "unsigned long *h_ret" +.Fa "void (*callback)(int, int, void *)" +.Fa "void *cb_arg" +.Fc +.Sh DESCRIPTION +.Fn DSA_generate_parameters_ex +generates primes p and q and a generator g for use in the DSA and stores +the result in +.Fa dsa . +.Pp +.Fa bits +is the length of the prime to be generated; the DSS allows a maximum of +1024 bits. +.Pp +If +.Fa seed +is +.Dv NULL +or +.Fa seed_len +< 20, the primes will be generated at random. +Otherwise, the seed is used to generate them. +If the given seed does not yield a prime q, a new random seed is chosen +and placed at +.Fa seed . +.Pp +.Fn DSA_generate_parameters_ex +places the iteration count in +.Pf * Fa counter_ret +and a counter used for finding a generator in +.Pf * Fa h_ret , +unless these are +.Dv NULL . +.Pp +A callback function may be used to provide feedback about the progress +of the key generation. +If +.Fa cb +is not +.Dv NULL , +it will be called as shown below. +For information on the +.Vt BN_GENCB +structure, refer to +.Xr BN_GENCB_call 3 . +.Bl -bullet +.It +When a candidate for q is generated, +.Fn BN_GENCB_call cb 0 m++ +is called +.Pf ( Fa m +is 0 for the first candidate). +.It +When a candidate for q has passed a test by trial division, +.Fn BN_GENCB_call cb 1 -1 +is called. +While a candidate for q is tested by Miller-Rabin primality tests, +.Fn BN_GENCB_call cb 1 i +is called in the outer loop (once for each witness that confirms that +the candidate may be prime); +.Fa i +is the loop counter (starting at 0). +.It +When a prime q has been found, +.Fn BN_GENCB_call cb 2 0 +and +.Fn BN_GENCB_call cb 3 0 +are called. +.It +Before a candidate for p (other than the first) is generated and tested, +.Fn BN_GENCB_call cb 0 counter +is called. +.It +When a candidate for p has passed the test by trial division, +.Fn BN_GENCB_call cb 1 -1 +is called. +While it is tested by the Miller-Rabin primality test, +.Fn BN_GENCB_call cb 1 i +is called in the outer loop (once for each witness that confirms that +the candidate may be prime). +.Fa i +is the loop counter (starting at 0). +.It +When p has been found, +.Fn BN_GENCB_call cb 2 1 +is called. +.It +When the generator has been found, +.Fn BN_GENCB_call cb 3 1 +is called. +.El +.Pp +.Fn DSA_generate_parameters +(deprecated) works in much the same way as for +.Fn DSA_generate_parameters_ex , +except that no +.Fa dsa +parameter is passed and instead a newly allocated +.Vt DSA +structure is returned. +Additionally "old style" callbacks are used instead of the newer +.Vt BN_GENCB +based approach. +Refer to +.Xr BN_generate_prime 3 +for further information. +.Sh RETURN VALUE +.Fn DSA_generate_parameters_ex +returns a 1 on success, or 0 otherwise. +.Pp +.Fn DSA_generate_parameters +returns a pointer to the +.Vt DSA +structure, or +.Dv NULL +if the parameter generation fails. +.Pp +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr BN_generate_prime 3 , +.Xr dsa 3 , +.Xr DSA_free 3 , +.Xr ERR_get_error 3 , +.Xr rand 3 +.Sh HISTORY +.Fn DSA_generate_parameters +appeared in SSLeay 0.8. +The +.Fa cb_arg +argument was added in SSLeay 0.9.0. +In versions up to OpenSSL 0.9.4, +.Fn callback 1 ...\& +was called in the inner loop of the Miller-Rabin test whenever it +reached the squaring step (the parameters to +.Fn callback +did not reveal how many witnesses had been tested); since OpenSSL 0.9.5, +.Fn callback 1 ...\& +is called as in +.Xr BN_is_prime 3 , +i.e. once for each witness. +.Sh BUGS +Seed 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 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt DSA_GET_EX_NEW_INDEX 3 +.Os +.Sh NAME +.Nm DSA_get_ex_new_index , +.Nm DSA_set_ex_data , +.Nm DSA_get_ex_data +.Nd add application specific data to DSA structures +.Sh SYNOPSIS +.In openssl/dsa.h +.Ft int +.Fo DSA_get_ex_new_index +.Fa "long argl" +.Fa "void *argp" +.Fa "CRYPTO_EX_new *new_func" +.Fa "CRYPTO_EX_dup *dup_func" +.Fa "CRYPTO_EX_free *free_func" +.Fc +.Ft int +.Fo DSA_set_ex_data +.Fa "DSA *d" +.Fa "int idx" +.Fa "void *arg" +.Fc +.Ft char * +.Fo DSA_get_ex_data +.Fa "DSA *d" +.Fa "int idx" +.Fc +.Sh DESCRIPTION +These functions handle application specific data in +.Vt DSA +structures. +Their usage is identical to that of +.Xr RSA_get_ex_new_index 3 , +.Xr RSA_set_ex_data 3 , +and +.Xr RSA_get_ex_data 3 . +.Sh SEE ALSO +.Xr dsa 3 , +.Xr RSA_get_ex_new_index 3 +.Sh HISTORY +.Fn DSA_get_ex_new_index , +.Fn DSA_set_ex_data , +and +.Fn DSA_get_ex_data +are 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 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt DSA_NEW 3 +.Os +.Sh NAME +.Nm DSA_new , +.Nm DSA_free +.Nd allocate and free DSA objects +.Sh SYNOPSIS +.In openssl/dsa.h +.Ft DSA* +.Fn DSA_new void +.Ft void +.Fo DSA_free +.Fa "DSA *dsa" +.Fc +.Sh DESCRIPTION +.Fn DSA_new +allocates and initializes a +.Vt DSA +structure. +It is equivalent to calling +.Fn DSA_new_method NULL . +.Pp +.Fn DSA_free +frees the +.Vt DSA +structure and its components. +The values are erased before the memory is returned to the system. +.Sh RETURN VALUES +If the allocation fails, +.Fn DSA_new +returns +.Dv NULL +and sets an error code that can be obtained by +.Xr ERR_get_error 3 . +Otherwise it returns a pointer to the newly allocated structure. +.Sh SEE ALSO +.Xr dsa 3 , +.Xr DSA_generate_key 3 , +.Xr DSA_generate_parameters 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn DSA_new +and +.Fn DSA_free +are 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 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt DSA_SET_METHOD 3 +.Os +.Sh NAME +.Nm DSA_set_default_method , +.Nm DSA_get_default_method , +.Nm DSA_set_method , +.Nm DSA_new_method , +.Nm DSA_OpenSSL , +.Nm DSA_set_default_openssl_method , +.Nm DSA_get_default_openssl_method +.Nd select DSA method +.Sh SYNOPSIS +.In openssl/dsa.h +.In openssl/engine.h +.Ft void +.Fo DSA_set_default_method +.Fa "const DSA_METHOD *meth" +.Fc +.Ft const DSA_METHOD * +.Fn DSA_get_default_method void +.Ft int +.Fo DSA_set_method +.Fa "DSA *dsa" +.Fa "const DSA_METHOD *meth" +.Fc +.Ft DSA * +.Fo DSA_new_method +.Fa "ENGINE *engine" +.Fc +.Ft DSA_METHOD * +.Fn DSA_OpenSSL void +.Sh DESCRIPTION +A +.Vt DSA_METHOD +specifies the functions that OpenSSL uses for DSA operations. +By modifying the method, alternative implementations such as hardware +accelerators may be used. +See the +.Sx CAVEATS +section for how these DSA API functions are affected by the use of +.Xr engine 3 +API calls. +.Pp +Initially, the default +.Vt DSA_METHOD +is the OpenSSL internal implementation, as returned by +.Fn DSA_OpenSSL . +.Pp +.Fn DSA_set_default_method +makes +.Fa meth +the default method for all +.Vt DSA +structures created later. +.Sy NB : +This is true only whilst no +.Vt ENGINE +has been set as a default for DSA, so this function is no longer +recommended. +.Pp +.Fn DSA_get_default_method +returns a pointer to the current default +.Vt DSA_METHOD . +However, the meaningfulness of this result is dependent on whether the +.Xr engine 3 +API is being used, so this function is no longer recommended. +.Pp +.Fn DSA_set_method +selects +.Fa meth +to perform all operations using the key +.Fa dsa . +This will replace the +.Vt DSA_METHOD +used by the DSA key and if the previous method was supplied by an +.Vt ENGINE , +the handle to that +.Vt ENGINE +will be released during the change. +It is possible to have DSA keys that only work with certain +.Vt DSA_METHOD +implementations (eg. from an +.Vt ENGINE +module that supports embedded hardware-protected keys), +and in such cases attempting to change the +.Vt DSA_METHOD +for the key can have unexpected results. +.Pp +.Fn DSA_new_method +allocates and initializes a +.Vt DSA +structure so that +.Fa engine +will be used for the DSA operations. +If +.Fa engine +is +.Dv NULL , +the default engine for DSA operations is used, and if no +default +.Vt ENGINE +is set, the +.Vt DSA_METHOD +controlled by +.Fn DSA_set_default_method +is used. +.Sh THE DSA_METHOD STRUCTURE +.Bd -literal +struct +{ + /* name of the implementation */ + const char *name; + + /* sign */ + DSA_SIG *(*dsa_do_sign)(const unsigned char *dgst, int dlen, + DSA *dsa); + + /* pre-compute k^-1 and r */ + int (*dsa_sign_setup)(DSA *dsa, BN_CTX *ctx_in, BIGNUM **kinvp, + BIGNUM **rp); + + /* verify */ + int (*dsa_do_verify)(const unsigned char *dgst, int dgst_len, + DSA_SIG *sig, DSA *dsa); + + /* compute rr = a1^p1 * a2^p2 mod m (May be NULL for some + implementations) */ + int (*dsa_mod_exp)(DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1, + BIGNUM *a2, BIGNUM *p2, BIGNUM *m, + BN_CTX *ctx, BN_MONT_CTX *in_mont); + + /* compute r = a ^ p mod m (May be NULL for some implementations) */ + int (*bn_mod_exp)(DSA *dsa, BIGNUM *r, BIGNUM *a, + const BIGNUM *p, const BIGNUM *m, + BN_CTX *ctx, BN_MONT_CTX *m_ctx); + + /* called at DSA_new */ + int (*init)(DSA *DSA); + + /* called at DSA_free */ + int (*finish)(DSA *DSA); + + int flags; + + char *app_data; /* ?? */ + +} DSA_METHOD; +.Ed +.Sh RETURN VALUES +.Fn DSA_OpenSSL +and +.Fn DSA_get_default_method +return pointers to the respective +.Vt DSA_METHOD Ns s. +.Pp +.Fn DSA_set_method +returns non-zero if the provided +.Fa meth +was successfully set as the method for +.Fa dsa +(including unloading the +.Vt ENGINE +handle if the previous method was supplied by an +.Vt ENGINE ) . +.Pp +.Fn DSA_new_method +returns +.Dv NULL +and sets an error code that can be obtained by +.Xr ERR_get_error 3 +if the allocation fails. +Otherwise it returns a pointer to the newly allocated structure. +.Sh SEE ALSO +.Xr dsa 3 , +.Xr DSA_new 3 +.Sh HISTORY +.Fn DSA_set_default_method , +.Fn DSA_get_default_method , +.Fn DSA_set_method , +.Fn DSA_new_method , +and +.Fn DSA_OpenSSL +were added in OpenSSL 0.9.4. +.Pp +.Fn DSA_set_default_openssl_method +and +.Fn DSA_get_default_openssl_method +replaced +.Fn DSA_set_default_method +and +.Fn DSA_get_default_method +respectively, and +.Fn DSA_set_method +and +.Fn DSA_new_method +were altered to use +.Vt ENGINE Ns s +rather than +.Vt DSA_METHOD Ns s +during development of the engine version of OpenSSL 0.9.6. +For 0.9.7, the handling of defaults in the +.Xr engine 3 +API was restructured so that this change was reversed, and behaviour +of the other functions resembled more closely the previous behaviour. +The behaviour of defaults in the +.Xr engine 3 +API now transparently overrides the behaviour of defaults in the +DSA API without requiring changing these function prototypes. +.Sh CAVEATS +As of version 0.9.7, DSA_METHOD implementations are grouped together +with other algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in +.Vt ENGINE +modules. +If a default +.Vt ENGINE +is specified for DSA functionality using an +.Xr engine 3 +API function, that will override any DSA defaults set using the DSA API +.Pq ie. DSA_set_default_method . +For this reason, the +.Xr engine 3 +API is the recommended way to control default implementations for +use 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 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt DSA_SIGN 3 +.Os +.Sh NAME +.Nm DSA_sign , +.Nm DSA_sign_setup , +.Nm DSA_verify +.Nd DSA signatures +.Sh SYNOPSIS +.In openssl/dsa.h +.Ft int +.Fo DSA_sign +.Fa "int type" +.Fa "const unsigned char *dgst" +.Fa "int len" +.Fa "unsigned char *sigret" +.Fa "unsigned int *siglen" +.Fa "DSA *dsa" +.Fc +.Ft int +.Fo DSA_sign_setup +.Fa "DSA *dsa" +.Fa "BN_CTX *ctx" +.Fa "BIGNUM **kinvp" +.Fa "BIGNUM **rp" +.Fc +.Ft int +.Fo DSA_verify +.Fa "int type" +.Fa "const unsigned char *dgst" +.Fa "int len" +.Fa "unsigned char *sigbuf" +.Fa "int siglen" +.Fa "DSA *dsa" +.Fc +.Sh DESCRIPTION +.Fn DSA_sign +computes a digital signature on the +.Fa len +byte message digest +.Fa dgst +using the private key +.Fa dsa +and places its ASN.1 DER encoding at +.Fa sigret . +The length of the signature is placed in +.Pf * Fa siglen . +.Fa sigret +must point to +.Fn DSA_size dsa +bytes of memory. +.Pp +.Fn DSA_sign_setup +may be used to precompute part of the signing operation in case +signature generation is time-critical. +It expects +.Fa dsa +to contain DSA parameters. +It places the precomputed values in newly allocated +.Vt BIGNUM Ns s +at +.Pf * Fa kinvp +and +.Pf * Fa rp , +after freeing the old ones unless +.Fa kinvp +and +.Fa rp +are +.Dv NULL . +These values may be passed to +.Fn DSA_sign +in +.Fa dsa->kinv +and +.Sy dsa->r . +.Fa ctx +is a pre-allocated +.Vt BN_CTX +or +.Dv NULL . +.Pp +.Fn DSA_verify +verifies that the signature +.Fa sigbuf +of size +.Fa siglen +matches a given message digest +.Fa dgst +of size +.Fa len . +.Fa dsa +is the signer's public key. +.Pp +The +.Fa type +parameter is ignored. +.Sh RETURN VALUES +.Fn DSA_sign +and +.Fn DSA_sign_setup +return 1 on success or 0 on error. +.Fn DSA_verify +returns 1 for a valid signature, 0 for an incorrect signature, +and -1 on error. +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr dsa 3 , +.Xr DSA_do_sign 3 , +.Xr ERR_get_error 3 , +.Xr rand 3 +.Sh STANDARDS +US Federal Information Processing Standard FIPS 186 (Digital Signature +Standard, DSS), ANSI X9.30 +.Sh HISTORY +.Fn DSA_sign +and +.Fn DSA_verify +are available in all versions of SSLeay. +.Fn DSA_sign_setup +was 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 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt DSA_SIZE 3 +.Os +.Sh NAME +.Nm DSA_size +.Nd get DSA signature size +.Sh SYNOPSIS +.In openssl/dsa.h +.Ft int +.Fo DSA_size +.Fa "const DSA *dsa" +.Fc +.Sh DESCRIPTION +This function returns the size of an ASN.1 encoded DSA signature in +bytes. +It can be used to determine how much memory must be allocated for a DSA +signature. +.Pp +.Fa dsa->q +must not be +.Dv NULL . +.Sh RETURN VALUE +The size in bytes. +.Sh SEE ALSO +.Xr dsa 3 , +.Xr DSA_sign 3 +.Sh HISTORY +.Fn DSA_size +is 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 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt EC_GFP_SIMPLE_METHOD 3 +.Os +.Sh NAME +.Nm EC_GFp_simple_method , +.Nm EC_GFp_mont_method , +.Nm EC_GFp_nist_method , +.Nm EC_GFp_nistp224_method , +.Nm EC_GFp_nistp256_method , +.Nm EC_GFp_nistp521_method , +.Nm EC_GF2m_simple_method , +.Nm EC_METHOD_get_field_type +.Nd obtain EC_METHOD objects +.Sh SYNOPSIS +.In openssl/ec.h +.Ft const EC_METHOD * +.Fn EC_GFp_simple_method void +.Ft const EC_METHOD * +.Fn EC_GFp_mont_method void +.Ft const EC_METHOD * +.Fn EC_GFp_nist_method void +.Ft const EC_METHOD * +.Fn EC_GFp_nistp224_method void +.Ft const EC_METHOD * +.Fn EC_GFp_nistp256_method void +.Ft const EC_METHOD * +.Fn EC_GFp_nistp521_method void +.Ft const EC_METHOD * +.Fn EC_GF2m_simple_method void +.Ft int +.Fo EC_METHOD_get_field_type +.Fa "const EC_METHOD *meth" +.Fc +.Sh DESCRIPTION +The elliptic curve library provides a number of different +implementations through a single common interface. +When constructing a curve using +.Xr EC_GROUP_new 3 , +an implementation method must be provided. +The functions described here all return a const pointer to an +.Sy EC_METHOD +structure that can be passed to +.Xr EC_GROUP_new . +It is important that the correct implementation type for the form +of curve selected is used. +.Pp +For F2^m curves there is only one implementation choice, +.Fn EC_GF2_simple_method . +.Pp +For Fp curves the lowest common denominator implementation is the +.Fn EC_GFp_simple_method +implementation. +All other implementations are based on this one. +.Fn EC_GFp_mont_method +adds the use of montgomery multiplication (see +.Xr BN_mod_mul_montgomery 3 ) . +.Fn EC_GFp_nist_method +offers an implementation optimised for use with NIST recommended +curves. +NIST curves are available through +.Xr EC_GROUP_new_by_curve_name 3 . +.Pp +The functions +.Fn EC_GFp_nistp224_method , +.Fn EC_GFp_nistp256_method , +and +.Fn EC_GFp_nistp521_method +offer 64 bit optimised implementations for the NIST P224, P256 and +P521 curves respectively. +Note, however, that these implementations are not available on all +platforms. +.Pp +.Fn EC_METHOD_get_field_type +identifies what type of field the +.Vt EC_METHOD +structure supports, which will be either F2^m or Fp. +If the field type is Fp, then the value +.Dv NID_X9_62_prime_field +is returned. +If the field type is F2^m, then the value +.Dv NID_X9_62_characteristic_two_field +is returned. +These values are defined in the +.In openssl/obj_mac.h +header file. +.Sh RETURN VALUES +All +.Fn EC_GFp* +functions and +.Fn EC_GF2m_simple_method +always return a const pointer to an +.Vt EC_METHOD +structure. +.Pp +.Fn EC_METHOD_get_field_type +returns an integer that identifies the type of field the +.Vt EC_METHOD +structure supports. +.Sh SEE ALSO +.Xr BN_mod_mul_montgomery 3 , +.Xr crypto 3 , +.Xr d2i_ECPKParameters 3 , +.Xr ec 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 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 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt EC_GROUP_COPY 3 +.Os +.Sh NAME +.Nm EC_GROUP_copy , +.Nm EC_GROUP_dup , +.Nm EC_GROUP_method_of , +.Nm EC_GROUP_set_generator , +.Nm EC_GROUP_get0_generator , +.Nm EC_GROUP_get_order , +.Nm EC_GROUP_get_cofactor , +.Nm EC_GROUP_set_curve_name , +.Nm EC_GROUP_get_curve_name , +.Nm EC_GROUP_set_asn1_flag , +.Nm EC_GROUP_get_asn1_flag , +.Nm EC_GROUP_set_point_conversion_form , +.Nm EC_GROUP_get_point_conversion_form , +.Nm EC_GROUP_get0_seed , +.Nm EC_GROUP_get_seed_len , +.Nm EC_GROUP_set_seed , +.Nm EC_GROUP_get_degree , +.Nm EC_GROUP_check , +.Nm EC_GROUP_check_discriminant , +.Nm EC_GROUP_cmp , +.Nm EC_GROUP_get_basis_type , +.Nm EC_GROUP_get_trinomial_basis , +.Nm EC_GROUP_get_pentanomial_basis +.Nd manipulate EC_GROUP objects +.Sh SYNOPSIS +.In openssl/ec.h +.In openssl/bn.h +.Ft int +.Fo EC_GROUP_copy +.Fa "EC_GROUP *dst" +.Fa "const EC_GROUP *src" +.Fc +.Ft EC_GROUP * +.Fo EC_GROUP_dup +.Fa "const EC_GROUP *src" +.Fc +.Ft const EC_METHOD * +.Fo EC_GROUP_method_of +.Fa "const EC_GROUP *group" +.Fc +.Ft int +.Fo EC_GROUP_set_generator +.Fa "EC_GROUP *group" +.Fa "const EC_POINT *generator" +.Fa "const BIGNUM *order" +.Fa "const BIGNUM *cofactor" +.Fc +.Ft const EC_POINT * +.Fo EC_GROUP_get0_generator +.Fa "const EC_GROUP *group" +.Fc +.Ft int +.Fo EC_GROUP_get_order +.Fa "const EC_GROUP *group" +.Fa "BIGNUM *order" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_get_cofactor +.Fa "const EC_GROUP *group" +.Fa "BIGNUM *cofactor" +.Fa "BN_CTX *ctx" +.Fc +.Ft void +.Fo EC_GROUP_set_curve_name +.Fa "EC_GROUP *group" +.Fa "int nid" +.Fc +.Ft int +.Fo EC_GROUP_get_curve_name +.Fa "const EC_GROUP *group" +.Fc +.Ft void +.Fo EC_GROUP_set_asn1_flag +.Fa "EC_GROUP *group" +.Fa "int flag" +.Fc +.Ft int +.Fo EC_GROUP_get_asn1_flag +.Fa "const EC_GROUP *group" +.Fc +.Ft void +.Fo EC_GROUP_set_point_conversion_form +.Fa "EC_GROUP *group" +.Fa "point_conversion_form_t form" +.Fc +.Ft point_conversion_form_t +.Fo EC_GROUP_get_point_conversion_form +.Fa "const EC_GROUP *" +.Fc +.Ft unsigned char * +.Fo EC_GROUP_get0_seed +.Fa "const EC_GROUP *x" +.Fc +.Ft size_t +.Fo EC_GROUP_get_seed_len +.Fa "const EC_GROUP *" +.Fc +.Ft size_t +.Fo EC_GROUP_set_seed +.Fa "EC_GROUP *" +.Fa "const unsigned char *" +.Fa "size_t len" +.Fc +.Ft int +.Fo EC_GROUP_get_degree +.Fa "const EC_GROUP *group" +.Fc +.Ft int +.Fo EC_GROUP_check +.Fa "const EC_GROUP *group" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_check_discriminant +.Fa "const EC_GROUP *group" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_cmp +.Fa "const EC_GROUP *a" +.Fa "const EC_GROUP *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_get_basis_type +.Fa "const EC_GROUP *" +.Fc +.Ft int +.Fo EC_GROUP_get_trinomial_basis +.Fa "const EC_GROUP *" +.Fa "unsigned int *k" +.Fc +.Ft int +.Fo EC_GROUP_get_pentanomial_basis +.Fa "const EC_GROUP *" +.Fa "unsigned int *k1" +.Fa "unsigned int *k2" +.Fa "unsigned int *k3" +.Fc +.Sh DESCRIPTION +.Fn EC_GROUP_copy +copies the curve +.Fa src +into +.Fa dst . +Both +.Fa src +and +.Fa dst +must use the same +.Vt EC_METHOD . +.Pp +.Fn EC_GROUP_dup +creates a new +.Vt EC_GROUP +object and copies the content from +.Fa src +to the newly created +.Vt EC_GROUP +object. +.Pp +.Fn EC_GROUP_method_of +obtains the +.Vt EC_METHOD +of +.Fa group . +.Pp +.Fn EC_GROUP_set_generator +sets curve paramaters that must be agreed by all participants using +the curve. +These paramaters include the +.Fa generator , +the +.Fa order +and the +.Fa cofactor . +The +.Fa generator +is a well defined point on the curve chosen for cryptographic +operations. +Integers used for point multiplications will be between 0 and +.Fa order No - 1 . +The +.Fa order +multipied by the +.Fa cofactor +gives the number of points on the curve. +.Pp +.Fn EC_GROUP_get0_generator +returns the generator for the identified +.Fa group . +.Pp +The functions +.Fn EC_GROUP_get_order +and +.Fn EC_GROUP_get_cofactor +populate the provided +.Fa order +and +.Fa cofactor +parameters with the respective order and cofactors for the +.Fa group . +.Pp +The functions +.Fn EC_GROUP_set_curve_name +and +.Fn EC_GROUP_get_curve_name +set and get the NID for the curve, respectively (see +.Xr EC_GROUP_new 3 ) . +If a curve does not have a NID associated with it, then +.Fn EC_GROUP_get_curve_name +will return 0. +.Pp +The asn1_flag value on a curve is used to determine whether there is a +specific ASN1 OID to describe the curve or not. +If 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 +.Fn EC_GROUP_get_asn1_flag +and +.Fn EC_GROUP_set_asn1_flag +get and set the status of the asn1_flag for the curve. +If set, then the curve_name must also be set. +.Pp +The point_conversion_form for a curve controls how +.Vt EC_POINT +data is encoded as ASN1 as defined in X9.62 (ECDSA). +.Vt point_conversion_form_t +is an enum defined as follows: +.Bd -literal +typedef enum { + /** the point is encoded as z||x, where the octet z specifies + * which solution of the quadratic equation y is */ + POINT_CONVERSION_COMPRESSED = 2, + /** the point is encoded as z||x||y, where z is the octet 0x02 */ + POINT_CONVERSION_UNCOMPRESSED = 4, + /** the point is encoded as z||x||y, where the octet z specifies + * which solution of the quadratic equation y is */ + POINT_CONVERSION_HYBRID = 6 +} point_conversion_form_t; +.Ed +.Pp +For +.Dv POINT_CONVERSION_UNCOMPRESSED +the point is encoded as an octet signifying the UNCOMPRESSED form +has been used followed by the octets for x, followed by the octets +for y. +.Pp +For any given x co-ordinate for a point on a curve it is possible to +derive two possible y values. +For +.Dv POINT_CONVERSION_COMPRESSED +the point is encoded as an octet signifying that the COMPRESSED +form has been used AND which of the two possible solutions for y +has been used, followed by the octets for x. +.Pp +For +.Dv POINT_CONVERSION_HYBRID +the point is encoded as an octet signifying the HYBRID form has +been used AND which of the two possible solutions for y has been +used, followed by the octets for x, followed by the octets for y. +.Pp +The functions +.Fn EC_GROUP_set_point_conversion_form +and +.Fn EC_GROUP_get_point_conversion_form +set and get the point_conversion_form for the curve, respectively. +.Pp +ANSI X9.62 (ECDSA standard) defines a method of generating the curve +parameter b from a random number. +This provides advantages in that a parameter obtained in this way is +highly unlikely to be susceptible to special purpose attacks, or have +any trapdoors in it. +If the seed is present for a curve then the b parameter was generated in +a verifiable fashion using that seed. +The OpenSSL EC library does not use this seed value but does enable you +to inspect it using +.Fn EC_GROUP_get0_seed . +This returns a pointer to a memory block containing the seed that was +used. +The length of the memory block can be obtained using +.Fn EC_GROUP_get_seed_len . +A number of the builtin curves within the library provide seed values +that can be obtained. +It is also possible to set a custom seed using +.Fn EC_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 this seed value, although it will be +preserved in any ASN1 based communications. +.Pp +.Fn EC_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 the value m. +.Pp +The function +.Fn EC_GROUP_check_discriminant +calculates the discriminant for the curve and verifies that it is +valid. +For 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 simply b. +In either case for the curve to be valid the discriminant must be +non-zero. +.Pp +The function +.Fn EC_GROUP_check +performs a number of checks on a curve to verify that it is valid. +Checks performed include verifying that the discriminant is non zero; +that a generator has been defined; that the generator is on the curve +and has the correct order. +.Pp +.Fn EC_GROUP_cmp +compares +.Fa a +and +.Fa b +to determine whether they represent the same curve or not. +.Pp +The functions +.Fn EC_GROUP_get_basis_type , +.Fn EC_GROUP_get_trinomial_basis , +and +.Fn EC_GROUP_get_pentanomial_basis +should only be called for curves defined over an F2^m field. +Addition and multiplication operations within an F2^m field are +performed using an irreducible polynomial function f(x). +This function is either a trinomial of the form: +.Pp +.Dl f(x) = x^m + x^k + 1 with m > k >= 1 +.Pp +or a pentanomial of the form: +.Pp +.Dl f(x) = x^m + x^k3 + x^k2 + x^k1 + 1 with m > k3 > k2 > k1 >= 1 +.Pp +The function +.Fn EC_GROUP_get_basis_type +returns a NID identifying whether a trinomial or pentanomial is in +use for the field. +The function +.Fn EC_GROUP_get_trinomial_basis +must only be called where f(x) is of the trinomial form, and returns +the value of +.Fa k . +Similarly, the function +.Fn EC_GROUP_get_pentanomial_basis +must only be called where f(x) is of the pentanomial form, and +returns the values of +.Fa k1 , +.Fa k2 , +and +.Fa k3 . +.Sh RETURN VALUES +The following functions return 1 on success or 0 on error: +.Fn EC_GROUP_copy , +.Fn EC_GROUP_set_generator , +.Fn EC_GROUP_check , +.Fn EC_GROUP_check_discriminant , +.Fn EC_GROUP_get_trinomial_basis , +and +.Fn EC_GROUP_get_pentanomial_basis . +.Pp +.Fn EC_GROUP_dup +returns a pointer to the duplicated curve or +.Dv NULL +on error. +.Pp +.Fn EC_GROUP_method_of +returns the +.Vt EC_METHOD +implementation in use for the given curve or +.Dv NULL +on error. +.Pp +.Fn EC_GROUP_get0_generator +returns the generator for the given curve or +.Dv NULL +on error. +.Pp +.Fn EC_GROUP_get_order , +.Fn EC_GROUP_get_cofactor , +.Fn EC_GROUP_get_curve_name , +.Fn EC_GROUP_get_asn1_flag , +.Fn EC_GROUP_get_point_conversion_form , +and +.Fn EC_GROUP_get_degree +return the order, cofactor, curve name (NID), ASN1 flag, +point_conversion_form and degree for the specified curve, respectively. +If there is no curve name associated with a curve then +.Fn EC_GROUP_get_curve_name +returns 0. +.Pp +.Fn EC_GROUP_get0_seed +returns a pointer to the seed that was used to generate the parameter +b, or +.Dv NULL +if the seed is not specified. +.Fn EC_GROUP_get_seed_len +returns the length of the seed or 0 if the seed is not specified. +.Pp +.Fn EC_GROUP_set_seed +returns the length of the seed that has been set. +If the supplied seed is +.Dv NULL +or the supplied seed length is 0, the return value will be 1. +On error 0 is returned. +.Pp +.Fn EC_GROUP_cmp +returns 0 if the curves are equal, 1 if they are not equal, +or -1 on error. +.Pp +.Fn EC_GROUP_get_basis_type +returns the values +.Dv NID_X9_62_tpBasis +or +.Dv NID_X9_62_ppBasis +as defined in +.In openssl/obj_mac.h +for a trinomial or pentanomial, respectively. +Alternatively in the event of an error a 0 is returned. +.Sh SEE ALSO +.Xr crypto 3 , +.Xr d2i_ECPKParameters 3 , +.Xr ec 3 , +.Xr EC_GFp_simple_method 3 , +.Xr EC_GROUP_new 3 , +.Xr EC_KEY_new 3 , +.Xr EC_POINT_add 3 , +.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 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt EC_GROUP_NEW 3 +.Os +.Sh NAME +.Nm EC_GROUP_new , +.Nm EC_GROUP_free , +.Nm EC_GROUP_clear_free , +.Nm EC_GROUP_new_curve_GFp , +.Nm EC_GROUP_new_curve_GF2m , +.Nm EC_GROUP_new_by_curve_name , +.Nm EC_GROUP_set_curve_GFp , +.Nm EC_GROUP_get_curve_GFp , +.Nm EC_GROUP_set_curve_GF2m , +.Nm EC_GROUP_get_curve_GF2m , +.Nm EC_get_builtin_curves +.Nd create and destroy EC_GROUP objects +.Sh SYNOPSIS +.In openssl/ec.h +.In openssl/bn.h +.Ft EC_GROUP * +.Fo EC_GROUP_new +.Fa "const EC_METHOD *meth" +.Fc +.Ft void +.Fo EC_GROUP_free +.Fa "EC_GROUP *group" +.Fc +.Ft void +.Fo EC_GROUP_clear_free +.Fa "EC_GROUP *group" +.Fc +.Ft EC_GROUP * +.Fo EC_GROUP_new_curve_GFp +.Fa "const BIGNUM *p" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft EC_GROUP * +.Fo EC_GROUP_new_curve_GF2m +.Fa "const BIGNUM *p" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft EC_GROUP * +.Fo EC_GROUP_new_by_curve_name +.Fa "int nid" +.Fc +.Ft int +.Fo EC_GROUP_set_curve_GFp +.Fa "EC_GROUP *group" +.Fa "const BIGNUM *p" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_get_curve_GFp +.Fa "const EC_GROUP *group" +.Fa "BIGNUM *p" +.Fa "BIGNUM *a" +.Fa "BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_set_curve_GF2m +.Fa "EC_GROUP *group" +.Fa "const BIGNUM *p" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_get_curve_GF2m +.Fa "const EC_GROUP *group" +.Fa "BIGNUM *p" +.Fa "BIGNUM *a" +.Fa "BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft size_t +.Fo EC_get_builtin_curves +.Fa "EC_builtin_curve *r" +.Fa "size_t nitems" +.Fc +.Sh DESCRIPTION +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. +The elements of Fp are the integers 0 to p-1, where +.Fa p +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 +.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. +For this form the elliptic curve equation is modified to: +.Pp +.Dl y^2 + xy = x^3 + ax^2 + b (where b != 0) +.Pp +Operations in a binary field are performed relative to an irreducible +polynomial. +All such curves with OpenSSL use a trinomial or a pentanomial for this +parameter. +.Pp +A new curve can be constructed by calling +.Fn EC_GROUP_new , +using the implementation provided by +.Fa meth +(see +.Xr EC_GFp_simple_method 3 ) . +It is then necessary to call either +.Fn EC_GROUP_set_curve_GFp +or +.Fn EC_GROUP_set_curve_GF2m +as appropriate to create a curve defined over Fp or over F2^m, respectively. +.Pp +.Fn EC_GROUP_set_curve_GFp +sets the curve parameters +.Fa p , +.Fa a , +and +.Fa b +for a curve over Fp stored in +.Fa group . +.Fn EC_group_get_curve_GFp +obtains the previously set curve parameters. +.Pp +.Fn EC_GROUP_set_curve_GF2m +sets the equivalent curve parameters for a curve over F2^m. +In this case +.Fa p +represents the irreducible polynomial - each bit represents a term in +the polynomial. +Therefore there will either be three or five bits set dependent on +whether the polynomial is a trinomial or a pentanomial. +.Fn EC_group_get_curve_GF2m +obtains the previously set curve parameters. +.Pp +The functions +.Fn EC_GROUP_new_curve_GFp +and +.Fn EC_GROUP_new_curve_GF2m +are shortcuts for calling +.Fn EC_GROUP_new +and the appropriate +.Fn EC_GROUP_set_curve_* +function. +An appropriate default implementation method will be used. +.Pp +Whilst the library can be used to create any curve using the functions +described above, there are also a number of predefined curves that are +available. +In order to obtain a list of all of the predefined curves, call the +function +.Fn EC_get_builtin_curves . +The parameter +.Fa r +should be an array of +.Vt EC_builtin_cure +structures of size +.Fa nitems . +The function will populate the +.Fa r +array with information about the builtin curves. +If +.Fa nitems +is less than the total number of curves available, then the first +.Fa nitems +curves will be returned. +Otherwise the total number of curves will be provided. +The return value is the total number of curves available (whether that +number has been populated in +.Fa r +or not). +Passing a +.Dv NULL +.Fa r , +or setting +.Fa nitems +to 0, will do nothing other than return the total number of curves +available. +The +.Vt EC_builtin_curve +structure is defined as follows: +.Bd -literal +typedef struct { + int nid; + const char *comment; +} EC_builtin_curve; +.Ed +.Pp +Each +.Vt EC_builtin_curve +item has a unique integer id +.Pq Fa nid +and a human readable comment string describing the curve. +.Pp +In order to construct a builtin curve use the function +.Fn EC_GROUP_new_by_curve_name +and provide the +.Fa nid +of the curve to be constructed. +.Pp +.Fn EC_GROUP_free +frees the memory associated with the +.Vt EC_GROUP . +.Pp +.Fn EC_GROUP_clear_free +destroys any sensitive data held within the +.Vt EC_GROUP +and then frees its memory. +.Sh RETURN VALUES +All +.Fn EC_GROUP_new* +functions return a pointer to the newly constructed group or +.Dv NULL +on error. +.Pp +.Fn EC_get_builtin_curves +returns the number of builtin curves that are available. +.Pp +.Fn EC_GROUP_set_curve_GFp , +.Fn EC_GROUP_get_curve_GFp , +.Fn EC_GROUP_set_curve_GF2m , +and +.Fn EC_GROUP_get_curve_GF2m +return 1 on success or 0 on error. +.Sh SEE ALSO +.Xr crypto 3 , +.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 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 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt EC_KEY_NEW 3 +.Os +.Sh NAME +.Nm EC_KEY_new , +.Nm EC_KEY_get_flags , +.Nm EC_KEY_set_flags , +.Nm EC_KEY_clear_flags , +.Nm EC_KEY_new_by_curve_name , +.Nm EC_KEY_free , +.Nm EC_KEY_copy , +.Nm EC_KEY_dup , +.Nm EC_KEY_up_ref , +.Nm EC_KEY_get0_group , +.Nm EC_KEY_set_group , +.Nm EC_KEY_get0_private_key , +.Nm EC_KEY_set_private_key , +.Nm EC_KEY_get0_public_key , +.Nm EC_KEY_set_public_key , +.Nm EC_KEY_get_enc_flags , +.Nm EC_KEY_set_enc_flags , +.Nm EC_KEY_get_conv_form , +.Nm EC_KEY_set_conv_form , +.Nm EC_KEY_get_key_method_data , +.Nm EC_KEY_insert_key_method_data , +.Nm EC_KEY_set_asn1_flag , +.Nm EC_KEY_precompute_mult , +.Nm EC_KEY_generate_key , +.Nm EC_KEY_check_key , +.Nm EC_KEY_set_public_key_affine_coordinates +.Nd create, destroy and manipulate EC_KEY objects +.Sh SYNOPSIS +.In openssl/ec.h +.In openssl/bn.h +.Ft EC_KEY * +.Fn EC_KEY_new void +.Ft int +.Fo EC_KEY_get_flags +.Fa "const EC_KEY *key" +.Fc +.Ft void +.Fo EC_KEY_set_flags +.Fa "EC_KEY *key" +.Fa "int flags" +.Fc +.Ft void +.Fo EC_KEY_clear_flags +.Fa "EC_KEY *key" +.Fa "int flags" +.Fc +.Ft EC_KEY * +.Fo EC_KEY_new_by_curve_name +.Fa "int nid" +.Fc +.Ft void +.Fo EC_KEY_free +.Fa "EC_KEY *key" +.Fc +.Ft EC_KEY * +.Fo EC_KEY_copy +.Fa "EC_KEY *dst" +.Fa "const EC_KEY *src" +.Fc +.Ft EC_KEY * +.Fo EC_KEY_dup +.Fa "const EC_KEY *src" +.Fc +.Ft int +.Fo EC_KEY_up_ref +.Fa "EC_KEY *key" +.Fc +.Ft const EC_GROUP * +.Fo EC_KEY_get0_group +.Fa "const EC_KEY *key" +.Fc +.Ft int +.Fo EC_KEY_set_group +.Fa "EC_KEY *key" +.Fa "const EC_GROUP *group" +.Fc +.Ft const BIGNUM * +.Fo EC_KEY_get0_private_key +.Fa "const EC_KEY *key" +.Fc +.Ft int +.Fo EC_KEY_set_private_key +.Fa "EC_KEY *key" +.Fa "const BIGNUM *prv" +.Fc +.Ft const EC_POINT * +.Fo EC_KEY_get0_public_key +.Fa "const EC_KEY *key" +.Fc +.Ft int +.Fo EC_KEY_set_public_key +.Fa "EC_KEY *key" +.Fa "const EC_POINT *pub" +.Fc +.Ft unsigned int +.Fo EC_KEY_get_enc_flags +.Fa "const EC_KEY *key" +.Fc +.Ft void +.Fo EC_KEY_set_enc_flags +.Fa "EC_KEY *key" +.Fa "unsigned int flags" +.Fc +.Ft point_conversion_form_t +.Fo EC_KEY_get_conv_form +.Fa "const EC_KEY *key" +.Fc +.Ft void +.Fo EC_KEY_set_conv_form +.Fa "EC_KEY *key" +.Fa "point_conversion_form_t cform" +.Fc +.Ft void * +.Fo EC_KEY_get_key_method_data +.Fa "EC_KEY *key" +.Fa "void *(*dup_func)(void *)" +.Fa "void (*free_func)(void *)" +.Fa "void (*clear_free_func)(void *)" +.Fc +.Ft void +.Fo EC_KEY_insert_key_method_data +.Fa "EC_KEY *key" +.Fa "void *data" +.Fa "void *(*dup_func)(void *)" +.Fa "void (*free_func)(void *)" +.Fa "void (*clear_free_func)(void *)" +.Fc +.Ft void +.Fo EC_KEY_set_asn1_flag +.Fa "EC_KEY *key" +.Fa "int asn1_flag" +.Fc +.Ft int +.Fo EC_KEY_precompute_mult +.Fa "EC_KEY *key" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_KEY_generate_key +.Fa "EC_KEY *key" +.Fc +.Ft int +.Fo EC_KEY_check_key +.Fa "const EC_KEY *key" +.Fc +.Ft int +.Fo EC_KEY_set_public_key_affine_coordinates +.Fa "EC_KEY *key" +.Fa "BIGNUM *x" +.Fa "BIGNUM *y" +.Fc +.Sh DESCRIPTION +An +.Vt EC_KEY +represents a public key and (optionally) an associated private key. +A new +.Vt EC_KEY +(with no associated curve) can be constructed by calling +.Fn EC_KEY_new . +The reference count for the newly created +.Vt EC_KEY +is initially set to 1. +A curve can be associated with the +.Vt EC_KEY +by calling +.Fn EC_KEY_set_group . +.Pp +Alternatively a new +.Vt EC_KEY +can be constructed by calling +.Fn EC_KEY_new_by_curve_name +and supplying the +.Fa nid +of the associated curve. +Refer to +.Xr EC_GROUP_new 3 +for a description of curve names. +This function simply wraps calls to +.Fn EC_KEY_new +and +.Fn EC_GROUP_new_by_curve_name . +.Pp +Calling +.Fn EC_KEY_free +decrements the reference count for the +.Vt EC_KEY +object, and if it has dropped to zero, then frees the memory associated +with it. +.Pp +.Fn EC_KEY_copy +copies the contents of the +.Vt EC_KEY +in +.Fa src +into +.Fa dst . +.Pp +.Fn EC_KEY_dup +creates a new +.Vt EC_KEY +object and copies +.Fa src +into it. +.Pp +.Fn EC_KEY_up_ref +increments the reference count associated with the +.Vt EC_KEY +object. +.Pp +.Fn EC_KEY_generate_key +generates a new public and private key for the supplied +.Fa key +object. +.Fa key +must have an +.Vt EC_GROUP +object associated with it before calling this function. +The private key is a random integer (0 < priv_key < order, where order +is the order of the +.Vt EC_GROUP +object). +The public key is an +.Vt EC_POINT +on the curve calculated by multiplying the generator for the curve +by the private key. +.Pp +.Fn EC_KEY_check_key +performs various sanity checks on the +.Vt EC_KEY +object to confirm that it is valid. +.Pp +.Fn EC_KEY_set_public_key_affine_coordinates +sets the public key for +.Fa key +based on its affine coordinates, i.e. it constructs an +.Vt EC_POINT +object based on the supplied +.Fa x +and +.Fa y +values and sets the public key to be this +.Vt EC_POINT . +It also performs certain sanity checks on the key to confirm that +it is valid. +.Pp +The functions +.Fn EC_KEY_get0_group , +.Fn EC_KEY_set_group , +.Fn EC_KEY_get0_private_key , +.Fn EC_KEY_set_private_key , +.Fn EC_KEY_get0_public_key , +and +.Fn EC_KEY_set_public_key +get and set the +.Vt EC_GROUP +object, the private key and the +.Vt EC_POINT +public key for the +.Fa key , +respectively. +.Pp +The functions +.Fn EC_KEY_get_enc_flags +and +.Fn EC_KEY_set_enc_flags +get and set the value of the encoding flags for the +.Fa key . +There are two encoding flags currently defined: +.Dv EC_PKEY_NO_PARAMETERS +and +.Dv EC_PKEY_NO_PUBKEY . +These flags define the behaviour of how the +.Fa key +is converted into ASN1 in a call to +.Fn i2d_ECPrivateKey . +If +.Dv EC_PKEY_NO_PARAMETERS +is set then the public parameters for the curve +are not encoded along with the private key. +If +.Dv EC_PKEY_NO_PUBKEY +is set then the public key is not encoded along with the private +key. +.Pp +The functions +.Fn EC_KEY_get_conv_form +and +.Fn EC_KEY_set_conv_form +get and set the point_conversion_form for the +.Fa key . +For a description of point_conversion_forms please refer to +.Xr EC_POINT_new 3 . +.Pp +.Fn EC_KEY_insert_key_method_data +and +.Fn EC_KEY_get_key_method_data +enable the caller to associate arbitrary additional data specific +to the elliptic curve scheme being used with the +.Vt EC_KEY +object. +This data is treated as a "black box" by the ec library. +The data to be stored by +.Fn EC_KEY_insert_key_method_data +is provided in the +.Fa data +parameter, which must have associated functions for duplicating, freeing +and "clear_freeing" the data item. +If a subsequent +.Fn 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. +.Pp +.Fn EC_KEY_set_flags +sets the flags in the +.Fa flags +parameter on the +.Vt EC_KEY +object. +Any flags that are already set are left set. +The currently defined standard flags are +.Dv EC_FLAG_NON_FIPS_ALLOW +and +.Dv EC_FLAG_FIPS_CHECKED . +In addition there is the flag +.Dv EC_FLAG_COFACTOR_ECDH +which is specific to ECDH and is defined in +.In openssl/ecdh.h . +.Fn EC_KEY_get_flags +returns the current flags that are set for this +.Vt EC_KEY . +.Fn EC_KEY_clear_flags +clears the flags indicated by the +.Fa flags +parameter. +All other flags are left in their existing state. +.Pp +.Fn EC_KEY_set_asn1_flag +sets the asn1_flag on the underlying +.Vt EC_GROUP +object (if set). +Refer to +.Xr EC_GROUP_copy 3 +for further information on the asn1_flag. +.Pp +.Fn EC_KEY_precompute_mult +stores multiples of the underlying +.Vt EC_GROUP +generator for faster point multiplication. +See also +.Xr EC_POINT_add 3 . +.Sh RETURN VALUES +.Fn EC_KEY_new , +.Fn EC_KEY_new_by_curve_name , +and +.Fn EC_KEY_dup +return a pointer to the newly created +.Vt EC_KEY object or +.Dv NULL +on error. +.Pp +.Fn EC_KEY_get_flags +returns the flags associated with the +.Vt EC_KEY object. +.Pp +.Fn EC_KEY_copy +returns a pointer to the destination key or +.Dv NULL +on error. +.Pp +.Fn EC_KEY_up_ref , +.Fn EC_KEY_set_group , +.Fn EC_KEY_set_private_key , +.Fn EC_KEY_set_public_key , +.Fn EC_KEY_precompute_mult , +.Fn EC_KEY_generate_key , +.Fn EC_KEY_check_key , +and +.Fn EC_KEY_set_public_key_affine_coordinates +return 1 on success or 0 on error. +.Pp +.Fn EC_KEY_get0_group +returns the +.Vt EC_GROUP +associated with the +.Vt EC_KEY . +.Pp +.Fn EC_KEY_get0_private_key +returns the private key associated with the +.Vt EC_KEY . +.Pp +.Fn EC_KEY_get_enc_flags +returns the value of the current encoding flags for the +.Vt EC_KEY . +.Pp +.Fn EC_KEY_get_conv_form +returns the point_conversion_form for the +.Vt EC_KEY . +.Sh SEE ALSO +.Xr crypto 3 , +.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 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 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt EC_POINT_ADD 3 +.Os +.Sh NAME +.Nm EC_POINT_add , +.Nm EC_POINT_dbl , +.Nm EC_POINT_invert , +.Nm EC_POINT_is_at_infinity , +.Nm EC_POINT_is_on_curve , +.Nm EC_POINT_cmp , +.Nm EC_POINT_make_affine , +.Nm EC_POINTs_make_affine , +.Nm EC_POINTs_mul , +.Nm EC_POINT_mul , +.Nm EC_GROUP_precompute_mult , +.Nm EC_GROUP_have_precompute_mult +.Nd perform mathematical operations and tests on EC_POINT objects +.Sh SYNOPSIS +.In openssl/ec.h +.In openssl/bn.h +.Ft int +.Fo EC_POINT_add +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *r" +.Fa "const EC_POINT *a" +.Fa "const EC_POINT *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_dbl +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *r" +.Fa "const EC_POINT *a" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_invert +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *a" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_is_at_infinity +.Fa "const EC_GROUP *group" +.Fa "const EC_POINT *p" +.Fc +.Ft int +.Fo EC_POINT_is_on_curve +.Fa "const EC_GROUP *group" +.Fa "const EC_POINT *point" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_cmp +.Fa "const EC_GROUP *group" +.Fa "const EC_POINT *a" +.Fa "const EC_POINT *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_make_affine +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *point" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINTs_make_affine +.Fa "const EC_GROUP *group" +.Fa "size_t num" +.Fa "EC_POINT *points[]" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINTs_mul +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *r" +.Fa "const BIGNUM *n" +.Fa "size_t num" +.Fa "const EC_POINT *p[]" +.Fa "const BIGNUM *m[]" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_mul +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *r" +.Fa "const BIGNUM *n" +.Fa "const EC_POINT *q" +.Fa "const BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_precompute_mult +.Fa "EC_GROUP *group" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_have_precompute_mult +.Fa "const EC_GROUP *group" +.Fc +.Sh DESCRIPTION +.Fn EC_POINT_add +adds the two points +.Fa a +and +.Fa b +and places the result in +.Fa r . +Similarly +.Fn EC_POINT_dbl +doubles the point +.Fa a +and places the result in +.Fa r . +In both cases it is valid for +.Fa r +to be one of +.Fa a +or +.Fa b . +.Pp +.Fn EC_POINT_invert +calculates the inverse of the supplied point +.Fa a . +The result is placed back in +.Fa a . +.Pp +The function +.Fn EC_POINT_is_at_infinity +tests whether the supplied point is at infinity or not. +.Pp +.Fn EC_POINT_is_on_curve +tests whether the supplied point is on the curve or not. +.Pp +.Fn EC_POINT_cmp +compares the two supplied points and tests whether or not they are +equal. +.Pp +The functions +.Fn EC_POINT_make_affine +and +.Fn EC_POINTs_make_affine +force the internal representation of the +.Vt EC_POINT Ns (s) +into the affine coordinate system. +In the case of +.Fn EC_POINTs_make_affine , +the value +.Fa num +provides the number of points in the array +.Fa points +to be forced. +.Pp +.Fn EC_POINT_mul +calculates the value +.Pp +.D1 generator * n + q * m +.Pp +and stores the result in +.Fa r . +The value +.Fa n +may be +.Dv NULL , +in which case the result is just q * m. +.Pp +.Fn EC_POINTs_mul +calculates the value +.Pp +.Dl generator * n + q[0] * m[0] + ... + q[num-1] * m[num-1] +.Pp +As for +.Fn EC_POINT_mul , +the value +.Fa n +may be +.Dv NULL . +.Pp +The function +.Fn EC_GROUP_precompute_mult +stores multiples of the generator for faster point multiplication, +whilst +.Fn EC_GROUP_have_precompute_mult +tests whether precomputation has already been done. +See +.Xr EC_GROUP_copy 3 +for information about the generator. +.Sh RETURN VALUES +The following functions return 1 on success or 0 on error: +.Fn EC_POINT_add , +.Fn EC_POINT_dbl , +.Fn EC_POINT_invert , +.Fn EC_POINT_make_affine , +.Fn EC_POINTs_make_affine , +.Fn EC_POINTs_make_affine , +.Fn EC_POINT_mul , +.Fn EC_POINTs_mul , +and +.Fn EC_GROUP_precompute_mult . +.Pp +.Fn EC_POINT_is_at_infinity +returns 1 if the point is at infinity or 0 otherwise. +.Pp +.Fn EC_POINT_is_on_curve +returns 1 if the point is on the curve, 0 if not, or -1 on error. +.Pp +.Fn EC_POINT_cmp +returns 1 if the points are not equal, 0 if they are, or -1 on error. +.Pp +.Fn EC_GROUP_have_precompute_mult +returns 1 if a precomputation has been done or 0 if not. +.Sh SEE ALSO +.Xr crypto 3 , +.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_KEY_new 3 , +.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 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt EC_POINT_NEW 3 +.Os +.Sh NAME +.Nm EC_POINT_new , +.Nm EC_POINT_free , +.Nm EC_POINT_clear_free , +.Nm EC_POINT_copy , +.Nm EC_POINT_dup , +.Nm EC_POINT_method_of , +.Nm EC_POINT_set_to_infinity , +.Nm EC_POINT_set_Jprojective_coordinates , +.Nm EC_POINT_get_Jprojective_coordinates_GFp , +.Nm EC_POINT_set_affine_coordinates_GFp , +.Nm EC_POINT_get_affine_coordinates_GFp , +.Nm EC_POINT_set_compressed_coordinates_GFp , +.Nm EC_POINT_set_affine_coordinates_GF2m , +.Nm EC_POINT_get_affine_coordinates_GF2m , +.Nm EC_POINT_set_compressed_coordinates_GF2m , +.Nm EC_POINT_point2oct , +.Nm EC_POINT_oct2point , +.Nm EC_POINT_point2bn , +.Nm EC_POINT_bn2point , +.Nm EC_POINT_point2hex , +.Nm EC_POINT_hex2point +.Nd create, destroy, and manipulate EC_POINT objects +.Sh SYNOPSIS +.In openssl/ec.h +.In openssl/bn.h +.Ft EC_POINT * +.Fo EC_POINT_new +.Fa "const EC_GROUP *group" +.Fc +.Ft void +.Fo EC_POINT_free +.Fa "EC_POINT *point" +.Fc +.Ft void +.Fo EC_POINT_clear_free +.Fa "EC_POINT *point" +.Fc +.Ft int +.Fo EC_POINT_copy +.Fa "EC_POINT *dst" +.Fa "const EC_POINT *src" +.Fc +.Ft EC_POINT * +.Fo EC_POINT_dup +.Fa "const EC_POINT *src" +.Fa "const EC_GROUP *group" +.Fc +.Ft const EC_METHOD * +.Fo EC_POINT_method_of +.Fa "const EC_POINT *point" +.Fc +.Ft int +.Fo EC_POINT_set_to_infinity +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *point" +.Fc +.Ft int +.Fo EC_POINT_set_Jprojective_coordinates_GFp +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *p" +.Fa "const BIGNUM *x" +.Fa "const BIGNUM *y" +.Fa "const BIGNUM *z" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_get_Jprojective_coordinates_GFp +.Fa "const EC_GROUP *group" +.Fa "const EC_POINT *p" +.Fa "BIGNUM *x" +.Fa "BIGNUM *y" +.Fa "BIGNUM *z" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_set_affine_coordinates_GFp +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *p" +.Fa "const BIGNUM *x" +.Fa "const BIGNUM *y" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_get_affine_coordinates_GFp +.Fa "const EC_GROUP *group" +.Fa "const EC_POINT *p" +.Fa "BIGNUM *x" +.Fa "BIGNUM *y" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_set_compressed_coordinates_GFp +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *p" +.Fa "const BIGNUM *x" +.Fa "int y_bit" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_set_affine_coordinates_GF2m +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *p" +.Fa "const BIGNUM *x" +.Fa "const BIGNUM *y" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_get_affine_coordinates_GF2m +.Fa "const EC_GROUP *group" +.Fa "const EC_POINT *p" +.Fa "BIGNUM *x" +.Fa "BIGNUM *y" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_set_compressed_coordinates_GF2m +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *p" +.Fa "const BIGNUM *x" +.Fa "int y_bit" +.Fa "BN_CTX *ctx" +.Fc +.Ft size_t +.Fo EC_POINT_point2oct +.Fa "const EC_GROUP *group" +.Fa "const EC_POINT *p" +.Fa "point_conversion_form_t form" +.Fa "unsigned char *buf" +.Fa "size_t len" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_oct2point +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *p" +.Fa "const unsigned char *buf" +.Fa "size_t len" +.Fa "BN_CTX *ctx" +.Fc +.Ft BIGNUM * +.Fo EC_POINT_point2bn +.Fa "const EC_GROUP *" +.Fa "const EC_POINT *" +.Fa "point_conversion_form_t form" +.Fa "BIGNUM *" +.Fa "BN_CTX *" +.Fc +.Ft EC_POINT * +.Fo EC_POINT_bn2point +.Fa "const EC_GROUP *" +.Fa "const BIGNUM *" +.Fa "EC_POINT *" +.Fa "BN_CTX *" +.Fc +.Ft char * +.Fo EC_POINT_point2hex +.Fa "const EC_GROUP *" +.Fa "const EC_POINT *" +.Fa "point_conversion_form_t form" +.Fa "BN_CTX *" +.Fc +.Ft EC_POINT * +.Fo EC_POINT_hex2point +.Fa "const EC_GROUP *" +.Fa "const char *" +.Fa "EC_POINT *" +.Fa "BN_CTX *" +.Fc +.Sh DESCRIPTION +An +.Vt EC_POINT +represents a point on a curve. +A new point is constructed by calling the function +.Fn EC_POINT_new +and providing the +.Fa group +object that the point relates to. +.Pp +.Fn EC_POINT_free +frees the memory associated with the +.Vt EC_POINT . +.Pp +.Fn EC_POINT_clear_free +destroys any sensitive data held within the +.Vt EC_POINT +and then frees its memory. +.Pp +.Fn EC_POINT_copy +copies the point +.Fa src +into +.Fa dst . +Both +.Fa src +and +.Fa dst +must use the same +.Vt EC_METHOD . +.Pp +.Fn EC_POINT_dup +creates a new +.Vt EC_POINT +object and copies the content from +.Fa src +to the newly created +.Vt EC_POINT +object. +.Pp +.Fn EC_POINT_method_of +obtains the +.Vt EC_METHOD +associated with +.Fa point . +.Pp +A valid point on a curve is the special point at infinity. +A point is set to be at infinity by calling +.Fn EC_POINT_set_to_infinity . +.Pp +The affine coordinates for a point describe a point in terms of its +.Fa x +and +.Fa y +position. +The functions +.Fn EC_POINT_set_affine_coordinates_GFp +and +.Fn EC_POINT_set_affine_coordinates_GF2m +set the +.Fa x +and +.Fa y +coordinates for the point +.Fa p +defined over the curve given in +.Fa group . +.Pp +As well as the affine coordinates, a point can alternatively be +described in terms of its Jacobian projective coordinates (for Fp +curves only). +Jacobian projective coordinates are expressed as three values +.Fa x , +.Fa y , +and +.Fa z . +Working in this coordinate system provides more efficient point +multiplication operations. +A mapping exists between Jacobian projective coordinates and affine +coordinates. +A Jacobian projective coordinate +.Pq Fa x , y , z +can be written as an affine coordinate as +.Pp +.Dl (x/(z^2), y/(z^3)) . +.Pp +Conversion to Jacobian projective to affine coordinates is simple. +The coordinate +.Pq Fa x , y +is mapped to +.Pq Fa x , y , No 1 . +To set or get the projective coordinates use +.Fn EC_POINT_set_Jprojective_coordinates_GFp +and +.Fn EC_POINT_get_Jprojective_coordinates_GFp , +respectively. +.Pp +Points can also be described in terms of their compressed coordinates. +For a point +.Pq Fa x , y , +for any given value for +.Fa x +such that the point is on the curve, there will only ever be two +possible values for +.Fa y . +Therefore a point can be set using the +.Fn EC_POINT_set_compressed_coordinates_GFp +and +.Fn EC_POINT_set_compressed_coordinates_GF2m +functions where +.Fa x +is the x coordinate and +.Fa y_bit +is a value 0 or 1 to identify which of the two possible values for y +should be used. +.Pp +In addition +.Vt EC_POINT Ns s +can be converted to and from various external representations. +Supported representations are octet strings, +.Vt BIGNUM Ns s , +and hexadecimal. +The format of the external representation is described by the +point_conversion_form. +See +.Xr EC_GROUP_copy 3 +for a description of point_conversion_form. +Octet strings are stored in a buffer along with an associated buffer +length. +A point held in a +.Vt BIGNUM +is calculated by converting the point to an octet string and then +converting that octet string into a +.Vt BIGNUM +integer. +Points in hexadecimal format are stored in a NUL terminated character +string where each character is one of the printable values 0-9 or A-F +(or a-f). +.Pp +The functions +.Fn EC_POINT_point2oct , +.Fn EC_POINT_oct2point , +.Fn EC_POINT_point2bn , +.Fn EC_POINT_bn2point , +.Fn EC_POINT_point2hex , +and +.Fn EC_POINT_hex2point +convert from and to +.Vt EC_POINT Ns s +for the formats octet string, +.Vt BIGNUM , +and hexadecimal, respectively. +.Pp +The function +.Fn EC_POINT_point2oct +must be supplied with a +.Fa buf +long enough to store the octet string. +The return value provides the number of octets stored. +Calling the function with a +.Dv NULL +.Fa buf +will not perform the conversion but will still return the required +buffer length. +.Pp +The function +.Fn EC_POINT_point2hex +will allocate sufficient memory to store the hexadecimal string. +It is the caller's responsibility to free this memory with a subsequent +call to +.Xr free 3 . +.Sh RETURN VALUES +.Fn EC_POINT_new +and +.Fn EC_POINT_dup +return the newly allocated +.Vt EC_POINT +or +.Dv NULL +on error. +.Pp +The following functions return 1 on success or 0 on error: +.Fn EC_POINT_copy , +.Fn EC_POINT_set_to_infinity , +.Fn EC_POINT_set_Jprojective_coordinates_GFp , +.Fn EC_POINT_get_Jprojective_coordinates_GFp , +.Fn EC_POINT_set_affine_coordinates_GFp , +.Fn EC_POINT_get_affine_coordinates_GFp , +.Fn EC_POINT_set_compressed_coordinates_GFp , +.Fn EC_POINT_set_affine_coordinates_GF2m , +.Fn EC_POINT_get_affine_coordinates_GF2m , +.Fn EC_POINT_set_compressed_coordinates_GF2m , +and +.Fn EC_POINT_oct2point . +.Pp +.Fn EC_POINT_method_of +returns the +.Vt EC_METHOD +associated with the supplied +.Vt EC_POINT . +.Pp +.Fn EC_POINT_point2oct +returns the length of the required buffer, or 0 on error. +.Pp +.Fn EC_POINT_point2bn +returns the pointer to the +.Vt BIGNUM +supplied or +.Vt NULL +on error. +.Pp +.Fn EC_POINT_bn2point +returns the pointer to the +.Vt EC_POINT +supplied or +.Dv NULL +on error. +.Pp +.Fn EC_POINT_point2hex +returns a pointer to the hex string or +.Dv NULL +on error. +.Pp +.Fn EC_POINT_hex2point +returns the pointer to the +.Vt EC_POINT supplied or +.Dv NULL +on error. +.Sh SEE ALSO +.Xr crypto 3 , +.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_KEY_new 3 , +.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 @@ -# $OpenBSD: Makefile,v 1.35 2016/11/02 09:11:53 schwarze Exp $ +# $OpenBSD: Makefile,v 1.36 2016/11/02 11:57:56 schwarze Exp $ .include # for NOMAN @@ -63,16 +63,6 @@ MAN= \ DH_new.3 \ DH_set_method.3 \ DH_size.3 \ - ECDSA_SIG_new.3 \ - EVP_AEAD_CTX_init.3 \ - UI_new.3 \ - bn_dump.3 \ - crypto.3 \ - d2i_PKCS8PrivateKey_bio.3 \ - des_read_pw.3 \ - lh_new.3 \ - -GENMAN= \ DSA_SIG_new.3 \ DSA_do_sign.3 \ DSA_dup_DH.3 \ @@ -89,6 +79,16 @@ GENMAN= \ EC_KEY_new.3 \ EC_POINT_add.3 \ EC_POINT_new.3 \ + ECDSA_SIG_new.3 \ + EVP_AEAD_CTX_init.3 \ + UI_new.3 \ + bn_dump.3 \ + crypto.3 \ + d2i_PKCS8PrivateKey_bio.3 \ + des_read_pw.3 \ + lh_new.3 \ + +GENMAN= \ ERR.3 \ ERR_GET_LIB.3 \ ERR_clear_error.3 \ -- cgit v1.2.3-55-g6feb