1.\" $OpenBSD: X509_STORE_CTX_get_error.3,v 1.16 2021/07/22 15:35:50 schwarze Exp $ 2.\" full merge up to: 3.\" OpenSSL crypto/X509_STORE_CTX_get_error f0e0fd51 Apr 14 23:59:26 2016 -0400 4.\" selective merge up to: 5.\" OpenSSL man3/X509_STORE_CTX_get_error 24a535ea Sep 22 13:14:20 2020 +0100 6.\" OpenSSL man3/X509_STORE_CTX_new 24a535ea Sep 22 13:14:20 2020 +0100 7.\" 8.\" This file is a derived work. 9.\" The changes are covered by the following Copyright and license: 10.\" 11.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org> 12.\" 13.\" Permission to use, copy, modify, and distribute this software for any 14.\" purpose with or without fee is hereby granted, provided that the above 15.\" copyright notice and this permission notice appear in all copies. 16.\" 17.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 18.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 19.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 20.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 21.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 22.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 23.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 24.\" 25.\" The original file was written by Dr. Stephen Henson <steve@openssl.org> 26.\" and Rich Salz <rsalz@openssl.org>. 27.\" Copyright (c) 2009, 2016 The OpenSSL Project. All rights reserved. 28.\" 29.\" Redistribution and use in source and binary forms, with or without 30.\" modification, are permitted provided that the following conditions 31.\" are met: 32.\" 33.\" 1. Redistributions of source code must retain the above copyright 34.\" notice, this list of conditions and the following disclaimer. 35.\" 36.\" 2. Redistributions in binary form must reproduce the above copyright 37.\" notice, this list of conditions and the following disclaimer in 38.\" the documentation and/or other materials provided with the 39.\" distribution. 40.\" 41.\" 3. All advertising materials mentioning features or use of this 42.\" software must display the following acknowledgment: 43.\" "This product includes software developed by the OpenSSL Project 44.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 45.\" 46.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 47.\" endorse or promote products derived from this software without 48.\" prior written permission. For written permission, please contact 49.\" openssl-core@openssl.org. 50.\" 51.\" 5. Products derived from this software may not be called "OpenSSL" 52.\" nor may "OpenSSL" appear in their names without prior written 53.\" permission of the OpenSSL Project. 54.\" 55.\" 6. Redistributions of any form whatsoever must retain the following 56.\" acknowledgment: 57.\" "This product includes software developed by the OpenSSL Project 58.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 59.\" 60.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 61.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 62.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 63.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 64.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 65.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 66.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 67.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 68.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 69.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 70.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 71.\" OF THE POSSIBILITY OF SUCH DAMAGE. 72.\" 73.Dd $Mdocdate: July 22 2021 $ 74.Dt X509_STORE_CTX_GET_ERROR 3 75.Os 76.Sh NAME 77.Nm X509_STORE_CTX_get_error , 78.Nm X509_STORE_CTX_set_error , 79.Nm X509_STORE_CTX_get_error_depth , 80.Nm X509_STORE_CTX_get_current_cert , 81.Nm X509_STORE_CTX_get0_current_issuer , 82.Nm X509_STORE_CTX_get0_current_crl , 83.Nm X509_STORE_CTX_get0_chain , 84.Nm X509_STORE_CTX_get_chain , 85.Nm X509_STORE_CTX_get1_chain , 86.Nm X509_verify_cert_error_string 87.Nd get or set certificate verification status information 88.Sh SYNOPSIS 89.In openssl/x509_vfy.h 90.Ft int 91.Fo X509_STORE_CTX_get_error 92.Fa "X509_STORE_CTX *ctx" 93.Fc 94.Ft void 95.Fo X509_STORE_CTX_set_error 96.Fa "X509_STORE_CTX *ctx" 97.Fa "int s" 98.Fc 99.Ft int 100.Fo X509_STORE_CTX_get_error_depth 101.Fa "X509_STORE_CTX *ctx" 102.Fc 103.Ft X509 * 104.Fo X509_STORE_CTX_get_current_cert 105.Fa "X509_STORE_CTX *ctx" 106.Fc 107.Ft X509 * 108.Fo X509_STORE_CTX_get0_current_issuer 109.Fa "X509_STORE_CTX *ctx" 110.Fc 111.Ft X509_CRL * 112.Fo X509_STORE_CTX_get0_current_crl 113.Fa "X509_STORE_CTX *ctx" 114.Fc 115.Ft STACK_OF(X509) * 116.Fo X509_STORE_CTX_get0_chain 117.Fa "X509_STORE_CTX *ctx" 118.Fc 119.Ft STACK_OF(X509) * 120.Fo X509_STORE_CTX_get_chain 121.Fa "X509_STORE_CTX *ctx" 122.Fc 123.Ft STACK_OF(X509) * 124.Fo X509_STORE_CTX_get1_chain 125.Fa "X509_STORE_CTX *ctx" 126.Fc 127.In openssl/x509.h 128.Ft const char * 129.Fo X509_verify_cert_error_string 130.Fa "long n" 131.Fc 132.Sh DESCRIPTION 133These functions are typically called after 134.Xr X509_verify_cert 3 135has indicated an error or in a verification callback to determine the 136nature of an error. 137.Pp 138.Fn X509_STORE_CTX_get_error 139returns the error code of 140.Fa ctx . 141See the 142.Sy ERROR CODES 143section for a full description of all error codes. 144.Pp 145.Fn X509_STORE_CTX_set_error 146sets the error code of 147.Fa ctx 148to 149.Fa s . 150For example it might be used in a verification callback to set an error 151based on additional checks. 152.Pp 153.Fn X509_STORE_CTX_get_error_depth 154returns the depth of the error. 155This is a non-negative integer representing where in the certificate 156chain the error occurred. 157If it is zero, it occurred in the end entity certificate, one if it is 158the certificate which signed the end entity certificate, and so on. 159.Pp 160.Fn X509_STORE_CTX_get_current_cert 161returns the certificate in 162.Fa ctx 163which caused the error or 164.Dv NULL 165if no certificate is relevant. 166.Pp 167.Fn X509_STORE_CTX_get0_current_issuer 168returns the certificate that caused issuer validation to fail or 169.Dv NULL 170if no CA certificate is relevant. 171.Pp 172.Fn X509_STORE_CTX_get0_current_crl 173returns the certificate revocation list that caused CRL checking to fail or 174.Dv NULL 175if no CRL is relevant. 176.Pp 177.Fn X509_STORE_CTX_get0_chain 178returns an internal pointer to a complete validate chain 179if a previous call to 180.Xr X509_verify_cert 3 181was successful. 182If the call to 183.Xr X509_verify_cert 3 184was not successful, the returned chain may be incomplete or invalid. 185.Fn X509_STORE_CTX_get_chain 186is a deprecated alias of 187.Fn X509_STORE_CTX_get0_chain . 188.Fn X509_STORE_CTX_get1_chain 189returns a deep copy of the same chain which persists even after the 190.Fa ctx 191structure is freed. 192When it is no longer needed, it should be freed using 193.Fn sk_X509_pop_free chain X509_free . 194.Pp 195.Fn X509_verify_cert_error_string 196returns a human readable error string for verification error 197.Fa n . 198.Pp 199The above functions should be used instead of directly referencing the 200fields in the 201.Sy X509_VERIFY_CTX 202structure. 203.Pp 204In versions of OpenSSL before 1.0, the current certificate returned by 205.Fn X509_STORE_CTX_get_current_cert 206was never 207.Dv NULL . 208Applications should check the return value before printing out any 209debugging information relating to the current certificate. 210.Pp 211If an unrecognised error code is passed to 212.Fn X509_verify_cert_error_string , 213the numerical value of the unknown code is returned in a static buffer. 214This is not thread safe but will never happen unless an invalid code is 215passed. 216.Sh RETURN VALUES 217.Fn X509_STORE_CTX_get_error 218returns 219.Dv X509_V_OK 220or an error code. 221.Pp 222.Fn X509_STORE_CTX_get_error_depth 223returns a non-negative error depth. 224.Pp 225.Fn X509_STORE_CTX_get_current_cert , 226.Fn X509_STORE_CTX_get0_current_issuer , 227and 228.Fn X509_STORE_CTX_get0_current_crl 229return the object which caused the error or 230.Dv NULL 231if no object of the requested kind is relevant to the error. 232.Pp 233.Fn X509_STORE_CTX_get0_chain , 234.Fn X509_STORE_CTX_get_chain , 235and 236.Fn X509_STORE_CTX_get1_chain 237return a pointer to a stack of certificates or 238.Dv NULL 239if an error occurs. 240.Pp 241.Fn X509_verify_cert_error_string 242returns a human readable error string for verification error 243.Fa n . 244.Sh ERROR CODES 245A list of error codes and messages is shown below. 246Some of the error codes are defined but currently never returned: 247these are described as "unused". 248.Bl -tag -width Ds 249.It Dv X509_V_OK : No ok 250The operation was successful. 251.It Dv X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT : \ 252 No unable to get issuer certificate 253The issuer certificate of a locally looked up certificate could not be found. 254This normally means the list of trusted certificates is not complete. 255.It Dv X509_V_ERR_UNABLE_TO_GET_CRL : No unable to get certificate CRL 256The CRL of a certificate could not be found. 257.It Dv X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE : \ 258 No unable to decrypt certificate's signature 259The certificate signature could not be decrypted. 260This means that the actual signature value could not be determined 261rather than it not matching the expected value. 262This is only meaningful for RSA keys. 263.It Dv X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE : \ 264 No unable to decrypt CRL's signature 265The CRL signature could not be decrypted: this means that the actual 266signature value could not be determined rather than it not matching the 267expected value. 268Unused. 269.It Dv X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY : \ 270 No unable to decode issuer public key 271The public key in the certificate 272.Vt SubjectPublicKeyInfo 273could not be read. 274.It Dv X509_V_ERR_CERT_SIGNATURE_FAILURE : No certificate signature failure 275The signature of the certificate is invalid. 276.It Dv X509_V_ERR_CRL_SIGNATURE_FAILURE : No CRL signature failure 277The signature of the certificate is invalid. 278.It Dv X509_V_ERR_CERT_NOT_YET_VALID : No certificate is not yet valid 279The certificate is not yet valid: the notBefore date is after the 280current time. 281.It Dv X509_V_ERR_CERT_HAS_EXPIRED : No certificate has expired 282The certificate has expired: that is the notAfter date is before the 283current time. 284.It Dv X509_V_ERR_CRL_NOT_YET_VALID : No CRL is not yet valid 285The CRL is not yet valid. 286.It Dv X509_V_ERR_CRL_HAS_EXPIRED : No CRL has expired 287The CRL has expired. 288.It Dv X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD : \ 289 No format error in certificate's notBefore field 290The certificate notBefore field contains an invalid time. 291.It Dv X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD : \ 292 No format error in certificate's notAfter field 293The certificate notAfter field contains an invalid time. 294.It Dv X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD : \ 295 No format error in CRL's lastUpdate field 296The CRL lastUpdate field contains an invalid time. 297.It Dv X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD : \ 298 No format error in CRL's nextUpdate field 299The CRL nextUpdate field contains an invalid time. 300.It Dv X509_V_ERR_OUT_OF_MEM : No out of memory 301An error occurred trying to allocate memory. 302This should never happen. 303.It Dv X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT : No self signed certificate 304The passed certificate is self signed and the same certificate cannot be 305found in the list of trusted certificates. 306.It Dv X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN : \ 307 No self signed certificate in certificate chain 308The certificate chain could be built up using the untrusted certificates 309but the root could not be found locally. 310.It Dv X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY : \ 311 No unable to get local issuer certificate 312The issuer certificate could not be found: this occurs if the issuer 313certificate of an untrusted certificate cannot be found. 314.It Dv X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE : \ 315 No unable to verify the first certificate 316No signatures could be verified because the chain contains only one 317certificate and it is not self signed. 318.It Dv X509_V_ERR_CERT_CHAIN_TOO_LONG : No certificate chain too long 319The certificate chain length is greater than the supplied maximum depth. 320Unused. 321.It Dv X509_V_ERR_CERT_REVOKED : No certificate revoked 322The certificate has been revoked. 323.It Dv X509_V_ERR_INVALID_CA : No invalid CA certificate 324A CA certificate is invalid. 325Either it is not a CA or its extensions are not consistent with the 326supplied purpose. 327.It Dv X509_V_ERR_PATH_LENGTH_EXCEEDED : No path length constraint exceeded 328The basicConstraints path-length parameter has been exceeded. 329.It Dv X509_V_ERR_INVALID_PURPOSE : No unsupported certificate purpose 330The supplied certificate cannot be used for the specified purpose. 331.It Dv X509_V_ERR_CERT_UNTRUSTED : No certificate not trusted 332The root CA is not marked as trusted for the specified purpose. 333.It Dv X509_V_ERR_CERT_REJECTED : No certificate rejected 334The root CA is marked to reject the specified purpose. 335.It Dv X509_V_ERR_SUBJECT_ISSUER_MISMATCH : No subject issuer mismatch 336The current candidate issuer certificate was rejected because its 337subject name did not match the issuer name of the current certificate. 338This is only set if issuer check debugging is enabled; it is used for 339status notification and is 340.Sy not 341in itself an error. 342.It Dv X509_V_ERR_AKID_SKID_MISMATCH : \ 343 No authority and subject key identifier mismatch 344The current candidate issuer certificate was rejected because its 345subject key identifier was present and did not match the authority key 346identifier current certificate. 347This is only set if issuer check debugging is enabled; it is used for 348status notification and is 349.Sy not 350in itself an error. 351.It Dv X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH : \ 352 Noauthority and issuer serial number mismatch 353The current candidate issuer certificate was rejected because its issuer 354name and serial number was present and did not match the authority key 355identifier of the current certificate. 356This is only set if issuer check debugging is enabled; it is used for 357status notification and is 358.Sy not 359in itself an error. 360.It Dv X509_V_ERR_KEYUSAGE_NO_CERTSIGN : \ 361 No key usage does not include certificate signing 362The current candidate issuer certificate was rejected because its 363keyUsage extension does not permit certificate signing. 364This is only set if issuer check debugging is enabled it is used for 365status notification and is 366.Sy not 367in itself an error. 368.It Dv X509_V_ERR_INVALID_EXTENSION : \ 369 No invalid or inconsistent certificate extension 370A certificate extension had an invalid value (for example an incorrect 371encoding) or some value inconsistent with other extensions. 372.It Dv X509_V_ERR_INVALID_POLICY_EXTENSION : \ 373 No invalid or inconsistent certificate policy extension 374A certificate policies extension had an invalid value (for example an 375incorrect encoding) or some value inconsistent with other extensions. 376This error only occurs if policy processing is enabled. 377.It Dv X509_V_ERR_NO_EXPLICIT_POLICY : No no explicit policy 378The verification flags were set to require an explicit policy but none 379was present. 380.It Dv X509_V_ERR_DIFFERENT_CRL_SCOPE : No different CRL scope 381The only CRLs that could be found did not match the scope of the 382certificate. 383.It Dv X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE : \ 384 No unsupported extension feature 385Some feature of a certificate extension is not supported. 386Unused. 387.It Dv X509_V_ERR_PERMITTED_VIOLATION : No permitted subtree violation 388A name constraint violation occurred in the permitted subtrees. 389.It Dv X509_V_ERR_EXCLUDED_VIOLATION : No excluded subtree violation 390A name constraint violation occurred in the excluded subtrees. 391.It Dv X509_V_ERR_SUBTREE_MINMAX : \ 392 No name constraints minimum and maximum not supported 393A certificate name constraints extension included a minimum or maximum 394field: this is not supported. 395.It Dv X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE : \ 396 No unsupported name constraint type 397An unsupported name constraint type was encountered. 398OpenSSL currently only supports directory name, DNS name, email and URI 399types. 400.It Dv X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX : \ 401 No unsupported or invalid name constraint syntax 402The format of the name constraint is not recognised: for example an 403email address format of a form not mentioned in RFC 3280. 404This could be caused by a garbage extension or some new feature not 405currently supported. 406.It Dv X509_V_ERR_CRL_PATH_VALIDATION_ERROR : No CRL path validation error 407An error occurred when attempting to verify the CRL path. 408This error can only happen if extended CRL checking is enabled. 409.It Dv X509_V_ERR_APPLICATION_VERIFICATION : \ 410 No application verification failure 411An application specific error. 412This will never be returned unless explicitly set by an application. 413.El 414.Sh SEE ALSO 415.Xr X509_STORE_CTX_new 3 , 416.Xr X509_up_ref 3 , 417.Xr X509_verify_cert 3 418.Sh HISTORY 419.Fn X509_STORE_CTX_get_error , 420.Fn X509_STORE_CTX_set_error , 421.Fn X509_STORE_CTX_get_error_depth , 422.Fn X509_STORE_CTX_get_current_cert , 423.Fn X509_STORE_CTX_get_chain , 424and 425.Fn X509_verify_cert_error_string 426first appeared in SSLeay 0.8.0 and have been available since 427.Ox 2.4 . 428.Pp 429.Fn X509_STORE_CTX_get1_chain 430first appeared in OpenSSL 0.9.5 and has been available since 431.Ox 2.7 . 432.Pp 433.Fn X509_STORE_CTX_get0_current_issuer 434and 435.Fn X509_STORE_CTX_get0_current_crl 436first appeared in OpenSSL 1.0.0 and have been available since 437.Ox 4.9 . 438.Pp 439.Fn X509_STORE_CTX_get0_chain 440first appeared in OpenSSL 1.1.0 and has been available since 441.Ox 6.3 . 442