jceks

README

JCEKS

Package jceks reads and writes JCEKS (Java Cryptogaphy Extension Key Store) files containing private keys and certificates. This module implements only a fraction of the JCEKS cryptographic protocols. In particular, it implements the SHA1 signature verification of the keystore and the PBEWithMD5AndDES3CBC cipher for encrypting private keys.

Documentation

Overview

Package jceks parses JCEKS (Java Cryptogaphy Extension Key Store) files and extracts keys and certificates. This module only implements a fraction of the JCEKS cryptographic protocols. In particular, it implements the SHA1 signature verification of the key store and the PBEWithMD5AndDES3CBC cipher for encrypting private keys.

Index

• Variables
• type Encoder
  • func (e *Encoder) AddKeyStore(ks *KeyStore) error
  • func (e *Encoder) AddPrivateKeyPKCS1(alias string, timestamp time.Time, keyPKCS1 []byte, certificatesDER [][]byte, ...) error
  • func (e *Encoder) AddTrustedCertificate(alias string, timestamp time.Time, certDER []byte) error
  • func (e *Encoder) SetIntegrityPassword(password string) error
  • func (e *Encoder) SetProhibitDuplicateAliases(prohibit bool)
  • func (e *Encoder) WriteTo(w io.Writer) (n int64, err error)
• type KeyStore
  • func LoadFromFile(filename string, password []byte) (*KeyStore, error)
  • func LoadFromReader(reader io.Reader, password []byte) (*KeyStore, error)
  • func (ks *KeyStore) GetCert(alias string) (*x509.Certificate, error)
  • func (ks *KeyStore) GetPrivateKeyAndCerts(alias string, password []byte) (key crypto.PrivateKey, certs []*x509.Certificate, err error)
  • func (ks *KeyStore) ListCerts() []string
  • func (ks *KeyStore) ListPrivateKeys() []string
  • func (ks *KeyStore) Parse(r io.Reader, password []byte) error
  • func (ks *KeyStore) ParseWithOptions(r io.Reader, password []byte, options ...ParseOption) error
  • func (ks *KeyStore) String() string
• type ParseOption
  • func WithMaxCertificateBytes(maxBytes uint) ParseOption
  • func WithMaxPrivateKeyBytes(maxBytes uint) ParseOption
• type PrivateKeyCipher
  • func PBEWithMD5AndDES3CBC(password []byte, rnd io.Reader, iterations int) (PrivateKeyCipher, error)

Variables

var (
	ErrInvalidCiphertext            = errors.New("invalid ciphertext")
	ErrInvalidJCEKSData             = errors.New("invalid JCEKS data")
	ErrJCEKSDataTooLarge            = errors.New("JCEKS data too large")
	ErrUnsupportedJCEKSData         = errors.New("unsupported JCEKS data")
	ErrIntegrityProtectionViolation = errors.New("integrity protection violation")
	ErrDecryptionFailed             = errors.New("decryption failed with the given password")
)

var (
	ErrNoIntegrityPassword        = errors.New("no integrity password was set")
	ErrInvalidString              = errors.New("string cannot be expressed in JCEKS format")
	ErrInvalidKeyProtectionParams = errors.New("invalid key protection parameters")
	ErrKeyProtectionFailed        = errors.New("key protection failed")
	ErrInvalidCertificates        = errors.New("invalid certificates")
	ErrTooManyEntries             = errors.New("too many entries")
	ErrDuplicateAlias             = errors.New("duplicate alias")
)

var (
	ErrInvalidPassword = errors.New("password is unsupported by JCEKS format")
)

Types

type Encoder

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

Encoder collects key material and then writes it in JCEKS format when WriteTo is called. The zero value of an Encoder is ready to use, but an integrity password must be set by calling SetIntegrityPassword before WriteTo can succeed.

func (*Encoder) AddKeyStore

func (e *Encoder) AddKeyStore(ks *KeyStore) error

AddKeyStore adds the trusted certificates and private keys from an existing keystore to the Encoder. The existing keystore's integrity password is ignored. Existing private keys are added to the Encoder without decrypting them, so no private key passwords are needed, but any existing problems with the private keys will be preserved.

func (*Encoder) AddPrivateKeyPKCS1

func (e *Encoder) AddPrivateKeyPKCS1(alias string, timestamp time.Time,
	keyPKCS1 []byte, certificatesDER [][]byte, cipher PrivateKeyCipher) error

AddPrivateKeyPKCS1 adds a private key and an associated certificate chain to the keystore. The method uses the given PrivateKeyCipher to encrypt the key for storage. The private key must be provided in PKCS#1 private key DER form, and the certificates must be provided in X.509 DER form.

func (*Encoder) AddTrustedCertificate

func (e *Encoder) AddTrustedCertificate(alias string, timestamp time.Time, certDER []byte) error

AddTrustedCertificate adds a trusted certificate to the keystore. The certificate is not associated with a private key and receives no confidentiality protection. Storing a certificate in the keystore provides a verifiable record of trust if the keystore's integrity protection is secure. The certificate must be provided in X.509 DER form.

func (*Encoder) SetIntegrityPassword

func (e *Encoder) SetIntegrityPassword(password string) error

SetIntegrityPassword sets a password that used to verify the integrity of the keystore as a whole. The metadata in the keystore can be read without providing the integrity password, but providing it may help to detect modifications by processes that do not know the password. A password must be set before the keystore can be written. Password runes must be from the basic multilingual plane.

func (*Encoder) SetProhibitDuplicateAliases

func (e *Encoder) SetProhibitDuplicateAliases(prohibit bool)

SetProhibitDuplicateAliases controls whether adding new entries with duplicate aliases is allowed. When prohibit is false (the default), newly written aliases overwrite old entries with the same alias. This matches the behavior of readers. As an optimization, the overwritten entries will not be written to the output at all. When prohibit is true, attempting to add an entry with a duplicate alias returns an error that is ErrDuplicateAlias. Calling this function does not change the behavior with respect to previous calls (e.g., setting prohibit to true does not undo any previous overwrites).

func (*Encoder) WriteTo

func (e *Encoder) WriteTo(w io.Writer) (n int64, err error)

WriteTo writes a JCEKS file to the given io.Writer. The keystore contains the key material that has been added to the Encoder in previous calls.

type KeyStore

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

KeyStore represents the contents of a parsed JCEKS keystore. It can contain a variety of entries, each identified by a unique alias string. Currently, we only support trusted certificate and private key entries. The zero value represents an empty keystore that is ready to use, but most callers should immediately call Parse, ParseWithOptions, or create a KeyStore using LoadFromFile or LoadFromReader.

func LoadFromFile

func LoadFromFile(filename string, password []byte) (*KeyStore, error)

LoadFromFile loads the key store from the specified file.

func LoadFromReader

func LoadFromReader(reader io.Reader, password []byte) (*KeyStore, error)

LoadFromReader loads the key store from the specified file.

func (*KeyStore) GetCert

func (ks *KeyStore) GetCert(alias string) (*x509.Certificate, error)

GetCert retrieves the specified certificate. Returns nil if the certificate does not exist or alias points to a non-certificate entry.

func (*KeyStore) GetPrivateKeyAndCerts

func (ks *KeyStore) GetPrivateKeyAndCerts(alias string, password []byte) (
	key crypto.PrivateKey, certs []*x509.Certificate, err error)

GetPrivateKeyAndCerts retrieves the specified private key. Returns nil if the private key does not exist or alias points to a non-private key entry.

func (*KeyStore) ListCerts

func (ks *KeyStore) ListCerts() []string

ListCerts lists the names of the certs stored in the key store.

func (*KeyStore) ListPrivateKeys

func (ks *KeyStore) ListPrivateKeys() []string

ListPrivateKeys lists the names of the private keys stored in the key store.

func (*KeyStore) Parse

func (ks *KeyStore) Parse(r io.Reader, password []byte) error

Parse parses the key store from the specified reader using default settings. It is equivalent to calling ParseWithOptions without any options.

func (*KeyStore) ParseWithOptions

func (ks *KeyStore) ParseWithOptions(r io.Reader, password []byte, options ...ParseOption) error

ParseWithOptions parses the key store from the specified reader.

func (*KeyStore) String

func (ks *KeyStore) String() string

type ParseOption

type ParseOption interface {
	// contains filtered or unexported methods
}

ParseOption modifies the behavior of KeyStore.ParseWithOptions.

func WithMaxCertificateBytes

func WithMaxCertificateBytes(maxBytes uint) ParseOption

WithMaxCertificateBytes sets the maximum size of certificates contained in the JCEKS file in bytes. This limit applies to the DER encoding of the certificates. When maxBytes is zero or the option is not provided, the parser uses an unspecified default that is suitable for most certificates. The default is not part of the API and may change in future minor release versions.

func WithMaxPrivateKeyBytes

func WithMaxPrivateKeyBytes(maxBytes uint) ParseOption

WithMaxPrivateKeyBytes sets the maximum size of private keys contained in the JCEKS file in bytes. This limit applies to the encrypted, encoded private key data, which has a format that varies by key type. Certificates attached to the private key individually adhere to the certificate size limit, and are unaffected by this option. When maxBytes is zero or the option is not provided, the parser uses an unspecified default that is suitable for most private keys. The default is not part of the API and may change in future minor release versions.

type PrivateKeyCipher

type PrivateKeyCipher interface {
	// contains filtered or unexported methods
}

PrivateKeyCipher represents an encryption method that can protect the confidentiality of private keys in a JCEKS file.

func PBEWithMD5AndDES3CBC

func PBEWithMD5AndDES3CBC(password []byte, rnd io.Reader, iterations int) (PrivateKeyCipher, error)

PBEWithMD5AndDES3CBC is a PrivateKeyCipher that encrypts a private key using 3DES in CBC mode with PKCS#5 padding, using a key and IV derived from the password using several iterations of MD5. This cipher supports only RSA keys.