crypto/x509: update MaxPathLen & MaxPathLenZero docs

Fixes #19285

Change-Id: I11e864eff9980dec8247c47e4c600f76602e7ada
Reviewed-on: https://go-review.googlesource.com/46092
Reviewed-by: Ian Lance Taylor <iant@golang.org>

diff --git a/src/crypto/x509/x509.go b/src/crypto/x509/x509.go
index 549b64b8304902f6159fd090e1496991b3150322..fdc7c5307bdcb984c201a6f099eddbdde78b534c 100644 (file)
--- a/src/crypto/x509/x509.go
+++ b/src/crypto/x509/x509.go
@@ -665,13 +665,28 @@ type Certificate struct {
        ExtKeyUsage        []ExtKeyUsage           // Sequence of extended key usages.
        UnknownExtKeyUsage []asn1.ObjectIdentifier // Encountered extended key usages unknown to this package.
 
-       BasicConstraintsValid bool // if true then the next two fields are valid.
+       // BasicConstraintsValid indicates whether IsCA, MaxPathLen,
+       // and MaxPathLenZero are valid.
+       BasicConstraintsValid bool
        IsCA                  bool
-       MaxPathLen            int
-       // MaxPathLenZero indicates that BasicConstraintsValid==true and
-       // MaxPathLen==0 should be interpreted as an actual maximum path length
-       // of zero. Otherwise, that combination is interpreted as MaxPathLen
-       // not being set.
+
+       // MaxPathLen and MaxPathLenZero indicate the presence and
+       // value of the BasicConstraints' "pathLenConstraint".
+       //
+       // When parsing a certificate, a positive non-zero MaxPathLen
+       // means that the field was specified, -1 means it was unset,
+       // and MaxPathLenZero being true mean that the field was
+       // explicitly set to zero. The case of MaxPathLen==0 with MaxPathLenZero==false
+       // should be treated equivalent to -1 (unset).
+       //
+       // When generating a certificate, an unset pathLenConstraint
+       // can be requested with either MaxPathLen == -1 or using the
+       // zero value for both MaxPathLen and MaxPathLenZero.
+       MaxPathLen int
+       // MaxPathLenZero indicates that BasicConstraintsValid==true
+       // and MaxPathLen==0 should be interpreted as an actual
+       // maximum path length of zero. Otherwise, that combination is
+       // interpreted as MaxPathLen not being set.
        MaxPathLenZero bool
 
        SubjectKeyId   []byte
@@ -1149,7 +1164,7 @@ func parseCertificate(in *certificate) (*Certificate, error) {
                                out.IsCA = constraints.IsCA
                                out.MaxPathLen = constraints.MaxPathLen
                                out.MaxPathLenZero = out.MaxPathLen == 0
-
+                               // TODO: map out.MaxPathLen to 0 if it has the -1 default value? (Issue 19285)
                        case 17:
                                out.DNSNames, out.EmailAddresses, out.IPAddresses, err = parseSANExtension(e.Value)
                                if err != nil {
@@ -1717,12 +1732,12 @@ func signingParamsForPublicKey(pub interface{}, requestedSigAlgo SignatureAlgori
        return
 }
 
-// CreateCertificate creates a new certificate based on a template. The
-// following members of template are used: AuthorityKeyId,
-// BasicConstraintsValid, DNSNames, ExcludedDNSDomains, ExtKeyUsage, IsCA,
-// KeyUsage, MaxPathLen, NotAfter, NotBefore, PermittedDNSDomains,
-// PermittedDNSDomainsCritical, SerialNumber, SignatureAlgorithm, Subject,
-// SubjectKeyId, and UnknownExtKeyUsage.
+// CreateCertificate creates a new certificate based on a template.
+// The following members of template are used: AuthorityKeyId,
+// BasicConstraintsValid, DNSNames, ExcludedDNSDomains, ExtKeyUsage,
+// IsCA, KeyUsage, MaxPathLen, MaxPathLenZero, NotAfter, NotBefore,
+// PermittedDNSDomains, PermittedDNSDomainsCritical, SerialNumber,
+// SignatureAlgorithm, Subject, SubjectKeyId, and UnknownExtKeyUsage.
 //
 // The certificate is signed by parent. If parent is equal to template then the
 // certificate is self-signed. The parameter pub is the public key of the