1.\" $OpenBSD: X509_STORE_set1_param.3,v 1.22 2024/03/14 22:19:12 tb Exp $ 2.\" content checked up to: 3.\" OpenSSL man3/X509_STORE_add_cert b0edda11 Mar 20 13:00:17 2018 +0000 4.\" OpenSSL man3/X509_STORE_get0_param e90fc053 Jul 15 09:39:45 2017 -0400 5.\" 6.\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org> 7.\" 8.\" Permission to use, copy, modify, and distribute this software for any 9.\" purpose with or without fee is hereby granted, provided that the above 10.\" copyright notice and this permission notice appear in all copies. 11.\" 12.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 13.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 14.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 15.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 16.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 17.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 18.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 19.\" 20.Dd $Mdocdate: March 14 2024 $ 21.Dt X509_STORE_SET1_PARAM 3 22.Os 23.Sh NAME 24.Nm X509_STORE_set1_param , 25.Nm X509_STORE_set_flags , 26.Nm X509_STORE_set_purpose , 27.Nm X509_STORE_set_trust , 28.Nm X509_STORE_set_depth , 29.Nm X509_STORE_add_cert , 30.Nm X509_STORE_add_crl , 31.Nm X509_STORE_get0_param , 32.Nm X509_STORE_get1_objects , 33.Nm X509_STORE_get0_objects , 34.Nm X509_STORE_get_ex_new_index , 35.Nm X509_STORE_set_ex_data , 36.Nm X509_STORE_get_ex_data 37.Nd get and set X509_STORE data 38.Sh SYNOPSIS 39.In openssl/x509_vfy.h 40.Ft int 41.Fo X509_STORE_set1_param 42.Fa "X509_STORE *store" 43.Fa "X509_VERIFY_PARAM *pm" 44.Fc 45.Ft int 46.Fo X509_STORE_set_flags 47.Fa "X509_STORE *store" 48.Fa "unsigned long flags" 49.Fc 50.Ft int 51.Fo X509_STORE_set_purpose 52.Fa "X509_STORE *store" 53.Fa "int purpose" 54.Fc 55.Ft int 56.Fo X509_STORE_set_trust 57.Fa "X509_STORE *store" 58.Fa "int trust" 59.Fc 60.Ft int 61.Fo X509_STORE_set_depth 62.Fa "X509_STORE *store" 63.Fa "int depth" 64.Fc 65.Ft int 66.Fo X509_STORE_add_cert 67.Fa "X509_STORE *store" 68.Fa "X509 *x" 69.Fc 70.Ft int 71.Fo X509_STORE_add_crl 72.Fa "X509_STORE *store" 73.Fa "X509_CRL *crl" 74.Fc 75.Ft X509_VERIFY_PARAM * 76.Fo X509_STORE_get0_param 77.Fa "X509_STORE *store" 78.Fc 79.Ft STACK_OF(X509_OBJECT) * 80.Fo X509_STORE_get1_objects 81.Fa "X509_STORE *store" 82.Fc 83.Ft STACK_OF(X509_OBJECT) * 84.Fo X509_STORE_get0_objects 85.Fa "X509_STORE *store" 86.Fc 87.Ft int 88.Fo X509_STORE_get_ex_new_index 89.Fa "long argl" 90.Fa "void *argp" 91.Fa "CRYPTO_EX_new *new_func" 92.Fa "CRYPTO_EX_dup *dup_func" 93.Fa "CRYPTO_EX_free *free_func" 94.Fc 95.Ft int 96.Fo X509_STORE_set_ex_data 97.Fa "X509_STORE *store" 98.Fa "int idx" 99.Fa "void *arg" 100.Fc 101.Ft void * 102.Fo X509_STORE_get_ex_data 103.Fa "X509_STORE *store" 104.Fa "int idx" 105.Fc 106.Sh DESCRIPTION 107.Fn X509_STORE_set1_param 108copies the verification parameters from 109.Fa pm 110using 111.Xr X509_VERIFY_PARAM_set1 3 112into the verification parameter object contained in the 113.Fa store . 114.Pp 115.Fn X509_VERIFY_PARAM_set_flags , 116.Fn X509_STORE_set_purpose , 117.Fn X509_STORE_set_trust , 118and 119.Fn X509_STORE_set_depth 120call 121.Fn X509_VERIFY_PARAM_set_flags , 122.Fn X509_VERIFY_PARAM_set_purpose , 123.Fn X509_VERIFY_PARAM_set_trust , 124and 125.Fn X509_VERIFY_PARAM_set_depth 126on the verification parameter object contained in the 127.Fa store . 128.Pp 129.Fn X509_STORE_add_cert 130and 131.Fn X509_STORE_add_crl 132add the certificate 133.Fa x 134or the certificate revocation list 135.Fa crl 136to the 137.Fa store , 138increasing its reference count by 1 in case of success. 139Untrusted objects should not be added in this way. 140.Pp 141.Fn X509_STORE_get_ex_new_index , 142.Fn X509_STORE_set_ex_data , 143and 144.Fn X509_STORE_get_ex_data 145handle application specific data in 146.Vt X509_STORE 147objects. 148Their usage is identical to that of 149.Xr RSA_get_ex_new_index 3 , 150.Xr RSA_set_ex_data 3 , 151and 152.Xr RSA_get_ex_data 3 . 153.Fn X509_STORE_get_ex_new_index 154is implemented as a macro. 155.Sh RETURN VALUES 156.Fn X509_STORE_set1_param , 157.Fn X509_STORE_set_purpose , 158.Fn X509_STORE_set_trust , 159and 160.Fn X509_STORE_set_ex_data 161return 1 for success or 0 for failure. 162.Pp 163.Fn X509_STORE_set_flags 164and 165.Fn X509_STORE_set_depth 166always return 1, indicating success. 167.Pp 168.Fn X509_STORE_add_cert 169and 170.Fn X509_STORE_add_crl 171return 1 for success or 0 for failure. 172For example, they fail if 173.Fa x 174or 175.Fa crl 176is a 177.Dv NULL 178pointer, if a certificate with the same subject name as 179.Fa x 180or a revocation list with the same issuer name as 181.Fa crl 182are already contained in the 183.Fa store , 184or if memory allocation fails. 185.Pp 186.Fn X509_STORE_get0_param 187returns an internal pointer to the verification parameter object 188contained in the 189.Fa store . 190The returned pointer must not be freed by the calling application. 191.Pp 192.Fn X509_STORE_get1_objects 193returns a newly allocated stack containing 194the certificates, revocation lists, and private keys in 195.Fa store , 196as well as cached objects added by 197.Xr X509_LOOKUP_hash_dir 3 . 198The caller must release the result with 199.Xr sk_pop_free 3 200and 201.Xr X509_OBJECT_free 3 202when done. 203.Pp 204.Fn X509_STORE_get0_objects 205is a deprecated function returning an internal pointer to 206the stack of certificates, revocation lists, and private keys contained in 207.Fa store . 208The returned pointer must not be modified or freed by the calling application. 209This function is not thread-safe. 210If 211.Fa store 212is shared across multiple threads, callers cannot safely inspect the result of 213this function, because another thread may have concurrently added to it. 214In particular, 215.Xr X509_LOOKUP_hash_dir 3 216treats this list as a cache and may add to it in the course of certificate 217verification. 218.Pp 219.Fn X509_STORE_get_ex_new_index 220returns a new index or \-1 on failure. 221.Pp 222.Fn X509_STORE_get_ex_data 223returns the application data or 224.Dv NULL 225on failure. 226.Sh SEE ALSO 227.Xr RSA_get_ex_new_index 3 , 228.Xr SSL_set1_param 3 , 229.Xr X509_LOOKUP_new 3 , 230.Xr X509_OBJECT_get0_X509 3 , 231.Xr X509_STORE_CTX_set0_param 3 , 232.Xr X509_STORE_load_locations 3 , 233.Xr X509_STORE_new 3 , 234.Xr X509_VERIFY_PARAM_new 3 , 235.Xr X509_VERIFY_PARAM_set_flags 3 236.Sh HISTORY 237.Fn X509_STORE_add_cert 238first appeared in SSLeay 0.8.0. 239.Fn X509_STORE_add_crl 240first appeared in SSLeay 0.9.0. 241These functions have been available since 242.Ox 2.4 . 243.Pp 244.Fn X509_STORE_set_flags , 245.Fn X509_STORE_set_purpose , 246and 247.Fn X509_STORE_set_trust 248first appeared in OpenSSL 0.9.7 and have been available since 249.Ox 3.2 . 250.Pp 251.Fn X509_STORE_set1_param 252and 253.Fn X509_STORE_set_depth 254first appeared in OpenSSL 0.9.8 and have been available since 255.Ox 4.5 . 256.Pp 257.Fn X509_STORE_get0_param , 258.Fn X509_STORE_get0_objects , 259.Fn X509_STORE_get_ex_new_index , 260.Fn X509_STORE_set_ex_data , 261and 262.Fn X509_STORE_get_ex_data 263first appeared in OpenSSL 1.1.0 and have been available since 264.Ox 6.3 . 265.Pp 266.Fn X509_STORE_get1_objects 267first appeared in BoringSSL and has been available since 268.Ox 7.5 . 269