Documentation

Index

Constants

View Source
const IDFormat = `^[a-zA-Z0-9-_]{1,64}$`

    IDFormat is a regex for the format IDs must follow

    Variables

    This section is empty.

    Functions

    func GetPrivKeyHandle

    func GetPrivKeyHandle(priv crypto.PrivateKey) uint

      GetPrivKeyHandle returns the hsm handler object id of a key stored in the hsm, or 0 if the key is not stored in the hsm

      func ParsePrivateKey

      func ParsePrivateKey(keyPEMBlock []byte) (key crypto.PrivateKey, err error)

        ParsePrivateKey takes a PEM blocks are returns a crypto.PrivateKey It tries to parse as many known key types as possible before failing and returning all the errors it encountered.

        Types

        type Configuration

        type Configuration struct {
        	ID            string            `json:"id"`
        	Type          string            `json:"type"`
        	Mode          string            `json:"mode"`
        	PrivateKey    string            `json:"privatekey,omitempty"`
        	PublicKey     string            `json:"publickey,omitempty"`
        	IssuerPrivKey string            `json:"issuerprivkey,omitempty"`
        	IssuerCert    string            `json:"issuercert,omitempty"`
        	Certificate   string            `json:"certificate,omitempty"`
        	DB            *database.Handler `json:"-"`
        
        	// X5U (X.509 URL) is a URL that points to an X.509 public key
        	// certificate chain to validate a content signature
        	X5U string `json:"x5u,omitempty"`
        
        	// RSACacheConfig for XPI signers this specifies config for an
        	// RSA cache
        	RSACacheConfig RSACacheConfig `json:"rsacacheconfig,omitempty"`
        
        	// RecommendationConfig specifies config values for
        	// recommendations files for XPI signers
        	RecommendationConfig RecommendationConfig `yaml:"recommendation,omitempty"`
        
        	// NoPKCS7SignedAttributes for signing legacy APKs don't sign
        	// attributes and use a legacy PKCS7 digest
        	NoPKCS7SignedAttributes bool `json:"nopkcs7signedattributes,omitempty"`
        
        	// KeyID is the fingerprint of the gpg key or subkey to use
        	// e.g. 0xA2B637F535A86009 for the gpg2 signer type
        	KeyID string `json:"keyid,omitempty"`
        
        	// Passphrase is the optional passphrase to use decrypt the
        	// gpg secret key for the gpg2 signer type
        	Passphrase string `json:"passphrase,omitempty"`
        
        	// Validity is the lifetime of a end-entity certificate
        	Validity time.Duration `json:"validity,omitempty"`
        
        	// ClockSkewTolerance increase the lifetime of a certificate
        	// to account for clients with skewed clocks by adding days
        	// to the notbefore and notafter values. For example, a certificate
        	// with a validity of 30d and a clock skew tolerance of 10 days will
        	// have a total validity of 10+30+10=50 days.
        	ClockSkewTolerance time.Duration `json:"clock_skew_tolerance,omitempty"`
        
        	// ChainUploadLocation is the target a certificate chain should be
        	// uploaded to in order for clients to find it at the x5u location.
        	ChainUploadLocation string `json:"chain_upload_location,omitempty"`
        
        	// CaCert is the certificate of the root of the pki, when used
        	CaCert string `json:"cacert,omitempty"`
        
        	// Hash is a hash algorithm like 'sha1' or 'sha256'
        	Hash string `json:"hash,omitempty"`
        
        	// SaltLength controls the length of the salt used in a RSA PSS
        	// signature. It can either be a number of bytes, or one of the special
        	// PSSSaltLength constants from the rsa package.
        	SaltLength int `json:"saltlength,omitempty"`
        
        	// SignerOpts contains options for signing with a Signer
        	SignerOpts crypto.SignerOpts `json:"signer_opts,omitempty"`
        	// contains filtered or unexported fields
        }

          Configuration defines the parameters of a signer

          func (*Configuration) CheckHSMConnection

          func (cfg *Configuration) CheckHSMConnection() error

            CheckHSMConnection is the default implementation of CheckHSMConnection (exposed via the signer.Configuration interface). It tried to fetch the signer private key and errors if that fails or the private key is not an HSM key handle.

            func (*Configuration) GetKeys

            func (cfg *Configuration) GetKeys() (priv crypto.PrivateKey, pub crypto.PublicKey, publicKey string, err error)

              GetKeys parses a configuration to retrieve the private and public key of a signer, and a marshalled public key. It fetches keys from the HSM when possible.

              func (*Configuration) GetPrivateKey

              func (cfg *Configuration) GetPrivateKey() (crypto.PrivateKey, error)

                GetPrivateKey uses a signer configuration to determine where a private key should be accessed from. If it is in local configuration, it will be parsed and loaded in the signer. If it is in an HSM, it will be used via a PKCS11 interface. This is completely transparent to the caller, who should simply assume that the privatekey implements a crypto.Sign interface

                Note that we assume the PKCS11 library has been previously initialized

                func (*Configuration) GetRand

                func (cfg *Configuration) GetRand() io.Reader

                  GetRand returns a cryptographically secure random number from the HSM if available and otherwise rand.Reader

                  func (*Configuration) InitHSM

                  func (cfg *Configuration) InitHSM(ctx *pkcs11.Ctx)

                    InitHSM indicates that an HSM has been initialized

                    func (*Configuration) MakeKey

                    func (cfg *Configuration) MakeKey(keyTpl interface{}, keyName string) (priv crypto.PrivateKey, pub crypto.PublicKey, err error)

                      MakeKey generates a new key of type keyTpl and returns the priv and public interfaces. If an HSM is available, it is used to generate and store the key, in which case 'priv' just points to the HSM handler and must be used via the crypto.Signer interface.

                      func (*Configuration) PrivateKeyHasPEMPrefix

                      func (cfg *Configuration) PrivateKeyHasPEMPrefix() bool

                        PrivateKeyHasPEMPrefix returns whether the signer configuration prefix begins with `-----BEGIN` (indicating a PEM block) after stripping newlines

                        type DataSigner

                        type DataSigner interface {
                        	SignData(data []byte, options interface{}) (Signature, error)
                        	GetDefaultOptions() interface{}
                        }

                          DataSigner is an interface to a signer able to sign raw data

                          type FileSigner

                          type FileSigner interface {
                          	SignFile(file []byte, options interface{}) (SignedFile, error)
                          	GetDefaultOptions() interface{}
                          }

                            FileSigner is an interface to a signer able to sign files

                            type HashSigner

                            type HashSigner interface {
                            	SignHash(data []byte, options interface{}) (Signature, error)
                            	GetDefaultOptions() interface{}
                            }

                              HashSigner is an interface to a signer able to sign hashes

                              type RSACacheConfig

                              type RSACacheConfig struct {
                              	// NumKeys is the number of RSA keys matching the issuer size
                              	// to cache
                              	NumKeys uint64
                              
                              	// NumGenerators is the number of key generator workers to run
                              	// that populate the RSA key cache
                              	NumGenerators uint8
                              
                              	// GeneratorSleepDuration is how frequently each cache key
                              	// generator tries to add a key to the cache chan
                              	GeneratorSleepDuration time.Duration
                              
                              	// FetchTimeout is how long a consumer waits for the cache
                              	// before generating its own key
                              	FetchTimeout time.Duration
                              
                              	// StatsSampleRate is how frequently the monitor reports the
                              	// cache size and capacity
                              	StatsSampleRate time.Duration
                              }

                                RSACacheConfig is a config for the RSAKeyCache

                                type RecommendationConfig

                                type RecommendationConfig struct {
                                	// AllowedStates is a map of strings the signer is allowed to
                                	// set in the recommendations file to true indicating whether
                                	// they're allowed or not
                                	AllowedStates map[string]bool `yaml:"states,omitempty"`
                                
                                	// FilePath is the path in the XPI to save the recommendations
                                	// file
                                	FilePath string `yaml:"path,omitempty"`
                                
                                	// ValidityRelativeStart is when to set the recommendation
                                	// validity not_before relative to now
                                	ValidityRelativeStart time.Duration `yaml:"relative_start,omitempty"`
                                
                                	// ValidityDuration is when to set the recommendation validity
                                	// not_after relative to now
                                	//
                                	// i.e.
                                	//         ValidityRelativeStart    ValidityDuration
                                	//       <----------------------> <------------------->
                                	//      |                        |                     |
                                	//   not_before          now / signing TS          not_after
                                	ValidityDuration time.Duration `yaml:"duration,omitempty"`
                                }

                                  RecommendationConfig is a config for the XPI recommendation file

                                  type Signature

                                  type Signature interface {
                                  	Marshal() (signature string, err error)
                                  }

                                    Signature is an interface to a digital signature

                                    type SignedFile

                                    type SignedFile []byte

                                      SignedFile is an []bytes that contains file data

                                      type Signer

                                      type Signer interface {
                                      	Config() Configuration
                                      }

                                        Signer is an interface to a configurable issuer of digital signatures

                                        type StatefulSigner

                                        type StatefulSigner interface {
                                        	AtExit() error
                                        }

                                          StatefulSigner is an interface to an issuer of digital signatures that stores out of memory state (files, HSM or DB connections, etc.) to clean up at exit

                                          type StatsClient

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

                                            StatsClient is a helper for sending statsd stats with the relevant tags for the signer and error handling

                                            func NewStatsClient

                                            func NewStatsClient(signerConfig Configuration, stats *statsd.Client) (*StatsClient, error)

                                              NewStatsClient makes a new stats client

                                              func (*StatsClient) SendGauge

                                              func (s *StatsClient) SendGauge(name string, value int)

                                                SendGauge checks for a statsd client and when one is present sends a statsd gauge with the given name, int value cast to float64, tags for the signer, and sampling rate of 1

                                                func (*StatsClient) SendHistogram

                                                func (s *StatsClient) SendHistogram(name string, value time.Duration)

                                                  SendHistogram checks for a statsd client and when one is present sends a statsd histogram with the given name, time.Duration value converted to ms, cast to float64, tags for the signer, and sampling rate of 1

                                                  type TestFileGetter

                                                  type TestFileGetter interface {
                                                  	GetTestFile() (testfile []byte)
                                                  }

                                                    TestFileGetter returns a test file a signer will accept in its SignFile interface

                                                    Source Files

                                                    Directories

                                                    Path Synopsis