cert_pool.go

     1  // Copyright 2011 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  package x509
     6  
     7  import (
     8  	"bytes"
     9  	"crypto/sha256"
    10  	"encoding/pem"
    11  	"sync"
    12  )
    13  
    14  type sum224 [sha256.Size224]byte
    15  
    16  // CertPool is a set of certificates.
    17  type CertPool struct {
    18  	byName map[string][]int // cert.RawSubject => index into lazyCerts
    19  
    20  	// lazyCerts contains funcs that return a certificate,
    21  	// lazily parsing/decompressing it as needed.
    22  	lazyCerts []lazyCert
    23  
    24  	// haveSum maps from sum224(cert.Raw) to true. It's used only
    25  	// for AddCert duplicate detection, to avoid CertPool.contains
    26  	// calls in the AddCert path (because the contains method can
    27  	// call getCert and otherwise negate savings from lazy getCert
    28  	// funcs).
    29  	haveSum map[sum224]bool
    30  
    31  	// systemPool indicates whether this is a special pool derived from the
    32  	// system roots. If it includes additional roots, it requires doing two
    33  	// verifications, one using the roots provided by the caller, and one using
    34  	// the system platform verifier.
    35  	systemPool bool
    36  }
    37  
    38  // lazyCert is minimal metadata about a Cert and a func to retrieve it
    39  // in its normal expanded *Certificate form.
    40  type lazyCert struct {
    41  	// rawSubject is the Certificate.RawSubject value.
    42  	// It's the same as the CertPool.byName key, but in []byte
    43  	// form to make CertPool.Subjects (as used by crypto/tls) do
    44  	// fewer allocations.
    45  	rawSubject []byte
    46  
    47  	// constraint is a function to run against a chain when it is a candidate to
    48  	// be added to the chain. This allows adding arbitrary constraints that are
    49  	// not specified in the certificate itself.
    50  	constraint func([]*Certificate) error
    51  
    52  	// getCert returns the certificate.
    53  	//
    54  	// It is not meant to do network operations or anything else
    55  	// where a failure is likely; the func is meant to lazily
    56  	// parse/decompress data that is already known to be good. The
    57  	// error in the signature primarily is meant for use in the
    58  	// case where a cert file existed on local disk when the program
    59  	// started up is deleted later before it's read.
    60  	getCert func() (*Certificate, error)
    61  }
    62  
    63  // NewCertPool returns a new, empty CertPool.
    64  func NewCertPool() *CertPool {
    65  	return &CertPool{
    66  		byName:  make(map[string][]int),
    67  		haveSum: make(map[sum224]bool),
    68  	}
    69  }
    70  
    71  // len returns the number of certs in the set.
    72  // A nil set is a valid empty set.
    73  func (s *CertPool) len() int {
    74  	if s == nil {
    75  		return 0
    76  	}
    77  	return len(s.lazyCerts)
    78  }
    79  
    80  // cert returns cert index n in s.
    81  func (s *CertPool) cert(n int) (*Certificate, func([]*Certificate) error, error) {
    82  	cert, err := s.lazyCerts[n].getCert()
    83  	return cert, s.lazyCerts[n].constraint, err
    84  }
    85  
    86  // Clone returns a copy of s.
    87  func (s *CertPool) Clone() *CertPool {
    88  	p := &CertPool{
    89  		byName:     make(map[string][]int, len(s.byName)),
    90  		lazyCerts:  make([]lazyCert, len(s.lazyCerts)),
    91  		haveSum:    make(map[sum224]bool, len(s.haveSum)),
    92  		systemPool: s.systemPool,
    93  	}
    94  	for k, v := range s.byName {
    95  		indexes := make([]int, len(v))
    96  		copy(indexes, v)
    97  		p.byName[k] = indexes
    98  	}
    99  	for k := range s.haveSum {
   100  		p.haveSum[k] = true
   101  	}
   102  	copy(p.lazyCerts, s.lazyCerts)
   103  	return p
   104  }
   105  
   106  // SystemCertPool returns a copy of the system cert pool.
   107  //
   108  // The environment variables SSL_CERT_FILE and SSL_CERT_DIR can be used to
   109  // override the system default locations for the SSL certificate file and SSL
   110  // certificate files directory, respectively. The latter can be a
   111  // colon-separated list, or a semicolon-separated list on Windows. On platforms
   112  // which have system APIs for certificate verification (macOS and Windows),
   113  // setting SSL_CERT_FILE or SSL_CERT_DIR will prevent those APIs from being
   114  // used, unless the x509sslcertoverrideplatform=0 GODEBUG setting is used. (This
   115  // changed in Go 1.27.)
   116  //
   117  // Any mutations to the returned pool are not written to disk and do not affect
   118  // any other pool returned by SystemCertPool.
   119  //
   120  // New changes in the system cert pool might not be reflected in subsequent calls.
   121  func SystemCertPool() (*CertPool, error) {
   122  	if sysRoots := systemRootsPool(); sysRoots != nil {
   123  		return sysRoots.Clone(), nil
   124  	}
   125  
   126  	return loadSystemRoots()
   127  }
   128  
   129  type potentialParent struct {
   130  	cert       *Certificate
   131  	constraint func([]*Certificate) error
   132  }
   133  
   134  // findPotentialParents returns the certificates in s which might have signed
   135  // cert.
   136  func (s *CertPool) findPotentialParents(cert *Certificate) []potentialParent {
   137  	if s == nil {
   138  		return nil
   139  	}
   140  
   141  	// consider all candidates where cert.Issuer matches cert.Subject.
   142  	// when picking possible candidates the list is built in the order
   143  	// of match plausibility as to save cycles in buildChains:
   144  	//   AKID and SKID match
   145  	//   AKID present, SKID missing / AKID missing, SKID present
   146  	//   AKID and SKID don't match
   147  	var matchingKeyID, oneKeyID, mismatchKeyID []potentialParent
   148  	for _, c := range s.byName[string(cert.RawIssuer)] {
   149  		candidate, constraint, err := s.cert(c)
   150  		if err != nil {
   151  			continue
   152  		}
   153  		kidMatch := bytes.Equal(candidate.SubjectKeyId, cert.AuthorityKeyId)
   154  		switch {
   155  		case kidMatch:
   156  			matchingKeyID = append(matchingKeyID, potentialParent{candidate, constraint})
   157  		case (len(candidate.SubjectKeyId) == 0 && len(cert.AuthorityKeyId) > 0) ||
   158  			(len(candidate.SubjectKeyId) > 0 && len(cert.AuthorityKeyId) == 0):
   159  			oneKeyID = append(oneKeyID, potentialParent{candidate, constraint})
   160  		default:
   161  			mismatchKeyID = append(mismatchKeyID, potentialParent{candidate, constraint})
   162  		}
   163  	}
   164  
   165  	found := len(matchingKeyID) + len(oneKeyID) + len(mismatchKeyID)
   166  	if found == 0 {
   167  		return nil
   168  	}
   169  	candidates := make([]potentialParent, 0, found)
   170  	candidates = append(candidates, matchingKeyID...)
   171  	candidates = append(candidates, oneKeyID...)
   172  	candidates = append(candidates, mismatchKeyID...)
   173  	return candidates
   174  }
   175  
   176  func (s *CertPool) contains(cert *Certificate) bool {
   177  	if s == nil {
   178  		return false
   179  	}
   180  	return s.haveSum[sha256.Sum224(cert.Raw)]
   181  }
   182  
   183  // AddCert adds a certificate to a pool.
   184  func (s *CertPool) AddCert(cert *Certificate) {
   185  	if cert == nil {
   186  		panic("adding nil Certificate to CertPool")
   187  	}
   188  	s.addCertFunc(sha256.Sum224(cert.Raw), string(cert.RawSubject), func() (*Certificate, error) {
   189  		return cert, nil
   190  	}, nil)
   191  }
   192  
   193  // addCertFunc adds metadata about a certificate to a pool, along with
   194  // a func to fetch that certificate later when needed.
   195  //
   196  // The rawSubject is Certificate.RawSubject and must be non-empty.
   197  // The getCert func may be called 0 or more times.
   198  func (s *CertPool) addCertFunc(rawSum224 sum224, rawSubject string, getCert func() (*Certificate, error), constraint func([]*Certificate) error) {
   199  	if getCert == nil {
   200  		panic("getCert can't be nil")
   201  	}
   202  
   203  	// Check that the certificate isn't being added twice.
   204  	if s.haveSum[rawSum224] {
   205  		return
   206  	}
   207  
   208  	s.haveSum[rawSum224] = true
   209  	s.lazyCerts = append(s.lazyCerts, lazyCert{
   210  		rawSubject: []byte(rawSubject),
   211  		getCert:    getCert,
   212  		constraint: constraint,
   213  	})
   214  	s.byName[rawSubject] = append(s.byName[rawSubject], len(s.lazyCerts)-1)
   215  }
   216  
   217  // AppendCertsFromPEM attempts to parse a series of PEM encoded certificates.
   218  // It appends any certificates found to s and reports whether any certificates
   219  // were successfully parsed.
   220  //
   221  // On many Linux systems, /etc/ssl/cert.pem will contain the system wide set
   222  // of root CAs in a format suitable for this function.
   223  func (s *CertPool) AppendCertsFromPEM(pemCerts []byte) (ok bool) {
   224  	for len(pemCerts) > 0 {
   225  		var block *pem.Block
   226  		block, pemCerts = pem.Decode(pemCerts)
   227  		if block == nil {
   228  			break
   229  		}
   230  		if block.Type != "CERTIFICATE" || len(block.Headers) != 0 {
   231  			continue
   232  		}
   233  
   234  		certBytes := block.Bytes
   235  		cert, err := ParseCertificate(certBytes)
   236  		if err != nil {
   237  			continue
   238  		}
   239  		var lazyCert struct {
   240  			sync.Once
   241  			v *Certificate
   242  		}
   243  		s.addCertFunc(sha256.Sum224(cert.Raw), string(cert.RawSubject), func() (*Certificate, error) {
   244  			lazyCert.Do(func() {
   245  				// This can't fail, as the same bytes already parsed above.
   246  				lazyCert.v, _ = ParseCertificate(certBytes)
   247  				certBytes = nil
   248  			})
   249  			return lazyCert.v, nil
   250  		}, nil)
   251  		ok = true
   252  	}
   253  
   254  	return ok
   255  }
   256  
   257  // Subjects returns a list of the DER-encoded subjects of
   258  // all of the certificates in the pool.
   259  //
   260  // Deprecated: if s was returned by [SystemCertPool], Subjects
   261  // will not include the system roots.
   262  func (s *CertPool) Subjects() [][]byte {
   263  	res := make([][]byte, s.len())
   264  	for i, lc := range s.lazyCerts {
   265  		res[i] = lc.rawSubject
   266  	}
   267  	return res
   268  }
   269  
   270  // Equal reports whether s and other are equal.
   271  func (s *CertPool) Equal(other *CertPool) bool {
   272  	if s == nil || other == nil {
   273  		return s == other
   274  	}
   275  	if s.systemPool != other.systemPool || len(s.haveSum) != len(other.haveSum) {
   276  		return false
   277  	}
   278  	for h := range s.haveSum {
   279  		if !other.haveSum[h] {
   280  			return false
   281  		}
   282  	}
   283  	return true
   284  }
   285  
   286  // AddCertWithConstraint adds a certificate to the pool with the additional
   287  // constraint. When Certificate.Verify builds a chain which is rooted by cert,
   288  // it will additionally pass the whole chain to constraint to determine its
   289  // validity. If constraint returns a non-nil error, the chain will be discarded.
   290  // constraint may be called concurrently from multiple goroutines.
   291  func (s *CertPool) AddCertWithConstraint(cert *Certificate, constraint func([]*Certificate) error) {
   292  	if cert == nil {
   293  		panic("adding nil Certificate to CertPool")
   294  	}
   295  	s.addCertFunc(sha256.Sum224(cert.Raw), string(cert.RawSubject), func() (*Certificate, error) {
   296  		return cert, nil
   297  	}, constraint)
   298  }
   299
View as plain text