.\" $OpenBSD: EVP_PKEY_check.3,v 1.2 2022/07/14 14:49:09 tb Exp $
.\"
.\" Copyright (c) 2022 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: July 14 2022 $
.Dt EVP_PKEY_CHECK 3
.Os
.Sh NAME
.Nm EVP_PKEY_check ,
.Nm EVP_PKEY_public_check ,
.Nm EVP_PKEY_param_check
.Nd key and parameter check functions
.Sh SYNOPSIS
.In openssl/evp.h
.Ft int
.Fn EVP_PKEY_check "EVP_PKEY_CTX *ctx"
.Ft int
.Fn EVP_PKEY_public_check "EVP_PKEY_CTX *ctx"
.Ft int
.Fn EVP_PKEY_param_check "EVP_PKEY_CTX *ctx"
.Sh DESCRIPTION
.Fn EVP_PKEY_check
performs various sanity checks on the key contained in
.Fa ctx
but only supports a small number of key types by default.
It preferably uses the function
.Fa check
configured for
.Fa ctx
with
.Xr EVP_PKEY_meth_set_check 3 .
It falls back to the function
.Fa pkey_check
configured for the private key contained in
.Fa ctx
with
.Xr EVP_PKEY_asn1_set_check 3 .
If that wasn't configured either, it attempts to use the following
check functions:
.Pp
.Bl -tag -width 3n -compact -offset -indent
.It DH
not supported, return value \-2
.It EC
.Xr EC_KEY_check_key 3
.It RSA
.Xr RSA_check_key 3
.El
.Pp
.Fn EVP_PKEY_public_check
performs various sanity checks on the public key contained in
.Fa ctx
but only supports a small number of key types by default.
It preferably uses the function
.Fa public_check
configured for
.Fa ctx
with
.Xr EVP_PKEY_meth_set_public_check 3 .
It falls back to the function
.Fa pkey_public_check
configured for the private key contained in
.Fa ctx
with
.Xr EVP_PKEY_asn1_set_public_check 3 .
If that wasn't configured either, it attempts to use the following
check functions:
.Pp
.Bl -tag -width 3n -compact -offset -indent
.It DH
.Xr DH_check_pub_key 3
.It EC
.Xr EC_KEY_check_key 3
.It RSA
not supported, return value \-2
.El
.Pp
.Fn EVP_PKEY_param_check
performs various sanity checks on the key parameters contained in
.Fa ctx
but only supports a small number of key types by default.
It preferably uses the function
.Fa check
configured for
.Fa ctx
with
.Xr EVP_PKEY_meth_set_param_check 3 .
It falls back to the function
.Fa pkey_check
configured for the private key contained in
.Fa ctx
with
.Xr EVP_PKEY_asn1_set_param_check 3 .
If that wasn't configured either, it attempts to use the following
check functions:
.Pp
.Bl -tag -width 3n -compact -offset -indent
.It DH
.Xr DH_check 3
.It EC
.Xr EC_GROUP_check 3
.It RSA
not supported, return value \-2
.El
.Sh RETURN VALUES
These functions return 1 if the check was performed and no problem
was found, 0 if a problem was found or if the check could not be
performed, for example because
.Fa ctx
does not contain an
.Vt EVP_PKEY
object, or \-2 if the required check function is neither configured for
.Fa ctx
nor for the
.Vt PKEY
contained therein, and the check in question is not supported by default
for the algorithm in question either.
.Sh SEE ALSO
.Xr DH_check 3 ,
.Xr EC_GROUP_check 3 ,
.Xr EC_KEY_new 3 ,
.Xr EVP_PKEY_asn1_new 3 ,
.Xr EVP_PKEY_CTX_new 3 ,
.Xr EVP_PKEY_meth_new 3 ,
.Xr EVP_PKEY_new 3 ,
.Xr RSA_check_key 3
.Sh HISTORY
These functions first appeared in OpenSSL 1.1.1
and have been available since
.Ox 7.1 .
.Sh BUGS
For EC keys,
.Fn EVP_PKEY_public_check
also checks the
.Em private
key and fails if there is a problem with any of the private
components, even if no problem is found with the public key.