1.\" $OpenBSD: X509_STORE_CTX_set_flags.3,v 1.8 2024/08/29 20:21:10 tb Exp $ 2.\" full merge up to: OpenSSL aae41f8c Jun 25 09:47:15 2015 +0100 3.\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 4.\" 5.\" This file is a derived work. 6.\" The changes are covered by the following Copyright and license: 7.\" 8.\" Copyright (c) 2019 Claudio Jeker <claudio@openbsd.org> 9.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org> 10.\" 11.\" Permission to use, copy, modify, and distribute this software for any 12.\" purpose with or without fee is hereby granted, provided that the above 13.\" copyright notice and this permission notice appear in all copies. 14.\" 15.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES 16.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 17.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR 18.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 19.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 20.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 21.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 22.\" 23.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>. 24.\" Copyright (c) 2009 The OpenSSL Project. All rights reserved. 25.\" 26.\" Redistribution and use in source and binary forms, with or without 27.\" modification, are permitted provided that the following conditions 28.\" are met: 29.\" 30.\" 1. Redistributions of source code must retain the above copyright 31.\" notice, this list of conditions and the following disclaimer. 32.\" 33.\" 2. Redistributions in binary form must reproduce the above copyright 34.\" notice, this list of conditions and the following disclaimer in 35.\" the documentation and/or other materials provided with the 36.\" distribution. 37.\" 38.\" 3. All advertising materials mentioning features or use of this 39.\" software must display the following acknowledgment: 40.\" "This product includes software developed by the OpenSSL Project 41.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 42.\" 43.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 44.\" endorse or promote products derived from this software without 45.\" prior written permission. For written permission, please contact 46.\" openssl-core@openssl.org. 47.\" 48.\" 5. Products derived from this software may not be called "OpenSSL" 49.\" nor may "OpenSSL" appear in their names without prior written 50.\" permission of the OpenSSL Project. 51.\" 52.\" 6. Redistributions of any form whatsoever must retain the following 53.\" acknowledgment: 54.\" "This product includes software developed by the OpenSSL Project 55.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 56.\" 57.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 58.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 59.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 60.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 61.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 62.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 63.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 64.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 65.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 66.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 67.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 68.\" OF THE POSSIBILITY OF SUCH DAMAGE. 69.\" 70.Dd $Mdocdate: August 29 2024 $ 71.Dt X509_STORE_CTX_SET_FLAGS 3 72.Os 73.Sh NAME 74.Nm X509_STORE_CTX_set_flags , 75.Nm X509_STORE_CTX_set_time , 76.Nm X509_STORE_CTX_set_depth , 77.Nm X509_STORE_CTX_set_trust , 78.Nm X509_STORE_CTX_set_purpose , 79.\" .Nm X509_STORE_CTX_purpose_inherit is intentionally undocumented 80.\" because it will be removed in the next major bump. 81.Nm X509_STORE_CTX_get0_param , 82.Nm X509_STORE_CTX_set0_param , 83.Nm X509_STORE_CTX_set_default 84.Nd X509_STORE_CTX parameter initialisation 85.Sh SYNOPSIS 86.In openssl/x509_vfy.h 87.Ft void 88.Fo X509_STORE_CTX_set_flags 89.Fa "X509_STORE_CTX *ctx" 90.Fa "unsigned long flags" 91.Fc 92.Ft void 93.Fo X509_STORE_CTX_set_time 94.Fa "X509_STORE_CTX *ctx" 95.Fa "unsigned long dummy" 96.Fa "time_t time" 97.Fc 98.Ft void 99.Fo X509_STORE_CTX_set_depth 100.Fa "X509_STORE_CTX *ctx" 101.Fa "int depth" 102.Fc 103.Ft int 104.Fo X509_STORE_CTX_set_trust 105.Fa "X509_STORE_CTX *ctx" 106.Fa "int trust" 107.Fc 108.Ft int 109.Fo X509_STORE_CTX_set_purpose 110.Fa "X509_STORE_CTX *ctx" 111.Fa "int purpose" 112.Fc 113.Ft X509_VERIFY_PARAM * 114.Fo X509_STORE_CTX_get0_param 115.Fa "X509_STORE_CTX *ctx" 116.Fc 117.Ft void 118.Fo X509_STORE_CTX_set0_param 119.Fa "X509_STORE_CTX *ctx" 120.Fa "X509_VERIFY_PARAM *param" 121.Fc 122.Ft int 123.Fo X509_STORE_CTX_set_default 124.Fa "X509_STORE_CTX *ctx" 125.Fa "const char *name" 126.Fc 127.Sh DESCRIPTION 128These functions operate on the 129.Vt X509_VERIFY_PARAM 130object used by 131.Fa ctx . 132Usually, 133.Xr X509_STORE_CTX_init 3 134is called on 135.Fa ctx 136before these functions, and 137.Xr X509_verify_cert 3 138afterwards. 139.Pp 140.Fn X509_STORE_CTX_set_flags 141sets the internal verification parameter flags to 142.Fa flags . 143See 144.Xr X509_VERIFY_PARAM_set_flags 3 145for a description of the verification flags. 146.Pp 147.Fn X509_STORE_CTX_set_time 148sets the verification 149.Fa time 150using 151.Xr X509_VERIFY_PARAM_set_time 3 . 152The 153.Fa dummy 154argument is ignored. 155.Pp 156.Fn X509_STORE_CTX_set_depth 157sets the maximum verification 158.Fa depth 159using 160.Xr X509_VERIFY_PARAM_set_depth 3 . 161That is the maximum number of untrusted CA certificates 162that can appear in a chain. 163.Pp 164.Fn X509_STORE_CTX_set_trust 165sets the 166.Fa trust 167identifier that can also be set using 168.Xr X509_VERIFY_PARAM_set_trust 3 . 169If the 170.Fa trust 171argument is 0 or invalid 172or the trust identifier is already set to a non-zero value in the 173.Vt X509_VERIFY_PARAM 174object, no action occurs. 175.Pp 176.Fn X509_STORE_CTX_set_purpose 177sets the 178.Fa purpose 179identifier that can also be set using 180.Xr X509_VERIFY_PARAM_set_purpose 3 . 181If the 182.Fa purpose 183argument is 0 or any failure occurs, nothing is changed. 184.Pp 185In the following, the trust identifier contained in the 186.Vt X509_PURPOSE 187object associated with 188.Fa purpose 189is called the 190.Dq associated trust . 191.Pp 192The function fails if the 193.Fa purpose 194argument or the associated trust is invalid but not 0; otherwise, 195.Fn X509_STORE_CTX_set_purpose 196also does the equivalent of calling 197.Fn X509_STORE_CTX_set_trust 198with the associated trust. 199.Pp 200If the purpose identifier is already set to a non-zero value in the 201.Vt X509_VERIFY_PARAM 202object, it is not changed, even if the 203.Fa purpose 204argument is valid, too. 205.Pp 206.Fn X509_STORE_CTX_get0_param 207retrieves an internal pointer to the verification parameters associated 208with 209.Fa ctx . 210.Pp 211.Fn X509_STORE_CTX_set0_param 212sets the internal verification parameter pointer to 213.Fa param . 214After this call 215.Fa param 216should not be used. 217.Pp 218.Fn X509_STORE_CTX_set_default 219looks up and sets the default verification method to 220.Fa name . 221This uses the function 222.Xr X509_VERIFY_PARAM_lookup 3 223to find an appropriate set of parameters from 224.Fa name 225and copies them using 226.Xr X509_VERIFY_PARAM_inherit 3 . 227.Sh RETURN VALUES 228.Fn X509_STORE_CTX_set_trust 229returns 1 if the 230.Fa trust 231argument is 0 or valid or 0 if it is invalid but not 0. 232A return value of 1 does 233.Em not 234imply that the trust identifier stored in the 235.Vt X509_VERIFY_PARAM 236object was changed. 237.Pp 238.Fn X509_STORE_CTX_set_purpose 239returns 1 if both the 240.Fa purpose 241argument and the associated trust are 0 or valid. 242It returns 0 if either the 243.Fa purpose 244argument or the associated trust is invalid but not 0. 245A return value of 1 does not imply that any data was changed. 246.Pp 247.Fn X509_STORE_CTX_get0_param 248returns a pointer to an 249.Vt X509_VERIFY_PARAM 250structure or 251.Dv NULL 252if an error occurred. 253.Pp 254.Fn X509_STORE_CTX_set_default 255returns 1 for success or 0 if an error occurred. 256.Sh ERRORS 257The following diagnostics can be retrieved with 258.Xr ERR_get_error 3 , 259.Xr ERR_GET_REASON 3 , 260and 261.Xr ERR_reason_error_string 3 : 262.Bl -tag -width Ds 263.It Dv X509_R_UNKNOWN_TRUST_ID Qq "unknown trust id" 264.Fn X509_STORE_CTX_set_trust 265was called with a 266.Fa trust 267argument that is invalid but not 0. 268Other implementations may also return this when 269.Fn X509_STORE_CTX_set_purpose 270is called with a 271.Fa purpose 272argument with invalid associated trust. 273.It Dv X509_R_UNKNOWN_PURPOSE_ID Qq "unknown purpose id" 274The 275.Fa purpose 276argument is invalid but not 0. 277.El 278.Pp 279The other functions provide no diagnostics. 280.Sh SEE ALSO 281.Xr X509_STORE_CTX_get_error 3 , 282.Xr X509_STORE_CTX_new 3 , 283.Xr X509_STORE_CTX_set_verify 3 , 284.Xr X509_STORE_CTX_set_verify_cb 3 , 285.Xr X509_STORE_new 3 , 286.Xr X509_STORE_set1_param 3 , 287.Xr X509_STORE_set_verify_cb 3 , 288.Xr X509_verify_cert 3 , 289.Xr X509_VERIFY_PARAM_new 3 , 290.Xr X509_VERIFY_PARAM_set_flags 3 291.Sh HISTORY 292.Fn X509_STORE_CTX_set_depth 293first appeared in OpenSSL 0.9.3 and has been available since 294.Ox 2.4 . 295.Pp 296.Fn X509_STORE_CTX_set_trust 297and 298.Fn X509_STORE_CTX_set_purpose 299first appeared in OpenSSL 0.9.5 and have been available since 300.Ox 2.7 . 301.Pp 302.Fn X509_STORE_CTX_set_flags 303and 304.Fn X509_STORE_CTX_set_time 305first appeared in OpenSSL 0.9.6 and have been available since 306.Ox 2.9 . 307.Pp 308.Fn X509_STORE_CTX_get0_param , 309.Fn X509_STORE_CTX_set0_param , 310and 311.Fn X509_STORE_CTX_set_default 312first appeared in OpenSSL 0.9.8 and have been available since 313.Ox 4.5 . 314.Sh CAVEATS 315The precise effect of a successful call to 316.Fn X509_STORE_CTX_set_trust 317and 318.Fn X509_STORE_CTX_set_purpose 319is unclear unless only one of these functions is used immediately after 320.Xr X509_STORE_CTX_init 3 . 321It is therefore recommended to use 322.Fn X509_STORE_CTX_get0_param , 323.Xr X509_VERIFY_PARAM_set_trust 3 , 324and 325.Xr X509_VERIFY_PARAM_set_purpose 3 326instead. 327