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