1.\" $OpenBSD: x509_verify.3,v 1.2 2020/09/14 14:21:46 schwarze Exp $ 2.\" 3.\" Copyright (c) 2020 Bob Beck <beck@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 14 2020 $ 18.Dt X509_VERIFY 3 19.Os 20.Sh NAME 21.Nm x509_verify , 22.Nm x509_verify_ctx_new , 23.Nm x509_verify_ctx_free , 24.Nm x509_verify_ctx_set_max_depth , 25.Nm x509_verify_ctx_set_max_signatures , 26.Nm x509_verify_ctx_set_max_chains , 27.Nm x509_verify_ctx_set_purpose , 28.Nm x509_verify_ctx_set_intermediates , 29.Nm x509_verify_ctx_error_string , 30.Nm x509_verify_ctx_error_depth , 31.Nm x509_verify_ctx_chain 32.Nd discover and verify X.509 certificate chains 33.Sh SYNOPSIS 34.In openssl/x509_verify.h 35.Ft size_t 36.Fo x509_verify 37.Fa "X509_VERIFY_CTX *ctx" 38.Fa "X509 *leaf" 39.Fa "char *name" 40.Fc 41.Ft X509_VERIFY_CTX * 42.Fo x509_verify_ctx_new 43.Fa "STACK_OF(X509) *roots" 44.Fc 45.Ft void 46.Fo x509_verify_ctx_free 47.Fa "X509_VERIFY_CTX *ctx" 48.Fc 49.Ft int 50.Fo x509_verify_ctx_set_max_depth 51.Fa "X509_VERIFY_CTX *ctx" 52.Fa "size_t max" 53.Fc 54.Ft int 55.Fo x509_verify_ctx_set_max_signatures 56.Fa "X509_VERIFY_CTX *ctx" 57.Fa "size_t max" 58.Fc 59.Ft int 60.Fo x509_verify_ctx_set_max_chains 61.Fa "X509_VERIFY_CTX *ctx" 62.Fa "size_t max" 63.Fc 64.Ft int 65.Fo x509_verify_ctx_set_purpose 66.Fa "X509_VERIFY_CTX *ctx" 67.Fa "int purpose_id" 68.Fc 69.Ft int 70.Fo x509_verify_ctx_set_intermediates 71.Fa "X509_VERIFY_CTX *ctx" 72.Fa "STACK_OF(X509) *intermediates" 73.Fc 74.Ft const char * 75.Fo x509_verify_ctx_error_string 76.Fa "X509_VERIFY_CTX *ctx" 77.Fc 78.Ft size_t 79.Fo x509_verify_ctx_error_depth 80.Fa "X509_VERIFY_CTX *ctx" 81.Fc 82.Ft STACK_OF(X509) * 83.Fo x509_verify_ctx_chain 84.Fa "X509_VERIFY_CTX *ctx" 85.Fa "size_t index" 86.Fc 87.Sh DESCRIPTION 88The 89.Fn x509_verify 90function attempts to discover and validate all certificate chains 91for the 92.Fa name 93from the 94.Fa leaf 95certificate based on the parameters in 96.Fa ctx . 97Multiple chains may be built and validated. 98Revocation checking is not done by this function, and should be 99performed by the caller on any returned chains if so desired. 100.Pp 101.Fn x509_verify_ctx_new 102allocates a new context using the trusted 103.Fa roots . 104In case of success, it increments the reference count of 105.Fa roots . 106.Pp 107.Fn x509_verify_ctx_free 108frees 109.Fa ctx 110and decrements the reference count of the 111.Fa roots 112and 113.Fa intermediates 114associated with it. 115If 116.Fa ctx 117is 118.Dv NULL , 119no action occurs. 120.Pp 121.Fn x509_verify_ctx_set_max_depth 122sets the maximum depth of certificate chains that will be constructed to 123.Fa max , 124which can be in the range from 1 to the default of 32. 125.Pp 126.Fn x509_verify_ctx_set_max_signatures 127sets the maximum number of public key signature operations that will be 128used when verifying certificate chains to 129.Fa max , 130which can be in the range from 1 to 100000. 131The default is 256. 132.Pp 133.Fn x509_verify_ctx_set_max_chains 134sets the maximum number of chains which may be returned to 135.Fa max , 136which can be in the range from 1 to the default of 8. 137.Pp 138.Fn x509_verify_ctx_set_purpose 139sets the certificate purpose for validation to 140.Fa purpose_id . 141The 142.Dv X509_PURPOSE_* 143constants listed in 144.Xr X509_check_purpose 3 145can be used. 146.Pp 147.Fn x509_verify_ctx_set_intermediates 148provides some intermediate certificates, typically received from 149the peer, to be used for building chains. 150In case of success, this function increases the reference count of 151.Fa intermediates . 152.Pp 153.Fn x509_verify_ctx_error_string 154extracts a description of the last error encountered by a previous 155call to 156.Fn x509_verify 157from 158.Fa ctx . 159.Pp 160.Fn x509_verify_ctx_error_depth 161extracts the depth of the last error encountered by a previous 162call to 163.Fn x509_verify 164from 165.Fa ctx . 166.Pp 167.Fn x509_verify_ctx_chain 168extracts the validated chain with the given 169.Fa index 170from 171.Fa ctx 172after a previous call to 173.Fn x509_verify . 174The 175.Fa index 176starts at 0, and it is an error to pass a number 177greater than or equal to the return value of 178.Fn x509_verify . 179The returned chain is neither copied, 180nor is its reference count increased. 181.Sh RETURN VALUES 182.Fn x509_verify 183returns the number of chains successfully built and validated 184or 0 on failure. 185.Pp 186.Fn x509_verify_ctx_new 187returns a newly allocated context or 188.Dv NULL 189on failure. 190.Pp 191.Fn x509_verify_ctx_set_max_depth , 192.Fn x509_verify_ctx_set_max_signatures , 193.Fn x509_verify_ctx_set_max_chains , 194.Fn x509_verify_ctx_set_purpose , 195and 196.Fn x509_verify_ctx_set_intermediates 197return 1 on success or 0 on failure. 198.Pp 199.Fn x509_verify_ctx_error_string 200returns a pointer to a human readable error string. 201If no error occurred, 202.Qq ok 203is returned. 204.Pp 205.Fn x509_verify_ctx_chain 206returns an internal pointer to a validated chain or 207.Dv NULL 208if 209.Fa index 210is greater than or equal to the number of chains 211that were successfully built and validated. 212The returned pointer becomes invalid when 213.Fa ctx 214is destroyed. 215.Sh SEE ALSO 216.Xr X509_verify_cert 3 217.Sh HISTORY 218These functions first appeared in 219.Ox 6.8 . 220.Sh AUTHORS 221.An Bob Beck Aq Mt beck@openbsd.org 222