[thirdparty/openssl.git] / doc / man3 / X509_verify.pod

=pod

=head1 NAME

X509_verify, X509_self_signed,
X509_REQ_verify_ex, X509_REQ_verify,
X509_CRL_verify -
verify certificate, certificate request, or CRL signature

=head1 SYNOPSIS

 #include <openssl/x509.h>

 int X509_verify(X509 *x, EVP_PKEY *pkey);
 int X509_self_signed(X509 *cert, int verify_signature);

 int X509_REQ_verify_ex(X509_REQ *a, EVP_PKEY *pkey, OSSL_LIB_CTX *libctx,
                        const char *propq);
 int X509_REQ_verify(X509_REQ *a, EVP_PKEY *r);
 int X509_CRL_verify(X509_CRL *a, EVP_PKEY *r);

=head1 DESCRIPTION

X509_verify() verifies the signature of certificate I<x> using public key
I<pkey>. Only the signature is checked: no other checks (such as certificate
chain validity) are performed.

X509_self_signed() checks whether certificate I<cert> is self-signed.
For success the issuer and subject names must match, the components of the
authority key identifier (if present) must match the subject key identifier etc.
The signature itself is actually verified only if B<verify_signature> is 1, as
for explicitly trusted certificates this verification is not worth the effort.

X509_REQ_verify_ex(), X509_REQ_verify() and X509_CRL_verify()
verify the signatures of certificate requests and CRLs, respectively.

=head1 RETURN VALUES

X509_verify(),
X509_REQ_verify_ex(), X509_REQ_verify() and X509_CRL_verify()
return 1 if the signature is valid and 0 if the signature check fails.
If the signature could not be checked at all because it was ill-formed,
the certificate or the request was not complete or some other error occurred
then -1 is returned.

X509_self_signed() returns the same values but also returns 1
if all respective fields match and B<verify_signature> is 0.

=head1 SEE ALSO

L<d2i_X509(3)>,
L<ERR_get_error(3)>,
L<X509_CRL_get0_by_serial(3)>,
L<X509_get0_signature(3)>,
L<X509_get_ext_d2i(3)>,
L<X509_get_extension_flags(3)>,
L<X509_get_pubkey(3)>,
L<X509_get_subject_name(3)>,
L<X509_get_version(3)>,
L<X509_NAME_ENTRY_get_object(3)>,
L<X509_NAME_get_index_by_NID(3)>,
L<X509_NAME_print_ex(3)>,
L<X509V3_get_d2i(3)>,
L<X509_verify_cert(3)>,
L<OSSL_LIB_CTX(3)>

=head1 HISTORY

The X509_verify(), X509_REQ_verify(), and X509_CRL_verify()
functions are available in all versions of OpenSSL.

X509_REQ_verify_ex(), and X509_self_signed() were added in OpenSSL 3.0.

=head1 COPYRIGHT

Copyright 2015-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.

=cut
Commit	Line	Data
4cec750c DDO	1	=pod
	2
	3	=head1 NAME
	4
6725682d	5	X509_verify, X509_self_signed,
d8652be0	6	X509_REQ_verify_ex, X509_REQ_verify,
4cec750c DDO	7	X509_CRL_verify -
	8	verify certificate, certificate request, or CRL signature
	9
	10	=head1 SYNOPSIS
	11
	12	#include <openssl/x509.h>
	13
4cec750c	14	int X509_verify(X509 x, EVP_PKEY pkey);
0d8dbb52	15	int X509_self_signed(X509 *cert, int verify_signature);
4cec750c	16
b4250010	17	int X509_REQ_verify_ex(X509_REQ a, EVP_PKEY pkey, OSSL_LIB_CTX *libctx,
d8652be0	18	const char *propq);
4cec750c DDO	19	int X509_REQ_verify(X509_REQ a, EVP_PKEY r);
	20	int X509_CRL_verify(X509_CRL a, EVP_PKEY r);
	21
	22	=head1 DESCRIPTION
	23
6725682d SL	24	X509_verify() verifies the signature of certificate I<x> using public key
	25	I<pkey>. Only the signature is checked: no other checks (such as certificate
	26	chain validity) are performed.
4cec750c	27
54c0480d	28	X509_self_signed() checks whether certificate I<cert> is self-signed.
0d8dbb52 DDO	29	For success the issuer and subject names must match, the components of the
	30	authority key identifier (if present) must match the subject key identifier etc.
	31	The signature itself is actually verified only if B<verify_signature> is 1, as
	32	for explicitly trusted certificates this verification is not worth the effort.
	33
d8652be0	34	X509_REQ_verify_ex(), X509_REQ_verify() and X509_CRL_verify()
4cec750c DDO	35	verify the signatures of certificate requests and CRLs, respectively.
	36
	37	=head1 RETURN VALUES
	38
6725682d	39	X509_verify(),
d8652be0	40	X509_REQ_verify_ex(), X509_REQ_verify() and X509_CRL_verify()
4cec750c	41	return 1 if the signature is valid and 0 if the signature check fails.
54c0480d TM	42	If the signature could not be checked at all because it was ill-formed,
	43	the certificate or the request was not complete or some other error occurred
	44	then -1 is returned.
4cec750c	45
0d8dbb52 DDO	46	X509_self_signed() returns the same values but also returns 1
	47	if all respective fields match and B<verify_signature> is 0.
	48
4cec750c DDO	49	=head1 SEE ALSO
	50
	51	L<d2i_X509(3)>,
	52	L<ERR_get_error(3)>,
	53	L<X509_CRL_get0_by_serial(3)>,
	54	L<X509_get0_signature(3)>,
	55	L<X509_get_ext_d2i(3)>,
	56	L<X509_get_extension_flags(3)>,
	57	L<X509_get_pubkey(3)>,
	58	L<X509_get_subject_name(3)>,
	59	L<X509_get_version(3)>,
	60	L<X509_NAME_ENTRY_get_object(3)>,
	61	L<X509_NAME_get_index_by_NID(3)>,
	62	L<X509_NAME_print_ex(3)>,
	63	L<X509V3_get_d2i(3)>,
	64	L<X509_verify_cert(3)>,
b4250010	65	L<OSSL_LIB_CTX(3)>
4cec750c DDO	66
	67	=head1 HISTORY
	68
	69	The X509_verify(), X509_REQ_verify(), and X509_CRL_verify()
	70	functions are available in all versions of OpenSSL.
	71
d8652be0	72	X509_REQ_verify_ex(), and X509_self_signed() were added in OpenSSL 3.0.
4cec750c DDO	73
	74	=head1 COPYRIGHT
	75
3c95ef22	76	Copyright 2015-2023 The OpenSSL Project Authors. All Rights Reserved.
4cec750c DDO	77
	78	Licensed under the Apache License 2.0 (the "License"). You may not use
	79	this file except in compliance with the License. You can obtain a copy
	80	in the file LICENSE in the source distribution or at
	81	L<https://www.openssl.org/source/license.html>.
	82
	83	=cut