Package encryption provides support for encrypting and decrypting data and files with granular key management.

    It is assumed that the data being encrypted is archival and long lived.

    The key management scheme supports arbitrary ciphers and many keys, the intent being to easily support using different keys per file. The encryption algorithm, blocksize, HMAC are determined by the choice of key management scheme.

    The encryption interface supports both traditional block-based and AEAD APIs.

    Encrypted files are layered on top of the encoding/recordio format whereby the first record in the file is used to store a header containing the necessary metadata to decrypt the remaining records in the file. For such files a single key is used to encrypt all of the data within the file. The recordio format encrypts each record as an independent block with its own encryption metadata (eg. IV, HMAC) and hence is not suitable for use with lots of small records due to the space overhead of this metadata.

    The format of the header record is: crc32 of the marshalled Key Descriptor JSON record. JSON encoding of KeyDescriptor

    The format of each encrypted record is: Initialization Vector (IV) encrypted(HMAC(plaintext) + plaintext)



    This section is empty.


    This section is empty.


    func Register

    func Register(name string, registry KeyRegistry) error

      Register registers a new KeyRegistry using the supplied name.

      func SetRandSource

      func SetRandSource(rd io.Reader)

        SetRandSource sets the source of random numbers be used and is intended for primarily for testing purposes.


        type Decrypter

        type Decrypter interface {
        	// PlaintextSize returns the size of the decrypted plaintext
        	// that will result from decrypting the supplied ciphertext.
        	// Note that this size will include any checksums enrypted
        	// with the original plaintext.
        	PlaintextSize(ciphertext []byte) int
        	// Decrypt decrypts the ciphertext in src into plaintext stored in dst and
        	// returns slices that contain the checksum of the original plaintext
        	// and the plaintext. dst should be at least PlainTextSize() bytes big.
        	Decrypt(src, dst []byte) (sum, plaintext []byte, err error)

          Decrypter defines decryption methods.

          func NewDecrypter

          func NewDecrypter(kd KeyDescriptor) (Decrypter, error)

            NewDecrypter returns a new decrypter.

            type Encrypter

            type Encrypter interface {
            	// CipherrextSize returns the size of the ciphertext that
            	// that will result from supplied plaintext. It should be used
            	// to size the slice supplied to Encrypt.
            	CiphertextSize(plaintext []byte) int
            	// CiphertextSizeSlices returns the size of the ciphertext that
            	// will result from the supplied plaintext slices. It should be used
            	// to size the slice supplied to EncryptSlices.
            	CiphertextSizeSlices(plaintexts ...[]byte) int
            	// Encrypt encrypts the plaintext in src into ciphertext in
            	// dst. dst must be at least CiphertextSize() bytes large.
            	Encrypt(src, dst []byte) error
            	// EncryptSlices encrypts the plaintext slices as a single
            	// block. It is intended to avoid the need for an external copy
            	// to obtain a single buffer for use with Encrypt. The slices
            	// will be decrypted as a single block.
            	EncryptSlices(dst []byte, src ...[]byte) error

              Encrypter defines encryption methods.

              func NewEncrypter

              func NewEncrypter(kd KeyDescriptor) (Encrypter, error)

                NewEncrypter returns a new encrypter. The implementation it returns uses an encrypted HMAC/SHA512 checksum of the plaintext to ensure integrity. The format of a block is: Initialization Vector (IV) encrypted(HMAC(plaintext) + plaintext)

                type IV

                type IV []byte

                  IV represents the initialization vector used to encrypt a block.

                  func (IV) MarshalJSON

                  func (iv IV) MarshalJSON() ([]byte, error)

                    MarshalJSON marshals an IV as a hex encoded string.

                    func (*IV) UnmarshalJSON

                    func (iv *IV) UnmarshalJSON(data []byte) error

                      UnmarshalJSON unmarshals a hex encoded string into an IV.

                      type KeyDescriptor

                      type KeyDescriptor struct {
                      	Registry string                 `json:"registry"`
                      	ID       KeyID                  `json:"keyid"`
                      	Options  map[string]interface{} `json:"options,omitempty"`

                        KeyDescriptor represents a given key and any associated options.

                        type KeyID

                        type KeyID []byte

                          KeyID represents the ID used to identify a particular key.

                          func (KeyID) MarshalJSON

                          func (id KeyID) MarshalJSON() ([]byte, error)

                            MarshalJSON marshals a KeyID as a hex encoded string.

                            func (*KeyID) UnmarshalJSON

                            func (id *KeyID) UnmarshalJSON(data []byte) error

                              UnmarshalJSON unmarshals a hex encoded string into a KeyID.

                              type KeyRegistry

                              type KeyRegistry interface {
                              	GenerateKey() (ID []byte, err error)
                              	BlockSize() int
                              	HMACSize() int
                              	NewBlock(ID []byte, opts ...interface{}) (hmac hash.Hash, block cipher.Block, err error)
                              	NewGCM(block cipher.Block, opts ...interface{}) (aead cipher.AEAD, err error)

                                KeyRegistry represents a database of keys for a particular cipher, ie. implementations of KeyRegistry manage the keys for a particular cipher. AEAD is supported by wrapping the block ciphers provided.

                                func Lookup

                                func Lookup(name string) (KeyRegistry, error)

                                  Lookup returns the key registry, if any, named by the supplied name.