README
¶
Secure (almost)
Secure provides a convenient String and Int types that are encrypted with the AES-256 with GCM upon Marshalling/Unmarshalling to JSON.
It uses the standard Go runtime encryption.
Do not use the provided "salt" for anything other than testing - it may change from version to version to encourage to use your own salt.
It is strongly encouraged to set your own salt with SetSalt() before using the encryption functions of the package.
Documentation
¶
Overview ¶
Package secure provides simple convenience encryption and decryption functions.
It should not be used to encrypt critical information in open source projects, where the salt might be known to attaker.
It uses the standard Go runtime AES-256 block cipher with GCM.
Encryption key is a 256-bit value (32 bytes).
The default "Salt" is a fixed 256 byte array of pseudo-random values, taken from /dev/urandom.
Then additional data, nonce and ciphertext are packed into the following sequence of bytes:
|_|__...__|_________|__...__| ^ ^ ^ ^ | | | +- ciphertext, n bytes. | | +---------- nonce, (nonceSz bytes) | +------------------- additinal data, m bytes, (maxDataSz bytes), +------------------------ additional data length value (adlSz bytes).
After this, packed byte sequence is armoured with base64 and the signature prefix added to it to distinct it from the plain text.
Index ¶
- Variables
- func Decrypt(s string) (string, error)
- func DecryptWithPassphrase(s string, passphrase []byte) (string, error)
- func DeriveKey(pass []byte, keySz int) ([]byte, error)
- func Encrypt(plaintext string) (string, error)
- func EncryptWithPassphrase(plaintext string, passphrase []byte) (string, error)
- func IsDecipherError(err error) bool
- func NewReader(r io.Reader, iv [aes.BlockSize]byte) (*cipher.StreamReader, error)
- func NewReaderWithKey(r io.Reader, key []byte, iv [aes.BlockSize]byte) (*cipher.StreamReader, error)
- func NewWriter(w io.Writer, iv [aes.BlockSize]byte) (*cipher.StreamWriter, error)
- func NewWriterWithKey(w io.Writer, key []byte, iv [aes.BlockSize]byte) (*cipher.StreamWriter, error)
- func SetEncoding(enc *base64.Encoding)
- func SetGlobalKey(k []byte) error
- func SetPassphrase(b []byte) error
- func SetSalt(sa []byte)
- func SetSignature(s string)
- type CipherError
- type CorruptError
- type Int
- type String
Constants ¶
This section is empty.
Variables ¶
var ( ErrNotEncrypted = errors.New("string not encrypted") ErrNoEncryptionKey = errors.New("no encryption gKey") ErrDataOverflow = errors.New("additional data overflow") ErrInvalidKeySz = errors.New("invalid key size, len(key)%8!=0") )
var (
// DeriveIter is the number of iterations used to derive the key.
DeriveIter = 4096
)
Functions ¶
func Decrypt ¶
Decrypt attempts to decrypt the string and return the password. In case s is not an encrypted string, ErrNotEncrypted returned along with original string.
func DecryptWithPassphrase ¶
DecryptWithPassphrase attempts to descrypt string with the provided passphrase.
func DeriveKey ¶ added in v0.0.3
DeriveKey interpolates the passphrase value to the gKey size and xors it with salt.
func Encrypt ¶
Encrypt encrypts the plain text password to use in the configuration file with the gKey generated by KeyFn.
func EncryptWithPassphrase ¶
EncryptWithPassphrase encrypts plaintext with the provided passphrase.
func IsDecipherError ¶
IsDecipherError returns true if there was a decryption error or corrupt data error and false if it's a different kind of error.
func NewReader ¶ added in v0.0.3
NewWriter returns a StreamReader, initialised with the global package key, and the provided initialisation vector. Key can be set with SetKey.
func NewReaderWithKey ¶ added in v0.0.3
func NewReaderWithKey(r io.Reader, key []byte, iv [aes.BlockSize]byte) (*cipher.StreamReader, error)
NewReaderWithKey returns a new StreamReader initialised with key and an initialisation vector.
func NewWriter ¶ added in v0.0.3
NewWriter returns a StreamWriter, initialised with the global package key, and the provided initialisation vector. Key can be set with SetKey.
func NewWriterWithKey ¶ added in v0.0.3
func NewWriterWithKey(w io.Writer, key []byte, iv [aes.BlockSize]byte) (*cipher.StreamWriter, error)
NewWriterWithKey returns a new StreamWriter initialised with key and an initialisation vector.
func SetEncoding ¶ added in v0.0.4
SetEncoding allows to set the package-wide encoding. Encoding is used for armoring the ciphertext.
func SetGlobalKey ¶ added in v0.0.3
SetGlobalKey sets the global package Key, it doesn't check for key size.
func SetPassphrase ¶
SetPassphrase allows to set the global passphrase, from which the key is derived.
func SetSalt ¶
func SetSalt(sa []byte)
SetSalt allows to set package-wide salt that will be used with every call. Salt should be a random set of bytes, but should remain the same across the calls and application restarts, so it should be generated in some deterministic way. It would not be possible to decrypt cipher text with different salt. It is recommended to use at least 8 bytes of salt.
IT IS STRONGLY ADVISED TO USE YOUR OWN SALT.
func SetSignature ¶
func SetSignature(s string)
SetSignature allows to set package-wide signature, that is used to identify encrypted strings.
Types ¶
type CipherError ¶
type CipherError struct {
Err error
}
CipherError indicates that there was an error during decrypting of ciphertext.
func (*CipherError) Error ¶
func (e *CipherError) Error() string
func (*CipherError) Is ¶
func (e *CipherError) Is(target error) bool
func (*CipherError) Unwrap ¶
func (e *CipherError) Unwrap() error
type CorruptError ¶
type CorruptError struct {
Value []byte
}
func (*CorruptError) Error ¶
func (e *CorruptError) Error() string
func (*CorruptError) Is ¶
func (e *CorruptError) Is(target error) bool
type Int ¶
type Int int
Int is an encrypted integer.
Source Files