diff options
author | Matt Caswell <matt@openssl.org> | 2019-07-15 15:54:08 +0100 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2019-08-06 11:19:07 +0100 |
commit | f585cefc046409d04f26b73307e677625be26e5a (patch) | |
tree | 38c24b4b33895a701f6ea596a3d954ef6dfbbc33 /doc | |
parent | 04ca002703fec56a44fc8704336709a309189e2c (diff) |
Add documentation for new EC functions
Document the new EC functions that are OPENSSL_CTX aware.
Reviewed-by: Nicola Tuveri <nic.tuv@gmail.com>
(Merged from https://github.com/openssl/openssl/pull/9380)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/EC_GROUP_new.pod | 29 | ||||
-rw-r--r-- | doc/man3/EC_KEY_new.pod | 43 |
2 files changed, 55 insertions, 17 deletions
diff --git a/doc/man3/EC_GROUP_new.pod b/doc/man3/EC_GROUP_new.pod index 87c3adaf33..6ac8e4aa83 100644 --- a/doc/man3/EC_GROUP_new.pod +++ b/doc/man3/EC_GROUP_new.pod @@ -4,6 +4,7 @@ EC_GROUP_get_ecparameters, EC_GROUP_get_ecpkparameters, +EC_GROUP_new_ex, EC_GROUP_new, EC_GROUP_new_from_ecparameters, EC_GROUP_new_from_ecpkparameters, @@ -11,6 +12,7 @@ EC_GROUP_free, EC_GROUP_clear_free, EC_GROUP_new_curve_GFp, EC_GROUP_new_curve_GF2m, +EC_GROUP_new_by_curve_name_ex, EC_GROUP_new_by_curve_name, EC_GROUP_set_curve, EC_GROUP_get_curve, @@ -25,6 +27,7 @@ objects #include <openssl/ec.h> + EC_GROUP *EC_GROUP_new_ex(OPENSSL_CTX *libctx, const EC_METHOD *meth); EC_GROUP *EC_GROUP_new(const EC_METHOD *meth); EC_GROUP *EC_GROUP_new_from_ecparameters(const ECPARAMETERS *params) EC_GROUP *EC_GROUP_new_from_ecpkparameters(const ECPKPARAMETERS *params) @@ -35,6 +38,7 @@ objects 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_ex(OPENSSL_CTX *libctx, int nid); EC_GROUP *EC_GROUP_new_by_curve_name(int nid); int EC_GROUP_set_curve(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, @@ -71,12 +75,18 @@ y^2 + xy = x^3 + ax^2 + b (where b != 0) Operations in a binary field are performed relative to an B<irreducible polynomial>. 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<meth> (see -L<EC_GFp_simple_method(3)>). It is then necessary to call EC_GROUP_set_curve() to set the curve parameters. +A new curve can be constructed by calling EC_GROUP_new_ex, using the implementation provided by B<meth> (see +L<EC_GFp_simple_method(3)>) and associated with the library context B<ctx> +(see L<OPENSSL_CTX(3)>). +The B<ctx> parameter may be NULL in which case the default library context is used. +It is then necessary to call EC_GROUP_set_curve() to set the curve parameters. EC_GROUP_new_from_ecparameters() will create a group from the specified B<params> and EC_GROUP_new_from_ecpkparameters() will create a group from the specific PK B<params>. +EC_GROUP_new is the same as EC_GROUP_new_ex() except that the library context +used is always the default library context. + EC_GROUP_set_curve() sets the curve parameters B<p>, B<a> and B<b>. For a curve over Fp B<b> is the prime for the field. For a curve over F2^m B<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 @@ -109,8 +119,12 @@ The EC_builtin_curve structure is defined as follows: Each EC_builtin_curve item has a unique integer id (B<nid>), 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<nid> of the curve to -be constructed. +In order to construct a builtin curve use the function EC_GROUP_new_by_curve_name_ex and provide the B<nid> of the curve to +be constructed and the associated library context to be used in B<ctx> (see L<OPENSSL_CTX(3)>). +The B<ctx> value may be NULL in which case the default library context is used. + +EC_GROUP_new_by_curve_name is the same as EC_GROUP_new_by_curve_name_ex except +that the default library context is always used. EC_GROUP_free frees the memory associated with the EC_GROUP. If B<group> is NULL nothing is done. @@ -130,7 +144,12 @@ EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROU L<crypto(7)>, L<EC_GROUP_copy(3)>, L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>, -L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)> +L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>, +L<OPENSSL_CTX(3)> + +=head1 HISTORY + +EC_GROUP_new_ex and EC_GROUP_new_by_curve_name_ex were added in OpenSSL 3.0. =head1 COPYRIGHT diff --git a/doc/man3/EC_KEY_new.pod b/doc/man3/EC_KEY_new.pod index 04ab2d5f57..ff4373ea35 100644 --- a/doc/man3/EC_KEY_new.pod +++ b/doc/man3/EC_KEY_new.pod @@ -2,10 +2,10 @@ =head1 NAME -EC_KEY_get_method, EC_KEY_set_method, +EC_KEY_get_method, EC_KEY_set_method, EC_KEY_new_ex, 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_engine, +EC_KEY_new_by_curve_name_ex, EC_KEY_new_by_curve_name, EC_KEY_free, EC_KEY_copy, +EC_KEY_dup, EC_KEY_up_ref, EC_KEY_get0_engine, 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_conv_form, @@ -19,10 +19,12 @@ EC_KEY objects #include <openssl/ec.h> + EC_KEY *EC_KEY_new_ex(OPENSSL_CTX *ctx); 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_ex(OPENSSL_CTX *ctx, int nid); 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); @@ -57,15 +59,31 @@ EC_KEY objects =head1 DESCRIPTION An EC_KEY represents a public key and, optionally, the 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 +key. +A new EC_KEY with no associated curve can be constructed by calling +EC_KEY_new_ex() and specifying the associated library context in B<ctx> +(see L<OPENSSL_CTX(3)>). +The B<ctx> parameter may be NULL in which case the default library context is +used. +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(). +EC_KEY_new() is the same as EC_KEY_new_ex() except that the default library +context is always used. + Alternatively a new EC_KEY can be constructed by calling -EC_KEY_new_by_curve_name() and supplying the nid of the associated curve. See -L<EC_GROUP_new(3)> for a description of curve names. This function simply -wraps calls to EC_KEY_new() and EC_GROUP_new_by_curve_name(). +EC_KEY_new_by_curve_name_ex() and supplying the nid of the associated curve and +the library context to be used B<ctx> (see L<OPENSSL_CTX(3)>). +The B<ctx> parameter may be NULL in which case the default library context is +used. +See L<EC_GROUP_new(3)> for a description of curve names. +This function simply wraps calls to EC_KEY_new_ex() and +EC_GROUP_new_by_curve_name_ex(). + +EC_KEY_new_by_curve_name() is the same as EC_KEY_new_by_curve_name_ex() except +that the default library context is always used. 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. If @@ -144,8 +162,8 @@ EC_KEY_priv2buf() converts an EC_KEY private key into an allocated buffer. =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_new_ex(), 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. @@ -174,7 +192,8 @@ L<crypto(7)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>, L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_GFp_simple_method(3)>, -L<d2i_ECPKParameters(3)> +L<d2i_ECPKParameters(3)>, +L<OPENSSL_CTX(3)> =head1 COPYRIGHT |