Add additional EC documentation.

Reviewed-by: Matt Caswell <matt@openssl.org>

doc/apps/genpkey.pod

@@ -141,11 +141,21 @@ and 2048 bit group with 256 bit subgroup as mentioned in RFC5114 sections
 
 =head1 EC PARAMETER GENERATION OPTIONS
 
+In OpenSSL 1.0.2 and later the EC parameter generation options below can also
+be supplied as EC key generation options. This can (for example) generate a
+key from a named curve without the need to use an explicit parameter file.
+
 =over 4
 
 =item B<ec_paramgen_curve:curve>
 
-the EC curve to use.
+the EC curve to use. OpenSSL 1.0.2 and later supports NIST curve names
+such as "P-256".
+
+=item B<ec_param_enc:encoding>
+
+the encoding to use for parameters. The "encoding" paramater must be either
+"named_curve" or "explicit".
 
 =back
 
@@ -223,6 +233,21 @@ Generate DH key from parameters:
 
  openssl genpkey -paramfile dhp.pem -out dhkey.pem
 
+Generate EC parameters:
+
+ openssl genpkey -genparam -algorithm EC -out ecp.pem \
+	-pkeyopt ec_paramgen_curve:secp384r1 \
+	-pkeyopt ec_param_enc:named_curve
+
+Generate EC key from parameters:
+
+ openssl genpkey -paramfile ecp.pem -out eckey.pem
+
+Generate EC key directly (OpenSSL 1.0.2+ only):
+
+ openssl genpkey -algorithm EC -out eckey.pem \
+	-pkeyopt ec_paramgen_curve:P-384 \
+	-pkeyopt ec_param_enc:named_curve
 
 =cut
 

doc/crypto/EC_GROUP_copy.pod

@@ -69,10 +69,18 @@ The functions EC_GROUP_set_curve_name and EC_GROUP_get_curve_name, set and get t
 (see L<EC_GROUP_new(3)|EC_GROUP_new(3)>). 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 asn1_flag value is used to determine whether the curve encoding uses
+explicit parameters or a named curve using an ASN1 OID: many applications only
+support the latter form. If asn1_flag is B<OPENSSL_EC_NAMED_CURVE> then the
+named curve form is used and the parameters must have a corresponding
+named curve NID set. If asn1_flags is B<OPENSSL_EC_EXPLICIT_CURVE> the
+parameters are explicitly encoded. 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.
+Note: B<OPENSSL_EC_EXPLICIT_CURVE> was first added to OpenSSL 1.1.0, for
+previous versions of OpenSSL the value 0 must be used instead. Before OpenSSL
+1.1.0 the default form was to use explicit parameters (meaning that
+applications would have to explicitly set the named curve form) in OpenSSL
+1.1.0 and later the named curve form is the default.
 
 The point_coversion_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: 

doc/crypto/EVP_PKEY_CTX_ctrl.pod

@@ -8,7 +8,8 @@ EVP_PKEY_CTX_set_rsa_pss_saltlen, EVP_PKEY_CTX_set_rsa_rsa_keygen_bits,
 EVP_PKEY_CTX_set_rsa_keygen_pubexp, EVP_PKEY_CTX_set_dsa_paramgen_bits,
 EVP_PKEY_CTX_set_dh_paramgen_prime_len,
 EVP_PKEY_CTX_set_dh_paramgen_generator,
-EVP_PKEY_CTX_set_ec_paramgen_curve_nid - algorithm specific control operations
+EVP_PKEY_CTX_set_ec_paramgen_curve_nid,
+EVP_PKEY_CTX_set_ec_param_enc - algorithm specific control operations
 
 =head1 SYNOPSIS
 
@@ -37,6 +38,7 @@ EVP_PKEY_CTX_set_ec_paramgen_curve_nid - algorithm specific control operations
 
  #include <openssl/ec.h>
  int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid);
+ int EVP_PKEY_CTX_set_ec_param_enc(EVP_PKEY_CTX *ctx, int param_enc);
 
 =head1 DESCRIPTION
 
@@ -106,7 +108,17 @@ for DH parameter generation. If not specified 2 is used.
 
 The EVP_PKEY_CTX_set_ec_paramgen_curve_nid() sets the EC curve for EC parameter
 generation to B<nid>. For EC parameter generation this macro must be called
-or an error occurs because there is no default curve.
+or an error occurs because there is no default curve. In OpenSSL 1.0.2 and
+later this function can also be called to set the curve explicitly when
+generating an EC key.
+
+The EVP_PKEY_CTX_set_ec_param_enc() sets the EC parameter encoding to
+B<param_enc> when generating EC parameters or an EC key. The encoding can be
+B<OPENSSL_EC_EXPLICIT_CURVE> for explicit parameters (the default in versions
+of OpenSSL before 1.1.0) or B<OPENSSL_EC_NAMED_CURVE> to use named curve form.
+For maximum compatibility the named curve form should be used. Note: the
+B<OPENSSL_EC_NAMED_CURVE> value was only added to OpenSSL 1.1.0: previous
+versions should use 0 instead.
 
 =head1 RETURN VALUES