1.\" $OpenBSD: X509_STORE_CTX_get_error.3,v 1.18 2021/07/29 09:14:23 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 29 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_parent_ctx , 84.Nm X509_STORE_CTX_get0_chain , 85.Nm X509_STORE_CTX_get_chain , 86.Nm X509_STORE_CTX_get1_chain , 87.Nm X509_STORE_CTX_get0_policy_tree , 88.Nm X509_STORE_CTX_get_explicit_policy , 89.Nm X509_verify_cert_error_string 90.Nd get or set certificate verification status information 91.Sh SYNOPSIS 92.In openssl/x509_vfy.h 93.Ft int 94.Fo X509_STORE_CTX_get_error 95.Fa "X509_STORE_CTX *ctx" 96.Fc 97.Ft void 98.Fo X509_STORE_CTX_set_error 99.Fa "X509_STORE_CTX *ctx" 100.Fa "int s" 101.Fc 102.Ft int 103.Fo X509_STORE_CTX_get_error_depth 104.Fa "X509_STORE_CTX *ctx" 105.Fc 106.Ft X509 * 107.Fo X509_STORE_CTX_get_current_cert 108.Fa "X509_STORE_CTX *ctx" 109.Fc 110.Ft X509 * 111.Fo X509_STORE_CTX_get0_current_issuer 112.Fa "X509_STORE_CTX *ctx" 113.Fc 114.Ft X509_CRL * 115.Fo X509_STORE_CTX_get0_current_crl 116.Fa "X509_STORE_CTX *ctx" 117.Fc 118.Ft X509_STORE_CTX * 119.Fo X509_STORE_CTX_get0_parent_ctx 120.Fa "X509_STORE_CTX *ctx" 121.Fc 122.Ft STACK_OF(X509) * 123.Fo X509_STORE_CTX_get0_chain 124.Fa "X509_STORE_CTX *ctx" 125.Fc 126.Ft STACK_OF(X509) * 127.Fo X509_STORE_CTX_get_chain 128.Fa "X509_STORE_CTX *ctx" 129.Fc 130.Ft STACK_OF(X509) * 131.Fo X509_STORE_CTX_get1_chain 132.Fa "X509_STORE_CTX *ctx" 133.Fc 134.Ft X509_POLICY_TREE * 135.Fo X509_STORE_CTX_get0_policy_tree 136.Fa "X509_STORE_CTX *ctx" 137.Fc 138.Ft int 139.Fo X509_STORE_CTX_get_explicit_policy 140.Fa "X509_STORE_CTX *ctx" 141.Fc 142.In openssl/x509.h 143.Ft const char * 144.Fo X509_verify_cert_error_string 145.Fa "long n" 146.Fc 147.Sh DESCRIPTION 148Most of these functions are typically called after 149.Xr X509_verify_cert 3 150to inspect status information related to certificate verification. 151Some may also be called in a verification callback to determine the 152nature of an error. 153.Pp 154.Fn X509_STORE_CTX_get_error 155returns the error code of 156.Fa ctx . 157See the 158.Sy ERROR CODES 159section for a full description of all error codes. 160.Pp 161.Fn X509_STORE_CTX_set_error 162sets the error code of 163.Fa ctx 164to 165.Fa s . 166For example it might be used in a verification callback to set an error 167based on additional checks. 168.Pp 169.Fn X509_STORE_CTX_get_error_depth 170returns the depth of the error. 171This is a non-negative integer representing where in the certificate 172chain the error occurred. 173If it is zero, it occurred in the end entity certificate, one if it is 174the certificate which signed the end entity certificate, and so on. 175.Pp 176.Fn X509_STORE_CTX_get_current_cert 177returns the certificate in 178.Fa ctx 179which caused the error or 180.Dv NULL 181if no certificate is relevant. 182.Pp 183.Fn X509_STORE_CTX_get0_current_issuer 184returns the certificate that caused issuer validation to fail or 185.Dv NULL 186if no CA certificate is relevant. 187.Pp 188.Fn X509_STORE_CTX_get0_current_crl 189returns the certificate revocation list that caused CRL checking to fail or 190.Dv NULL 191if no CRL is relevant. 192.Pp 193When, during certification path validation, the need arises to check 194the validity of the certification path of a CRL issuer certificate, 195the library creates a new, temporary 196.Vt X509_STORE_CTX 197object. 198If 199.Fn X509_STORE_CTX_get0_parent_ctx 200is called on that temporary object, a pointer to the original 201certification path validation context is returned. 202This may be useful in callback functions called from 203.Xr X509_verify_cert 3 204or from its subroutines to find out whether the callback is called 205from the path validation of the target certificate or from the path 206validation of a related CRL issuer certificate, and if the latter, 207what the target certificate is. 208.Pp 209.Fn X509_STORE_CTX_get0_chain 210returns an internal pointer to a complete validate chain 211if a previous call to 212.Xr X509_verify_cert 3 213was successful. 214If the call to 215.Xr X509_verify_cert 3 216was not successful, the returned chain may be incomplete or invalid. 217.Fn X509_STORE_CTX_get_chain 218is a deprecated alias of 219.Fn X509_STORE_CTX_get0_chain . 220.Fn X509_STORE_CTX_get1_chain 221returns a deep copy of the same chain which persists even after the 222.Fa ctx 223structure is freed. 224When it is no longer needed, it should be freed using 225.Fn sk_X509_pop_free chain X509_free . 226.Pp 227.Fn X509_verify_cert_error_string 228returns a human readable error string for verification error 229.Fa n . 230.Pp 231The above functions should be used instead of directly referencing the 232fields in the 233.Sy X509_VERIFY_CTX 234structure. 235.Pp 236In versions of OpenSSL before 1.0, the current certificate returned by 237.Fn X509_STORE_CTX_get_current_cert 238was never 239.Dv NULL . 240Applications should check the return value before printing out any 241debugging information relating to the current certificate. 242.Pp 243If an unrecognised error code is passed to 244.Fn X509_verify_cert_error_string , 245the numerical value of the unknown code is returned in a static buffer. 246This is not thread safe but will never happen unless an invalid code is 247passed. 248.Sh RETURN VALUES 249.Fn X509_STORE_CTX_get_error 250returns 251.Dv X509_V_OK 252or an error code. 253.Pp 254.Fn X509_STORE_CTX_get_error_depth 255returns a non-negative error depth. 256.Pp 257.Fn X509_STORE_CTX_get_current_cert , 258.Fn X509_STORE_CTX_get0_current_issuer , 259and 260.Fn X509_STORE_CTX_get0_current_crl 261return the object which caused the error or 262.Dv NULL 263if no object of the requested kind is relevant to the error. 264.Pp 265.Fn X509_STORE_CTX_get0_parent_ctx 266returns the parent context or 267.Dv NULL 268if 269.Fa ctx 270is not a temporary child context 271used for path validation of a CRL issuer certificate. 272.Pp 273.Fn X509_STORE_CTX_get0_chain , 274.Fn X509_STORE_CTX_get_chain , 275and 276.Fn X509_STORE_CTX_get1_chain 277return a pointer to a stack of certificates or 278.Dv NULL 279if an error occurs. 280.Pp 281.Fn X509_STORE_CTX_get0_policy_tree 282returns an internal pointer to the 283.Fa valid_policy_tree 284created by 285.Xr X509_policy_check 3 286or 287.Dv NULL 288if validation failed or the resulting tree was empty. 289.Pp 290.Fn X509_STORE_CTX_get_explicit_policy 291returns the 292.Pf * Fa pexplicit_policy 293output argument of 294.Xr X509_policy_check 3 . 295If validation succeeded, it is 1 if 296.Dv X509_V_FLAG_EXPLICIT_POLICY 297was requested or 0 otherwise. 298.Pp 299.Fn X509_verify_cert_error_string 300returns a human readable error string for verification error 301.Fa n . 302.Sh ERROR CODES 303A list of error codes and messages is shown below. 304Some of the error codes are defined but currently never returned: 305these are described as "unused". 306.Bl -tag -width Ds 307.It Dv X509_V_OK : No ok 308The operation was successful. 309.It Dv X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT : \ 310 No unable to get issuer certificate 311The issuer certificate of a locally looked up certificate could not be found. 312This normally means the list of trusted certificates is not complete. 313.It Dv X509_V_ERR_UNABLE_TO_GET_CRL : No unable to get certificate CRL 314The CRL of a certificate could not be found. 315.It Dv X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE : \ 316 No unable to decrypt certificate's signature 317The certificate signature could not be decrypted. 318This means that the actual signature value could not be determined 319rather than it not matching the expected value. 320This is only meaningful for RSA keys. 321.It Dv X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE : \ 322 No unable to decrypt CRL's signature 323The CRL signature could not be decrypted: this means that the actual 324signature value could not be determined rather than it not matching the 325expected value. 326Unused. 327.It Dv X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY : \ 328 No unable to decode issuer public key 329The public key in the certificate 330.Vt SubjectPublicKeyInfo 331could not be read. 332.It Dv X509_V_ERR_CERT_SIGNATURE_FAILURE : No certificate signature failure 333The signature of the certificate is invalid. 334.It Dv X509_V_ERR_CRL_SIGNATURE_FAILURE : No CRL signature failure 335The signature of the certificate is invalid. 336.It Dv X509_V_ERR_CERT_NOT_YET_VALID : No certificate is not yet valid 337The certificate is not yet valid: the notBefore date is after the 338current time. 339.It Dv X509_V_ERR_CERT_HAS_EXPIRED : No certificate has expired 340The certificate has expired: that is the notAfter date is before the 341current time. 342.It Dv X509_V_ERR_CRL_NOT_YET_VALID : No CRL is not yet valid 343The CRL is not yet valid. 344.It Dv X509_V_ERR_CRL_HAS_EXPIRED : No CRL has expired 345The CRL has expired. 346.It Dv X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD : \ 347 No format error in certificate's notBefore field 348The certificate notBefore field contains an invalid time. 349.It Dv X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD : \ 350 No format error in certificate's notAfter field 351The certificate notAfter field contains an invalid time. 352.It Dv X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD : \ 353 No format error in CRL's lastUpdate field 354The CRL lastUpdate field contains an invalid time. 355.It Dv X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD : \ 356 No format error in CRL's nextUpdate field 357The CRL nextUpdate field contains an invalid time. 358.It Dv X509_V_ERR_OUT_OF_MEM : No out of memory 359An error occurred trying to allocate memory. 360This should never happen. 361.It Dv X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT : No self signed certificate 362The passed certificate is self signed and the same certificate cannot be 363found in the list of trusted certificates. 364.It Dv X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN : \ 365 No self signed certificate in certificate chain 366The certificate chain could be built up using the untrusted certificates 367but the root could not be found locally. 368.It Dv X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY : \ 369 No unable to get local issuer certificate 370The issuer certificate could not be found: this occurs if the issuer 371certificate of an untrusted certificate cannot be found. 372.It Dv X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE : \ 373 No unable to verify the first certificate 374No signatures could be verified because the chain contains only one 375certificate and it is not self signed. 376.It Dv X509_V_ERR_CERT_CHAIN_TOO_LONG : No certificate chain too long 377The certificate chain length is greater than the supplied maximum depth. 378Unused. 379.It Dv X509_V_ERR_CERT_REVOKED : No certificate revoked 380The certificate has been revoked. 381.It Dv X509_V_ERR_INVALID_CA : No invalid CA certificate 382A CA certificate is invalid. 383Either it is not a CA or its extensions are not consistent with the 384supplied purpose. 385.It Dv X509_V_ERR_PATH_LENGTH_EXCEEDED : No path length constraint exceeded 386The basicConstraints path-length parameter has been exceeded. 387.It Dv X509_V_ERR_INVALID_PURPOSE : No unsupported certificate purpose 388The supplied certificate cannot be used for the specified purpose. 389.It Dv X509_V_ERR_CERT_UNTRUSTED : No certificate not trusted 390The root CA is not marked as trusted for the specified purpose. 391.It Dv X509_V_ERR_CERT_REJECTED : No certificate rejected 392The root CA is marked to reject the specified purpose. 393.It Dv X509_V_ERR_SUBJECT_ISSUER_MISMATCH : No subject issuer mismatch 394The current candidate issuer certificate was rejected because its 395subject name did not match the issuer name of the current certificate. 396This is only set if issuer check debugging is enabled; it is used for 397status notification and is 398.Sy not 399in itself an error. 400.It Dv X509_V_ERR_AKID_SKID_MISMATCH : \ 401 No authority and subject key identifier mismatch 402The current candidate issuer certificate was rejected because its 403subject key identifier was present and did not match the authority key 404identifier current certificate. 405This is only set if issuer check debugging is enabled; it is used for 406status notification and is 407.Sy not 408in itself an error. 409.It Dv X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH : \ 410 Noauthority and issuer serial number mismatch 411The current candidate issuer certificate was rejected because its issuer 412name and serial number was present and did not match the authority key 413identifier of the current certificate. 414This is only set if issuer check debugging is enabled; it is used for 415status notification and is 416.Sy not 417in itself an error. 418.It Dv X509_V_ERR_KEYUSAGE_NO_CERTSIGN : \ 419 No key usage does not include certificate signing 420The current candidate issuer certificate was rejected because its 421keyUsage extension does not permit certificate signing. 422This is only set if issuer check debugging is enabled it is used for 423status notification and is 424.Sy not 425in itself an error. 426.It Dv X509_V_ERR_INVALID_EXTENSION : \ 427 No invalid or inconsistent certificate extension 428A certificate extension had an invalid value (for example an incorrect 429encoding) or some value inconsistent with other extensions. 430.It Dv X509_V_ERR_INVALID_POLICY_EXTENSION : \ 431 No invalid or inconsistent certificate policy extension 432A certificate policies extension had an invalid value (for example an 433incorrect encoding) or some value inconsistent with other extensions. 434This error only occurs if policy processing is enabled. 435.It Dv X509_V_ERR_NO_EXPLICIT_POLICY : No no explicit policy 436The verification flags were set to require an explicit policy but none 437was present. 438.It Dv X509_V_ERR_DIFFERENT_CRL_SCOPE : No different CRL scope 439The only CRLs that could be found did not match the scope of the 440certificate. 441.It Dv X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE : \ 442 No unsupported extension feature 443Some feature of a certificate extension is not supported. 444Unused. 445.It Dv X509_V_ERR_PERMITTED_VIOLATION : No permitted subtree violation 446A name constraint violation occurred in the permitted subtrees. 447.It Dv X509_V_ERR_EXCLUDED_VIOLATION : No excluded subtree violation 448A name constraint violation occurred in the excluded subtrees. 449.It Dv X509_V_ERR_SUBTREE_MINMAX : \ 450 No name constraints minimum and maximum not supported 451A certificate name constraints extension included a minimum or maximum 452field: this is not supported. 453.It Dv X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE : \ 454 No unsupported name constraint type 455An unsupported name constraint type was encountered. 456OpenSSL currently only supports directory name, DNS name, email and URI 457types. 458.It Dv X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX : \ 459 No unsupported or invalid name constraint syntax 460The format of the name constraint is not recognised: for example an 461email address format of a form not mentioned in RFC 3280. 462This could be caused by a garbage extension or some new feature not 463currently supported. 464.It Dv X509_V_ERR_CRL_PATH_VALIDATION_ERROR : No CRL path validation error 465An error occurred when attempting to verify the CRL path. 466This error can only happen if extended CRL checking is enabled. 467.It Dv X509_V_ERR_APPLICATION_VERIFICATION : \ 468 No application verification failure 469An application specific error. 470This will never be returned unless explicitly set by an application. 471.El 472.Sh SEE ALSO 473.Xr X509_policy_check 3 , 474.Xr X509_policy_tree_level_count 3 , 475.Xr X509_STORE_CTX_new 3 , 476.Xr X509_up_ref 3 , 477.Xr X509_verify_cert 3 478.Sh HISTORY 479.Fn X509_STORE_CTX_get_error , 480.Fn X509_STORE_CTX_set_error , 481.Fn X509_STORE_CTX_get_error_depth , 482.Fn X509_STORE_CTX_get_current_cert , 483.Fn X509_STORE_CTX_get_chain , 484and 485.Fn X509_verify_cert_error_string 486first appeared in SSLeay 0.8.0 and have been available since 487.Ox 2.4 . 488.Pp 489.Fn X509_STORE_CTX_get1_chain 490first appeared in OpenSSL 0.9.5 and has been available since 491.Ox 2.7 . 492.Pp 493.Fn X509_STORE_CTX_get0_policy_tree 494and 495.Fn X509_STORE_CTX_get_explicit_policy 496first appeared in OpenSSL 0.9.8 and have been available since 497.Ox 4.5 . 498.Pp 499.Fn X509_STORE_CTX_get0_current_issuer , 500.Fn X509_STORE_CTX_get0_current_crl , 501and 502.Fn X509_STORE_CTX_get0_parent_ctx 503first appeared in OpenSSL 1.0.0 and have been available since 504.Ox 4.9 . 505.Pp 506.Fn X509_STORE_CTX_get0_chain 507first appeared in OpenSSL 1.1.0 and has been available since 508.Ox 6.3 . 509