1.\" $OpenBSD: X509_STORE_CTX_set_verify.3,v 1.8 2024/06/07 05:51:39 tb Exp $ 2.\" 3.\" Copyright (c) 2021, 2022 Ingo Schwarze <schwarze@openbsd.org> 4.\" Copyright (c) 2023 Job Snijders <job@openbsd.org> 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.Dd $Mdocdate: June 7 2024 $ 19.Dt X509_STORE_CTX_SET_VERIFY 3 20.Os 21.Sh NAME 22.Nm X509_STORE_CTX_verify_fn , 23.Nm X509_STORE_CTX_set_verify , 24.Nm X509_STORE_CTX_get_verify , 25.Nm X509_STORE_set_verify , 26.Nm X509_STORE_set_verify_func , 27.Nm X509_STORE_get_verify , 28.Nm X509_STORE_CTX_check_issued_fn , 29.Nm X509_STORE_set_check_issued , 30.Nm X509_STORE_get_check_issued , 31.Nm X509_STORE_CTX_get_check_issued 32.Nd user-defined certificate chain verification function 33.Sh SYNOPSIS 34.In openssl/x509_vfy.h 35.Ft typedef int 36.Fo (*X509_STORE_CTX_verify_fn) 37.Fa "X509_STORE_CTX *ctx" 38.Fc 39.Ft void 40.Fo X509_STORE_CTX_set_verify 41.Fa "X509_STORE_CTX *ctx" 42.Fa "X509_STORE_CTX_verify_fn verify" 43.Fc 44.Ft X509_STORE_CTX_verify_fn 45.Fo X509_STORE_CTX_get_verify 46.Fa "X509_STORE_CTX *ctx" 47.Fc 48.Ft void 49.Fo X509_STORE_set_verify 50.Fa "X509_STORE *store" 51.Fa "X509_STORE_CTX_verify_fn verify" 52.Fc 53.Ft void 54.Fo X509_STORE_set_verify_func 55.Fa "X509_STORE *store" 56.Fa "X509_STORE_CTX_verify_fn verify" 57.Fc 58.Ft X509_STORE_CTX_verify_fn 59.Fo X509_STORE_get_verify 60.Fa "X509_STORE_CTX *ctx" 61.Fc 62.Ft typedef int 63.Fo (*X509_STORE_CTX_check_issued_fn) 64.Fa "X509_STORE_CTX *ctx" 65.Fa "X509 *subject" 66.Fa "X509 *issuer" 67.Fc 68.Ft void 69.Fo X509_STORE_set_check_issued 70.Fa "X509_STORE *store" 71.Fa "X509_STORE_CTX_check_issued_fn check_issued" 72.Fc 73.Ft X509_STORE_CTX_check_issued_fn 74.Fo X509_STORE_get_check_issued 75.Fa "X509_STORE *store" 76.Fc 77.Ft X509_STORE_CTX_check_issued_fn 78.Fo X509_STORE_CTX_get_check_issued 79.Fa "X509_STORE_CTX *ctx" 80.Fc 81.Sh DESCRIPTION 82.Fn X509_STORE_CTX_set_verify 83configures 84.Fa ctx 85to use the 86.Fa verify 87argument as the X.509 certificate chain verification function instead 88of the default verification function built into the library when 89.Xr X509_verify_cert 3 90is called. 91.Pp 92The 93.Fa verify 94function provided by the user is only called if the 95.Dv X509_V_FLAG_LEGACY_VERIFY 96or 97.Dv X509_V_FLAG_NO_ALT_CHAINS 98flag was set on 99.Fa ctx 100using 101.Xr X509_STORE_CTX_set_flags 3 102or 103.Xr X509_VERIFY_PARAM_set_flags 3 . 104Otherwise, it is ignored and a different algorithm is used that does 105not support replacing the verification function. 106.Pp 107.Fn X509_STORE_set_verify 108saves the function pointer 109.Fa verify 110in the given 111.Fa store 112object. 113That pointer will be copied to an 114.Vt X509_STORE_CTX 115object when 116.Fa store 117is later passed as an argument to 118.Xr X509_STORE_CTX_init 3 . 119.Pp 120.Fn X509_STORE_set_verify_func 121is an alias for 122.Fn X509_STORE_set_verify 123implemented as a macro. 124.Pp 125.Fn X509_STORE_set_check_issued 126saves the function pointer 127.Fa check_issued 128in the given 129.Fa store 130object. 131That pointer will be copied to an 132.Vt X509_STORE_CTX 133object when 134.Fa store 135is later passed as an argument to 136.Fn X509_STORE_CTX_init 3 . 137.Pp 138The 139.Fa check_issued 140function provided by the user should check whether a given certificate 141.Fa subject 142was issued using the CA certificate 143.Fa issuer , 144and must return 0 on failure and 1 on success. 145The default implementation ignores the 146.Fa ctx 147argument and returns success if and only if 148.Xr X509_check_issued 3 149returns 150.Dv X509_V_OK . 151It is important to pay close attention to the order of the 152.Fa issuer 153and 154.Fa subject 155arguments. 156In 157.Xr X509_check_issued 3 158the 159.Fa issuer 160precedes the 161.Fa subject 162while in 163.Fn check_issued 164the 165.Fa subject 166comes first. 167.Sh RETURN VALUES 168.Fn X509_STORE_CTX_verify_fn 169is supposed to return 1 to indicate that the chain is valid 170or 0 if it is not or if an error occurred. 171.Pp 172.Fn X509_STORE_CTX_get_verify 173returns a function pointer previously set with 174.Fn X509_STORE_CTX_set_verify 175or 176.Xr X509_STORE_CTX_init 3 , 177or 178.Dv NULL 179if 180.Fa ctx 181is uninitialized. 182.Pp 183.Fn X509_STORE_get_verify 184returns the function pointer previously set with 185.Fn X509_STORE_set_verify , 186or 187.Dv NULL 188if that function was not called on the 189.Fa store . 190.Pp 191.Fn X509_STORE_get_check_issued 192returns the function pointer previously set with 193.Fn X509_STORE_set_check_issued , 194or 195.Dv NULL 196if that function was not called on the 197.Fa store . 198.Pp 199.Fn X509_STORE_CTX_get_check_issued 200returns the 201.Fn check_issued 202function pointer set on the 203.Vt X509_STORE_CTX . 204This is either the 205.Fn check_issued 206function inherited from the 207.Fa store 208used in 209.Xr X509_STORE_CTX_init 3 210or the library's default implementation. 211.Sh SEE ALSO 212.Xr X509_check_issued 3 , 213.Xr X509_STORE_CTX_init 3 , 214.Xr X509_STORE_CTX_set_error 3 , 215.Xr X509_STORE_CTX_set_flags 3 , 216.Xr X509_STORE_CTX_set_verify_cb 3 , 217.Xr X509_STORE_new 3 , 218.Xr X509_STORE_set_flags 3 , 219.Xr X509_STORE_set_verify_cb 3 , 220.Xr X509_verify_cert 3 , 221.Xr X509_VERIFY_PARAM_set_flags 3 222.Sh HISTORY 223.Fn X509_STORE_set_verify_func 224first appeared in SSLeay 0.8.0 and has been available since 225.Ox 2.4 . 226.Pp 227.Fn X509_STORE_CTX_set_verify 228and 229.Fn X509_STORE_CTX_get_verify 230first appeared in OpenSSL 1.1.0 and have been available since 231.Ox 7.1 . 232.Pp 233.Fn X509_STORE_CTX_verify_fn , 234.Fn X509_STORE_set_verify , 235and 236.Fn X509_STORE_get_verify 237first appeared in OpenSSL 1.1.0 and have been available since 238.Ox 7.2 . 239.Pp 240.Fn X509_STORE_set_check_issued , 241.Fn X509_STORE_get_check_issued , 242and 243.Fn X509_STORE_CTX_get_check_issued 244first appeared in OpenSSL 1.1.0 and have been available since 245.Ox 7.3 . 246.Sh BUGS 247The reversal of order of 248.Fa subject 249and 250.Fa issuer 251between 252.Fn check_issued 253and 254.Xr X509_check_issued 3 255is very confusing. 256It has led to bugs and will cause many more. 257