Make it possible for external code to set the certiciate proxy path length

[openssl.git] / doc / crypto / X509_get_extension_flags.pod

diff --git a/doc/crypto/X509_get_extension_flags.pod b/doc/crypto/X509_get_extension_flags.pod
index d19eb8957493203a8e235a87165416e7df46a9ec..0fc42e8b920b77b05a466a57839391767ef50a58 100644 (file)
--- a/doc/crypto/X509_get_extension_flags.pod
+++ b/doc/crypto/X509_get_extension_flags.pod
@@ -2,21 +2,35 @@
 
 =head1 NAME
 
-X509_get_extension_flags, X509_get_key_usage, X509_get_extended_key_usage -
-retrieve certificate extension flags.
+X509_get0_subject_key_id,
+X509_get_pathlen,
+X509_get_extension_flags,
+X509_get_key_usage,
+X509_get_extended_key_usage,
+X509_set_proxy_flag,
+X509_set_proxy_pathlen,
+X509_get_proxy_pathlen - retrieve certificate extension data
 
 =head1 SYNOPSIS
 
    #include <openssl/x509v3.h>
 
+   long X509_get_pathlen(X509 *x);
    uint32_t X509_get_extension_flags(X509 *x);
    uint32_t X509_get_key_usage(X509 *x);
    uint32_t X509_get_extended_key_usage(X509 *x);
    const ASN1_OCTET_STRING *X509_get0_subject_key_id(X509 *x);
+   void X509_set_proxy_flag(X509 *x);
+   void X509_set_proxy_path_length(int l);
+   long X509_get_proxy_pathlen(X509 *x);
 
 =head1 DESCRIPTION
 
-These functions retrieve flags related to commonly used certificate extensions.
+These functions retrieve information related to commonly used certificate extensions.
+
+X509_get_pathlen() retrieves the path length extension from a certificate.
+This extension is used to limit the length of a cert chain that may be
+issued from that CA.
 
 X509_get_extension_flags() retrieves general information about a certificate,
 it will return one or more of the following flags ored together.
@@ -95,6 +109,17 @@ X509_get_extended_key_usage() return an internal pointer to the subject key
 identifier of B<x> as an B<ASN1_OCTET_STRING> or B<NULL> if the extension
 is not present or cannot be parsed.
 
+X509_set_proxy_flag() marks the certificate with the B<EXFLAG_PROXY> flag.
+This is for the users who need to mark non-RFC3820 proxy certificates as
+such, as OpenSSL only detects RFC3820 compliant ones.
+
+X509_set_proxy_pathlen() sets the proxy certificate path length for the given
+certificate B<x>.  This is for the users who need to mark non-RFC3820 proxy
+certificates as such, as OpenSSL only detects RFC3820 compliant ones.
+
+X509_get_proxy_pathlen() returns the proxy certificate path length for the
+given certificate B<x> if it is a proxy certicate.
+
 =head1 NOTES
 
 The value of the flags correspond to extension values which are cached
@@ -115,16 +140,36 @@ X509_get_ext_d2i().
 
 =head1 RETURN VALUE
 
+X509_get_pathlen() returns the path length value, or -1 if the extension
+is not present.
+
 X509_get_extension_flags(), X509_get_key_usage() and
 X509_get_extended_key_usage() return sets of flags corresponding to the
 certificate extension values.
 
 X509_get0_subject_key_id() returns the subject key identifier as a
 pointer to an B<ASN1_OCTET_STRING> structure or B<NULL> if the extension
-is absent or an error occured during parsing.
+is absent or an error occurred during parsing.
+
+X509_get_proxy_pathlen() returns the path length value if the given
+certificate is a proxy one and has a path length set, and -1 otherwise.
 
 =head1 SEE ALSO
 
 L<X509_check_purpose(3)>
 
+=head1 HISTORY
+
+X509_get_pathlen(), X509_set_proxy_flag(), X509_set_proxy_pathlen() and
+X509_get_proxy_pathlen() were added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (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