.\"	$NetBSD: EVP_PKEY-EC.7,v 1.2 2023/05/31 19:42:42 christos Exp $
.\"
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "EVP_PKEY-EC 7"
.TH EVP_PKEY-EC 7 "2023-05-31" "3.0.9" "OpenSSL"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
EVP_PKEY\-EC,
EVP_KEYMGMT\-EC
\&\- EVP_PKEY EC keytype and algorithm support
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fB\s-1EC\s0\fR keytype is implemented in OpenSSL's default provider.
.SS "Common \s-1EC\s0 parameters"
.IX Subsection "Common EC parameters"
The normal way of specifying domain parameters for an \s-1EC\s0 curve is via the
curve name \*(L"group\*(R". For curves with no curve name, explicit parameters can be
used that specify \*(L"field-type\*(R", \*(L"p\*(R", \*(L"a\*(R", \*(L"b\*(R", \*(L"generator\*(R" and \*(L"order\*(R".
Explicit parameters are supported for backwards compability reasons, but they
are not compliant with multiple standards (including \s-1RFC5915\s0) which only allow
named curves.
.PP
The following KeyGen/Gettable/Import/Export types are available for the
built-in \s-1EC\s0 algorithm:
.ie n .IP """group"" (\fB\s-1OSSL_PKEY_PARAM_GROUP_NAME\s0\fR) <\s-1UTF8\s0 string>" 4
.el .IP "``group'' (\fB\s-1OSSL_PKEY_PARAM_GROUP_NAME\s0\fR) <\s-1UTF8\s0 string>" 4
.IX Item "group (OSSL_PKEY_PARAM_GROUP_NAME) <UTF8 string>"
The curve name.
.ie n .IP """field-type"" (\fB\s-1OSSL_PKEY_PARAM_EC_FIELD_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4
.el .IP "``field-type'' (\fB\s-1OSSL_PKEY_PARAM_EC_FIELD_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4
.IX Item "field-type (OSSL_PKEY_PARAM_EC_FIELD_TYPE) <UTF8 string>"
The value should be either \*(L"prime-field\*(R" or \*(L"characteristic-two-field\*(R",
which correspond to prime field Fp and binary field F2^m.
.ie n .IP """p"" (\fB\s-1OSSL_PKEY_PARAM_EC_P\s0\fR) <unsigned integer>" 4
.el .IP "``p'' (\fB\s-1OSSL_PKEY_PARAM_EC_P\s0\fR) <unsigned integer>" 4
.IX Item "p (OSSL_PKEY_PARAM_EC_P) <unsigned integer>"
For a curve over Fp \fIp\fR is the prime for the field. For a curve over F2^m \fIp\fR
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.
.ie n .IP """a"" (\fB\s-1OSSL_PKEY_PARAM_EC_A\s0\fR) <unsigned integer>" 4
.el .IP "``a'' (\fB\s-1OSSL_PKEY_PARAM_EC_A\s0\fR) <unsigned integer>" 4
.IX Item "a (OSSL_PKEY_PARAM_EC_A) <unsigned integer>"
.PD 0
.ie n .IP """b"" (\fB\s-1OSSL_PKEY_PARAM_EC_B\s0\fR) <unsigned integer>" 4
.el .IP "``b'' (\fB\s-1OSSL_PKEY_PARAM_EC_B\s0\fR) <unsigned integer>" 4
.IX Item "b (OSSL_PKEY_PARAM_EC_B) <unsigned integer>"
.ie n .IP """seed"" (\fB\s-1OSSL_PKEY_PARAM_EC_SEED\s0\fR) <octet string>" 4
.el .IP "``seed'' (\fB\s-1OSSL_PKEY_PARAM_EC_SEED\s0\fR) <octet string>" 4
.IX Item "seed (OSSL_PKEY_PARAM_EC_SEED) <octet string>"
.PD
\&\fIa\fR and \fIb\fR represents the coefficients of the curve
For Fp:   y^2 mod p = x^3 +ax + b mod p \s-1OR\s0
For F2^m: y^2 + xy = x^3 + ax^2 + b
.Sp
\&\fIseed\fR is an optional value that is for information purposes only.
It represents the random number seed used to generate the coefficient \fIb\fR from a
random number.
.ie n .IP """generator"" (\fB\s-1OSSL_PKEY_PARAM_EC_GENERATOR\s0\fR) <octet string>" 4
.el .IP "``generator'' (\fB\s-1OSSL_PKEY_PARAM_EC_GENERATOR\s0\fR) <octet string>" 4
.IX Item "generator (OSSL_PKEY_PARAM_EC_GENERATOR) <octet string>"
.PD 0
.ie n .IP """order"" (\fB\s-1OSSL_PKEY_PARAM_EC_ORDER\s0\fR) <unsigned integer>" 4
.el .IP "``order'' (\fB\s-1OSSL_PKEY_PARAM_EC_ORDER\s0\fR) <unsigned integer>" 4
.IX Item "order (OSSL_PKEY_PARAM_EC_ORDER) <unsigned integer>"
.ie n .IP """cofactor"" (\fB\s-1OSSL_PKEY_PARAM_EC_COFACTOR\s0\fR) <unsigned integer>" 4
.el .IP "``cofactor'' (\fB\s-1OSSL_PKEY_PARAM_EC_COFACTOR\s0\fR) <unsigned integer>" 4
.IX Item "cofactor (OSSL_PKEY_PARAM_EC_COFACTOR) <unsigned integer>"
.PD
The \fIgenerator\fR is a well defined point on the curve chosen for cryptographic
operations. The encoding conforms with Sec. 2.3.3 of the \s-1SECG SEC 1\s0 (\*(L"Elliptic Curve
Cryptography\*(R") standard. See \fBEC_POINT_oct2point()\fR.
Integers used for point multiplications will be between 0 and
\&\fIorder\fR \- 1.
\&\fIcofactor\fR is an optional value.
\&\fIorder\fR multiplied by the \fIcofactor\fR gives the number of points on the curve.
.ie n .IP """decoded-from-explicit"" (\fB\s-1OSSL_PKEY_PARAM_EC_DECODED_FROM_EXPLICIT_PARAMS\s0\fR) <integer>" 4
.el .IP "``decoded-from-explicit'' (\fB\s-1OSSL_PKEY_PARAM_EC_DECODED_FROM_EXPLICIT_PARAMS\s0\fR) <integer>" 4
.IX Item "decoded-from-explicit (OSSL_PKEY_PARAM_EC_DECODED_FROM_EXPLICIT_PARAMS) <integer>"
Gets a flag indicating wether the key or parameters were decoded from explicit
curve parameters. Set to 1 if so or 0 if a named curve was used.
.ie n .IP """use-cofactor-flag"" (\fB\s-1OSSL_PKEY_PARAM_USE_COFACTOR_ECDH\s0\fR) <integer>" 4
.el .IP "``use-cofactor-flag'' (\fB\s-1OSSL_PKEY_PARAM_USE_COFACTOR_ECDH\s0\fR) <integer>" 4
.IX Item "use-cofactor-flag (OSSL_PKEY_PARAM_USE_COFACTOR_ECDH) <integer>"
Enable Cofactor \s-1DH\s0 (\s-1ECC CDH\s0) if this value is 1, otherwise it uses normal \s-1EC DH\s0
if the value is zero. The cofactor variant multiplies the shared secret by the
\&\s-1EC\s0 curve's cofactor (note for some curves the cofactor is 1).
.Sp
See also \s-1\fBEVP_KEYEXCH\-ECDH\s0\fR\|(7) for the related
\&\fB\s-1OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE\s0\fR parameter that can be set on a
per-operation basis.
.ie n .IP """encoding"" (\fB\s-1OSSL_PKEY_PARAM_EC_ENCODING\s0\fR) <\s-1UTF8\s0 string>" 4
.el .IP "``encoding'' (\fB\s-1OSSL_PKEY_PARAM_EC_ENCODING\s0\fR) <\s-1UTF8\s0 string>" 4
.IX Item "encoding (OSSL_PKEY_PARAM_EC_ENCODING) <UTF8 string>"
Set the format used for serializing the \s-1EC\s0 group parameters.
Valid values are \*(L"explicit\*(R" or \*(L"named_curve\*(R". The default value is \*(L"named_curve\*(R".
.ie n .IP """point-format"" (\fB\s-1OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT\s0\fR) <\s-1UTF8\s0 string>" 4
.el .IP "``point-format'' (\fB\s-1OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT\s0\fR) <\s-1UTF8\s0 string>" 4
.IX Item "point-format (OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT) <UTF8 string>"
Sets or gets the point_conversion_form for the \fIkey\fR. For a description of
point_conversion_forms please see \fBEC_POINT_new\fR\|(3). Valid values are
\&\*(L"uncompressed\*(R" or \*(L"compressed\*(R". The default value is \*(L"uncompressed\*(R".
.ie n .IP """group-check"" (\fB\s-1OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4
.el .IP "``group-check'' (\fB\s-1OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4
.IX Item "group-check (OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE) <UTF8 string>"
Sets or Gets the type of group check done when \fBEVP_PKEY_param_check()\fR is called.
Valid values are \*(L"default\*(R", \*(L"named\*(R" and \*(L"named-nist\*(R".
The \*(L"named\*(R" type checks that the domain parameters match the inbuilt curve parameters,
\&\*(L"named-nist\*(R" is similiar but also checks that the named curve is a nist curve.
The \*(L"default\*(R" type does domain parameter validation for the OpenSSL default provider,
but is equivalent to \*(L"named-nist\*(R" for the OpenSSL \s-1FIPS\s0 provider.
.ie n .IP """include-public"" (\fB\s-1OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC\s0\fR) <integer>" 4
.el .IP "``include-public'' (\fB\s-1OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC\s0\fR) <integer>" 4
.IX Item "include-public (OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC) <integer>"
Setting this value to 0 indicates that the public key should not be included when
encoding the private key. The default value of 1 will include the public key.
.ie n .IP """pub"" (\fB\s-1OSSL_PKEY_PARAM_PUB_KEY\s0\fR) <octet string>" 4
.el .IP "``pub'' (\fB\s-1OSSL_PKEY_PARAM_PUB_KEY\s0\fR) <octet string>" 4
.IX Item "pub (OSSL_PKEY_PARAM_PUB_KEY) <octet string>"
The public key value in encoded \s-1EC\s0 point format conforming to Sec. 2.3.3 and
2.3.4 of the \s-1SECG SEC 1\s0 (\*(L"Elliptic Curve Cryptography\*(R") standard.
This parameter is used when importing or exporting the public key value with the
\&\fBEVP_PKEY_fromdata()\fR and \fBEVP_PKEY_todata()\fR functions.
.Sp
Note, in particular, that the choice of point compression format used for
encoding the exported value via \fBEVP_PKEY_todata()\fR depends on the underlying
provider implementation.
Before OpenSSL 3.0.8, the implementation of providers included with OpenSSL always
opted for an encoding in compressed format, unconditionally.
Since OpenSSL 3.0.8, the implementation has been changed to honor the
\&\fB\s-1OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT\s0\fR parameter, if set, or to default
to uncompressed format.
.ie n .IP """priv"" (\fB\s-1OSSL_PKEY_PARAM_PRIV_KEY\s0\fR) <unsigned integer>" 4
.el .IP "``priv'' (\fB\s-1OSSL_PKEY_PARAM_PRIV_KEY\s0\fR) <unsigned integer>" 4
.IX Item "priv (OSSL_PKEY_PARAM_PRIV_KEY) <unsigned integer>"
The private key value.
.ie n .IP """encoded-pub-key"" (\fB\s-1OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY\s0\fR) <octet string>" 4
.el .IP "``encoded-pub-key'' (\fB\s-1OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY\s0\fR) <octet string>" 4
.IX Item "encoded-pub-key (OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY) <octet string>"
Used for getting and setting the encoding of an \s-1EC\s0 public key. The public key
is expected to be a point conforming to Sec. 2.3.4 of the \s-1SECG SEC 1\s0 (\*(L"Elliptic
Curve Cryptography\*(R") standard.
.ie n .IP """qx"" (\fB\s-1OSSL_PKEY_PARAM_EC_PUB_X\s0\fR) <unsigned integer>" 4
.el .IP "``qx'' (\fB\s-1OSSL_PKEY_PARAM_EC_PUB_X\s0\fR) <unsigned integer>" 4
.IX Item "qx (OSSL_PKEY_PARAM_EC_PUB_X) <unsigned integer>"
Used for getting the \s-1EC\s0 public key X component.
.ie n .IP """qy"" (\fB\s-1OSSL_PKEY_PARAM_EC_PUB_Y\s0\fR) <unsigned integer>" 4
.el .IP "``qy'' (\fB\s-1OSSL_PKEY_PARAM_EC_PUB_Y\s0\fR) <unsigned integer>" 4
.IX Item "qy (OSSL_PKEY_PARAM_EC_PUB_Y) <unsigned integer>"
Used for getting the \s-1EC\s0 public key Y component.
.ie n .IP """default-digest"" (\fB\s-1OSSL_PKEY_PARAM_DEFAULT_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4
.el .IP "``default-digest'' (\fB\s-1OSSL_PKEY_PARAM_DEFAULT_DIGEST\s0\fR) <\s-1UTF8\s0 string>" 4
.IX Item "default-digest (OSSL_PKEY_PARAM_DEFAULT_DIGEST) <UTF8 string>"
Getter that returns the default digest name.
(Currently returns \*(L"\s-1SHA256\*(R"\s0 as of OpenSSL 3.0).
.PP
The following Gettable types are also available for the built-in \s-1EC\s0 algorithm:
.ie n .IP """basis-type"" (\fB\s-1OSSL_PKEY_PARAM_EC_CHAR2_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4
.el .IP "``basis-type'' (\fB\s-1OSSL_PKEY_PARAM_EC_CHAR2_TYPE\s0\fR) <\s-1UTF8\s0 string>" 4
.IX Item "basis-type (OSSL_PKEY_PARAM_EC_CHAR2_TYPE) <UTF8 string>"
Supports the values \*(L"tpBasis\*(R" for a trinomial or \*(L"ppBasis\*(R" for a pentanomial.
This field is only used for a binary field F2^m.
.ie n .IP """m"" (\fB\s-1OSSL_PKEY_PARAM_EC_CHAR2_M\s0\fR) <integer>" 4
.el .IP "``m'' (\fB\s-1OSSL_PKEY_PARAM_EC_CHAR2_M\s0\fR) <integer>" 4
.IX Item "m (OSSL_PKEY_PARAM_EC_CHAR2_M) <integer>"
.PD 0
.ie n .IP """tp"" (\fB\s-1OSSL_PKEY_PARAM_EC_CHAR2_TP_BASIS\s0\fR) <integer>" 4
.el .IP "``tp'' (\fB\s-1OSSL_PKEY_PARAM_EC_CHAR2_TP_BASIS\s0\fR) <integer>" 4
.IX Item "tp (OSSL_PKEY_PARAM_EC_CHAR2_TP_BASIS) <integer>"
.ie n .IP """k1"" (\fB\s-1OSSL_PKEY_PARAM_EC_CHAR2_PP_K1\s0\fR) <integer>" 4
.el .IP "``k1'' (\fB\s-1OSSL_PKEY_PARAM_EC_CHAR2_PP_K1\s0\fR) <integer>" 4
.IX Item "k1 (OSSL_PKEY_PARAM_EC_CHAR2_PP_K1) <integer>"
.ie n .IP """k2"" (\fB\s-1OSSL_PKEY_PARAM_EC_CHAR2_PP_K2\s0\fR) <integer>" 4
.el .IP "``k2'' (\fB\s-1OSSL_PKEY_PARAM_EC_CHAR2_PP_K2\s0\fR) <integer>" 4
.IX Item "k2 (OSSL_PKEY_PARAM_EC_CHAR2_PP_K2) <integer>"
.ie n .IP """k3"" (\fB\s-1OSSL_PKEY_PARAM_EC_CHAR2_PP_K3\s0\fR) <integer>" 4
.el .IP "``k3'' (\fB\s-1OSSL_PKEY_PARAM_EC_CHAR2_PP_K3\s0\fR) <integer>" 4
.IX Item "k3 (OSSL_PKEY_PARAM_EC_CHAR2_PP_K3) <integer>"
.PD
These fields are only used for a binary field F2^m.
\&\fIm\fR is the degree of the binary field.
.Sp
\&\fItp\fR is the middle bit of a trinomial so its value must be in the
range m > tp > 0.
.Sp
\&\fIk1\fR, \fIk2\fR and \fIk3\fR are used to get the middle bits of a pentanomial such
that m > k3 > k2 > k1 > 0
.SS "\s-1EC\s0 key validation"
.IX Subsection "EC key validation"
For \s-1EC\s0 keys, \fBEVP_PKEY_param_check\fR\|(3) behaves in the following way:
For the OpenSSL default provider it uses either
\&\fBEC_GROUP_check\fR\|(3) or \fBEC_GROUP_check_named_curve\fR\|(3) depending on the flag
\&\s-1EC_FLAG_CHECK_NAMED_GROUP.\s0
The OpenSSL \s-1FIPS\s0 provider uses \fBEC_GROUP_check_named_curve\fR\|(3) in order to
conform to SP800\-56Ar3 \fIAssurances of Domain-Parameter Validity\fR.
.PP
For \s-1EC\s0 keys, \fBEVP_PKEY_param_check_quick\fR\|(3) is equivalent to
\&\fBEVP_PKEY_param_check\fR\|(3).
.PP
For \s-1EC\s0 keys, \fBEVP_PKEY_public_check\fR\|(3) and \fBEVP_PKEY_public_check_quick\fR\|(3)
conform to SP800\-56Ar3 \fI\s-1ECC\s0 Full Public-Key Validation\fR and
\&\fI\s-1ECC\s0 Partial Public-Key Validation\fR respectively.
.PP
For \s-1EC\s0 Keys, \fBEVP_PKEY_private_check\fR\|(3) and \fBEVP_PKEY_pairwise_check\fR\|(3)
conform to SP800\-56Ar3 \fIPrivate key validity\fR and
\&\fIOwner Assurance of Pair-wise Consistency\fR respectively.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
An \fB\s-1EVP_PKEY\s0\fR context can be obtained by calling:
.PP
.Vb 2
\&    EVP_PKEY_CTX *pctx =
\&        EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
.Ve
.PP
An \fB\s-1EVP_PKEY\s0\fR \s-1ECDSA\s0 or \s-1ECDH\s0 key can be generated with a \*(L"P\-256\*(R" named group by
calling:
.PP
.Vb 1
\&    pkey = EVP_EC_gen("P\-256");
.Ve
.PP
or like this:
.PP
.Vb 4
\&    EVP_PKEY *key = NULL;
\&    OSSL_PARAM params[2];
\&    EVP_PKEY_CTX *gctx =
\&        EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
\&
\&    EVP_PKEY_keygen_init(gctx);
\&
\&    params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME,
\&                                                 "P\-256", 0);
\&    params[1] = OSSL_PARAM_construct_end();
\&    EVP_PKEY_CTX_set_params(gctx, params);
\&
\&    EVP_PKEY_generate(gctx, &key);
\&
\&    EVP_PKEY_print_private(bio_out, key, 0, NULL);
\&    ...
\&    EVP_PKEY_free(key);
\&    EVP_PKEY_CTX_free(gctx);
.Ve
.PP
An \fB\s-1EVP_PKEY\s0\fR \s-1EC CDH\s0 (Cofactor Diffie-Hellman) key can be generated with a
\&\*(L"K\-571\*(R" named group by calling:
.PP
.Vb 5
\&    int use_cdh = 1;
\&    EVP_PKEY *key = NULL;
\&    OSSL_PARAM params[3];
\&    EVP_PKEY_CTX *gctx =
\&        EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
\&
\&    EVP_PKEY_keygen_init(gctx);
\&
\&    params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME,
\&                                                 "K\-571", 0);
\&    /*
\&     * This curve has a cofactor that is not 1 \- so setting CDH mode changes
\&     * the behaviour. For many curves the cofactor is 1 \- so setting this has
\&     * no effect.
\&     */
\&    params[1] = OSSL_PARAM_construct_int(OSSL_PKEY_PARAM_USE_COFACTOR_ECDH,
\&                                         &use_cdh);
\&    params[2] = OSSL_PARAM_construct_end();
\&    EVP_PKEY_CTX_set_params(gctx, params);
\&
\&    EVP_PKEY_generate(gctx, &key);
\&    EVP_PKEY_print_private(bio_out, key, 0, NULL);
\&    ...
\&    EVP_PKEY_free(key);
\&    EVP_PKEY_CTX_free(gctx);
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBEVP_EC_gen\fR\|(3),
\&\s-1\fBEVP_KEYMGMT\s0\fR\|(3),
\&\s-1\fBEVP_PKEY\s0\fR\|(3),
\&\fBprovider\-keymgmt\fR\|(7),
\&\s-1\fBEVP_SIGNATURE\-ECDSA\s0\fR\|(7),
\&\s-1\fBEVP_KEYEXCH\-ECDH\s0\fR\|(7)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2020\-2023 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (the \*(L"License\*(R").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.