Documentation

Overview

    Package certconfig contains code to work with imported CAs and their CRLs.

    These CAs are used to validate certificates used in MintMachineToken RPC calls.

    Index

    Constants

    View Source
    const CRLShardCount = 16

      CRLShardCount is a number of shards to use for storing CRL in the datastore.

      Each shard can hold ~2 MB of data (taking into account zlib compression), so 16 shards ~= 32 MB. Good enough for a foreseeable future.

      Changing this value requires rerunning of Admin.FetchCRL RPC to rebuild the entities.

      Variables

      This section is empty.

      Functions

      func GetCAByUniqueID

      func GetCAByUniqueID(c context.Context, id int64) (string, error)

        GetCAByUniqueID returns CN name that corresponds to given unique ID.

        It uses cached CAUniqueIDToCNMap for lookups. Returns empty string if there's no such CA.

        func ListCAs

        func ListCAs(c context.Context) ([]string, error)

          ListCAs returns names of all currently active CAs, in no particular order.

          func LoadCAUniqueIDToCNMap

          func LoadCAUniqueIDToCNMap(c context.Context) (map[int64]string, error)

            LoadCAUniqueIDToCNMap loads CAUniqueIDToCNMap from the datastore.

            func StoreCAUniqueIDToCNMap

            func StoreCAUniqueIDToCNMap(c context.Context, mapping map[int64]string) error

              StoreCAUniqueIDToCNMap overwrites CAUniqueIDToCNMap with new content.

              func UpdateCRLSet

              func UpdateCRLSet(c context.Context, cn string, shardCount int, crl *pkix.CertificateList) error

                UpdateCRLSet splits a set of revoked certificate serial numbers into shards, storing each shard in a separate entity (CRLShardBody).

                It effectively overwrites the entire set.

                Types

                type CA

                type CA struct {
                	// CN is CA's Common Name.
                	CN string `gae:"$id"`
                
                	// Config is serialized CertificateAuthorityConfig proto message.
                	Config []byte `gae:",noindex"`
                
                	// Cert is a certificate of this CA (in der encoding).
                	//
                	// It is read from luci-config from path specified in the config.
                	Cert []byte `gae:",noindex"`
                
                	// Removed is true if this CA has been removed from the config.
                	Removed bool
                
                	// Ready is false before this CA's CRL is fetched for the first time.
                	Ready bool
                
                	AddedRev   string `gae:",noindex"` // config rev when this CA appeared
                	UpdatedRev string `gae:",noindex"` // config rev when this CA was updated
                	RemovedRev string `gae:",noindex"` // config rev when it was removed
                
                	// ParsedConfig is parsed Config.
                	//
                	// Populated if CA is fetched through CertChecker.
                	ParsedConfig *admin.CertificateAuthorityConfig `gae:"-"`
                
                	// ParsedCert is parsed Cert.
                	//
                	// Populated if CA is fetched through CertChecker.
                	ParsedCert *x509.Certificate `gae:"-"`
                }

                  CA defines one trusted Certificate Authority (imported from config).

                  Entity key is CA Common Name (that must match what's is in the certificate). Certificate issuer (and the certificate signature) is ignored. Usually, the certificates here will be self-signed.

                  Removed CAs are kept in the datastore, but not actively used.

                  func (*CA) ParseConfig

                  func (c *CA) ParseConfig() (*admin.CertificateAuthorityConfig, error)

                    ParseConfig parses proto message stored in Config.

                    type CAUniqueIDToCNMap

                    type CAUniqueIDToCNMap struct {
                    	GobEncodedMap []byte `gae:",noindex"` // gob-encoded map[int64]string
                    	// contains filtered or unexported fields
                    }

                      CAUniqueIDToCNMap is a singleton entity that stores a mapping between CA's unique_id (specified in config) and its Common Name.

                      It's loaded in memory in full and kept cached there (for 1 min). See GetCAByUniqueID below.

                      type CRL

                      type CRL struct {
                      
                      	// Parent is pointing to parent CA entity.
                      	Parent *ds.Key `gae:"$parent"`
                      
                      	// EntityVersion is used for simple concurrency control.
                      	//
                      	// Increase on each update of this entity.
                      	EntityVersion int `gae:",noindex"`
                      
                      	// LastUpdateTime is extracted from corresponding field of CRL.
                      	//
                      	// It indicates a time when CRL was generated by the CA.
                      	LastUpdateTime time.Time `gae:",noindex"`
                      
                      	// LastFetchTime is when this CRL was fetched the last time.
                      	//
                      	// Updated only when newer CRL version is fetched.
                      	LastFetchTime time.Time `gae:",noindex"`
                      
                      	// LastFetchETag is ETag header of last downloaded CRL file.
                      	//
                      	// If CRL's etag doesn't change, we can skip reparsing CRL.
                      	LastFetchETag string `gae:",noindex"`
                      
                      	// RevokedCertsCount is a number of revoked certificates in CRL. FYI only.
                      	RevokedCertsCount int `gae:",noindex"`
                      	// contains filtered or unexported fields
                      }

                        CRL represents a parsed Certificate Revocation List of some CA.

                        ID is always "crl", the parent entity is corresponding CA.

                        func (*CRL) GetStatusProto

                        func (crl *CRL) GetStatusProto() *admin.CRLStatus

                          GetStatusProto returns populated CRLStatus proto message.

                          type CRLChecker

                          type CRLChecker struct {
                          	// contains filtered or unexported fields
                          }

                            CRLChecker knows how to check presence of a certificate serial number in CRL.

                            Uses entities prepared by UpdateCRLSet.

                            It is a stateful object that caches CRL shards in memory (occasionally refetching them from the datastore), thus providing an eventually consistent view of the CRL set.

                            Safe for concurrent use. Should be reused between requests.

                            func NewCRLChecker

                            func NewCRLChecker(cn string, shardCount int, cacheDuration time.Duration) *CRLChecker

                              NewCRLChecker initializes new CRLChecker that knows how to examine CRL of a CA (identifies by its Common Name).

                              It must know number of shards in advance. Usually is it just CRLShardCount.

                              It will cache shards in local memory, refetching them if necessary after 'cacheDuration' interval.

                              func (*CRLChecker) IsRevokedSN

                              func (ch *CRLChecker) IsRevokedSN(c context.Context, sn *big.Int) (bool, error)

                                IsRevokedSN returns true if given serial number is in the CRL.

                                type CRLShardBody

                                type CRLShardBody struct {
                                	Parent     *ds.Key `gae:"$parent"`  // key of CRLShardHeader
                                	SHA1       string  `gae:",noindex"` // SHA1 of serialized shard data (before compression)
                                	ZippedData []byte  `gae:",noindex"` // zlib-compressed serialized shards.Shard.
                                	// contains filtered or unexported fields
                                }

                                  CRLShardBody is a fat entity that contains serialized CRL shard.

                                  See CRLShardHeader for more info.

                                  Parent entity is CRLShardHeader. ID is always "1".

                                  type CRLShardHeader

                                  type CRLShardHeader struct {
                                  	ID   string `gae:"$id"`
                                  	SHA1 string `gae:",noindex"` // SHA1 of serialized shard data (before compression)
                                  }

                                    CRLShardHeader represents a hash of a shard of a CRL sharded set.

                                    We split CRL into a bunch of shards to avoid hitting datastore entity size limits. Each shard lives in its own entity group, where root entity (CRLShardHeader) contains a hash of the shard data (CRLShardBody).

                                    It is used to skip fetches of fat shard entities if we already have the same data locally (based on matching hash).

                                    ID is "<cn name>|<total number of shards>|<shard index>" (see shardEntityID).

                                    type FetchCRLRPC

                                    type FetchCRLRPC struct {
                                    }

                                      FetchCRLRPC implements CertificateAuthorities.FetchCRL RPC method.

                                      func (*FetchCRLRPC) FetchCRL

                                      func (r *FetchCRLRPC) FetchCRL(c context.Context, req *admin.FetchCRLRequest) (*admin.FetchCRLResponse, error)

                                        FetchCRL makes the server fetch a CRL for some CA.

                                        type GetCAStatusRPC

                                        type GetCAStatusRPC struct {
                                        }

                                          GetCAStatusRPC implements CertificateAuthorities.GetCAStatus RPC method.

                                          func (*GetCAStatusRPC) GetCAStatus

                                          func (r *GetCAStatusRPC) GetCAStatus(c context.Context, req *admin.GetCAStatusRequest) (*admin.GetCAStatusResponse, error)

                                            GetCAStatus returns configuration of some CA defined in the config.

                                            type ImportCAConfigsRPC

                                            type ImportCAConfigsRPC struct {
                                            }

                                              ImportCAConfigsRPC implements Admin.ImportCAConfigs RPC method.

                                              func (*ImportCAConfigsRPC) ImportCAConfigs

                                              func (r *ImportCAConfigsRPC) ImportCAConfigs(c context.Context, _ *emptypb.Empty) (*admin.ImportedConfigs, error)

                                                ImportCAConfigs fetches CA configs from from luci-config right now.

                                                func (*ImportCAConfigsRPC) SetupConfigValidation

                                                func (r *ImportCAConfigsRPC) SetupConfigValidation(rules *validation.RuleSet)

                                                  SetupConfigValidation registers the config validation rules.

                                                  type ListCAsRPC

                                                  type ListCAsRPC struct {
                                                  }

                                                    ListCAsRPC implements CertificateAuthorities.ListCAs RPC method.

                                                    func (*ListCAsRPC) ListCAs

                                                    func (r *ListCAsRPC) ListCAs(c context.Context, _ *emptypb.Empty) (*admin.ListCAsResponse, error)

                                                      ListCAs returns a list of Common Names of registered CAs.