1.\" $OpenBSD: X509_VERIFY_PARAM_new.3,v 1.5 2023/05/24 09:57:50 tb Exp $ 2.\" 3.\" Copyright (c) 2018, 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: May 24 2023 $ 18.Dt X509_VERIFY_PARAM_NEW 3 19.Os 20.Sh NAME 21.Nm X509_VERIFY_PARAM_new , 22.Nm X509_VERIFY_PARAM_inherit , 23.Nm X509_VERIFY_PARAM_set1 , 24.Nm X509_VERIFY_PARAM_free , 25.Nm X509_VERIFY_PARAM_add0_table , 26.Nm X509_VERIFY_PARAM_lookup , 27.Nm X509_VERIFY_PARAM_get_count , 28.Nm X509_VERIFY_PARAM_get0 , 29.Nm X509_VERIFY_PARAM_table_cleanup 30.\" The following constants defined in the public header <openssl/x509_vfy.h> 31.\" are intentionally undocumented because X509_VERIFY_PARAM is an opaque 32.\" struct and LibreSSL provides neither X509_VERIFY_PARAM_set_inh_flags(3) 33.\" nor X509_VERIFY_PARAM_get_inh_flags(3): 34.\" X509_VP_FLAG_DEFAULT 35.\" X509_VP_FLAG_OVERWRITE 36.\" X509_VP_FLAG_RESET_FLAGS 37.\" X509_VP_FLAG_LOCKED 38.\" X509_VP_FLAG_ONCE 39.Nd X509 verification parameter objects 40.Sh SYNOPSIS 41.In openssl/x509_vfy.h 42.Ft X509_VERIFY_PARAM * 43.Fo X509_VERIFY_PARAM_new 44.Fa void 45.Fc 46.Ft int 47.Fo X509_VERIFY_PARAM_inherit 48.Fa "X509_VERIFY_PARAM *destination" 49.Fa "const X509_VERIFY_PARAM *source" 50.Fc 51.Ft int 52.Fo X509_VERIFY_PARAM_set1 53.Fa "X509_VERIFY_PARAM *destination" 54.Fa "const X509_VERIFY_PARAM *source" 55.Fc 56.Ft void 57.Fo X509_VERIFY_PARAM_free 58.Fa "X509_VERIFY_PARAM *param" 59.Fc 60.Ft int 61.Fo X509_VERIFY_PARAM_add0_table 62.Fa "X509_VERIFY_PARAM *param" 63.Fc 64.Ft const X509_VERIFY_PARAM * 65.Fo X509_VERIFY_PARAM_lookup 66.Fa "const char *name" 67.Fc 68.Ft int 69.Fo X509_VERIFY_PARAM_get_count 70.Fa void 71.Fc 72.Ft const X509_VERIFY_PARAM * 73.Fo X509_VERIFY_PARAM_get0 74.Fa "int id" 75.Fc 76.Ft void 77.Fo X509_VERIFY_PARAM_table_cleanup 78.Fa void 79.Fc 80.Sh DESCRIPTION 81.Fn X509_VERIFY_PARAM_new 82allocates and initializes an empty 83.Vt X509_VERIFY_PARAM 84object. 85.Pp 86.Fn X509_VERIFY_PARAM_inherit 87copies some data from the 88.Fa source 89object to the 90.Fa destination 91object. 92.Pp 93The verification flags set with 94.Xr X509_VERIFY_PARAM_set_flags 3 95in the 96.Fa source 97object are always OR'ed into the verification flags of the 98.Fa destination 99object. 100.Pp 101Fields having their default value in the 102.Fa source 103object are not copied. 104.Pp 105By default, fields in the 106.Fa destination 107object already having a non-default value are not overwritten. 108However, if at least one of the 109.Fa source 110or 111.Fa destination 112objects was created during a call to 113.Xr X509_STORE_CTX_init 3 114that did not have a 115.Fa store 116argument, and if that object was not previously used as the 117.Fa destination 118in an earlier call to 119.Fn X509_VERIFY_PARAM_inherit , 120this restriction is waived and even non-default fields in the 121.Fa destination 122object get overwritten. 123If fields overwritten in this way contain pointers to allocated memory, 124that memory is freed. 125.Pp 126As far as permitted by the above rules, the following fields are copied: 127.Bl -bullet -width 1n 128.It 129the verification purpose identifier set with 130.Xr X509_VERIFY_PARAM_set_purpose 3 131.It 132the trust setting set with 133.Xr X509_VERIFY_PARAM_set_trust 3 134.It 135the verification time set with 136.Xr X509_VERIFY_PARAM_set_time 3 ; 137in this case, the only condition is that 138.Dv X509_V_FLAG_USE_CHECK_TIME 139is not set in the 140.Fa destination 141object, whereas the time value in the 142.Fa destination 143object is not inspected before overwriting it 144.It 145the acceptable policy set with 146.Xr X509_VERIFY_PARAM_set1_policies 3 147.It 148the maximum verification depth set with 149.Xr X509_VERIFY_PARAM_set_depth 3 150.It 151flags that were set with 152.Xr X509_VERIFY_PARAM_set_hostflags 3 153.It 154the list of expected DNS hostnames built with 155.Xr X509_VERIFY_PARAM_set1_host 3 156and 157.Xr X509_VERIFY_PARAM_add1_host 3 158.It 159the expected RFC 822 email address set with 160.Xr X509_VERIFY_PARAM_set1_email 3 161.It 162the expected IP address set with 163.Xr X509_VERIFY_PARAM_set1_ip 3 164or 165.Xr X509_VERIFY_PARAM_set1_ip_asc 3 166.El 167.Pp 168Some data that may be contained in the 169.Fa source 170object is never copied, for example the subject name of the peer 171certificate that can be retrieved with 172.Xr X509_VERIFY_PARAM_get0_peername 3 . 173.Pp 174If 175.Fa source 176is a 177.Dv NULL 178pointer, the function has no effect but returns successfully. 179.Pp 180.Fn X509_VERIFY_PARAM_set1 181is identical to 182.Fn X509_VERIFY_PARAM_inherit 183except that fields in the 184.Fa destination 185object are overwritten even if they do not match their default values. 186Still, fields having their default value in the 187.Fa source 188object are not copied. 189.Pp 190If 191.Fn X509_VERIFY_PARAM_inherit 192or 193.Fn X509_VERIFY_PARAM_set1 194fail, partial copying may have occurred, so all data in the 195.Fa destination 196object should be regarded as invalid. 197.Pp 198.Fn X509_VERIFY_PARAM_inherit 199is used internally by 200.Xr X509_STORE_CTX_init 3 201and by 202.Xr X509_STORE_CTX_set_default 3 , 203and 204.Fn X509_VERIFY_PARAM_set1 205is used internally by 206.Xr X509_STORE_set1_param 3 . 207.Pp 208.Fn X509_VERIFY_PARAM_free 209clears all data contained in 210.Fa param 211and releases all memory used by it. 212If 213.Fa param 214is a 215.Dv NULL 216pointer, no action occurs. 217.Pp 218.Fn X509_VERIFY_PARAM_add0_table 219adds 220.Fa param 221to a static list of 222.Vt X509_VERIFY_PARAM 223objects maintained by the library. 224This function is extremely dangerous because contrary to the name 225of the function, if the list already contains an object that happens 226to have the same name, that old object is not only silently removed 227from the list, but also silently freed, which may silently invalidate 228various pointers existing elsewhere in the program. 229.Pp 230.Fn X509_VERIFY_PARAM_lookup 231searches this list for an object of the given 232.Fa name . 233If no match is found, the predefined objects built-in to the library 234are also inspected. 235.Pp 236.Fn X509_VERIFY_PARAM_get_count 237returns the sum of the number of objects on this list and the number 238of predefined objects built-in to the library. 239Note that this is not necessarily the total number of 240.Vt X509_VERIFY_PARAM 241objects existing in the program because there may be additional such 242objects that were never added to the list. 243.Pp 244.Fn X509_VERIFY_PARAM_get0 245accesses predefined and user-defined objects using 246.Fa id 247as an index, useful for looping over objects without knowing their names. 248An argument less than the number of predefined objects selects 249one of the predefined objects; a higher argument selects an object 250from the list. 251.Pp 252.Fn X509_VERIFY_PARAM_table_cleanup 253deletes all objects from this list. 254It is extremely dangerous because it also invalidates all data that 255was contained in all objects that were on the list and because it 256frees all these objects, which may invalidate various pointers 257existing elsewhere in the program. 258.Sh RETURN VALUES 259.Fn X509_VERIFY_PARAM_new 260returns a pointer to the new object, or 261.Dv NULL 262on allocation failure. 263.Pp 264.Fn X509_VERIFY_PARAM_inherit , 265.Fn X509_VERIFY_PARAM_set1 , 266and 267.Fn X509_VERIFY_PARAM_add0_table 268return 1 for success or 0 for failure. 269.Pp 270.Fn X509_VERIFY_PARAM_lookup 271and 272.Fn X509_VERIFY_PARAM_get0 273return a pointer to an existing built-in or user-defined object, or 274.Dv NULL 275if no object with the given 276.Fa name 277is found, or if 278.Fa id 279is at least 280.Fn X509_VERIFY_PARAM_get_count . 281.Pp 282.Fn X509_VERIFY_PARAM_get_count 283returns a number of objects. 284.Sh SEE ALSO 285.Xr SSL_set1_param 3 , 286.Xr X509_STORE_CTX_set0_param 3 , 287.Xr X509_STORE_set1_param 3 , 288.Xr X509_verify_cert 3 , 289.Xr X509_VERIFY_PARAM_set_flags 3 290.Sh HISTORY 291.Fn X509_VERIFY_PARAM_new , 292.Fn X509_VERIFY_PARAM_inherit , 293.Fn X509_VERIFY_PARAM_set1 , 294.Fn X509_VERIFY_PARAM_free , 295.Fn X509_VERIFY_PARAM_add0_table , 296.Fn X509_VERIFY_PARAM_lookup , 297and 298.Fn X509_VERIFY_PARAM_table_cleanup 299first appeared in OpenSSL 0.9.8 and have been available since 300.Ox 4.5 . 301.Pp 302.Fn X509_VERIFY_PARAM_get_count 303and 304.Fn X509_VERIFY_PARAM_get0 305first appeared in OpenSSL 1.0.2 and have been available since 306.Ox 6.3 . 307