1.\" $OpenBSD: X509_STORE_CTX_get_error.3,v 1.13 2019/08/25 15:39:10 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 bb00b040 Aug 5 14:14:54 2019 +0200 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: August 25 2019 $ 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_vfy.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.In openssl/x509.h 101.Ft const char * 102.Fo X509_verify_cert_error_string 103.Fa "long n" 104.Fc 105.Sh DESCRIPTION 106These functions are typically called after 107.Xr X509_verify_cert 3 108has indicated an error or in a verification callback to determine the 109nature of an error. 110.Pp 111.Fn X509_STORE_CTX_get_error 112returns the error code of 113.Fa ctx . 114See the 115.Sy ERROR CODES 116section for a full description of all error codes. 117.Pp 118.Fn X509_STORE_CTX_set_error 119sets the error code of 120.Fa ctx 121to 122.Fa s . 123For example it might be used in a verification callback to set an error 124based on additional checks. 125.Pp 126.Fn X509_STORE_CTX_get_error_depth 127returns the depth of the error. 128This is a non-negative integer representing where in the certificate 129chain the error occurred. 130If it is zero, it occurred in the end entity certificate, one if it is 131the certificate which signed the end entity certificate, and so on. 132.Pp 133.Fn X509_STORE_CTX_get_current_cert 134returns the certificate in 135.Fa ctx 136which caused the error or 137.Dv NULL 138if no certificate is relevant. 139.Pp 140.Fn X509_STORE_CTX_get0_chain 141returns an internal pointer to a complete validate chain 142if a previous call to 143.Xr X509_verify_cert 3 144was successful. 145If the call to 146.Xr X509_verify_cert 3 147was not successful, the returned chain may be incomplete or invalid. 148.Fn X509_STORE_CTX_get1_chain 149returns a deep copy of the same chain which persists even after the 150.Fa ctx 151structure is freed. 152When it is no longer needed, it should be freed using 153.Fn sk_X509_pop_free chain X509_free . 154.Pp 155.Fn X509_verify_cert_error_string 156returns a human readable error string for verification error 157.Fa n . 158.Pp 159The above functions should be used instead of directly referencing the 160fields in the 161.Sy X509_VERIFY_CTX 162structure. 163.Pp 164In versions of OpenSSL before 1.0, the current certificate returned by 165.Fn X509_STORE_CTX_get_current_cert 166was never 167.Dv NULL . 168Applications should check the return value before printing out any 169debugging information relating to the current certificate. 170.Pp 171If an unrecognised error code is passed to 172.Fn X509_verify_cert_error_string , 173the numerical value of the unknown code is returned in a static buffer. 174This is not thread safe but will never happen unless an invalid code is 175passed. 176.Sh RETURN VALUES 177.Fn X509_STORE_CTX_get_error 178returns 179.Dv X509_V_OK 180or an error code. 181.Pp 182.Fn X509_STORE_CTX_get_error_depth 183returns a non-negative error depth. 184.Pp 185.Fn X509_STORE_CTX_get_current_cert 186returns the certificate which caused the error or 187.Dv NULL 188if no certificate is relevant to the error. 189.Pp 190.Fn X509_STORE_CTX_get0_cert 191retrieves an internal pointer to the certificate being verified by 192.Fa ctx . 193.Pp 194.Fn X509_STORE_CTX_get0_chain 195and 196.Fn X509_STORE_CTX_get1_chain 197return a pointer to a stack of certificates or 198.Dv NULL 199if an error occurs. 200.Pp 201.Fn X509_verify_cert_error_string 202returns a human readable error string for verification error 203.Fa n . 204.Sh ERROR CODES 205A list of error codes and messages is shown below. 206Some of the error codes are defined but currently never returned: 207these are described as "unused". 208.Bl -tag -width Ds 209.It Dv X509_V_OK : No ok 210The operation was successful. 211.It Dv X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT : \ 212 No unable to get issuer certificate 213The issuer certificate of a locally looked up certificate could not be found. 214This normally means the list of trusted certificates is not complete. 215.It Dv X509_V_ERR_UNABLE_TO_GET_CRL : No unable to get certificate CRL 216The CRL of a certificate could not be found. 217.It Dv X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE : \ 218 No unable to decrypt certificate's signature 219The certificate signature could not be decrypted. 220This means that the actual signature value could not be determined 221rather than it not matching the expected value. 222This is only meaningful for RSA keys. 223.It Dv X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE : \ 224 No unable to decrypt CRL's signature 225The CRL signature could not be decrypted: this means that the actual 226signature value could not be determined rather than it not matching the 227expected value. 228Unused. 229.It Dv X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY : \ 230 No unable to decode issuer public key 231The public key in the certificate 232.Vt SubjectPublicKeyInfo 233could not be read. 234.It Dv X509_V_ERR_CERT_SIGNATURE_FAILURE : No certificate signature failure 235The signature of the certificate is invalid. 236.It Dv X509_V_ERR_CRL_SIGNATURE_FAILURE : No CRL signature failure 237The signature of the certificate is invalid. 238.It Dv X509_V_ERR_CERT_NOT_YET_VALID : No certificate is not yet valid 239The certificate is not yet valid: the notBefore date is after the 240current time. 241.It Dv X509_V_ERR_CERT_HAS_EXPIRED : No certificate has expired 242The certificate has expired: that is the notAfter date is before the 243current time. 244.It Dv X509_V_ERR_CRL_NOT_YET_VALID : No CRL is not yet valid 245The CRL is not yet valid. 246.It Dv X509_V_ERR_CRL_HAS_EXPIRED : No CRL has expired 247The CRL has expired. 248.It Dv X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD : \ 249 No format error in certificate's notBefore field 250The certificate notBefore field contains an invalid time. 251.It Dv X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD : \ 252 No format error in certificate's notAfter field 253The certificate notAfter field contains an invalid time. 254.It Dv X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD : \ 255 No format error in CRL's lastUpdate field 256The CRL lastUpdate field contains an invalid time. 257.It Dv X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD : \ 258 No format error in CRL's nextUpdate field 259The CRL nextUpdate field contains an invalid time. 260.It Dv X509_V_ERR_OUT_OF_MEM : No out of memory 261An error occurred trying to allocate memory. 262This should never happen. 263.It Dv X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT : No self signed certificate 264The passed certificate is self signed and the same certificate cannot be 265found in the list of trusted certificates. 266.It Dv X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN : \ 267 No self signed certificate in certificate chain 268The certificate chain could be built up using the untrusted certificates 269but the root could not be found locally. 270.It Dv X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY : \ 271 No unable to get local issuer certificate 272The issuer certificate could not be found: this occurs if the issuer 273certificate of an untrusted certificate cannot be found. 274.It Dv X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE : \ 275 No unable to verify the first certificate 276No signatures could be verified because the chain contains only one 277certificate and it is not self signed. 278.It Dv X509_V_ERR_CERT_CHAIN_TOO_LONG : No certificate chain too long 279The certificate chain length is greater than the supplied maximum depth. 280Unused. 281.It Dv X509_V_ERR_CERT_REVOKED : No certificate revoked 282The certificate has been revoked. 283.It Dv X509_V_ERR_INVALID_CA : No invalid CA certificate 284A CA certificate is invalid. 285Either it is not a CA or its extensions are not consistent with the 286supplied purpose. 287.It Dv X509_V_ERR_PATH_LENGTH_EXCEEDED : No path length constraint exceeded 288The basicConstraints path-length parameter has been exceeded. 289.It Dv X509_V_ERR_INVALID_PURPOSE : No unsupported certificate purpose 290The supplied certificate cannot be used for the specified purpose. 291.It Dv X509_V_ERR_CERT_UNTRUSTED : No certificate not trusted 292The root CA is not marked as trusted for the specified purpose. 293.It Dv X509_V_ERR_CERT_REJECTED : No certificate rejected 294The root CA is marked to reject the specified purpose. 295.It Dv X509_V_ERR_SUBJECT_ISSUER_MISMATCH : No subject issuer mismatch 296The current candidate issuer certificate was rejected because its 297subject name did not match the issuer name of the current certificate. 298This is only set if issuer check debugging is enabled; it is used for 299status notification and is 300.Sy not 301in itself an error. 302.It Dv X509_V_ERR_AKID_SKID_MISMATCH : \ 303 No authority and subject key identifier mismatch 304The current candidate issuer certificate was rejected because its 305subject key identifier was present and did not match the authority key 306identifier current certificate. 307This is only set if issuer check debugging is enabled; it is used for 308status notification and is 309.Sy not 310in itself an error. 311.It Dv X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH : \ 312 Noauthority and issuer serial number mismatch 313The current candidate issuer certificate was rejected because its issuer 314name and serial number was present and did not match the authority key 315identifier of the current certificate. 316This is only set if issuer check debugging is enabled; it is used for 317status notification and is 318.Sy not 319in itself an error. 320.It Dv X509_V_ERR_KEYUSAGE_NO_CERTSIGN : \ 321 No key usage does not include certificate signing 322The current candidate issuer certificate was rejected because its 323keyUsage extension does not permit certificate signing. 324This is only set if issuer check debugging is enabled it is used for 325status notification and is 326.Sy not 327in itself an error. 328.It Dv X509_V_ERR_INVALID_EXTENSION : \ 329 No invalid or inconsistent certificate extension 330A certificate extension had an invalid value (for example an incorrect 331encoding) or some value inconsistent with other extensions. 332.It Dv X509_V_ERR_INVALID_POLICY_EXTENSION : \ 333 No invalid or inconsistent certificate policy extension 334A certificate policies extension had an invalid value (for example an 335incorrect encoding) or some value inconsistent with other extensions. 336This error only occurs if policy processing is enabled. 337.It Dv X509_V_ERR_NO_EXPLICIT_POLICY : No no explicit policy 338The verification flags were set to require an explicit policy but none 339was present. 340.It Dv X509_V_ERR_DIFFERENT_CRL_SCOPE : No different CRL scope 341The only CRLs that could be found did not match the scope of the 342certificate. 343.It Dv X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE : \ 344 No unsupported extension feature 345Some feature of a certificate extension is not supported. 346Unused. 347.It Dv X509_V_ERR_PERMITTED_VIOLATION : No permitted subtree violation 348A name constraint violation occurred in the permitted subtrees. 349.It Dv X509_V_ERR_EXCLUDED_VIOLATION : No excluded subtree violation 350A name constraint violation occurred in the excluded subtrees. 351.It Dv X509_V_ERR_SUBTREE_MINMAX : \ 352 No name constraints minimum and maximum not supported 353A certificate name constraints extension included a minimum or maximum 354field: this is not supported. 355.It Dv X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE : \ 356 No unsupported name constraint type 357An unsupported name constraint type was encountered. 358OpenSSL currently only supports directory name, DNS name, email and URI 359types. 360.It Dv X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX : \ 361 No unsupported or invalid name constraint syntax 362The format of the name constraint is not recognised: for example an 363email address format of a form not mentioned in RFC 3280. 364This could be caused by a garbage extension or some new feature not 365currently supported. 366.It Dv X509_V_ERR_CRL_PATH_VALIDATION_ERROR : No CRL path validation error 367An error occurred when attempting to verify the CRL path. 368This error can only happen if extended CRL checking is enabled. 369.It Dv X509_V_ERR_APPLICATION_VERIFICATION : \ 370 No application verification failure 371An application specific error. 372This will never be returned unless explicitly set by an application. 373.El 374.Sh SEE ALSO 375.Xr X509_STORE_CTX_new 3 , 376.Xr X509_up_ref 3 , 377.Xr X509_verify_cert 3 378.Sh HISTORY 379.Fn X509_STORE_CTX_get_error , 380.Fn X509_STORE_CTX_set_error , 381.Fn X509_STORE_CTX_get_error_depth , 382.Fn X509_STORE_CTX_get_current_cert , 383and 384.Fn X509_verify_cert_error_string 385first appeared in SSLeay 0.8.0 and have been available since 386.Ox 2.4 . 387.Pp 388.Fn X509_STORE_CTX_get1_chain 389first appeared in OpenSSL 0.9.5 and has been available since 390.Ox 2.7 . 391.Pp 392.Fn X509_STORE_CTX_get0_cert 393and 394.Fn X509_STORE_CTX_get0_chain 395first appeared in OpenSSL 1.1.0 and have been available since 396.Ox 6.3 . 397