README
¶
Taber - NaCl at Higher Elevation
by Cathal Garvey, Copyright Oct 2015, Proudly AGPL licensed.
How do I use this?
Get thee to Taber's Godoc.
What is this?
This is the technical heavy lifting behind encryption in go-minilock, separated from the main repository to keep things tidy and make it easier to re-use for other stuff.
miniLock, a high-level file encryption system, offers an extremely user-friendly way to encrypt and decrypt things, designed for normal people, using NaCl along with some other great pieces:
- zxcvbn, a passphrase-strength checking library that ensures safe passwords and forbids the stupid ones we're all prone to using.
- blake2s, a fast and variable length cryptographic hash function.
- scrypt, a password hardening function that helps combat computers' natural advantage in brute-force-guessing passwords.
- Networking and Cryptography Library ("NaCl"), a high-level cryptographic library designed for application developers to make crypto harder to screw up.
With the exception of zxcvbn, which hasn't yet been ported to Go, this library offers the constructions used by miniLock in pure Go, built using Blake2s, Scrypt and NaCl.
What's in a name?
Taber-NaCl. You put your precious stuff in it. :)
Documentation
¶
Overview ¶
Package taber - for all your NaCL needs. A set of constructs for go-miniLock that enclose the NaCL operations and more.
Index ¶
- Constants
- Variables
- func Harden(salt, passphrase string) ([]byte, error)
- func WipeKeyArray(arr *[32]byte) error
- type DecryptInfo
- type Keys
- func (ks *Keys) Decrypt(ciphertext, nonce []byte, from *Keys) (plaintext []byte, err error)
- func (ks *Keys) EncodeID() (string, error)
- func (ks *Keys) Encrypt(plaintext, nonce []byte, to *Keys) (ciphertext []byte, err error)
- func (ks *Keys) HasPrivate() bool
- func (ks *Keys) HasPublic() bool
- func (ks *Keys) PrivateArray() *[32]byte
- func (ks *Keys) PublicArray() *[32]byte
- func (ks *Keys) PublicOnly() *Keys
- func (ks *Keys) Wipe() (err error)
Constants ¶
const ( // ConstChunkSize is the maximum length of chunks. ConstChunkSize = 1048576 // ConstFilenameBlockLength is the length of the block that contains the filename, // also the first block in the raw ciphertext. ConstFilenameBlockLength = (256 + 16 + 4) // ConstBlockLength is the length of the encrypted chunks. ConstBlockLength = ConstChunkSize + 16 + 4 )
Variables ¶
var ( // ErrBadKeyLength is returned when encryption key must be 32 bytes long. ErrBadKeyLength = errors.New("Encryption key must be 32 bytes long") // ErrBadBaseNonceLength is returned when length of base_nonce must be 16. ErrBadBaseNonceLength = errors.New("Length of base_nonce must be 16") // ErrBadLengthPrefix is returned when block length prefixes indicate a length longer than the remaining ciphertext. ErrBadLengthPrefix = errors.New("Block length prefixes indicate a length longer than the remaining ciphertext") // ErrBadPrefix is returned when chunk length prefix is longer than 4 bytes, would clobber ciphertext. ErrBadPrefix = errors.New("Chunk length prefix is longer than 4 bytes, would clobber ciphertext") // ErrBadBoxAuth is returned when authentication of box failed on opening. ErrBadBoxAuth = errors.New("Authentication of box failed on opening") // ErrBadBoxDecryptVars is returned when key or Nonce is not correct length to attempt decryption. ErrBadBoxDecryptVars = errors.New("Key or Nonce is not correct length to attempt decryption") // ErrBoxDecryptionEOP is returned when declared length of chunk would write past end of plaintext slice!. ErrBoxDecryptionEOP = errors.New("Declared length of chunk would write past end of plaintext slice!") // ErrBoxDecryptionEOS is returned when chunk length is longer than expected slot in plaintext slice. ErrBoxDecryptionEOS = errors.New("Chunk length is longer than expected slot in plaintext slice") // ErrFilenameTooLong is returned when filename cannot be longer than 256 bytes. ErrFilenameTooLong = errors.New("Filename cannot be longer than 256 bytes") // ErrNilPlaintext is returned when asked to encrypt empty plaintext. ErrNilPlaintext = errors.New("Asked to encrypt empty plaintext") )
var ( // ErrChecksumFail is returned when generating checksum value failed. ErrChecksumFail = errors.New("Generating checksum value failed") // ErrInsufficientEntropy is returned when got insufficient random bytes from RNG. ErrInsufficientEntropy = errors.New("Got insufficient random bytes from RNG") // ErrInvalidIDLength is returned when provided public ID was not expected length (33 bytes when decoded). ErrInvalidIDLength = errors.New("Provided public ID was not expected length (33 bytes when decoded)") // ErrInvalidIDChecksum is returned when provided public ID had an invalid checksum. ErrInvalidIDChecksum = errors.New("Provided public ID had an invalid checksum") // ErrPrivateKeyOpOnly is returned when cannot conduct specified operation using a public-only keypair. ErrPrivateKeyOpOnly = errors.New("Cannot conduct specified operation using a public-only keypair") // ErrBadNonceLength is returned when nonce length must be 24 length. ErrBadNonceLength = errors.New("Nonce length must be 24 length") // ErrDecryptionAuthFail is returned when authentication of decryption using keys failed. ErrDecryptionAuthFail = errors.New("Authentication of decryption using keys failed") )
Functions ¶
func WipeKeyArray ¶
WipeKeyArray fills a 32-byte array such as used for key material with random bytes. It is intended for use with defer to wipe temporary arrays used to contain key material.
Types ¶
type DecryptInfo ¶
type DecryptInfo struct {
// Decryption key (32 bytes) and Nonce (24 bytes) required to decrypt.
Key, BaseNonce []byte
}
DecryptInfo is a structured object returned by Encrypt to go with ciphertexts, which provides a method for Decrypting ciphertexts. Can easily be constructed from raw data, passed around, serialised, etcetera.
func Encrypt ¶
func Encrypt(filename string, file_data []byte) (DI *DecryptInfo, ciphertext []byte, err error)
Generates random key/nonce, encrypts the data with it, and returns a DecryptInfo object for storage, serialisation or deconstruction, along with the ciphertext. According to the miniLock encryption protocol, the filename is encrypted in the first block.
func NewDecryptInfo ¶
func NewDecryptInfo() (*DecryptInfo, error)
NewDecryptInfo returns a prepared DecryptInfo with a new Symmetric Key and BaseNonce.
func (*DecryptInfo) Decrypt ¶
func (di *DecryptInfo) Decrypt(ciphertext []byte) (filename string, plaintext []byte, err error)
Decrypt uses enclosed encryption vars to decrypt and authenticate a file.
func (*DecryptInfo) Encrypt ¶
func (self *DecryptInfo) Encrypt(filename string, file_data []byte) (ciphertext []byte, err error)
Encrypt symmetrically using this DecryptInfo object.
func (*DecryptInfo) Validate ¶
func (di *DecryptInfo) Validate() bool
Validate returns simply that the Key and BaseNonce look OK. It's not very clever, but it helps prevent accidental attempts to encrypt with a blank DecryptInfo created accidentally with new(DecryptInfo) or DecryptInfo{}.
type Keys ¶
type Keys struct {
// May be empty for pubkey-only keypairs.
Private []byte
// Should always be full.
Public []byte
}
Keys in Taber NaCl are stored simply as two byte slices with handy methods attached. They can be generated determnistically from passphrase and email, according to the method used by miniLock.io, or randomly generated. They can emit an "ID" as a string, which is the base58 representation of the public Key with a one-byte checksum, and can be imported from same. They have a "Wipe" method which should always be used when finished with the keys to protect keys from compromise.
func FromEmailAndPassphrase ¶
FromEmailAndPassphrase generates keys using a passphrase with a GUID as salt value. The GUID is usually expected to be an email, but it is not normalised here, so be aware of the various ways one email may be represented; capitalisation, "+" extensions, etcetera will all result in different outcomes here. The passphrase is first hashed using 32-byte blake2s and is then passed through scrypt using the email as salt. 32 bytes of scrypt output are used to create a private nacl.box key and a keys object.
func FromID ¶
FromID creates a Keys struct from a checksummed ID string. The last byte is expected to be the blake2s checksum.
func (*Keys) EncodeID ¶
EncodeID generate base58-encoded pubkey + 1-byte blake2s checksum as a string.
func (*Keys) Encrypt ¶
Encrypt uses key material to encrypt plaintext using the NaCl SecretBox construct.
func (*Keys) HasPrivate ¶
HasPrivate returns whether the private component of the key appears to be a valid taber/nacl key.
func (*Keys) HasPublic ¶
HasPublic returns whether the public component of the key appears to be a valid taber/nacl pubkey.
func (*Keys) PrivateArray ¶
PrivateArray returns a copy of the private key slice in an array. This is useful when some operations call for an array and not a slice. Please be aware that the returned array is *not* the underlying array of the private slice, it is a copy! This means that the Keys.Wipe() operation will not clean up this copy, so it should be sanitised separately if security of that grade is called for.
func (*Keys) PublicArray ¶
PublicArray returns a copy of the public key in an array rather than a slice. Some nacl functions require arrays, not slices.
func (*Keys) PublicOnly ¶
PublicOnly returns a Keys object containing only the public key of this object.
Source Files