1.\" $OpenBSD: X509_STORE_get_by_subject.3,v 1.3 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_STORE_GET_BY_SUBJECT 3 19.Os 20.Sh NAME 21.Nm X509_STORE_CTX_get_by_subject , 22.Nm X509_STORE_CTX_get_obj_by_subject , 23.Nm X509_STORE_get_by_subject , 24.Nm X509_STORE_get1_certs , 25.Nm X509_STORE_get1_crls , 26.Nm X509_STORE_CTX_get1_issuer 27.Nd retrieve objects from a certificate store 28.Sh SYNOPSIS 29.In openssl/x509_vfy.h 30.Ft int 31.Fo X509_STORE_CTX_get_by_subject 32.Fa "X509_STORE_CTX *ctx" 33.Fa "X509_LOOKUP_TYPE type" 34.Fa "X509_NAME *name" 35.Fa "X509_OBJECT *object" 36.Fc 37.Ft X509_OBJECT * 38.Fo X509_STORE_CTX_get_obj_by_subject 39.Fa "X509_STORE_CTX *ctx" 40.Fa "X509_LOOKUP_TYPE type" 41.Fa "X509_NAME *name" 42.Fc 43.Ft int 44.Fo X509_STORE_get_by_subject 45.Fa "X509_STORE_CTX *ctx" 46.Fa "X509_LOOKUP_TYPE type" 47.Fa "X509_NAME *name" 48.Fa "X509_OBJECT *object" 49.Fc 50.Ft STACK_OF(X509) * 51.Fo X509_STORE_get1_certs 52.Fa "X509_STORE_CTX *ctx" 53.Fa "X509_NAME *name" 54.Fc 55.Ft STACK_OF(X509_CRL) * 56.Fo X509_STORE_get1_crls 57.Fa "X509_STORE_CTX *ctx" 58.Fa "X509_NAME *name" 59.Fc 60.Ft int 61.Fo X509_STORE_CTX_get1_issuer 62.Fa "X509 **issuer" 63.Fa "X509_STORE_CTX *ctx" 64.Fa "X509 *certificate" 65.Fc 66.Sh DESCRIPTION 67.Fn X509_STORE_CTX_get_by_subject 68retrieves the first object having a matching 69.Fa type 70and 71.Fa name 72from the 73.Vt X509_STORE 74associated with the 75.Fa ctx . 76The 77.Fa type 78can be 79.Dv X509_LU_X509 80to retrieve a certificate or 81.Dv X509_LU_CRL 82to retrieve a revocation list. 83.Pp 84If the store does not yet contain a matching object or if the type is 85.Dv X509_LU_CRL , 86.Xr X509_LOOKUP_by_subject 3 87is called on 88.Vt X509_LOOKUP 89objects associated with the store until a match is found, 90which may add zero or more objects to the store. 91.Pp 92In case of success, the content of the 93.Fa object 94provided by the caller is overwritten with a pointer to the first 95match, and the reference count of that certificate or revocation 96list is incremented by 1. 97Avoiding a memory leak by making sure the provided 98.Fa object 99is empty is the responsibility of the caller. 100.Pp 101.Fn X509_STORE_CTX_get_obj_by_subject 102is similar except that a new object is allocated and returned. 103.Pp 104.Fn X509_STORE_get_by_subject 105is a deprecated alias for 106.Fn X509_STORE_CTX_get_by_subject . 107.Pp 108.Fn X509_STORE_get1_certs 109retrieves all certificates matching the subject 110.Vt name 111from the 112.Vt X509_STORE 113associated with 114.Fa ctx . 115If there are none yet, 116.Fn X509_STORE_get_by_subject 117is called to try and add some. 118In case of success, the reference counts of all certificates 119added to the returned array are incremented by 1. 120.Pp 121.Fn X509_STORE_get1_crls 122is similar except that it operates on certificate revocation lists 123rather than on certificates and that it always calls 124.Fn X509_STORE_get_by_subject , 125even if the 126.Vt X509_STORE 127already contains a matching revocation list. 128.Pp 129.Fn X509_STORE_CTX_get1_issuer 130retrieves the 131.Fa issuer 132CA certificate for the given 133.Fa certificate 134from the 135.Vt X509_STORE 136associated with 137.Fa ctx . 138Internally, the issuer name is retrieved with 139.Xr X509_get_issuer_name 3 140and the candidate issuer CA certificate with 141.Fn X509_STORE_get_by_subject 142using that issuer name. 143.Xr X509_check_issued 3 144or a user-supplied replacement function is used to check whether the 145.Fa certificate 146was indeed issued using the 147.Fa issuer 148CA certificate before returning it. 149If verification parameters associated with 150.Fa ctx 151encourage checking of validity times, CAs with a valid time are 152preferred, but if no matching CA has a valid time, one with an 153invalid time is accepted anyway. 154.Sh RETURN VALUES 155.Fn X509_STORE_CTX_get_by_subject 156and 157.Fn X509_STORE_get_by_subject 158return 1 if a match is found or 0 on failure. 159In addition to simply not finding a match, 160they may also fail due to memory allocation failure in 161.Xr X509_LOOKUP_by_subject 3 . 162With library implementations other than LibreSSL, 163they might also return negative values for internal errors. 164.Pp 165.Fn X509_STORE_CTX_get_obj_by_subject 166returns the new object or 167.Dv NULL 168on failure, in particular if no match is found or memory allocation fails. 169.Pp 170.Fn X509_STORE_get1_certs 171returns a newly allocated and populated array of certificates or 172.Dv NULL 173on failure. 174It fails if no match is found, if 175.Fn X509_STORE_get_by_subject 176fails, or if memory allocation fails. 177.Pp 178.Fn X509_STORE_get1_crls 179returns a newly allocated and populated array of CRLs or 180.Dv NULL 181on failure. 182It fails if 183.Fn X509_STORE_get_by_subject 184finds no new match, even if the associated 185.Vt X509_STORE 186already contains matching CRLs, or if memory allocation fails. 187.Pp 188.Fn X509_STORE_CTX_get1_issuer 189returns 1 if a matching 190.Fa issuer 191CA certificate is found or 0 otherwise. 192With library implementations other than LibreSSL, 193it might also return negative values for internal errors. 194.Sh SEE ALSO 195.Xr STACK_OF 3 , 196.Xr X509_check_issued 3 , 197.Xr X509_CRL_new 3 , 198.Xr X509_get_issuer_name 3 , 199.Xr X509_LOOKUP_by_subject 3 , 200.Xr X509_NAME_new 3 , 201.Xr X509_new 3 , 202.Xr X509_OBJECT_retrieve_by_subject 3 , 203.Xr X509_STORE_CTX_new 3 , 204.Xr X509_VERIFY_PARAM_set_flags 3 205.Sh HISTORY 206.Fn X509_STORE_get_by_subject 207first appeared in SSLeay 0.8.0 and has been available since 208.Ox 2.4 . 209.Pp 210.Fn X509_STORE_CTX_get1_issuer 211first appeared in OpenSSL 0.9.6 and has been available since 212.Ox 2.9 . 213.Pp 214.Fn X509_STORE_get1_certs 215and 216.Fn X509_STORE_get1_crls 217first appeared in OpenSSL 1.0.0 and have been available since 218.Ox 4.9 . 219.Pp 220.Fn X509_STORE_CTX_get_by_subject 221and 222.Fn X509_STORE_CTX_get_obj_by_subject 223first appeared in OpenSSL 1.1.0 and have been available since 224.Ox 7.1 . 225