1.\" $OpenBSD: X509_LOOKUP_new.3,v 1.12 2024/09/06 07:48:20 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: September 6 2024 $ 18.Dt X509_LOOKUP_NEW 3 19.Os 20.Sh NAME 21.Nm X509_LOOKUP_free , 22.Nm X509_LOOKUP_ctrl , 23.Nm X509_LOOKUP_add_dir , 24.Nm X509_LOOKUP_load_file , 25.Nm X509_LOOKUP_add_mem , 26.Nm X509_get_default_cert_dir , 27.Nm X509_get_default_cert_file , 28.Nm X509_get_default_cert_dir_env , 29.Nm X509_get_default_cert_file_env 30.\" X509_get_default_private_dir is intentionally undocumented 31.\" because it appears to be unused by any real-world software 32.\" and because it doesn't do much in the first place. 33.Nd certificate lookup object 34.Sh SYNOPSIS 35.In openssl/x509_vfy.h 36.Ft void 37.Fn X509_LOOKUP_free "X509_LOOKUP *lookup" 38.Ft int 39.Fo X509_LOOKUP_ctrl 40.Fa "X509_LOOKUP *lookup" 41.Fa "int command" 42.Fa "const char *source" 43.Fa "long type" 44.Fa "char **ret" 45.Fc 46.Ft int 47.Fo X509_LOOKUP_add_dir 48.Fa "X509_LOOKUP *lookup" 49.Fa "const char *source" 50.Fa "long type" 51.Fc 52.Ft int 53.Fo X509_LOOKUP_load_file 54.Fa "X509_LOOKUP *lookup" 55.Fa "const char *source" 56.Fa "long type" 57.Fc 58.Ft int 59.Fo X509_LOOKUP_add_mem 60.Fa "X509_LOOKUP *lookup" 61.Fa "const struct iovec *source" 62.Fa "long type" 63.Fc 64.In openssl/x509.h 65.Ft const char * 66.Fn X509_get_default_cert_dir void 67.Ft const char * 68.Fn X509_get_default_cert_file void 69.Ft const char * 70.Fn X509_get_default_cert_dir_env void 71.Ft const char * 72.Fn X509_get_default_cert_file_env void 73.Sh DESCRIPTION 74.Fn X509_LOOKUP_free 75is a deprecated function that 76releases the memory used by 77.Fa lookup . 78It is provided for compatibility only. 79If 80.Fa lookup 81is a 82.Dv NULL 83pointer, no action occurs. 84.Pp 85The operation of 86.Fn X509_LOOKUP_ctrl 87depends on the 88.Vt X509_LOOKUP_METHOD 89used by 90.Fa lookup : 91.Bl -tag -width 4n 92.It Xr X509_LOOKUP_hash_dir 3 93The 94.Fa command 95is required to be 96.Dv X509_L_ADD_DIR 97and the 98.Fa source 99argument is interpreted 100as a colon-separated, NUL-terminated list of directory names. 101These directories are added to an internal list of directories to search 102for certificate files of the given 103.Fa type . 104.Pp 105If 106.Fa type 107is 108.Dv X509_FILETYPE_DEFAULT , 109the 110.Fa source 111argument is ignored and 112.Pa /etc/ssl/certs 113and a type of 114.Dv X509_FILETYPE_PEM 115are used instead. 116.Pp 117.Fn X509_LOOKUP_add_dir 118is a macro that calls 119.Fn X509_LOOKUP_ctrl 120with a 121.Fa command 122of 123.Dv X509_L_ADD_DIR 124and 125.Fa ret 126set to 127.Dv NULL . 128.Pp 129This lookup method is peculiar in so far as calling 130.Fn X509_LOOKUP_ctrl 131on a lookup object using it does not yet add any certificates to the associated 132.Vt X509_STORE 133object. 134.It Xr X509_LOOKUP_file 3 135The 136.Fa command 137is required to be 138.Dv X509_L_FILE_LOAD 139and the 140.Fa source 141argument is interpreted as a NUL-terminated file name. 142If the 143.Fa type 144is 145.Dv X509_FILETYPE_PEM , 146the file is read with 147.Xr BIO_new_file 3 148and 149.Xr PEM_X509_INFO_read_bio 3 150and the certificates and revocation lists found are added to the 151.Vt X509_STORE 152object associated with 153.Fa lookup 154using 155.Xr X509_STORE_add_cert 3 156and 157.Xr X509_STORE_add_crl 3 . 158If 159.Fa type 160is 161.Dv X509_FILETYPE_DEFAULT , 162the 163.Fa source 164argument is ignored and 165.Pa /etc/ssl/certs.pem 166and a type of 167.Dv X509_FILETYPE_PEM 168are used instead. 169If 170.Fa type 171is 172.Dv X509_FILETYPE_ASN1 , 173the file is read with 174.Xr d2i_X509_bio 3 175and the single certificate is added to the 176.Vt X509_STORE 177object associated with 178.Fa lookup 179using 180.Xr X509_STORE_add_cert 3 . 181.Pp 182.Fn X509_LOOKUP_load_file 183is a macro calling 184.Fn X509_LOOKUP_ctrl 185with a 186.Fa command 187of 188.Dv X509_L_FILE_LOAD 189and 190.Fa ret 191set to 192.Dv NULL . 193.It Xr X509_LOOKUP_mem 3 194The 195.Fa command 196and 197.Fa type 198are required to be 199.Dv X509_L_MEM 200and 201.Dv X509_FILETYPE_PEM , 202respectively. 203The 204.Fa source 205argument is interpreted as a pointer to an 206.Vt iovec 207structure defined in 208.In sys/uio.h . 209The memory area described by that structure is read with 210.Xr BIO_new_mem_buf 3 211and 212.Xr PEM_X509_INFO_read_bio 3 213and the certificates and revocation lists found are added to the 214.Vt X509_STORE 215object associated with 216.Fa lookup 217using 218.Xr X509_STORE_add_cert 3 219and 220.Xr X509_STORE_add_crl 3 . 221.Pp 222.Fn X509_LOOKUP_add_mem 223is a macro calling 224.Fn X509_LOOKUP_ctrl 225with a command of 226.Dv X509_L_MEM 227and 228.Fa ret 229set to 230.Dv NULL . 231.El 232.Pp 233With LibreSSL, 234.Fn X509_LOOKUP_ctrl 235always ignores the 236.Fa ret 237argument. 238.Pp 239If the 240.Fa type 241is 242.Dv X509_LU_X509 , 243it searches the configured directories for files having that name, 244with a file name extension that is a small, non-negative decimal integer 245starting at 246.Qq ".0" . 247These files are read with 248.Xr X509_load_cert_file 3 . 249In each directory, the search is ended once a file with the expected name 250and extension does not exists. 251.Pp 252If the 253.Fa type 254is 255.Dv X509_LU_CRL , 256the file name extensions are expected to have a prefix of 257.Qq "r" , 258i.e. they start with 259.Qq ".r0" , 260and the files are read with 261.Xr X509_load_crl_file 3 . 262.Pp 263In case of success, the first match is returned in the 264.Pf * Fa object 265provided by the caller, overwriting any previous content. 266.Sh RETURN VALUES 267.Fn X509_LOOKUP_ctrl 268returns 1 for success or 0 for failure. 269With library implementations other than LibreSSL, 270it might also return \-1 for internal errors. 271.Pp 272.Fn X509_get_default_cert_dir 273returns a pointer to the constant string 274.Qq /etc/ssl/certs , 275.Fn X509_get_default_cert_file 276to 277.Qq /etc/ssl/certs.pem , 278.Fn X509_get_default_cert_dir_env 279to 280.Qq SSL_CERT_DIR , 281and 282.Fn X509_get_default_cert_file_env 283to 284.Qq SSL_CERT_FILE . 285.Sh ENVIRONMENT 286For reasons of security and simplicity, 287LibreSSL ignores the environment variables 288.Ev SSL_CERT_DIR 289and 290.Ev SSL_CERT_FILE , 291but other library implementations may use their contents instead 292of the standard locations for trusted certificates, and a few 293third-party application programs also inspect these variables 294directly and may pass their values to 295.Fn X509_LOOKUP_add_dir 296and 297.Fn X509_LOOKUP_load_file . 298.Sh FILES 299.Bl -tag -width /etc/ssl/certs.pem -compact 300.It Pa /etc/ssl/certs/ 301default directory for storing trusted certificates 302.It Pa /etc/ssl/certs.pem 303default file for storing trusted certificates 304.El 305.Sh ERRORS 306The following diagnostics can be retrieved with 307.Xr ERR_get_error 3 , 308.Xr ERR_GET_REASON 3 , 309and 310.Xr ERR_reason_error_string 3 : 311.Bl -tag -width Ds 312.It Dv ERR_R_ASN1_LIB Qq "ASN1 lib" 313.Xr d2i_X509_bio 3 314failed in 315.Fn X509_LOOKUP_ctrl . 316.It Dv X509_R_BAD_X509_FILETYPE Qq "bad x509 filetype" 317.Fn X509_LOOKUP_ctrl 318was called with an invalid 319.Fa type . 320.It Dv ERR_R_BUF_LIB Qq "BUF lib" 321Memory allocation failed. 322.It Dv X509_R_INVALID_DIRECTORY Qq "invalid directory" 323The 324.Fa source 325argument of 326.Fn X509_LOOKUP_ctrl 327with 328.Dv X509_L_ADD_DIR 329or 330.Fn X509_LOOKUP_add_dir 331was 332.Dv NULL 333or an empty string. 334.It Dv X509_R_LOADING_CERT_DIR Qq "loading cert dir" 335.Fn X509_LOOKUP_ctrl 336with 337.Dv X509_L_ADD_DIR 338or 339.Fn X509_LOOKUP_add_dir 340was called with 341.Dv X509_FILETYPE_DEFAULT 342and adding the default directories failed. 343This error is added after and in addition to a more specific diagnostic. 344.It Dv X509_R_LOADING_DEFAULTS Qq "loading defaults" 345.Fn X509_LOOKUP_ctrl 346with 347.Dv X509_L_FILE_LOAD 348or 349.Fn X509_LOOKUP_load_file 350was called with 351.Dv X509_FILETYPE_DEFAULT 352and adding the certificates and revocation lists failed. 353This error is added after and in addition to a more specific diagnostic. 354.It Dv ERR_R_MALLOC_FAILURE Qq "malloc failure" 355Memory allocation failed. 356.It Dv ERR_R_PEM_LIB Qq "PEM lib" 357.Xr PEM_X509_INFO_read_bio 3 , 358.Xr PEM_read_bio_X509_AUX 3 , 359or 360.Xr PEM_read_bio_X509_CRL 3 361failed in 362.Fn X509_LOOKUP_ctrl . 363.It Dv ERR_R_SYS_LIB Qq "system lib" 364.Xr BIO_new 3 , 365.Xr BIO_new_file 3 , 366or 367.Xr BIO_read_filename 3 368failed in 369.Fn X509_LOOKUP_ctrl . 370.It Dv X509_R_WRONG_LOOKUP_TYPE Qq "wrong lookup type" 371.Xr X509_STORE_CTX_get_by_subject 3 372was called with an invalid 373.Fa type . 374.El 375.Pp 376Passing an invalid 377.Fa command 378to 379.Fn X509_LOOKUP_ctrl 380causes failure but provides no diagnostics. 381.Sh SEE ALSO 382.Xr d2i_X509_bio 3 , 383.Xr PEM_read_bio_X509_AUX 3 , 384.Xr PEM_X509_INFO_read_bio 3 , 385.Xr X509_load_cert_file 3 , 386.Xr X509_LOOKUP_hash_dir 3 , 387.Xr X509_NAME_hash 3 , 388.Xr X509_NAME_new 3 , 389.Xr X509_new 3 , 390.Xr X509_OBJECT_get_type 3 , 391.Xr X509_STORE_add_cert 3 , 392.Xr X509_STORE_get_by_subject 3 393.Sh HISTORY 394.Fn X509_get_default_cert_dir , 395.Fn X509_get_default_cert_file , 396.Fn X509_get_default_cert_dir_env , 397and 398.Fn X509_get_default_cert_file_env 399first appeared in SSLeay 0.4.1 and have been available since 400.Ox 2.4 . 401.Pp 402.Fn X509_LOOKUP_add_mem 403first appeared in 404.Ox 5.7 . 405.Pp 406The other functions first appeared in SSLeay 0.8.0 407and have been available since 408.Ox 2.4 . 409.Sh BUGS 410If the 411.Fa type 412is 413.Dv X509_FILETYPE_DEFAULT 414or 415.Dv X509_FILETYPE_PEM , 416.Fn X509_LOOKUP_ctrl 417with 418.Dv X509_L_FILE_LOAD 419and 420.Fn X509_LOOKUP_load_file 421silently ignore failure of 422.Xr X509_STORE_add_cert 3 423and 424.Xr X509_STORE_add_crl 3 425and indicate success anyway. 426.Pp 427Handling of a 428.Dv NULL 429.Fa source 430is inconsistent for 431.Fn X509_LOOKUP_ctrl 432with 433.Dv X509_L_FILE_LOAD 434and for 435.Fn X509_LOOKUP_load_file . 436With 437.Dv X509_FILETYPE_PEM , 438it causes failure, but with 439.Dv X509_FILETYPE_ASN1 , 440no action occurs and success is indicated. 441.Pp 442When called on a 443.Fa lookup 444object using 445.Xr X509_LOOKUP_mem 3 , 446.Fn X509_LOOKUP_ctrl 447raises 448.Dv ERR_R_PEM_LIB 449when called with an invalid 450.Fa command 451or 452.Fa type , 453when 454.Xr BIO_new_mem_buf 3 455fails, when 456.Fa source 457contains zero objects, or when 458.Xr X509_STORE_add_cert 3 459fails on the first object encountered, which is all inconsistent 460with the behaviour of the other lookup methods. 461