.\" $OpenBSD: X509_STORE_CTX_set_verify.3,v 1.8 2024/06/07 05:51:39 tb Exp $ .\" .\" Copyright (c) 2021, 2022 Ingo Schwarze .\" Copyright (c) 2023 Job Snijders .\" .\" 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: June 7 2024 $ .Dt X509_STORE_CTX_SET_VERIFY 3 .Os .Sh NAME .Nm X509_STORE_CTX_verify_fn , .Nm X509_STORE_CTX_set_verify , .Nm X509_STORE_CTX_get_verify , .Nm X509_STORE_set_verify , .Nm X509_STORE_set_verify_func , .Nm X509_STORE_get_verify , .Nm X509_STORE_CTX_check_issued_fn , .Nm X509_STORE_set_check_issued , .Nm X509_STORE_get_check_issued , .Nm X509_STORE_CTX_get_check_issued .Nd user-defined certificate chain verification function .Sh SYNOPSIS .In openssl/x509_vfy.h .Ft typedef int .Fo (*X509_STORE_CTX_verify_fn) .Fa "X509_STORE_CTX *ctx" .Fc .Ft void .Fo X509_STORE_CTX_set_verify .Fa "X509_STORE_CTX *ctx" .Fa "X509_STORE_CTX_verify_fn verify" .Fc .Ft X509_STORE_CTX_verify_fn .Fo X509_STORE_CTX_get_verify .Fa "X509_STORE_CTX *ctx" .Fc .Ft void .Fo X509_STORE_set_verify .Fa "X509_STORE *store" .Fa "X509_STORE_CTX_verify_fn verify" .Fc .Ft void .Fo X509_STORE_set_verify_func .Fa "X509_STORE *store" .Fa "X509_STORE_CTX_verify_fn verify" .Fc .Ft X509_STORE_CTX_verify_fn .Fo X509_STORE_get_verify .Fa "X509_STORE_CTX *ctx" .Fc .Ft typedef int .Fo (*X509_STORE_CTX_check_issued_fn) .Fa "X509_STORE_CTX *ctx" .Fa "X509 *subject" .Fa "X509 *issuer" .Fc .Ft void .Fo X509_STORE_set_check_issued .Fa "X509_STORE *store" .Fa "X509_STORE_CTX_check_issued_fn check_issued" .Fc .Ft X509_STORE_CTX_check_issued_fn .Fo X509_STORE_get_check_issued .Fa "X509_STORE *store" .Fc .Ft X509_STORE_CTX_check_issued_fn .Fo X509_STORE_CTX_get_check_issued .Fa "X509_STORE_CTX *ctx" .Fc .Sh DESCRIPTION .Fn X509_STORE_CTX_set_verify configures .Fa ctx to use the .Fa verify argument as the X.509 certificate chain verification function instead of the default verification function built into the library when .Xr X509_verify_cert 3 is called. .Pp The .Fa verify function provided by the user is only called if the .Dv X509_V_FLAG_LEGACY_VERIFY or .Dv X509_V_FLAG_NO_ALT_CHAINS flag was set on .Fa ctx using .Xr X509_STORE_CTX_set_flags 3 or .Xr X509_VERIFY_PARAM_set_flags 3 . Otherwise, it is ignored and a different algorithm is used that does not support replacing the verification function. .Pp .Fn X509_STORE_set_verify saves the function pointer .Fa verify in the given .Fa store object. That pointer will be copied to an .Vt X509_STORE_CTX object when .Fa store is later passed as an argument to .Xr X509_STORE_CTX_init 3 . .Pp .Fn X509_STORE_set_verify_func is an alias for .Fn X509_STORE_set_verify implemented as a macro. .Pp .Fn X509_STORE_set_check_issued saves the function pointer .Fa check_issued in the given .Fa store object. That pointer will be copied to an .Vt X509_STORE_CTX object when .Fa store is later passed as an argument to .Fn X509_STORE_CTX_init 3 . .Pp The .Fa check_issued function provided by the user should check whether a given certificate .Fa subject was issued using the CA certificate .Fa issuer , and must return 0 on failure and 1 on success. The default implementation ignores the .Fa ctx argument and returns success if and only if .Xr X509_check_issued 3 returns .Dv X509_V_OK . It is important to pay close attention to the order of the .Fa issuer and .Fa subject arguments. In .Xr X509_check_issued 3 the .Fa issuer precedes the .Fa subject while in .Fn check_issued the .Fa subject comes first. .Sh RETURN VALUES .Fn X509_STORE_CTX_verify_fn is supposed to return 1 to indicate that the chain is valid or 0 if it is not or if an error occurred. .Pp .Fn X509_STORE_CTX_get_verify returns a function pointer previously set with .Fn X509_STORE_CTX_set_verify or .Xr X509_STORE_CTX_init 3 , or .Dv NULL if .Fa ctx is uninitialized. .Pp .Fn X509_STORE_get_verify returns the function pointer previously set with .Fn X509_STORE_set_verify , or .Dv NULL if that function was not called on the .Fa store . .Pp .Fn X509_STORE_get_check_issued returns the function pointer previously set with .Fn X509_STORE_set_check_issued , or .Dv NULL if that function was not called on the .Fa store . .Pp .Fn X509_STORE_CTX_get_check_issued returns the .Fn check_issued function pointer set on the .Vt X509_STORE_CTX . This is either the .Fn check_issued function inherited from the .Fa store used in .Xr X509_STORE_CTX_init 3 or the library's default implementation. .Sh SEE ALSO .Xr X509_check_issued 3 , .Xr X509_STORE_CTX_init 3 , .Xr X509_STORE_CTX_set_error 3 , .Xr X509_STORE_CTX_set_flags 3 , .Xr X509_STORE_CTX_set_verify_cb 3 , .Xr X509_STORE_new 3 , .Xr X509_STORE_set_flags 3 , .Xr X509_STORE_set_verify_cb 3 , .Xr X509_verify_cert 3 , .Xr X509_VERIFY_PARAM_set_flags 3 .Sh HISTORY .Fn X509_STORE_set_verify_func first appeared in SSLeay 0.8.0 and has been available since .Ox 2.4 . .Pp .Fn X509_STORE_CTX_set_verify and .Fn X509_STORE_CTX_get_verify first appeared in OpenSSL 1.1.0 and have been available since .Ox 7.1 . .Pp .Fn X509_STORE_CTX_verify_fn , .Fn X509_STORE_set_verify , and .Fn X509_STORE_get_verify first appeared in OpenSSL 1.1.0 and have been available since .Ox 7.2 . .Pp .Fn X509_STORE_set_check_issued , .Fn X509_STORE_get_check_issued , and .Fn X509_STORE_CTX_get_check_issued first appeared in OpenSSL 1.1.0 and have been available since .Ox 7.3 . .Sh BUGS The reversal of order of .Fa subject and .Fa issuer between .Fn check_issued and .Xr X509_check_issued 3 is very confusing. It has led to bugs and will cause many more.