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/doc/DSA_SIG_new.pod | 38 -- src/lib/libcrypto/doc/DSA_do_sign.pod | 47 --- src/lib/libcrypto/doc/DSA_dup_DH.pod | 36 -- src/lib/libcrypto/doc/DSA_generate_key.pod | 32 -- src/lib/libcrypto/doc/DSA_generate_parameters.pod | 122 ------ src/lib/libcrypto/doc/DSA_get_ex_new_index.pod | 37 -- src/lib/libcrypto/doc/DSA_new.pod | 40 -- src/lib/libcrypto/doc/DSA_set_method.pod | 143 ------- src/lib/libcrypto/doc/DSA_sign.pod | 63 ---- src/lib/libcrypto/doc/DSA_size.pod | 33 -- src/lib/libcrypto/doc/EC_GFp_simple_method.pod | 60 --- src/lib/libcrypto/doc/EC_GROUP_copy.pod | 174 --------- src/lib/libcrypto/doc/EC_GROUP_new.pod | 95 ----- src/lib/libcrypto/doc/EC_KEY_new.pod | 115 ------ src/lib/libcrypto/doc/EC_POINT_add.pod | 72 ---- src/lib/libcrypto/doc/EC_POINT_new.pod | 123 ------ 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 +- 33 files changed, 2658 insertions(+), 1241 deletions(-) delete mode 100644 src/lib/libcrypto/doc/DSA_SIG_new.pod delete mode 100644 src/lib/libcrypto/doc/DSA_do_sign.pod delete mode 100644 src/lib/libcrypto/doc/DSA_dup_DH.pod delete mode 100644 src/lib/libcrypto/doc/DSA_generate_key.pod delete mode 100644 src/lib/libcrypto/doc/DSA_generate_parameters.pod delete mode 100644 src/lib/libcrypto/doc/DSA_get_ex_new_index.pod delete mode 100644 src/lib/libcrypto/doc/DSA_new.pod delete mode 100644 src/lib/libcrypto/doc/DSA_set_method.pod delete mode 100644 src/lib/libcrypto/doc/DSA_sign.pod delete mode 100644 src/lib/libcrypto/doc/DSA_size.pod delete mode 100644 src/lib/libcrypto/doc/EC_GFp_simple_method.pod delete mode 100644 src/lib/libcrypto/doc/EC_GROUP_copy.pod delete mode 100644 src/lib/libcrypto/doc/EC_GROUP_new.pod delete mode 100644 src/lib/libcrypto/doc/EC_KEY_new.pod delete mode 100644 src/lib/libcrypto/doc/EC_POINT_add.pod delete mode 100644 src/lib/libcrypto/doc/EC_POINT_new.pod 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') diff --git a/src/lib/libcrypto/doc/DSA_SIG_new.pod b/src/lib/libcrypto/doc/DSA_SIG_new.pod deleted file mode 100644 index 77aa649db0..0000000000 --- a/src/lib/libcrypto/doc/DSA_SIG_new.pod +++ /dev/null @@ -1,38 +0,0 @@ -=pod - -=head1 NAME - -DSA_SIG_new, DSA_SIG_free - allocate and free DSA signature objects - -=head1 SYNOPSIS - - #include - - DSA_SIG *DSA_SIG_new(void); - - void DSA_SIG_free(DSA_SIG *a); - -=head1 DESCRIPTION - -DSA_SIG_new() allocates and initializes a B structure. - -DSA_SIG_free() frees the B structure and its components. The -values are erased before the memory is returned to the system. - -=head1 RETURN VALUES - -If the allocation fails, DSA_SIG_new() returns B and sets an -error code that can be obtained by -L. Otherwise it returns a pointer -to the newly allocated structure. - -=head1 SEE ALSO - -L, L, -L - -=head1 HISTORY - -DSA_SIG_new() and DSA_SIG_free() were added in OpenSSL 0.9.3. - -=cut diff --git a/src/lib/libcrypto/doc/DSA_do_sign.pod b/src/lib/libcrypto/doc/DSA_do_sign.pod deleted file mode 100644 index 5dfc733b20..0000000000 --- a/src/lib/libcrypto/doc/DSA_do_sign.pod +++ /dev/null @@ -1,47 +0,0 @@ -=pod - -=head1 NAME - -DSA_do_sign, DSA_do_verify - raw DSA signature operations - -=head1 SYNOPSIS - - #include - - DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa); - - int DSA_do_verify(const unsigned char *dgst, int dgst_len, - DSA_SIG *sig, DSA *dsa); - -=head1 DESCRIPTION - -DSA_do_sign() computes a digital signature on the B byte message -digest B using the private key B and returns it in a -newly allocated B structure. - -L may be used to precompute part -of the signing operation in case signature generation is -time-critical. - -DSA_do_verify() verifies that the signature B matches a given -message digest B of size B. B is the signer's public -key. - -=head1 RETURN VALUES - -DSA_do_sign() returns the signature, NULL on error. 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 -L. - -=head1 SEE ALSO - -L, L, L, -L, -L - -=head1 HISTORY - -DSA_do_sign() and DSA_do_verify() were added in OpenSSL 0.9.3. - -=cut diff --git a/src/lib/libcrypto/doc/DSA_dup_DH.pod b/src/lib/libcrypto/doc/DSA_dup_DH.pod deleted file mode 100644 index 7f6f0d1115..0000000000 --- a/src/lib/libcrypto/doc/DSA_dup_DH.pod +++ /dev/null @@ -1,36 +0,0 @@ -=pod - -=head1 NAME - -DSA_dup_DH - create a DH structure out of DSA structure - -=head1 SYNOPSIS - - #include - - DH * DSA_dup_DH(const DSA *r); - -=head1 DESCRIPTION - -DSA_dup_DH() duplicates DSA parameters/keys as DH parameters/keys. q -is lost during that conversion, but the resulting DH parameters -contain its length. - -=head1 RETURN VALUE - -DSA_dup_DH() returns the new B structure, and NULL on error. The -error codes can be obtained by L. - -=head1 NOTE - -Be careful to avoid small subgroup attacks when using this. - -=head1 SEE ALSO - -L, L, L - -=head1 HISTORY - -DSA_dup_DH() was added in OpenSSL 0.9.4. - -=cut diff --git a/src/lib/libcrypto/doc/DSA_generate_key.pod b/src/lib/libcrypto/doc/DSA_generate_key.pod deleted file mode 100644 index 069a05767c..0000000000 --- a/src/lib/libcrypto/doc/DSA_generate_key.pod +++ /dev/null @@ -1,32 +0,0 @@ -=pod - -=head1 NAME - -DSA_generate_key - generate DSA key pair - -=head1 SYNOPSIS - - #include - - int DSA_generate_key(DSA *a); - -=head1 DESCRIPTION - -DSA_generate_key() expects B to contain DSA parameters. It generates -a new key pair and stores it in Bpub_key> and Bpriv_key>. - -=head1 RETURN VALUE - -DSA_generate_key() returns 1 on success, 0 otherwise. -The error codes can be obtained by L. - -=head1 SEE ALSO - -L, L, L, -L - -=head1 HISTORY - -DSA_generate_key() is available since SSLeay 0.8. - -=cut diff --git a/src/lib/libcrypto/doc/DSA_generate_parameters.pod b/src/lib/libcrypto/doc/DSA_generate_parameters.pod deleted file mode 100644 index 698b555a0e..0000000000 --- a/src/lib/libcrypto/doc/DSA_generate_parameters.pod +++ /dev/null @@ -1,122 +0,0 @@ -=pod - -=head1 NAME - -DSA_generate_parameters_ex, DSA_generate_parameters - generate DSA parameters - -=head1 SYNOPSIS - - #include - - int DSA_generate_parameters_ex(DSA *dsa, int bits, - const unsigned char *seed,int seed_len, - int *counter_ret, unsigned long *h_ret, BN_GENCB *cb); - -Deprecated: - - DSA *DSA_generate_parameters(int bits, unsigned char *seed, - int seed_len, int *counter_ret, unsigned long *h_ret, - void (*callback)(int, int, void *), void *cb_arg); - -=head1 DESCRIPTION - -DSA_generate_parameters_ex() generates primes p and q and a generator g -for use in the DSA and stores the result in B. - -B is the length of the prime to be generated; the DSS allows a -maximum of 1024 bits. - -If B is B or B E 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 B. - -DSA_generate_parameters_ex() places the iteration count in -*B and a counter used for finding a generator in -*B, unless these are B. - -A callback function may be used to provide feedback about the progress -of the key generation. If B is not B, it will be -called as shown below. For information on the BN_GENCB structure and the -BN_GENCB_call function discussed below, refer to -L. - -=over 4 - -=item * - -When a candidate for q is generated, B is called -(m is 0 for the first candidate). - -=item * - -When a candidate for q has passed a test by trial division, -B is called. -While a candidate for q is tested by Miller-Rabin primality tests, -B is called in the outer loop -(once for each witness that confirms that the candidate may be prime); -i is the loop counter (starting at 0). - -=item * - -When a prime q has been found, B and -B are called. - -=item * - -Before a candidate for p (other than the first) is generated and tested, -B is called. - -=item * - -When a candidate for p has passed the test by trial division, -B is called. -While it is tested by the Miller-Rabin primality test, -B is called in the outer loop -(once for each witness that confirms that the candidate may be prime). -i is the loop counter (starting at 0). - -=item * - -When p has been found, B is called. - -=item * - -When the generator has been found, B is called. - -=back - -DSA_generate_parameters() (deprecated) works in much the same way as for DSA_generate_parameters_ex, except that no B parameter is passed and -instead a newly allocated B structure is returned. Additionally "old -style" callbacks are used instead of the newer BN_GENCB based approach. -Refer to L for further information. - -=head1 RETURN VALUE - -DSA_generate_parameters_ex() returns a 1 on success, or 0 otherwise. - -DSA_generate_parameters() returns a pointer to the DSA structure, or -B if the parameter generation fails. - -The error codes can be obtained by L. - -=head1 BUGS - -Seed lengths E 20 are not supported. - -=head1 SEE ALSO - -L, L, L, -L, L - -=head1 HISTORY - -DSA_generate_parameters() appeared in SSLeay 0.8. The B -argument was added in SSLeay 0.9.0. -In versions up to OpenSSL 0.9.4, B was called -in the inner loop of the Miller-Rabin test whenever it reached the -squaring step (the parameters to B did not reveal how many -witnesses had been tested); since OpenSSL 0.9.5, B -is called as in BN_is_prime(3), i.e. once for each witness. - -=cut diff --git a/src/lib/libcrypto/doc/DSA_get_ex_new_index.pod b/src/lib/libcrypto/doc/DSA_get_ex_new_index.pod deleted file mode 100644 index e2fcabf370..0000000000 --- a/src/lib/libcrypto/doc/DSA_get_ex_new_index.pod +++ /dev/null @@ -1,37 +0,0 @@ -=pod - -=head1 NAME - -DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data - add application -specific data to DSA structures - -=head1 SYNOPSIS - - #include - - int DSA_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int DSA_set_ex_data(DSA *d, int idx, void *arg); - - char *DSA_get_ex_data(DSA *d, int idx); - -=head1 DESCRIPTION - -These functions handle application specific data in DSA -structures. Their usage is identical to that of -RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() -as described in L. - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -DSA_get_ex_new_index(), DSA_set_ex_data() and DSA_get_ex_data() are -available since OpenSSL 0.9.5. - -=cut diff --git a/src/lib/libcrypto/doc/DSA_new.pod b/src/lib/libcrypto/doc/DSA_new.pod deleted file mode 100644 index e1e30b9a07..0000000000 --- a/src/lib/libcrypto/doc/DSA_new.pod +++ /dev/null @@ -1,40 +0,0 @@ -=pod - -=head1 NAME - -DSA_new, DSA_free - allocate and free DSA objects - -=head1 SYNOPSIS - - #include - - DSA* DSA_new(void); - - void DSA_free(DSA *dsa); - -=head1 DESCRIPTION - -DSA_new() allocates and initializes a B structure. It is equivalent to -calling DSA_new_method(NULL). - -DSA_free() frees the B structure and its components. The values are -erased before the memory is returned to the system. - -=head1 RETURN VALUES - -If the allocation fails, DSA_new() returns B and sets an error -code that can be obtained by -L. Otherwise it returns a pointer -to the newly allocated structure. - -=head1 SEE ALSO - -L, L, -L, -L - -=head1 HISTORY - -DSA_new() and DSA_free() are available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/src/lib/libcrypto/doc/DSA_set_method.pod b/src/lib/libcrypto/doc/DSA_set_method.pod deleted file mode 100644 index bc57a3e8e2..0000000000 --- a/src/lib/libcrypto/doc/DSA_set_method.pod +++ /dev/null @@ -1,143 +0,0 @@ -=pod - -=head1 NAME - -DSA_set_default_method, DSA_get_default_method, -DSA_set_method, DSA_new_method, DSA_OpenSSL, -DSA_set_default_openssl_method, DSA_get_default_openssl_method -- select DSA method - -=head1 SYNOPSIS - - #include - #include - - void DSA_set_default_method(const DSA_METHOD *meth); - - const DSA_METHOD *DSA_get_default_method(void); - - int DSA_set_method(DSA *dsa, const DSA_METHOD *meth); - - DSA *DSA_new_method(ENGINE *engine); - - DSA_METHOD *DSA_OpenSSL(void); - -=head1 DESCRIPTION - -A B specifies the functions that OpenSSL uses for DSA -operations. By modifying the method, alternative implementations -such as hardware accelerators may be used. IMPORTANT: See the NOTES section for -important information about how these DSA API functions are affected by the use -of B API calls. - -Initially, the default DSA_METHOD is the OpenSSL internal implementation, -as returned by DSA_OpenSSL(). - -DSA_set_default_method() makes B the default method for all DSA -structures created later. B: This is true only whilst no ENGINE has -been set as a default for DSA, so this function is no longer recommended. - -DSA_get_default_method() returns a pointer to the current default -DSA_METHOD. However, the meaningfulness of this result is dependent on -whether the ENGINE API is being used, so this function is no longer -recommended. - -DSA_set_method() selects B to perform all operations using the key -B. This will replace the DSA_METHOD used by the DSA key and if the -previous method was supplied by an ENGINE, the handle to that ENGINE will -be released during the change. It is possible to have DSA keys that only -work with certain DSA_METHOD implementations (eg. from an ENGINE module -that supports embedded hardware-protected keys), and in such cases -attempting to change the DSA_METHOD for the key can have unexpected -results. - -DSA_new_method() allocates and initializes a DSA structure so that B -will be used for the DSA operations. If B is NULL, the default engine -for DSA operations is used, and if no default ENGINE is set, the DSA_METHOD -controlled by DSA_set_default_method() is used. - -=head1 THE DSA_METHOD STRUCTURE - -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; - -=head1 RETURN VALUES - -DSA_OpenSSL() and DSA_get_default_method() return pointers to the respective -Bs. - -DSA_set_method() returns non-zero if the provided B was successfully set -as the method for B (including unloading the ENGINE handle if the previous -method was supplied by an ENGINE). - -DSA_new_method() returns NULL and sets an error code that can be -obtained by L if the allocation -fails. Otherwise it returns a pointer to the newly allocated structure. - -=head1 NOTES - -As of version 0.9.7, DSA_METHOD implementations are grouped together with other -algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B modules. If a -default ENGINE is specified for DSA functionality using an ENGINE API function, -that will override any DSA defaults set using the DSA API (ie. -DSA_set_default_method()). For this reason, the ENGINE API is the recommended -way to control default implementations for use in DSA and other cryptographic -algorithms. - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -DSA_set_default_method(), DSA_get_default_method(), DSA_set_method(), -DSA_new_method() and DSA_OpenSSL() were added in OpenSSL 0.9.4. - -DSA_set_default_openssl_method() and DSA_get_default_openssl_method() replaced -DSA_set_default_method() and DSA_get_default_method() respectively, and -DSA_set_method() and DSA_new_method() were altered to use Bs rather than -Bs during development of the engine version of OpenSSL 0.9.6. For -0.9.7, the handling of defaults in the ENGINE 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 ENGINE API now -transparently overrides the behaviour of defaults in the DSA API without -requiring changing these function prototypes. - -=cut diff --git a/src/lib/libcrypto/doc/DSA_sign.pod b/src/lib/libcrypto/doc/DSA_sign.pod deleted file mode 100644 index 4e78a71390..0000000000 --- a/src/lib/libcrypto/doc/DSA_sign.pod +++ /dev/null @@ -1,63 +0,0 @@ -=pod - -=head1 NAME - -DSA_sign, DSA_sign_setup, DSA_verify - DSA signatures - -=head1 SYNOPSIS - - #include - - int DSA_sign(int type, const unsigned char *dgst, int len, - unsigned char *sigret, unsigned int *siglen, DSA *dsa); - - int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp, - BIGNUM **rp); - - int DSA_verify(int type, const unsigned char *dgst, int len, - unsigned char *sigbuf, int siglen, DSA *dsa); - -=head1 DESCRIPTION - -DSA_sign() computes a digital signature on the B byte message -digest B using the private key B and places its ASN.1 DER -encoding at B. The length of the signature is places in -*B. B must point to DSA_size(B) bytes of memory. - -DSA_sign_setup() may be used to precompute part of the signing -operation in case signature generation is time-critical. It expects -B to contain DSA parameters. It places the precomputed values -in newly allocated Bs at *B and *B, after freeing -the old ones unless *B and *B are NULL. These values may -be passed to DSA_sign() in Bkinv> and Br>. -B is a pre-allocated B or NULL. - -DSA_verify() verifies that the signature B of size B -matches a given message digest B of size B. -B is the signer's public key. - -The B parameter is ignored. - -=head1 RETURN VALUES - -DSA_sign() and DSA_sign_setup() return 1 on success, 0 on error. -DSA_verify() returns 1 for a valid signature, 0 for an incorrect -signature and -1 on error. The error codes can be obtained by -L. - -=head1 CONFORMING TO - -US Federal Information Processing Standard FIPS 186 (Digital Signature -Standard, DSS), ANSI X9.30 - -=head1 SEE ALSO - -L, L, L, -L - -=head1 HISTORY - -DSA_sign() and DSA_verify() are available in all versions of SSLeay. -DSA_sign_setup() was added in SSLeay 0.8. - -=cut diff --git a/src/lib/libcrypto/doc/DSA_size.pod b/src/lib/libcrypto/doc/DSA_size.pod deleted file mode 100644 index ba4f650361..0000000000 --- a/src/lib/libcrypto/doc/DSA_size.pod +++ /dev/null @@ -1,33 +0,0 @@ -=pod - -=head1 NAME - -DSA_size - get DSA signature size - -=head1 SYNOPSIS - - #include - - int DSA_size(const DSA *dsa); - -=head1 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. - -Bq> must not be B. - -=head1 RETURN VALUE - -The size in bytes. - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -DSA_size() is available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/src/lib/libcrypto/doc/EC_GFp_simple_method.pod b/src/lib/libcrypto/doc/EC_GFp_simple_method.pod deleted file mode 100644 index aff20ac175..0000000000 --- a/src/lib/libcrypto/doc/EC_GFp_simple_method.pod +++ /dev/null @@ -1,60 +0,0 @@ -=pod - -=head1 NAME - -EC_GFp_simple_method, EC_GFp_mont_method, EC_GFp_nist_method, EC_GFp_nistp224_method, EC_GFp_nistp256_method, EC_GFp_nistp521_method, EC_GF2m_simple_method, EC_METHOD_get_field_type - Functions for obtaining B objects. - -=head1 SYNOPSIS - - #include - - const EC_METHOD *EC_GFp_simple_method(void); - const EC_METHOD *EC_GFp_mont_method(void); - const EC_METHOD *EC_GFp_nist_method(void); - const EC_METHOD *EC_GFp_nistp224_method(void); - const EC_METHOD *EC_GFp_nistp256_method(void); - const EC_METHOD *EC_GFp_nistp521_method(void); - - const EC_METHOD *EC_GF2m_simple_method(void); - - int EC_METHOD_get_field_type(const EC_METHOD *meth); - -=head1 DESCRIPTION - -The Elliptic Curve library provides a number of different implementations through a single common interface. -When constructing a curve using EC_GROUP_new (see L) an -implementation method must be provided. The functions described here all return a const pointer to an -B structure that can be passed to EC_GROUP_NEW. It is important that the correct implementation -type for the form of curve selected is used. - -For F2^m curves there is only one implementation choice, i.e. EC_GF2_simple_method. - -For Fp curves the lowest common denominator implementation is the EC_GFp_simple_method implementation. All -other implementations are based on this one. EC_GFp_mont_method builds on EC_GFp_simple_method but adds the -use of montgomery multiplication (see L). EC_GFp_nist_method -offers an implementation optimised for use with NIST recommended curves (NIST curves are available through -EC_GROUP_new_by_curve_name as described in L). - -The functions EC_GFp_nistp224_method, EC_GFp_nistp256_method and 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. - -EC_METHOD_get_field_type identifies what type of field the EC_METHOD structure supports, which will be either -F2^m or Fp. If the field type is Fp then the value B is returned. If the field type is -F2^m then the value B is returned. These values are defined in the -obj_mac.h header file. - -=head1 RETURN VALUES - -All EC_GFp* functions and EC_GF2m_simple_method always return a const pointer to an EC_METHOD structure. - -EC_METHOD_get_field_type returns an integer that identifies the type of field the EC_METHOD structure supports. - -=head1 SEE ALSO - -L, L, L, L, -L, L, L, -L, -L - -=cut diff --git a/src/lib/libcrypto/doc/EC_GROUP_copy.pod b/src/lib/libcrypto/doc/EC_GROUP_copy.pod deleted file mode 100644 index d4896af1d5..0000000000 --- a/src/lib/libcrypto/doc/EC_GROUP_copy.pod +++ /dev/null @@ -1,174 +0,0 @@ -=pod - -=head1 NAME - -EC_GROUP_copy, EC_GROUP_dup, EC_GROUP_method_of, EC_GROUP_set_generator, EC_GROUP_get0_generator, EC_GROUP_get_order, EC_GROUP_get_cofactor, EC_GROUP_set_curve_name, EC_GROUP_get_curve_name, EC_GROUP_set_asn1_flag, EC_GROUP_get_asn1_flag, EC_GROUP_set_point_conversion_form, EC_GROUP_get_point_conversion_form, EC_GROUP_get0_seed, EC_GROUP_get_seed_len, EC_GROUP_set_seed, EC_GROUP_get_degree, EC_GROUP_check, EC_GROUP_check_discriminant, EC_GROUP_cmp, EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis, EC_GROUP_get_pentanomial_basis - Functions for manipulating B objects. - -=head1 SYNOPSIS - - #include - #include - - int EC_GROUP_copy(EC_GROUP *dst, const EC_GROUP *src); - EC_GROUP *EC_GROUP_dup(const EC_GROUP *src); - - const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group); - - int EC_GROUP_set_generator(EC_GROUP *group, const EC_POINT *generator, const BIGNUM *order, const BIGNUM *cofactor); - const EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group); - - int EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order, BN_CTX *ctx); - int EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx); - - void EC_GROUP_set_curve_name(EC_GROUP *group, int nid); - int EC_GROUP_get_curve_name(const EC_GROUP *group); - - void EC_GROUP_set_asn1_flag(EC_GROUP *group, int flag); - int EC_GROUP_get_asn1_flag(const EC_GROUP *group); - - void EC_GROUP_set_point_conversion_form(EC_GROUP *group, point_conversion_form_t form); - point_conversion_form_t EC_GROUP_get_point_conversion_form(const EC_GROUP *); - - unsigned char *EC_GROUP_get0_seed(const EC_GROUP *x); - size_t EC_GROUP_get_seed_len(const EC_GROUP *); - size_t EC_GROUP_set_seed(EC_GROUP *, const unsigned char *, size_t len); - - int EC_GROUP_get_degree(const EC_GROUP *group); - - int EC_GROUP_check(const EC_GROUP *group, BN_CTX *ctx); - - int EC_GROUP_check_discriminant(const EC_GROUP *group, BN_CTX *ctx); - - int EC_GROUP_cmp(const EC_GROUP *a, const EC_GROUP *b, BN_CTX *ctx); - - int EC_GROUP_get_basis_type(const EC_GROUP *); - int EC_GROUP_get_trinomial_basis(const EC_GROUP *, unsigned int *k); - int EC_GROUP_get_pentanomial_basis(const EC_GROUP *, unsigned int *k1, - unsigned int *k2, unsigned int *k3); - -=head1 DESCRIPTION - -EC_GROUP_copy copies the curve B into B. Both B and B must use the same EC_METHOD. - -EC_GROUP_dup creates a new EC_GROUP object and copies the content from B to the newly created -EC_GROUP object. - -EC_GROUP_method_of obtains the EC_METHOD of B. - -EC_GROUP_set_generator sets curve paramaters that must be agreed by all participants using the curve. These -paramaters include the B, the B and the B. The B is a well defined point on the -curve chosen for cryptographic operations. Integers used for point multiplications will be between 0 and -n-1 where n is the B. The B multipied by the B gives the number of points on the curve. - -EC_GROUP_get0_generator returns the generator for the identified B. - -The functions EC_GROUP_get_order and EC_GROUP_get_cofactor populate the provided B and B parameters -with the respective order and cofactors for the B. - -The functions EC_GROUP_set_curve_name and EC_GROUP_get_curve_name, set and get the NID for the curve respectively -(see L). If a curve does not have a NID associated with it, then EC_GROUP_get_curve_name -will return 0. - -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 -EC_GROUP_get_asn1_flag and EC_GROUP_set_asn1_flag get and set the status of the asn1_flag for the curve. If set then -the curve_name must also be set. - -The point_conversion_form for a curve controls how EC_POINT data is encoded as ASN1 as defined in X9.62 (ECDSA). -point_conversion_form_t is an enum defined as follows: - - 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; - - -For 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. - -For any given x co-ordinate for a point on a curve it is possible to derive two possible y values. For -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. - -For 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. - -The functions EC_GROUP_set_point_conversion_form and EC_GROUP_get_point_conversion_form set and get the point_conversion_form -for the curve respectively. - -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 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 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 -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. - -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. - -The function 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. - -The function 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. - -EC_GROUP_cmp compares B and B to determine whether they represent the same curve or not. - -The functions EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis and 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: - -f(x) = x^m + x^k + 1 with m > k >= 1 - -or a pentanomial of the form: - -f(x) = x^m + x^k3 + x^k2 + x^k1 + 1 with m > k3 > k2 > k1 >= 1 - -The function EC_GROUP_get_basis_type returns a NID identifying whether a trinomial or pentanomial is in use for the field. The -function EC_GROUP_get_trinomial_basis must only be called where f(x) is of the trinomial form, and returns the value of B. Similarly -the function EC_GROUP_get_pentanomial_basis must only be called where f(x) is of the pentanomial form, and returns the values of B, -B and B respectively. - -=head1 RETURN VALUES - -The following functions return 1 on success or 0 on error: EC_GROUP_copy, EC_GROUP_set_generator, EC_GROUP_check, -EC_GROUP_check_discriminant, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis. - -EC_GROUP_dup returns a pointer to the duplicated curve, or NULL on error. - -EC_GROUP_method_of returns the EC_METHOD implementation in use for the given curve or NULL on error. - -EC_GROUP_get0_generator returns the generator for the given curve or NULL on error. - -EC_GROUP_get_order, EC_GROUP_get_cofactor, EC_GROUP_get_curve_name, EC_GROUP_get_asn1_flag, EC_GROUP_get_point_conversion_form -and 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 EC_GROUP_get_curve_name will return 0. - -EC_GROUP_get0_seed returns a pointer to the seed that was used to generate the parameter b, or NULL if the seed is not -specified. EC_GROUP_get_seed_len returns the length of the seed or 0 if the seed is not specified. - -EC_GROUP_set_seed returns the length of the seed that has been set. If the supplied seed is NULL, or the supplied seed length is -0, the return value will be 1. On error 0 is returned. - -EC_GROUP_cmp returns 0 if the curves are equal, 1 if they are not equal, or -1 on error. - -EC_GROUP_get_basis_type returns the values NID_X9_62_tpBasis or NID_X9_62_ppBasis (as defined in ) for a -trinomial or pentanomial respectively. Alternatively in the event of an error a 0 is returned. - -=head1 SEE ALSO - -L, L, L, -L, L, L, -L, L - -=cut diff --git a/src/lib/libcrypto/doc/EC_GROUP_new.pod b/src/lib/libcrypto/doc/EC_GROUP_new.pod deleted file mode 100644 index 9ab3566e65..0000000000 --- a/src/lib/libcrypto/doc/EC_GROUP_new.pod +++ /dev/null @@ -1,95 +0,0 @@ -=pod - -=head1 NAME - -EC_GROUP_new, EC_GROUP_free, EC_GROUP_clear_free, EC_GROUP_new_curve_GFp, EC_GROUP_new_curve_GF2m, EC_GROUP_new_by_curve_name, EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m, EC_get_builtin_curves - Functions for creating and destroying B objects. - -=head1 SYNOPSIS - - #include - #include - - EC_GROUP *EC_GROUP_new(const EC_METHOD *meth); - void EC_GROUP_free(EC_GROUP *group); - void EC_GROUP_clear_free(EC_GROUP *group); - - EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); - EC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); - EC_GROUP *EC_GROUP_new_by_curve_name(int nid); - - int EC_GROUP_set_curve_GFp(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); - int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); - int EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); - int EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); - - size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems); - -=head1 DESCRIPTION - -Within the library there are two forms of elliptic curve 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 p is a prime number. This gives us a revised -elliptic curve equation as follows: - -y^2 mod p = x^3 +ax + b mod p - -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: - -y^2 + xy = x^3 + ax^2 + b (where b != 0) - -Operations in a binary field are performed relative to an B. All such curves with OpenSSL -use a trinomial or a pentanomial for this parameter. - -A new curve can be constructed by calling EC_GROUP_new, using the implementation provided by B (see -L). It is then necessary to call either EC_GROUP_set_curve_GFp or -EC_GROUP_set_curve_GF2m as appropriate to create a curve defined over Fp or over F2^m respectively. - -EC_GROUP_set_curve_GFp sets the curve parameters B

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. -EC_group_get_curve_GF2m obtains the previously set curve parameters. - -The functions EC_GROUP_new_curve_GFp and EC_GROUP_new_curve_GF2m are shortcuts for calling EC_GROUP_new and the -appropriate EC_group_set_curve function. An appropriate default implementation method will be used. - -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 -EC_get_builtin_curves. The parameter B should be an array of EC_builtin_curve structures of size B. The function -will populate the B array with information about the builtin curves. If B is less than the total number of -curves available, then the first B 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 B or -not). Passing a NULL B, or setting B to 0 will do nothing other than return the total number of curves available. -The EC_builtin_curve structure is defined as follows: - - typedef struct { - int nid; - const char *comment; - } EC_builtin_curve; - -Each EC_builtin_curve item has a unique integer id (B), and a human readable comment string describing the curve. - -In order to construct a builtin curve use the function EC_GROUP_new_by_curve_name and provide the B of the curve to -be constructed. - -EC_GROUP_free frees the memory associated with the EC_GROUP. - -EC_GROUP_clear_free destroys any sensitive data held within the EC_GROUP and then frees its memory. - -=head1 RETURN VALUES - -All EC_GROUP_new* functions return a pointer to the newly constructed group, or NULL on error. - -EC_get_builtin_curves returns the number of builtin curves that are available. - -EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m return 1 on success or 0 on error. - -=head1 SEE ALSO - -L, L, L, -L, L, L, -L, L - -=cut diff --git a/src/lib/libcrypto/doc/EC_KEY_new.pod b/src/lib/libcrypto/doc/EC_KEY_new.pod deleted file mode 100644 index 02d7bac82c..0000000000 --- a/src/lib/libcrypto/doc/EC_KEY_new.pod +++ /dev/null @@ -1,115 +0,0 @@ -=pod - -=head1 NAME - -EC_KEY_new, EC_KEY_get_flags, EC_KEY_set_flags, EC_KEY_clear_flags, EC_KEY_new_by_curve_name, EC_KEY_free, EC_KEY_copy, EC_KEY_dup, EC_KEY_up_ref, EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key, EC_KEY_set_private_key, EC_KEY_get0_public_key, EC_KEY_set_public_key, EC_KEY_get_enc_flags, EC_KEY_set_enc_flags, EC_KEY_get_conv_form, EC_KEY_set_conv_form, EC_KEY_get_key_method_data, EC_KEY_insert_key_method_data, EC_KEY_set_asn1_flag, EC_KEY_precompute_mult, EC_KEY_generate_key, EC_KEY_check_key, EC_KEY_set_public_key_affine_coordinates - Functions for creating, destroying and manipulating B objects. - -=head1 SYNOPSIS - - #include - #include - - EC_KEY *EC_KEY_new(void); - int EC_KEY_get_flags(const EC_KEY *key); - void EC_KEY_set_flags(EC_KEY *key, int flags); - void EC_KEY_clear_flags(EC_KEY *key, int flags); - EC_KEY *EC_KEY_new_by_curve_name(int nid); - void EC_KEY_free(EC_KEY *key); - EC_KEY *EC_KEY_copy(EC_KEY *dst, const EC_KEY *src); - EC_KEY *EC_KEY_dup(const EC_KEY *src); - int EC_KEY_up_ref(EC_KEY *key); - const EC_GROUP *EC_KEY_get0_group(const EC_KEY *key); - int EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group); - const BIGNUM *EC_KEY_get0_private_key(const EC_KEY *key); - int EC_KEY_set_private_key(EC_KEY *key, const BIGNUM *prv); - const EC_POINT *EC_KEY_get0_public_key(const EC_KEY *key); - int EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub); - unsigned int EC_KEY_get_enc_flags(const EC_KEY *key); - void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags); - point_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key); - void EC_KEY_set_conv_form(EC_KEY *eckey, point_conversion_form_t cform); - void *EC_KEY_get_key_method_data(EC_KEY *key, - void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *)); - void EC_KEY_insert_key_method_data(EC_KEY *key, void *data, - void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *)); - void EC_KEY_set_asn1_flag(EC_KEY *eckey, int asn1_flag); - int EC_KEY_precompute_mult(EC_KEY *key, BN_CTX *ctx); - int EC_KEY_generate_key(EC_KEY *key); - int EC_KEY_check_key(const EC_KEY *key); - int EC_KEY_set_public_key_affine_coordinates(EC_KEY *key, BIGNUM *x, BIGNUM *y); - -=head1 DESCRIPTION - -An EC_KEY represents a public key and (optionally) an associated private key. A new EC_KEY (with no associated curve) can be constructed by calling EC_KEY_new. -The reference count for the newly created EC_KEY is initially set to 1. A curve can be associated with the EC_KEY by calling -EC_KEY_set_group. - -Alternatively a new EC_KEY can be constructed by calling EC_KEY_new_by_curve_name and supplying the nid of the associated curve. Refer to L for a description of curve names. This function simply wraps calls to EC_KEY_new and -EC_GROUP_new_by_curve_name. - -Calling EC_KEY_free decrements the reference count for the EC_KEY object, and if it has dropped to zero then frees the memory associated -with it. - -EC_KEY_copy copies the contents of the EC_KEY in B into B. - -EC_KEY_dup creates a new EC_KEY object and copies B into it. - -EC_KEY_up_ref increments the reference count associated with the EC_KEY object. - -EC_KEY_generate_key generates a new public and private key for the supplied B object. B must have an 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 EC_GROUP object). The public key is an EC_POINT on the curve calculated by multiplying the generator for the curve by the -private key. - -EC_KEY_check_key performs various sanity checks on the EC_KEY object to confirm that it is valid. - -EC_KEY_set_public_key_affine_coordinates sets the public key for B based on its affine co-ordinates, i.e. it constructs an EC_POINT -object based on the supplied B and B values and sets the public key to be this EC_POINT. It will also performs certain sanity checks -on the key to confirm that it is valid. - -The functions EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key, EC_KEY_set_private_key, EC_KEY_get0_public_key, and EC_KEY_set_public_key get and set the EC_GROUP object, the private key and the EC_POINT public key for the B respectively. - -The functions EC_KEY_get_enc_flags and EC_KEY_set_enc_flags get and set the value of the encoding flags for the B. There are two encoding -flags currently defined - EC_PKEY_NO_PARAMETERS and EC_PKEY_NO_PUBKEY. These flags define the behaviour of how the B is -converted into ASN1 in a call to i2d_ECPrivateKey. If EC_PKEY_NO_PARAMETERS is set then the public parameters for the curve are not encoded -along with the private key. If EC_PKEY_NO_PUBKEY is set then the public key is not encoded along with the private key. - -The functions EC_KEY_get_conv_form and EC_KEY_set_conv_form get and set the point_conversion_form for the B. For a description -of point_conversion_forms please refer to L. - -EC_KEY_insert_key_method_data and EC_KEY_get_key_method_data enable the caller to associate arbitrary additional data specific to the -elliptic curve scheme being used with the EC_KEY object. This data is treated as a "black box" by the ec library. The data to be stored by EC_KEY_insert_key_method_data is provided in the B parameter, which must have associated functions for duplicating, freeing and "clear_freeing" the data item. If a subsequent EC_KEY_get_key_method_data call is issued, the functions for duplicating, freeing and "clear_freeing" the data item must be provided again, and they must be the same as they were when the data item was inserted. - -EC_KEY_set_flags sets the flags in the B parameter on the EC_KEY object. Any flags that are already set are left set. The currently defined standard flags are EC_FLAG_NON_FIPS_ALLOW and EC_FLAG_FIPS_CHECKED. In addition there is the flag EC_FLAG_COFACTOR_ECDH which is specific to ECDH and is defined in ecdh.h. EC_KEY_get_flags returns the current flags that are set for this EC_KEY. EC_KEY_clear_flags clears the flags indicated by the B parameter. All other flags are left in their existing state. - -EC_KEY_set_asn1_flag sets the asn1_flag on the underlying EC_GROUP object (if set). Refer to L for further information on the asn1_flag. - -EC_KEY_precompute_mult stores multiples of the underlying EC_GROUP generator for faster point multiplication. See also L. - - -=head1 RETURN VALUES - -EC_KEY_new, EC_KEY_new_by_curve_name and EC_KEY_dup return a pointer to the newly created EC_KEY object, or NULL on error. - -EC_KEY_get_flags returns the flags associated with the EC_KEY object as an integer. - -EC_KEY_copy returns a pointer to the destination key, or NULL on error. - -EC_KEY_up_ref, EC_KEY_set_group, EC_KEY_set_private_key, EC_KEY_set_public_key, EC_KEY_precompute_mult, EC_KEY_generate_key, EC_KEY_check_key and EC_KEY_set_public_key_affine_coordinates return 1 on success or 0 on error. - -EC_KEY_get0_group returns the EC_GROUP associated with the EC_KEY. - -EC_KEY_get0_private_key returns the private key associated with the EC_KEY. - -EC_KEY_get_enc_flags returns the value of the current encoding flags for the EC_KEY. - -EC_KEY_get_conv_form return the point_conversion_form for the EC_KEY. - - -=head1 SEE ALSO - -L, L, L, L, -L, L, -L, L - -=cut diff --git a/src/lib/libcrypto/doc/EC_POINT_add.pod b/src/lib/libcrypto/doc/EC_POINT_add.pod deleted file mode 100644 index ae92640843..0000000000 --- a/src/lib/libcrypto/doc/EC_POINT_add.pod +++ /dev/null @@ -1,72 +0,0 @@ -=pod - -=head1 NAME - -EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_is_at_infinity, EC_POINT_is_on_curve, EC_POINT_cmp, EC_POINT_make_affine, EC_POINTs_make_affine, EC_POINTs_mul, EC_POINT_mul, EC_GROUP_precompute_mult, EC_GROUP_have_precompute_mult - Functions for performing mathematical operations and tests on B objects. - -=head1 SYNOPSIS - - #include - #include - - int EC_POINT_add(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx); - int EC_POINT_dbl(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, BN_CTX *ctx); - int EC_POINT_invert(const EC_GROUP *group, EC_POINT *a, BN_CTX *ctx); - int EC_POINT_is_at_infinity(const EC_GROUP *group, const EC_POINT *p); - int EC_POINT_is_on_curve(const EC_GROUP *group, const EC_POINT *point, BN_CTX *ctx); - int EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx); - int EC_POINT_make_affine(const EC_GROUP *group, EC_POINT *point, BN_CTX *ctx); - int EC_POINTs_make_affine(const EC_GROUP *group, size_t num, EC_POINT *points[], BN_CTX *ctx); - int EC_POINTs_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, size_t num, const EC_POINT *p[], const BIGNUM *m[], BN_CTX *ctx); - int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, const EC_POINT *q, const BIGNUM *m, BN_CTX *ctx); - int EC_GROUP_precompute_mult(EC_GROUP *group, BN_CTX *ctx); - int EC_GROUP_have_precompute_mult(const EC_GROUP *group); - - -=head1 DESCRIPTION - -EC_POINT_add adds the two points B and B and places the result in B. Similarly EC_POINT_dbl doubles the point B and places the -result in B. In both cases it is valid for B to be one of B or B. - -EC_POINT_invert calculates the inverse of the supplied point B. The result is placed back in B. - -The function EC_POINT_is_at_infinity tests whether the supplied point is at infinity or not. - -EC_POINT_is_on_curve tests whether the supplied point is on the curve or not. - -EC_POINT_cmp compares the two supplied points and tests whether or not they are equal. - -The functions EC_POINT_make_affine and EC_POINTs_make_affine force the internal representation of the EC_POINT(s) into the affine -co-ordinate system. In the case of EC_POINTs_make_affine the value B provides the number of points in the array B to be -forced. - -EC_POINT_mul calculates the value generator * B + B * B and stores the result in B. The value B may be NULL in which case the result is just B * B. - -EC_POINTs_mul calculates the value generator * B + B * B + ... + B * B. As for EC_POINT_mul the value -B may be NULL. - -The function EC_GROUP_precompute_mult stores multiples of the generator for faster point multiplication, whilst -EC_GROUP_have_precompute_mult tests whether precomputation has already been done. See L for information -about the generator. - - -=head1 RETURN VALUES - -The following functions return 1 on success or 0 on error: EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_make_affine, -EC_POINTs_make_affine, EC_POINTs_make_affine, EC_POINT_mul, EC_POINTs_mul and EC_GROUP_precompute_mult. - -EC_POINT_is_at_infinity returns 1 if the point is at infinity, or 0 otherwise. - -EC_POINT_is_on_curve returns 1 if the point is on the curve, 0 if not, or -1 on error. - -EC_POINT_cmp returns 1 if the points are not equal, 0 if they are, or -1 on error. - -EC_GROUP_have_precompute_mult return 1 if a precomputation has been done, or 0 if not. - -=head1 SEE ALSO - -L, L, L, L, -L, L, -L, L - -=cut diff --git a/src/lib/libcrypto/doc/EC_POINT_new.pod b/src/lib/libcrypto/doc/EC_POINT_new.pod deleted file mode 100644 index b41ca0ed0c..0000000000 --- a/src/lib/libcrypto/doc/EC_POINT_new.pod +++ /dev/null @@ -1,123 +0,0 @@ -=pod - -=head1 NAME - -EC_POINT_new, EC_POINT_free, EC_POINT_clear_free, EC_POINT_copy, EC_POINT_dup, EC_POINT_method_of, EC_POINT_set_to_infinity, EC_POINT_set_Jprojective_coordinates, EC_POINT_get_Jprojective_coordinates_GFp, EC_POINT_set_affine_coordinates_GFp, EC_POINT_get_affine_coordinates_GFp, EC_POINT_set_compressed_coordinates_GFp, EC_POINT_set_affine_coordinates_GF2m, EC_POINT_get_affine_coordinates_GF2m, EC_POINT_set_compressed_coordinates_GF2m, EC_POINT_point2oct, EC_POINT_oct2point, EC_POINT_point2bn, EC_POINT_bn2point, EC_POINT_point2hex, EC_POINT_hex2point - Functions for creating, destroying and manipulating B objects. - -=head1 SYNOPSIS - - #include - #include - - EC_POINT *EC_POINT_new(const EC_GROUP *group); - void EC_POINT_free(EC_POINT *point); - void EC_POINT_clear_free(EC_POINT *point); - int EC_POINT_copy(EC_POINT *dst, const EC_POINT *src); - EC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group); - const EC_METHOD *EC_POINT_method_of(const EC_POINT *point); - int EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point); - int EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, const BIGNUM *y, const BIGNUM *z, BN_CTX *ctx); - int EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group, - const EC_POINT *p, BIGNUM *x, BIGNUM *y, BIGNUM *z, BN_CTX *ctx); - int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx); - int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group, - const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx); - int EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, int y_bit, BN_CTX *ctx); - int EC_POINT_set_affine_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx); - int EC_POINT_get_affine_coordinates_GF2m(const EC_GROUP *group, - const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx); - int EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, int y_bit, BN_CTX *ctx); - size_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p, - point_conversion_form_t form, - unsigned char *buf, size_t len, BN_CTX *ctx); - int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p, - const unsigned char *buf, size_t len, BN_CTX *ctx); - BIGNUM *EC_POINT_point2bn(const EC_GROUP *, const EC_POINT *, - point_conversion_form_t form, BIGNUM *, BN_CTX *); - EC_POINT *EC_POINT_bn2point(const EC_GROUP *, const BIGNUM *, - EC_POINT *, BN_CTX *); - char *EC_POINT_point2hex(const EC_GROUP *, const EC_POINT *, - point_conversion_form_t form, BN_CTX *); - EC_POINT *EC_POINT_hex2point(const EC_GROUP *, const char *, - EC_POINT *, BN_CTX *); - - -=head1 DESCRIPTION - -An EC_POINT represents a point on a curve. A new point is constructed by calling the function EC_POINT_new and providing the B -object that the point relates to. - -EC_POINT_free frees the memory associated with the EC_POINT. - -EC_POINT_clear_free destroys any sensitive data held within the EC_POINT and then frees its memory. - -EC_POINT_copy copies the point B into B. Both B and B must use the same EC_METHOD. - -EC_POINT_dup creates a new EC_POINT object and copies the content from B to the newly created -EC_POINT object. - -EC_POINT_method_of obtains the EC_METHOD associated with B. - -A valid point on a curve is the special point at infinity. A point is set to be at infinity by calling EC_POINT_set_to_infinity. - -The affine co-ordinates for a point describe a point in terms of its x and y position. The functions -EC_POINT_set_affine_coordinates_GFp and EC_POINT_set_affine_coordinates_GF2m set the B and B co-ordinates for the point -B

defined over the curve given in B. - -As well as the affine co-ordinates, a point can alternatively be described in terms of its Jacobian -projective co-ordinates (for Fp curves only). Jacobian projective co-ordinates are expressed as three values x, y and z. Working in -this co-ordinate system provides more efficient point multiplication operations. -A mapping exists between Jacobian projective co-ordinates and affine co-ordinates. A Jacobian projective co-ordinate (x, y, z) can be written as an affine co-ordinate as (x/(z^2), y/(z^3)). Conversion to Jacobian projective to affine co-ordinates is simple. The co-ordinate (x, y) is -mapped to (x, y, 1). To set or get the projective co-ordinates use EC_POINT_set_Jprojective_coordinates_GFp and -EC_POINT_get_Jprojective_coordinates_GFp respectively. - -Points can also be described in terms of their compressed co-ordinates. For a point (x, y), for any given value for x such that the point is -on the curve there will only ever be two possible values for y. Therefore a point can be set using the EC_POINT_set_compressed_coordinates_GFp -and EC_POINT_set_compressed_coordinates_GF2m functions where B is the x co-ordinate and B is a value 0 or 1 to identify which of -the two possible values for y should be used. - -In addition EC_POINTs can be converted to and from various external representations. Supported representations are octet strings, BIGNUMs and hexadecimal. The format of the external representation is described by the point_conversion_form. See L 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 BIGNUM is calculated by converting the point to an octet string and then converting that octet string into a BIGNUM integer. Points in hexadecimal format are stored in a NULL terminated character string where each character is one of the printable values 0-9 or A-F (or a-f). - -The functions EC_POINT_point2oct, EC_POINT_oct2point, EC_POINT_point2bn, EC_POINT_bn2point, EC_POINT_point2hex and EC_POINT_hex2point convert -from and to EC_POINTs for the formats: octet string, BIGNUM and hexadecimal respectively. - -The function EC_POINT_point2oct must be supplied with a buffer long enough to store the octet string. The return value provides the number of -octets stored. Calling the function with a NULL buffer will not perform the conversion but will still return the required buffer length. - -The function 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 free(). - -=head1 RETURN VALUES - -EC_POINT_new and EC_POINT_dup return the newly allocated EC_POINT or NULL on error. - -The following functions return 1 on success or 0 on error: EC_POINT_copy, EC_POINT_set_to_infinity, EC_POINT_set_Jprojective_coordinates_GFp, -EC_POINT_get_Jprojective_coordinates_GFp, EC_POINT_set_affine_coordinates_GFp, EC_POINT_get_affine_coordinates_GFp, -EC_POINT_set_compressed_coordinates_GFp, EC_POINT_set_affine_coordinates_GF2m, EC_POINT_get_affine_coordinates_GF2m, -EC_POINT_set_compressed_coordinates_GF2m and EC_POINT_oct2point. - -EC_POINT_method_of returns the EC_METHOD associated with the supplied EC_POINT. - -EC_POINT_point2oct returns the length of the required buffer, or 0 on error. - -EC_POINT_point2bn returns the pointer to the BIGNUM supplied, or NULL on error. - -EC_POINT_bn2point returns the pointer to the EC_POINT supplied, or NULL on error. - -EC_POINT_point2hex returns a pointer to the hex string, or NULL on error. - -EC_POINT_hex2point returns the pointer to the EC_POINT supplied, or NULL on error. - -=head1 SEE ALSO - -L, L, L, L, -L, L, -L, L - -=cut diff --git a/src/lib/libcrypto/man/DSA_SIG_new.3 b/src/lib/libcrypto/man/DSA_SIG_new.3 new file mode 100644 index 0000000000..32d21fb782 --- /dev/null +++ b/src/lib/libcrypto/man/DSA_SIG_new.3 @@ -0,0 +1,43 @@ +.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

, B and B for a curve over Fp stored in B. -EC_group_get_curve_GFp obtains the previously set curve parameters. - -EC_GROUP_set_curve_GF2m sets the equivalent curve parameters for a curve over F2^m. In this case B