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