1.\" $OpenBSD: X509_STORE_CTX_set_verify.3,v 1.2 2021/11/23 17:06:05 tb Exp $ 2.\" 3.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: November 23 2021 $ 18.Dt X509_STORE_CTX_SET_VERIFY 3 19.Os 20.\" ds LIBRESSL_NEXT_API 21.Sh NAME 22.if dLIBRESSL_NEXT_API \{\ 23.Nm X509_STORE_CTX_verify_fn , 24.\} 25.Nm X509_STORE_CTX_set_verify , 26.ie dLIBRESSL_NEXT_API \{\ 27.Nm X509_STORE_CTX_get_verify , 28.Nm X509_STORE_set_verify , 29.Nm X509_STORE_set_verify_func 30.\} 31.el \{\ 32.Nm X509_STORE_CTX_get_verify 33.\} 34.Nd user-defined certificate chain verification function 35.Sh SYNOPSIS 36.In openssl/x509_vfy.h 37.if dLIBRESSL_NEXT_API \{\ 38.Ft typedef int 39.Fo "(*X509_STORE_CTX_verify_fn)" 40.Fa "X509_STORE_CTX *ctx" 41.Fc 42.\} 43.Ft void 44.Fo X509_STORE_CTX_set_verify 45.Fa "X509_STORE_CTX *ctx" 46.ie dLIBRESSL_NEXT_API \{\ 47.Fa "X509_STORE_CTX_verify_fn verify" 48.\} 49.el \{\ 50.Fa "int (*verify)(X509_STORE_CTX *)" 51.\} 52.Fc 53.ie dLIBRESSL_NEXT_API \{\ 54.Ft X509_STORE_CTX_verify_fn 55.Fo X509_STORE_CTX_get_verify 56.\} 57.el \{\ 58.Ft int 59.Fo "(*X509_STORE_CTX_get_verify(X509_STORE_CTX *ctx))" 60.\} 61.Fa "X509_STORE_CTX *ctx" 62.Fc 63.if dLIBRESSL_NEXT_API \{\ 64.Ft void 65.Fo X509_STORE_set_verify 66.Fa "X509_STORE *store" 67.Fa "X509_STORE_CTX_verify_fn verify" 68.Fc 69.Ft void 70.Fo X509_STORE_set_verify_func 71.Fa "X509_STORE *store" 72.Fa "X509_STORE_CTX_verify_fn verify" 73.Fc 74.\} 75.Sh DESCRIPTION 76.Fn X509_STORE_CTX_set_verify 77configures 78.Fa ctx 79to use the 80.Fa verify 81argument as the X.509 certificate chain verification function instead 82of the default verification function built into the library when 83.Xr X509_verify_cert 3 84is called. 85.Pp 86The 87.Fa verify 88function provided by the user is only called if the 89.Dv X509_V_FLAG_LEGACY_VERIFY 90or 91.Dv X509_V_FLAG_NO_ALT_CHAINS 92flag was set on 93.Fa ctx 94using 95.Xr X509_STORE_CTX_set_flags 3 96or 97.Xr X509_VERIFY_PARAM_set_flags 3 . 98Otherwise, it is ignored and a different algorithm is used that does 99not support replacing the verification function. 100.if dLIBRESSL_NEXT_API \{\ 101.Pp 102.Fn X509_STORE_set_verify 103saves the function pointer 104.Fa verify 105in the given 106.Fa store 107object. 108That pointer will be copied to an 109.Vt X509_STORE_CTX 110object when 111.Fa store 112is later passed as an argument to 113.Xr X509_STORE_CTX_init 3 . 114.Pp 115.Fn X509_STORE_set_verify_func 116is an alias for 117.Fn X509_STORE_set_verify 118implemented as a macro. 119.\} 120.Sh RETURN VALUES 121.if dLIBRESSL_NEXT_API \{\ 122.Fn X509_STORE_CTX_verify_fn 123is supposed to return 1 to indicate that the chain is valid 124or 0 if it is not or if an error occurred. 125.Pp 126.\} 127.Fn X509_STORE_CTX_get_verify 128returns a function pointer to the function previously set with 129.Fn X509_STORE_CTX_set_verify 130or 131.Xr X509_STORE_CTX_init 3 , 132or 133.Dv NULL 134if 135.Fa ctx 136is uninitialized. 137.Sh SEE ALSO 138.Xr X509_STORE_CTX_init 3 , 139.Xr X509_STORE_CTX_set_error 3 , 140.Xr X509_STORE_CTX_set_flags 3 , 141.Xr X509_STORE_CTX_set_verify_cb 3 , 142.Xr X509_STORE_new 3 , 143.Xr X509_STORE_set_flags 3 , 144.Xr X509_STORE_set_verify_cb 3 , 145.Xr X509_verify_cert 3 , 146.Xr X509_VERIFY_PARAM_set_flags 3 147.Sh HISTORY 148.if dLIBRESSL_NEXT_API \{\ 149.Fn X509_STORE_set_verify_func 150first appeared in SSLeay 0.8.0 and has been available since 151.Ox 2.4 . 152.Pp 153.\} 154.Fn X509_STORE_CTX_set_verify 155and 156.Fn X509_STORE_CTX_get_verify 157first appeared in OpenSSL 1.1.0 and have been available since 158.Ox 7.1 . 159.if dLIBRESSL_NEXT_API \{\ 160.Pp 161.Fn X509_STORE_CTX_verify_fn 162and 163.Fn X509_STORE_set_verify 164first appeared in OpenSSL 1.1.0 and have been available since 165.reminder Check the version number! 166.Ox 7.1 . 167.\} 168