From 07e2f4b2aabdc5709ae055b226fb54d9d21c631e Mon Sep 17 00:00:00 2001
From: Jake Maynard <jake@maynard-labs.com>
Date: Wed, 30 Oct 2019 11:27:04 -0400
Subject: [PATCH] Add manpage entry for X509_check_purpose()

Fixes #10263

Reviewed-by: Paul Dale <paul.dale@oracle.com>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10301)

(cherry picked from commit eacd30a703b52f5b3e8e70b58f99bd1128458c7c)
---
 crypto/x509v3/v3_purp.c         |  4 +-
 doc/man3/X509_check_purpose.pod | 74 +++++++++++++++++++++++++++++++++
 2 files changed, 77 insertions(+), 1 deletion(-)
 create mode 100644 doc/man3/X509_check_purpose.pod

diff --git a/crypto/x509v3/v3_purp.c b/crypto/x509v3/v3_purp.c
index 2eaad1a763..f023c64895 100644
--- a/crypto/x509v3/v3_purp.c
+++ b/crypto/x509v3/v3_purp.c
@@ -549,9 +549,11 @@ static void x509v3_cache_extensions(X509 *x)
  * 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 <openssl/x509v3.h>
+
+ int X509_check_purpose(X509 *x, int id, int ca)
+
+=head1 DESCRIPTION
+
+This function checks if certificate I<x> was created with the purpose
+represented by I<id>. If I<ca> is nonzero, then certificate I<x> 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<id>
+
+=item E<32>0 if the certificate was not created to perform the purpose represented by I<id>
+
+=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<id>
+
+=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<https://www.openssl.org/source/license.html>.
+
+=cut
-- 
2.25.1