goodkey

Documentation

Index

• Variables
• type AllowedKeys
  • func LetsEncryptCPS() AllowedKeys
• type BlockedKeyCheckFunc
• type Config
• type KeyPolicy
  • func NewPolicy(config *Config, bkc BlockedKeyCheckFunc) (KeyPolicy, error)
  • func (policy *KeyPolicy) GoodKey(ctx context.Context, key crypto.PublicKey) error

Variables

var ErrBadKey = errors.New("")

ErrBadKey represents an error with a key. It is distinct from the various ways in which an ACME request can have an erroneous key (BadPublicKeyError, BadCSRError) because this library is used to check both JWS signing keys and keys in CSRs.

Types

type AllowedKeys

type AllowedKeys struct {
	// Baseline Requirements, Section 6.1.5 requires key size >= 2048 and a multiple
	// of 8 bits: https://github.com/cabforum/servercert/blob/main/docs/BR.md#615-key-sizes
	// Baseline Requirements, Section 6.1.1.3 requires that we reject any keys which
	// have a known method to easily compute their private key, such as Debian Weak
	// Keys. Our enforcement mechanism relies on enumerating all Debian Weak Keys at
	// common key sizes, so we restrict all issuance to those common key sizes.
	RSA2048 bool
	RSA3072 bool
	RSA4096 bool
	// Baseline Requirements, Section 6.1.5 requires that ECDSA keys be valid
	// points on the NIST P-256, P-384, or P-521 elliptic curves.
	ECDSAP256 bool
	ECDSAP384 bool
	ECDSAP521 bool
}

AllowedKeys is a map of six specific key algorithm and size combinations to booleans indicating whether keys of that type are considered good.

func LetsEncryptCPS

func LetsEncryptCPS() AllowedKeys

LetsEncryptCPS encodes the five key algorithms and sizes allowed by the Let's Encrypt CPS CV-SSL Subscriber Certificate Profile: RSA 2048, RSA 3076, RSA 4096, ECDSA 256 and ECDSA P384. https://github.com/letsencrypt/cp-cps/blob/main/CP-CPS.md#dv-ssl-subscriber-certificate If this is ever changed, the CP/CPS MUST be changed first.

type BlockedKeyCheckFunc

type BlockedKeyCheckFunc func(ctx context.Context, keyHash []byte) (bool, error)

BlockedKeyCheckFunc is used to pass in the sa.BlockedKey functionality to KeyPolicy, rather than storing a full sa.SQLStorageAuthority. This allows external users who don’t want to import all of boulder/sa, and makes testing significantly simpler. On success, the function returns a boolean which is true if the key is blocked.

type Config

type Config struct {
	// AllowedKeys enables or disables specific key algorithms and sizes. If
	// nil, defaults to just those keys allowed by the Let's Encrypt CPS.
	AllowedKeys *AllowedKeys
	// FermatRounds is an integer number of rounds of Fermat's factorization
	// method that should be performed to attempt to detect keys whose modulus can
	// be trivially factored because the two factors are very close to each other.
	// If this config value is empty or 0, it will default to 110 rounds.
	FermatRounds int
}

type KeyPolicy

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

KeyPolicy determines which types of key may be used with various boulder operations.

func NewPolicy

func NewPolicy(config *Config, bkc BlockedKeyCheckFunc) (KeyPolicy, error)

NewPolicy returns a key policy based on the given configuration, with sane defaults. If the config's AllowedKeys is nil, the LetsEncryptCPS AllowedKeys is used. If the configured FermatRounds is 0, Fermat Factorization defaults to attempting 110 rounds.

func (*KeyPolicy) GoodKey

func (policy *KeyPolicy) GoodKey(ctx context.Context, key crypto.PublicKey) error

GoodKey returns true if the key is acceptable for both TLS use and account key use (our requirements are the same for either one), according to basic strength and algorithm checking. GoodKey only supports pointers: *rsa.PublicKey and *ecdsa.PublicKey. It will reject non-pointer types. TODO: Support JSONWebKeys once go-jose migration is done.