README
¶
crypgo 1.2.0
A dead simple Go library that encrypts, decrypts, and optionally compresses strings to strings.
Algorithms used:
- SCrypt to generate keys from passwords (N=1024, R=8, P=1);
- XChaCha20Poly1305 to encrypt and ensure integrity (AEAD);
- ZStandard to compress;
- Base64 to encode bytes into string.
Compression is applied only if it reduces the size of the message.
Documentation
Import
go get github.com/proofrock/crypgo
Usage
Given a password and a plaintext, we want to encrypt and decrypt them:
password := "hello"
plaintext := "world"
cyphertext, err := crypgo.Encrypt(password, plaintext)
// or cyphertext, err := crypgo.CompressAndEncrypt(password, plaintext, 19)
if err != nil {
// ...
}
plaintext2, err := crypgo.Decrypt(password, cyphertext)
if err != nil {
// ...
}
assert(plaintext == plaintext2)
The third argument for CompressAndEncrypt is the compression level for zstd, values are 1 to 19 (inclusive).
Byte mode
Each method also has a byte variant (same name, suffixed by Bytes) where the plaintext is a byte array instead of a
string.
Different Base64 encodings
The method SetVariant allows to setup a Base64 variant, as defined by Go. For example, to use a URL-safe Base64 encoding, just for the method, code can be:
SetVariant(base64.URLEncoding)
defer SetVariant(base64.StdEncoding)
Notes
cyphertext will be Base64-encoded, and includes a checksum, the random bytes for the salt and IV (the same random bytes are used for Scrypt's salt and for XChaCha's nonce), and the encrypted/compressed plaintext, of course. Expect it to be longer than the plaintext, if compression is not applied.
Changelog
v1.2.0
- migration to klauspost/compress, which doesn't require CGO
- added more tests
Documentation
¶
Index ¶
- func CompressAndEncrypt(password string, plainText string, zLevel int) (string, error)
- func CompressAndEncryptBytes(password string, plainText []byte, zLevel int) (string, error)
- func Decrypt(password string, base64CipherText string) (string, error)
- func DecryptBytes(password string, base64CipherText string) ([]byte, error)
- func Encrypt(password string, plainText string) (string, error)
- func EncryptBytes(password string, plainText []byte) (string, error)
- func SetVariant(variant *base64.Encoding)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CompressAndEncrypt ¶ added in v0.2.1
This function receives a password and a plain text (in string form), and a level for compression (from 1 to 19) and produces a string with their encryption, compressing the plaintext if possible. Returns it, or an eventual error, and closes all related resources.
More in detail:
- generates a key derived from the password, using SCrypt;
- converts the plain text to a byte array;
- compresses this array using ZStd and the given compression level;
- if the data aren't compressible, keeps the uncompressed data;
- encrypts the data with the key using XChaCha20-Poly1305, with an authentication tag.
The output string is the output data, Base64-encoded. It contains:
- an header with the format version and information on whether data were encrypted or not;
- an array of random bytes, used as the Salt for SCrypt and IV for XChaCha;
- encrypted data;
- an authentication tag, part of the output of XChaCha20-Poly1305, used to verify the integrity when decrypting.
func CompressAndEncryptBytes ¶ added in v1.1.0
This function receives a password, a byte array, and a level for compression (from 1 to 19) and produces a string with their encryption, compressing the byte array if possible. Returns it, or an eventual error, and closes all related resources.
More in detail:
- generates a key derived from the password, using SCrypt;
- compresses the byte array using ZStd and the given compression level;
- if the data aren't compressible, keeps the uncompressed data;
- encrypts the data with the key using XChaCha20-Poly1305, with an authentication tag.
The output string is the output data, Base64-encoded. It contains:
- an header with the format version and information on whether data were encrypted or not;
- an array of random bytes, used as the Salt for SCrypt and IV for XChaCha;
- encrypted data;
- an authentication tag, part of the output of XChaCha20-Poly1305, used to verify the integrity when decrypting.
func Decrypt ¶ added in v0.2.1
This function receives a password and a cypher text (as produced by one of the Encrypt* methods) and decodes the original plaintext (if the password is the one used for encryption).
It will return it or an eventual error, and closes all related resources. XChaCha20-Poly1305's authentication tag is used to detect any decryption error. It also transparently decompress data, if needed.
func DecryptBytes ¶ added in v1.1.0
This function receives a password and a cypher text (as produced by one of the *EncryptBytes methods) and decodes the original plaintext (if the password is the one used for encryption).
It will return it or an eventual error, and closes all related resources. XChaCha20-Poly1305's authentication tag is used to detect any decryption error. It also transparently decompress data, if needed.
func Encrypt ¶ added in v0.2.1
This function receives a password and a plain text (in string form) and produces a string with their encryption. Returns it, or an eventual error, and closes all related resources.
More in detail:
- generates a key derived from the password, using SCrypt;
- converts the plain text to a byte array;
- encrypts the data with the key using XChaCha20-Poly1305, with an authentication tag.
No compression is performed.
The output string is the output data, Base64-encoded. It contains:
- an header with the format version and information on whether data were encrypted or not;
- an array of random bytes, used as the Salt for SCrypt and IV for XChaCha;
- encrypted data;
- an authentication tag, part of the output of XChaCha20-Poly1305, used to verify the integrity when decrypting.
func EncryptBytes ¶ added in v1.1.0
This function receives a password and a a byte array and produces a string with their encryption. Returns it, or an eventual error, and closes all related resources.
More in detail:
- generates a key derived from the password, using SCrypt;
- encrypts the data with the key using XChaCha20-Poly1305, with an authentication tag.
No compression is performed.
The output string is the output data, Base64-encoded. It contains:
- an header with the format version and information on whether data were encrypted or not;
- an array of random bytes, used as the Salt for SCrypt and IV for XChaCha;
- encrypted data;
- an authentication tag, part of the output of XChaCha20-Poly1305, used to verify the integrity when decrypting.
func SetVariant ¶ added in v1.1.0
Sets a Base64 variant, for example base64.URLEncoding for URL_safe encoding.
Types ¶
This section is empty.
Source Files