From eacd30a703b52f5b3e8e70b58f99bd1128458c7c Mon Sep 17 00:00:00 2001 From: Jake Maynard Date: Wed, 30 Oct 2019 11:27:04 -0400 Subject: [PATCH] Add manpage entry for X509_check_purpose() Fixes #10263 Reviewed-by: Paul Dale Reviewed-by: Matt Caswell (Merged from https://github.com/openssl/openssl/pull/10301) --- crypto/x509/v3_purp.c | 4 +- doc/man3/X509_check_purpose.pod | 74 +++++++++++++++++++++++++++++++++ util/missingcrypto.txt | 1 - 3 files changed, 77 insertions(+), 2 deletions(-) create mode 100644 doc/man3/X509_check_purpose.pod diff --git a/crypto/x509/v3_purp.c b/crypto/x509/v3_purp.c index bb60276d94..bee8210bfc 100644 --- a/crypto/x509/v3_purp.c +++ b/crypto/x509/v3_purp.c @@ -552,9 +552,11 @@ int X509v3_cache_extensions(X509 *x, OPENSSL_CTX *libctx, const char *propq) * return codes: * 0 not a CA * 1 is a CA - * 2 basicConstraints absent so "maybe" a CA + * 2 Only possible in older versions of openSSL when basicConstraints are absent + * new versions will not return this value. May be a CA * 3 basicConstraints absent but self signed V1. * 4 basicConstraints absent but keyUsage present and keyCertSign asserted. + * 5 Netscape specific CA Flags present */ static int check_ca(const X509 *x) diff --git a/doc/man3/X509_check_purpose.pod b/doc/man3/X509_check_purpose.pod new file mode 100644 index 0000000000..e44a9ea15b --- /dev/null +++ b/doc/man3/X509_check_purpose.pod @@ -0,0 +1,74 @@ +=pod + +=head1 NAME + +X509_check_purpose - Check the purpose of a certificate + +=head1 SYNOPSIS + + #include + + int X509_check_purpose(X509 *x, int id, int ca) + +=head1 DESCRIPTION + +This function checks if certificate I was created with the purpose +represented by I. If I is nonzero, then certificate I is +checked to determine if it's a possible CA with various levels of certainty +possibly returned. + +Below are the potential ID's that can be checked: + + # define X509_PURPOSE_SSL_CLIENT 1 + # define X509_PURPOSE_SSL_SERVER 2 + # define X509_PURPOSE_NS_SSL_SERVER 3 + # define X509_PURPOSE_SMIME_SIGN 4 + # define X509_PURPOSE_SMIME_ENCRYPT 5 + # define X509_PURPOSE_CRL_SIGN 6 + # define X509_PURPOSE_ANY 7 + # define X509_PURPOSE_OCSP_HELPER 8 + # define X509_PURPOSE_TIMESTAMP_SIGN 9 + +=head1 RETURN VALUES + +For non-CA checks + +=over 4 + +=item -1 an error condition has occured + +=item E<32>1 if the certificate was created to perform the purpose represented by I + +=item E<32>0 if the certificate was not created to perform the purpose represented by I + +=back + +For CA checks the below integers could be returned with the following meanings: + +=over 4 + +=item -1 an error condition has occured + +=item E<32>0 not a CA or does not have the purpose represented by I + +=item E<32>1 is a CA. + +=item E<32>2 Only possible in old versions of openSSL when basicConstraints are absent. + New versions will not return this value. May be a CA + +=item E<32>3 basicConstraints absent but self signed V1. + +=item E<32>4 basicConstraints absent but keyUsage present and keyCertSign asserted. + +=item E<32>5 legacy Netscape specific CA Flags present + +=back + +=head1 COPYRIGHT + +Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. +Licensed under the Apache License 2.0 (the "License"). You may not use this +file except in compliance with the License. You can obtain a copy in the file +LICENSE in the source distribution or at L. + +=cut diff --git a/util/missingcrypto.txt b/util/missingcrypto.txt index a53909f4d2..73c5af9101 100644 --- a/util/missingcrypto.txt +++ b/util/missingcrypto.txt @@ -1455,7 +1455,6 @@ X509_aux_print(3) X509_certificate_type(3) X509_chain_check_suiteb(3) X509_check_akid(3) -X509_check_purpose(3) X509_check_trust(3) X509_email_free(3) X509_find_by_issuer_and_serial(3) -- 2.25.1