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