Documentation ¶
Overview ¶
Package encprim provides simple encryption primitives that are easy to use and hard to get wrong. encprim provides one tool that can be used to securely encrypt, decrypt, and generate encryption keys. The default behavior is set up in such a way that when using the library as simply as possible is as secure as possible. When needed each function will contain warnings for behavior that is not default and which may cause the output to be insecure or less secure.
Index ¶
Constants ¶
const ( AESNonceLength = 16 // the unique nonce will always be this size (128 bits). AESKeyLength = 32 // the aes key size will always be this size (256 bits). ScryptSaltLength = 16 // the scrypt salt size will always be this size (128 bits). ScryptN = 131072 // the CPU/memory cost parameter for scrypt. ScryptR = 8 // the block size parameter for scrypt. ScryptP = 1 // the parallelization parameter for scrypt. MinimumPassword = 10 // this is the minimum number of bytes accepted for key derivation. )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CipherBlock ¶
type CipherBlock struct { Bytes []byte // an arbitrary slice of bytes representing a ciphertext. Nonce [AESNonceLength]byte // the nonce that was generated and used when performing encryption. }
CipherBlock provides a structured representation of a ciphertext and it's parts.
NOTE: When encryption is performed a random nonce is generated. This must be included with the ciphertext in order for decryption to be performed successfully.
It is a good idea, if you are using a shared password/passphrase, to include the random salt that was used to generate the key as well so that the recipient/user can use the same password to generate the same key needed to perform the decryption of the ciphertext.
func NewCipherBlock ¶
func NewCipherBlock(bytes []byte, nonce []byte) (CipherBlock, error)
NewCipherBlock creates a new encprim.CipherBlock given a ciphertext and a nonce.
type Key ¶
type Key struct { Key [AESKeyLength]byte // the key used for encryption/decryption operations. Salt [ScryptSaltLength]byte // the salt used to derive the key (encryption only) }
Key provides a structured representation of an encryption/decryption key.
NOTE: NEVER REUSE A SALT FOR ENCRYPTION!
A salt must always be cryptographically random when derivation for encryption is performed otherwise it greatly reduces the security afforded by the operation. The ability to specify a salt when deriving is only provided to ease the ability to test the code predictably and should never appear in use outside of testing.
func (*Key) Decrypt ¶
func (k *Key) Decrypt(ciphertext CipherBlock) ([]byte, error)
Decrypt provides a way to decrypt an arbitrary slice of bytes given a known nonce.
The nonce provided should always be the nonce that was used to encrypt the ciphertext otherwise this function will fail to produce a plaintext and will instead return an error.
It is important that the nonce be included when distributing the ciphertext and the nonce does not need to be kept secret and can be shared in the clear.
func (*Key) Encrypt ¶
func (k *Key) Encrypt(plaintext []byte) (CipherBlock, error)
Encrypt provides a way to encrypt an arbitrary slice of bytes using a given key.
The key should be derived from the FromString function and NEVER from the RederiveKey function!
func (*Key) FromString ¶
FromString provides a way to generate a new key from a password/passphrase.
This function should only ever be used when deriving a key for encryption. To rederive a key from a known salt and a pre-shared or otherwise already known password/passphrase please use the RederiveKey method. The salt does not need to be kept secret.
func (*Key) RederiveKey ¶
RederiveKey provides a way to rederive a key from a known salt and a known password/passphrase
This function SHOULD ONLY BE USED FOR DECRYPTION as reusing a salt reduces the security of the generated key. If you are using this for encryption outside unit testing you need to stop and rethink what you are doing because I promise you that you don't want to do this. Just use a new salt for every new key **unless** you are trying to rederive a key from a known password/passphrase and a salt.