simplecipher

package module
v2.0.0-alpha.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 14, 2026 License: BSD-3-Clause Imports: 13 Imported by: 0

README

simplecipher v2

[!warning] simplecipher v2 is not backward compatible with v1 (and v0). And there is no plan to provide a migration guide from v1 to v2.

GoDoc

Package simplecipher provides a simple interface for encrypting and decrypting data using AES, effortlessly.

package main

import (
	"fmt"
	"github.com/cdfmlr/simplecipher/v2"
)

func main() {
	// encrypt "plaintext" with a key "123456" (not this one I hope)
	encrypted, _ := simplecipher.SimpleCTR("123456").Encrypt("plaintext")
	fmt.Println("ciphertext:", encrypted)

	// decrypt with the same key
	decrypted, _ := simplecipher.SimpleCTR("123456").Decrypt(encrypted)
	fmt.Println("plaintext:", decrypted)
}

Features:

  • Muggle friendly and ready-to-use: wraps around the standard crypto/aes and crypto/cipher package. Don't worry if you can't read the words like "cipher mode", "iv", "nonce", etc.
  • string in -> string out: Input key, input plaintext, output ciphertext or output plaintext are all strings. Optional hex, base64 or base32 encoding for ciphertext.
  • Key derivation: Able to generate a secure key matching the required length from an arbitrary passphrase.
  • Don't panic: instead of panic directly for a lot of cryptography related errors, return them as error values so that you can handle them properly.
  • Padding and unpadding for plaintext if necessary.
  • Fully tested and Fuzz tested.

Cipher modes:

  • AEAD mode (working with string): GCM.
  • Block mode (working with string): CBC, CFB, OFB, CTR.
  • Stream mode (working with io.Reader/io.Writer): CFB, OFB, CTR.

Low-level block cipher:

  • Currently, the only supported underlying block cipher is AES (AES-128, AES-192 and AES-256).

Usage

Install:

go get github.com/cdfmlr/simplecipher/v2

Example:

package main

import (
	"fmt"
	"github.com/cdfmlr/simplecipher/v2"
)

func main() {
	// Configure a Provider with custom salt.
	sc := simplecipher.NewProvider(
		simplecipher.WithSaltFunc(func() string { return "NaCl" }),
	)

	// don't worry about the key length, simplecipher will derive a secure key from it.
	key := "123456"

	// plaintext to be encrypted, any string
	plaintext := "Hello, world!"

	// instance a cipher with the key
	cipher := sc.SimpleCTR(key)

	// encrypt with cipher
	encrypted, _ := cipher.Encrypt(plaintext)
	fmt.Println("ciphertext:", encrypted)

	// decrypt with cipher
	decrypted, _ := cipher.Decrypt(encrypted)
	fmt.Println("plaintext:", decrypted)
}

Please refer to the godoc for more examples and details.

Best practice:

  • Create a new cipher instance for each encryption (reuse a cipher instance for decryption is ok).
  • Store and pass the key securely.
  • Remember to set you own salt for key derivation. And Keep it secret and safe too if possible. (Notice: You need to use the same salt for decryption and encryption.)

APIs

Block interface:

  • Encrypt(plaintext string) (ciphertext string, err error): Encrypt a plaintext string.
  • Decrypt(ciphertext string) (plaintext string, err error): Decrypt a ciphertext string.

Stream interface:

  • EncryptStream(in io.Reader, out io.Writer) (err error): Encrypt data from in to out.
  • DecryptStream(in io.Reader, out io.Writer) (err error): Decrypt data from in to out.

Key derivation interface:

  • Bytes() []byte: Return the key in bytes. So basically, anything can be a key. And we also treat the nonce, iv, etc. as keys, to make things simple.

Implementations:

Group Method Description
simple block SimpleCBC, SimpleCFB, SimpleOFB, SimpleCTR encrypt/decrypt a string, using another string to derive the key. (AES-256)
new block NewCBC, NewCFB, NewOFB, NewCTR encrypt/decrypt a string, using your custom key, with options to control key length, iv, padding, etc.
simple stream SimpleCFBStream, SimpleOFBStream, SimpleCTRStream encrypt/decrypt data from/to an io.Reader/io.Writer, using another string to derive the key. (AES-256)
new stream NewCFBStream, NewOFBStream, NewCTRStream encrypt/decrypt data from/to an io.Reader/io.Writer, using your custom key, with options to control key length, iv, padding, etc.
simple AEAD SimpleGCM encrypt/decrypt a string with associated authenticated data, using another string to derive the key. (AES-256)
new AEAD NewGCM encrypt/decrypt a string with associated authenticated data, using your custom key, with options to control key length, iv, padding, etc.
key derivation NewKey, NewAeskey, NewNonce, NewIV, NewRandomIv generate a secure key, aes key, nonce, iv from an arbitrary passphrase, with options to control key length, salt, etc.

Which mode should I use?

Click to see the decision tree 
flowchart TD
	streamOrBlock{stream or block?}
	associatedData{associated authenticated data?}
	simpleOrCompatibleStream{simple or compatible?}
	simpleOrCompatibleAEAD{simple or compatible?}
	simpleOrCompatibleBlock{simple or compatible?}
	
	newStreams(NewCFBStream, NewOFBStream, NewCTRStream)
	simpleStreams(SimpleCFBStream, SimpleOFBStream, SimpleCTRStream)

	newBlocks(NewCBC, NewCFB, NewOFB, NewCTR)
	simpleBlocks(SimpleCBC, SimpleCFB, SimpleOFB, SimpleCTR)

	newAEADs(NewGCM)
	simpleAEADs(SimpleGCM)

	streamOrBlock--->|io.Reader in, io.Writer out|simpleOrCompatibleStream
	streamOrBlock--->|string in, string out|associatedData
	
	simpleOrCompatibleStream--->|I am a Cryptography Muggle|simpleStreams
	simpleOrCompatibleStream--->|I want to encrypt/decrypt wiht other tools|newStreams

	associatedData--->|I don't know|simpleOrCompatibleBlock
	associatedData--->|Yes|simpleOrCompatibleAEAD

	simpleOrCompatibleBlock--->|Any string as the key|simpleBlocks
	simpleOrCompatibleBlock--->|I want to encrypt/decrypt wiht other tools|newBlocks

	simpleOrCompatibleAEAD--->|Any string as the key|simpleAEADs
	simpleOrCompatibleAEAD--->|I want to encrypt/decrypt wiht other tools|newAEADs

	newBlocks--->|What's the difference?|NewCTR
	simpleBlocks--->|What's the difference?|SimpleCTR
	newStreams--->|What's the difference?|NewCTRStream
	simpleStreams--->|What's the difference?|SimpleCTRStream

What's your use case?

  • I just want to encrypt/decrypt a string: use SimpleCTR or NewCTR.
    • Plus, if you want to associate some authenticated data with the ciphertext: use SimpleGCM or NewGCM.
  • I am expecting to encrypt/decrypt a lot of data from/to an io.Reader/io.Writer: use SimpleCTRStream or NewCTRStream.

What's the difference between SimpleXXX and NewXXX?

  • I only use this package for encryption/decryption with another string as the key (or password): SimpleXXX;
  • I want to encrypt/decrypt with other tools (for example, encrypting via simplecipher, decrypting via OpenSSL), or I am happy to tweak things like iv: NewXXX.

And why CTR? what's the difference between CTR, CFB, OFB and CBC?

  • Just use CTR if you don't know what to choose. (Because I prefer this name, literally.)
  • Or learn some cryptography and choose the right one for your use case: Block cipher mode of operation.

Technical details:

  • SimpleXXX force to use AES-256, while NewXXX allows you to choose from AES-128, AES-192 and AES-256.
  • SimpleXXX does key derivation and random iv/nonce generation behind the sense. The result is not accessible (though you can always hack it out of course). So use NewXXX if you want to get the key and to use it with other tools.

License

BSD-3-Clause license. See LICENSE file for details.

Documentation

Overview

Package simplecipher wraps the standard library's crypto/cipher package.

It provides a simple interface to encrypt and decrypt strings or io.Reader/io.Writer streams using AES and choices of cipher modes.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	ErrPlaintextBlockSize  = errors.New("plaintext is not a multiple of the block size")
	ErrCipherTextTooShort  = errors.New("ciphertext too short")
	ErrCipherTextBlockSize = errors.New("ciphertext is not a multiple of the block size")
	ErrCopy                = errors.New("copy error")
	ErrNewAesCipher        = errors.New("aes.NewCipher error")
	ErrPanic               = dontpanic.ErrPanic
)

Errors

View Source 
var DefaultProvider = defaultProvider()

DefaultProvider is a ready-to-use Provider instance with default configs:

  • StringCodec: codec.Hex, encodes/decodes bytes to/from hex strings.
  • SaltFunc: a fixed salt hardcode "5f11a4921aea524b9d3cb7f2514b0724", promised to be consistent across simplecipher v2 versions. Callers MUST override this in production!
  • KeyDerivation: kdf.CheapArgon2id, a quick Argon2id KDF with Time: 1, Memory: 16*1024, Threads: 1. It typically derives a key in ~10ms.

Functions

This section is empty.

Types

type Block 

type Block interface {
	// Encrypt the given plaintext and return the ciphertext as a [Provider.StringCodec] encoded string.
	Encrypt(plainText string) (cipherText string, err error)
	// Decrypt the given ciphertext ([Provider.StringCodec] encoded) and return the plaintext.
	Decrypt(cipherText string) (plainText string, err error)
}

Block is an interface for encryption and decryption of strings.

Block implementations should recover from underlying panics and return them as errors.

Block encodes the ciphertext with [Provider.StringCodec] when Encrypting and decodes the ciphertext from a [Provider.StringCodec] string when Decrypting.

func NewCBC 

func NewCBC(key, iv Key) Block

NewCBC creates a new CBC cipher with the given key and iv using the DefaultProvider.

The iv will be prepended to the ciphertext during encryption, and the first block of the ciphertext will be treated as the IV during decryption.

It's caller's responsibility to ensure the following:

  • The key must be 16, 24, or 32 bytes long to select AES-128, AES-192, or AES-256.
  • The IV must be aes.BlockSize bytes long.
  • The plaintext must be padded to a multiple of aes.BlockSize bytes.

Use SimpleCBC if you are not familiar with these.

See also: cipher.NewCBCDecrypter, cipher.NewCBCEncrypter for low-level usage.

func NewCFB 

func NewCFB(key, iv Key) Block

NewCFB creates a new CFB cipher with the given key and iv using the DefaultProvider.

The key must be 16, 24, or 32 bytes long to select AES-128, AES-192, or AES-256. The iv must be aes.BlockSize bytes long.

The iv will be prepended to the ciphertext during encryption, and the first block of the ciphertext will be treated as the IV during decryption.

Use SimpleCFB if you are not familiar with this.

See also: cipher.NewCFBDecrypter, cipher.NewCFBEncrypter for low-level usage.

func NewCTR 

func NewCTR(key, iv Key) Block

NewCTR creates a new CTR cipher with the given key and iv using the DefaultProvider.

The key must be 16, 24, or 32 bytes long to select AES-128, AES-192, or AES-256. The iv must be aes.BlockSize bytes long.

The iv will be prepended to the ciphertext during encryption, and the first block of the ciphertext will be treated as the IV during decryption.

Use SimpleCTR if you are not familiar with this.

See also: cipher.NewCTR for low-level usage.

Example

ExampleNewCTR demonstrates how to use NewCTR to encrypt a plaintext and decrypt the ciphertext using the same key and iv via OpenSSL. 

rawKey := "my-raw-key-with-32-bytes-length-"
rawIv := "16ByteInitVector"

cipher := NewCTR(String(rawKey), String(rawIv))

encrypted, _ := cipher.Encrypt("Hello, World!")
fmt.Println("ciphertext by simplecipher:", encrypted)

decrypted, _ := cipher.Decrypt(encrypted)
fmt.Println("decrypted by simplecipher:", decrypted)

// or use openssl to decrypt the ciphertext
// echo "raw ciphertext" | openssl enc -d -aes-256-ctr -K "key in hex" -iv "iv in hex"

rawCiphertext, _ := hex.DecodeString(encrypted[32:]) // remove the iv, openssl doesn't recognize it
hexKey := hex.EncodeToString([]byte(rawKey))
hexIv := hex.EncodeToString([]byte(rawIv))

// fmt.Println("key in hex:", hexKey)
// fmt.Println("iv in hex:", hexIv)

opensslCmd := exec.Command("openssl", "enc", "-d", "-aes-256-ctr", "-K", hexKey, "-iv", hexIv)

opensslStdin, _ := opensslCmd.StdinPipe()
_, _ = opensslStdin.Write(rawCiphertext)
_ = opensslStdin.Close()

opensslDecrypted, _ := opensslCmd.CombinedOutput()
fmt.Println("decrypted by openssl:", string(opensslDecrypted))

Output:

ciphertext by simplecipher: 313642797465496e6974566563746f720c2058d6452bd8771bf706e8b0
decrypted by simplecipher: Hello, World!
decrypted by openssl: Hello, World!

func NewGCM 

func NewGCM(key, nonce, additionalData Key) Block

NewGCM creates a new GCM cipher with the given key and nonce using the DefaultProvider. It's caller's responsibility to ensure the following:

  • The key must be 16 or 32 bytes long to select AES-128 or AES-256.
  • The nonce must be 12 bytes long.

Use SimpleGCM if you are not familiar with these.

See also: cipher.NewGCM for low-level usage.

func NewOFB 

func NewOFB(key, iv Key) Block

NewOFB creates a new OFB cipher with the given key and iv using the DefaultProvider.

The key must be 16, 24, or 32 bytes long to select AES-128, AES-192, or AES-256. The iv must be aes.BlockSize bytes long.

The iv will be prepended to the ciphertext during encryption, and the first block of the ciphertext will be treated as the IV during decryption.

Use SimpleOFB if you are not familiar with this.

See also: cipher.NewOFB for low-level usage.

func SimpleCBC 

func SimpleCBC(keyPassphrase string) Block

SimpleCBC creates a new AES-256-CBC cipher with the given key using the DefaultProvider.

The keyPassphrase parameter can be any arbitrary string. It will be used to derive the real key used in the CBC mode via scrypt.

Random iv will be generated for each encryption and prepended to the ciphertext.

The plaintext is automatically padded to a multiple of aes.BlockSize bytes with PKCS7 padding.

See also: NewCBC for more control.

func SimpleCFB 

func SimpleCFB(keyPassphrase string) Block

SimpleCFB creates a new AES-256-CFB cipher with a key derived from the given keyPassphrase and a random iv prepended to the ciphertext.

See also: NewCFB for more control.

func SimpleCTR 

func SimpleCTR(keyPassphrase string) Block

SimpleCTR creates a new AES-256-CTR cipher with a key derived from the given keyPassphrase and a random iv prepended to the ciphertext.

See also: NewCTR for more control.

Example 
sc := NewProvider(
	WithSaltFunc(func() string { return "NaCl" }),
)

key := "my-secret-key"
plainText := "Hello, World!"

cipher := sc.SimpleCTR(key)

encrypted, _ := cipher.Encrypt(plainText)
// fmt.Println(encrypted)

decrypted, _ := cipher.Decrypt(encrypted)
fmt.Println(decrypted)

Output:

Hello, World!

func SimpleGCM 

func SimpleGCM(keyPassphrase, additionalPassphrase string) Block

SimpleGCM creates a new AES-256-GCM cipher from the given key and additional data using the DefaultProvider.

The keyPassphrase and additionalPassphrase parameters can be any arbitrary strings. SimpleGCM will derive the real key, nonce and additionalData used in the GCM mode from the these passphrases via DefaultProvider's KeyDerivation function.

The nonce used in this SimpleGCM implementation is randomly generated.

See also: NewGCM

Example 
sc := NewProvider(
	WithSaltFunc(func() string { return "NaCl" }),
)

key := "my-secret-key"
aad := time.Now().Format(time.DateOnly)

plainText := "Hello, World!"

cipher := sc.SimpleGCM(key, aad)

encrypted, _ := cipher.Encrypt(plainText)
// fmt.Println(encrypted)

decrypted, _ := cipher.Decrypt(encrypted)
fmt.Println(decrypted)

Output:

Hello, World!

func SimpleOFB 

func SimpleOFB(keyPassphrase string) Block

SimpleOFB creates a new AES-256-OFB cipher with a key derived from the given keyPassphrase and a random iv prepended to the ciphertext.

See also: NewOFB for more control.

type Key 

type Key interface {
	// Bytes return a byte slice of the key.
	Bytes() []byte
}

Key is an interface for AES cipher keys, ivs, and nonces.

To keep things simple, basically everything you need to encrypt/decrypt with AES, except the plaintext/ciphertext, are treated as keys in this package.

Notice different use cases of keys require different lengths. Use NewAesKey, NewNonce, or NewIv to create keys matching the requirements if you are not sure.

func Bytes 

func Bytes(b []byte) Key

Bytes is a helper function to convert a byte slice to a Key.

func NewAesKey 

func NewAesKey(passphrase string, options ...KeyGenOption) Key

NewAesKey creates a new AES key derived from the passphrase using the DefaultProvider's salt.

Aes256 and [DefaultProvider.SaltFunc] are used by default. Use WithSalt and WithLen options to customize the key derivation.

For custom salt function, use DefaultProvider.NewAesKey() or create your own Provider.

func NewIv 

func NewIv(passphrase string, options ...KeyGenOption) Key

NewIv creates a new IV with aes.BlockSize bytes using the DefaultProvider's salt.

The output key will be derived from the passphrase via Sequential Memory-Hard Functions with [DefaultProvider.SaltFunc].

For custom salt function, use DefaultProvider.NewIv() or create your own Provider.

func NewKey 

func NewKey(passphrase string, len KeyLen, salt string) Key

NewKey derives a new key in the specified length from the passphrase.

The output key will be derived from the Passphrase (with Salt) via Sequential Memory-Hard Functions (see [scrypt.Key] for details).

Any UTF-8 string can be used as an input key (including "") and Salt.

More than 32 bytes are recommended for the Passphrase. And at least 8 bytes are recommended for Salt.

Use NewAesKey, NewNonce, or NewIv for specific key types.

Example

derive a key from a passphrase, with the default provider settings. 

passphrase := "my-secret-key"
keyLen := Aes256 // 32
salt := "NaCl"

key := NewKey(passphrase, keyLen, salt)

// use the key for encryption or any other purpose
_ = key

func NewNonce 

func NewNonce(passphrase string, options ...KeyGenOption) Key

NewNonce creates a new nonce with default NonceSize using the DefaultProvider's salt.

The output key will be derived from the passphrase via Sequential Memory-Hard Functions with [DefaultProvider.SaltFunc].

For custom salt function, use DefaultProvider.NewNonce() or create your own Provider.

func NewRandomIv 

func NewRandomIv() Key

NewRandomIv creates a new random IV with aes.BlockSize bytes.

func NewRandomNonce 

func NewRandomNonce() Key

NewRandomNonce creates a new random nonce with NonceSize bytes.

func String 

func String(s string) Key

String is a helper function to convert a string to a Key.

type KeyDerivation 

type KeyDerivation = kdf.KeyDerivation

KeyDerivation is a key derivation function (KDF) interface. See kdf.KeyDerivation for details.

type KeyGenOption 

type KeyGenOption func(gen *keyGen)

KeyGenOption is a functional option to customize the KeyGen struct.

func WithLen 

func WithLen(keyLen KeyLen) KeyGenOption

WithLen sets the key length for the AES key. Available key lengths are Aes128, Aes192, and Aes256.

If an invalid key length is provided, it will default to Aes256.

func WithPassphrase 

func WithPassphrase(passphrase string) KeyGenOption

WithPassphrase sets the passphrase for the key derivation. The passphrase can be any UTF-8 string. The length of the passphrase is recommended to be >= 32 bytes for security and < 72 bytes for performance.

func WithSalt 

func WithSalt(salt string) KeyGenOption

WithSalt sets the salt for the key derivation. The salt should be a random string >= 8 bytes long to make the key derivation more secure.

type KeyLen 

type KeyLen = int

KeyLen is a type to indicate the length of the key in bytes. 

const (
	Aes128 KeyLen = 16
	Aes192 KeyLen = 24
	Aes256 KeyLen = 32
)

Available KeyLen values for AES keys are 16, 24 and 32 bytes for Aes128, Aes192, and Aes256 respectively. 

const (
	NonceSize KeyLen = 12
)

NonceSize is the default size of the nonce for AEAD ciphers.

type Provider 

type Provider struct {
	// StringCodec is the codec used to encode/decode ciphertext strings.
	// Defaults to Hex.
	StringCodec StringCodec

	// SaltFunc is a function that returns the salt used for key derivation.
	// Defaults to a fixed random string.
	SaltFunc SaltFunc

	// KeyDerivation is the key derivation function used to derive keys from passphrases.
	// Defaults to a cheap Argon2id KDF (Time: 1, Memory: 16*1024, Threads: 1).
	KeyDerivation KeyDerivation
}

Provider encapsulates the configuration for cipher operations. It groups all cipher-related configuration and provides methods to create ciphers, keys, and other cryptographic primitives.

It is highly recommended to create a Provider instance by NewProvider() with custom ProviderOption.

Be careful when constructing a literal Provider struct. The Ensure() method is recommended to be called before using such instances, to avoid potential unexpected behaviors.

func NewProvider 

func NewProvider(options ...ProviderOption) *Provider

NewProvider creates a new Provider with the given options. Available options include setting the StringCodec, SaltFunc, and KeyDerivation. Any fields not set or nil will be filled with default values (see DefaultProvider).

Example 
sc := NewProvider(
	WithSaltFunc(func() string { return "example-salt" }),
	WithStringCodec(codec.Base64Std),
	WithKeyDerivation(kdf.NewScrypt(16*1024, 8, 1)),
)

cipher := sc.SimpleCTR("example-password")
plaintext := "Hello, Example!"

encrypted, _ := cipher.Encrypt(plaintext)
decrypted, _ := cipher.Decrypt(encrypted)

fmt.Println(decrypted)

Output:

Hello, Example!

func (*Provider) Ensure 

func (p *Provider) Ensure()

Ensure fills in any unexpected nil fields with default values. This should (only) be called during Provider initialization.

func (*Provider) NewAesKey 

func (p *Provider) NewAesKey(passphrase string, options ...KeyGenOption) Key

NewAesKey creates a new AES key derived from the passphrase.

Aes256 and the provider's salt function are used by default. Use WithSalt and WithLen options to customize the key derivation.

func (*Provider) NewCBC 

func (p *Provider) NewCBC(key, iv Key) Block

NewCBC creates a new CBC cipher with the given key and iv.

The iv will be prepended to the ciphertext during encryption, and the first block of the ciphertext will be treated as the IV during decryption.

It's caller's responsibility to ensure the following:

  • The key must be 16, 24, or 32 bytes long to select AES-128, AES-192, or AES-256.
  • The IV must be aes.BlockSize bytes long.
  • The plaintext must be padded to a multiple of aes.BlockSize bytes.

Use Provider.SimpleCBC if you are not familiar with these.

See also: cipher.NewCBCDecrypter, cipher.NewCBCEncrypter for low-level usage.

func (*Provider) NewCFB 

func (p *Provider) NewCFB(key, iv Key) Block

NewCFB creates a new CFB cipher with the given key and iv.

The key must be 16, 24, or 32 bytes long to select AES-128, AES-192, or AES-256. The iv must be aes.BlockSize bytes long.

The iv will be prepended to the ciphertext during encryption, and the first block of the ciphertext will be treated as the IV during decryption.

Use Provider.SimpleCFB if you are not familiar with this.

See also: cipher.NewCFBDecrypter, cipher.NewCFBEncrypter for low-level usage.

func (*Provider) NewCFBStream 

func (p *Provider) NewCFBStream(key, iv Key) Stream

NewCFBStream creates a new CFB stream cipher with the given key and iv.

The iv will be used as the initial value for the CFB mode.

It's caller's responsibility to ensure the following:

  • The key must be 16, 24, or 32 bytes long to select AES-128, AES-192, or AES-256.
  • The IV must be aes.BlockSize bytes long.

Use Provider.SimpleCFBStream if you are not familiar with these. See also: cipher.NewCFBDecrypter, cipher.NewCFBEncrypter for low-level usage.

func (*Provider) NewCTR 

func (p *Provider) NewCTR(key, iv Key) Block

NewCTR creates a new CTR cipher with the given key and iv.

The key must be 16, 24, or 32 bytes long to select AES-128, AES-192, or AES-256. The iv must be aes.BlockSize bytes long.

The iv will be prepended to the ciphertext during encryption, and the first block of the ciphertext will be treated as the IV during decryption.

Use Provider.SimpleCTR if you are not familiar with this.

See also: cipher.NewCTR for low-level usage.

func (*Provider) NewCTRStream 

func (p *Provider) NewCTRStream(key, iv Key) Stream

NewCTRStream creates a new CTR stream cipher with the given key and iv.

The iv will be used as the initial value for the CTR mode.

It's caller's responsibility to ensure the following:

  • The key must be 16, 24, or 32 bytes long to select AES-128, AES-192, or AES-256.
  • The IV must be aes.BlockSize bytes long.

Use Provider.SimpleCTRStream if you are not familiar with these. See also: cipher.NewCTR for low-level usage.

func (*Provider) NewGCM 

func (p *Provider) NewGCM(key, nonce, additionalData Key) Block

NewGCM creates a new GCM cipher with the given key and nonce. It's caller's responsibility to ensure the following:

  • The key must be 16 or 32 bytes long to select AES-128 or AES-256.
  • The nonce must be 12 bytes long.

Use Provider.SimpleGCM if you are not familiar with these.

See also: cipher.NewGCM for low-level usage.

func (*Provider) NewIv 

func (p *Provider) NewIv(passphrase string, options ...KeyGenOption) Key

NewIv creates a new IV with aes.BlockSize bytes.

The output key will be derived from the passphrase via Sequential Memory-Hard Functions with the provider's salt function.

func (*Provider) NewKey 

func (p *Provider) NewKey(passphrase string, len KeyLen, salt string) Key

NewKey derives a new key in the specified length from the passphrase.

The output key will be derived from the Passphrase (with Salt) via Sequential Memory-Hard Functions (see [scrypt.Key] for details).

Any UTF-8 string can be used as an input key (including "") and Salt.

More than 32 bytes are recommended for the Passphrase. And at least 8 bytes are recommended for Salt.

Use Provider.NewAesKey, Provider.NewNonce, or Provider.NewIv for specific key types.

Example

derive a key from a passphrase, with custom provider settings. 

sc := NewProvider(
	WithKeyDerivation(kdf.RecommendedArgon2id()),
)

passphrase := "my-secret-key"
keyLen := Aes256 // 32
salt := "NaCl"

key := sc.NewKey(passphrase, keyLen, salt)

// use the key for encryption or any other purpose
_ = key

func (*Provider) NewNonce 

func (p *Provider) NewNonce(passphrase string, options ...KeyGenOption) Key

NewNonce creates a new nonce with default NonceSize.

The output key will be derived from the passphrase via Sequential Memory-Hard Functions with the provider's salt function.

func (*Provider) NewOFB 

func (p *Provider) NewOFB(key, iv Key) Block

NewOFB creates a new OFB cipher with the given key and iv.

The key must be 16, 24, or 32 bytes long to select AES-128, AES-192, or AES-256. The iv must be aes.BlockSize bytes long.

The iv will be prepended to the ciphertext during encryption, and the first block of the ciphertext will be treated as the IV during decryption.

Use Provider.SimpleOFB if you are not familiar with this.

See also: cipher.NewOFB for low-level usage.

func (*Provider) NewOFBStream 

func (p *Provider) NewOFBStream(key, iv Key) Stream

NewOFBStream creates a new OFB stream cipher with the given key and iv.

The iv will be used as the initial value for the OFB mode.

It's caller's responsibility to ensure the following:

  • The key must be 16, 24, or 32 bytes long to select AES-128, AES-192, or AES-256.
  • The IV must be aes.BlockSize bytes long.

Use Provider.SimpleOFBStream if you are not familiar with these. See also: cipher.NewOFB for low-level usage.

func (*Provider) NewRandomIv 

func (p *Provider) NewRandomIv() Key

NewRandomIv creates a new random IV with aes.BlockSize bytes.

It first attempts to use crypto/rand for cryptographically secure randomness. If that fails, it falls back to generating an IV using the current time and math/rand as a passphrase for key derivation.

func (*Provider) NewRandomNonce 

func (p *Provider) NewRandomNonce() Key

NewRandomNonce creates a new random nonce with default NonceSize.

The output key will be derived from the passphrase via Sequential Memory-Hard Functions with the provider's salt function.

func (*Provider) SimpleCBC 

func (p *Provider) SimpleCBC(keyPassphrase string) Block

SimpleCBC creates a new AES-256-CBC cipher with the given key.

The keyPassphrase parameter can be any arbitrary string. It will be used to derive the real key used in the CBC mode via scrypt.

Random iv will be generated for each encryption and prepended to the ciphertext.

The plaintext is automatically padded to a multiple of aes.BlockSize bytes with PKCS7 padding.

See also: Provider.NewCBC for more control.

func (*Provider) SimpleCFB 

func (p *Provider) SimpleCFB(keyPassphrase string) Block

SimpleCFB creates a new AES-256-CFB cipher with a key derived from the given keyPassphrase and a random iv prepended to the ciphertext.

See also: Provider.NewCFB for more control.

func (*Provider) SimpleCFBStream 

func (p *Provider) SimpleCFBStream(keyPassphrase string) Stream

SimpleCFBStream creates a new AES-256-CFB stream cipher from the given key and iv.

An Aes256 key for encryption/decryption will be derived from the arbitrary keyPassphrase string via scrypt.

The iv will be a random value.

See also: Provider.NewCFBStream for more control.

func (*Provider) SimpleCTR 

func (p *Provider) SimpleCTR(keyPassphrase string) Block

SimpleCTR creates a new AES-256-CTR cipher with a key derived from the given keyPassphrase and a random iv prepended to the ciphertext.

See also: Provider.NewCTR for more control.

func (*Provider) SimpleCTRStream 

func (p *Provider) SimpleCTRStream(keyPassphrase string) Stream

SimpleCTRStream creates a new AES-256-CTR stream cipher from the given key and iv.

An Aes256 key for encryption/decryption will be derived from the arbitrary keyPassphrase string via scrypt.

The iv will be a random value.

See also: Provider.NewCTRStream for more control.

func (*Provider) SimpleGCM 

func (p *Provider) SimpleGCM(keyPassphrase, additionalPassphrase string) Block

SimpleGCM creates a new AES-256-GCM cipher from the given key and additional data.

The keyPassphrase and additionalPassphrase parameters can be any arbitrary strings. SimpleGCM will derive the real key, nonce and additionalData used in the GCM mode from the these passphrases via Provider.KeyDerivation with the Provider.SaltFunc().

The nonce will be a random value.

See also: Provider.NewGCM

func (*Provider) SimpleOFB 

func (p *Provider) SimpleOFB(keyPassphrase string) Block

SimpleOFB creates a new AES-256-OFB cipher with a key derived from the given keyPassphrase and a random iv prepended to the ciphertext.

See also: Provider.NewOFB for more control.

func (*Provider) SimpleOFBStream 

func (p *Provider) SimpleOFBStream(keyPassphrase string) Stream

SimpleOFBStream creates a new AES-256-OFB stream cipher from the given key and iv.

An Aes256 key for encryption/decryption will be derived from the arbitrary keyPassphrase string via scrypt.

The iv will be a random value.

See also: Provider.NewOFBStream for more control.

type ProviderOption 

type ProviderOption func(*Provider)

func WithKeyDerivation 

func WithKeyDerivation(kdf KeyDerivation) ProviderOption

WithKeyDerivation sets the KeyDerivation function for the Provider.

func WithSaltFunc 

func WithSaltFunc(saltFunc func() string) ProviderOption

WithSaltFunc sets the SaltFunc for the Provider.

func WithStringCodec 

func WithStringCodec(codec StringCodec) ProviderOption

WithStringCodec sets the StringCodec for the Provider.

type SaltFunc 

type SaltFunc = func() string

SaltFunc is a function type that returns a salt string.

A SaltFunc should be deterministic, i.e. it MUST return the same salt string whenever it is called. (Otherwise, decryption will fail, unless you design the func/process very trickily.)

Typically, a SaltFunc is a simple wrapper around a constant string: 

func() string { return "my-fixed-salt" }

type Stream 

type Stream interface {
	// EncryptStream encrypts the given plaintext from the reader
	// and write the ciphertext to the given writer without encoding.
	EncryptStream(plainText io.Reader, cipherText io.Writer) error
	// DecryptStream decrypts the given ciphertext (not encoded)
	// and write the plaintext to the given writer.
	DecryptStream(cipherText io.Reader, plainText io.Writer) error
}

Stream is an interface for encryption and decryption of io.Reader and io.Writer.

Notice that, unlike Block, Stream does not encode the ciphertext. The cipherText output of Encrypt and the cipherText input of Decrypt are not encoded in any way (or in codec.Nop), they are just raw bytes.

func NewCFBStream 

func NewCFBStream(key, iv Key) Stream

NewCFBStream creates a new CFB stream cipher with the given key and iv using the DefaultProvider.

The iv will be used as the initial value for the CFB mode.

It's caller's responsibility to ensure the following:

  • The key must be 16, 24, or 32 bytes long to select AES-128, AES-192, or AES-256.
  • The IV must be aes.BlockSize bytes long.

Use SimpleCFBStream if you are not familiar with these. See also: cipher.NewCFBDecrypter, cipher.NewCFBEncrypter for low-level usage.

func NewCTRStream 

func NewCTRStream(key, iv Key) Stream

NewCTRStream creates a new CTR stream cipher with the given key and iv using the DefaultProvider.

The iv will be used as the initial value for the CTR mode.

It's caller's responsibility to ensure the following:

  • The key must be 16, 24, or 32 bytes long to select AES-128, AES-192, or AES-256.
  • The IV must be aes.BlockSize bytes long.

Use SimpleCTRStream if you are not familiar with these. See also: cipher.NewCTR for low-level usage.

func NewOFBStream 

func NewOFBStream(key, iv Key) Stream

NewOFBStream creates a new OFB stream cipher with the given key and iv using the DefaultProvider.

The iv will be used as the initial value for the OFB mode.

It's caller's responsibility to ensure the following:

  • The key must be 16, 24, or 32 bytes long to select AES-128, AES-192, or AES-256.
  • The IV must be aes.BlockSize bytes long.

Use SimpleOFBStream if you are not familiar with these. See also: cipher.NewOFB for low-level usage.

func SimpleCFBStream 

func SimpleCFBStream(keyPassphrase string) Stream

SimpleCFBStream creates a new AES-256-CFB stream cipher from the given key and iv using the DefaultProvider.

An Aes256 key for encryption/decryption will be derived from the arbitrary keyPassphrase string via scrypt.

The iv will be a random value.

See also: NewCFBStream for more control.

func SimpleCTRStream 

func SimpleCTRStream(keyPassphrase string) Stream

SimpleCTRStream creates a new AES-256-CTR stream cipher from the given key and iv using the DefaultProvider.

An Aes256 key for encryption/decryption will be derived from the arbitrary keyPassphrase string via scrypt.

The iv will be a random value.

See also: NewCTRStream for more control.

Example 
sc := NewProvider(
	WithSaltFunc(func() string { return "NaCl" }),
)

key := "my-secret-key"
plainText := "Hello, World!"

stream := sc.SimpleCTRStream(key)

// Encrypting
plaintextReader := bytes.NewReader([]byte(plainText))
encryptedBuffer := new(bytes.Buffer)

_ = stream.EncryptStream(plaintextReader, encryptedBuffer)

encrypted := encryptedBuffer.String()
// fmt.Println(encrypted)

// Decrypting
encryptedReader := bytes.NewReader([]byte(encrypted))
decryptedBuffer := new(bytes.Buffer)

_ = stream.DecryptStream(encryptedReader, decryptedBuffer)

decrypted := decryptedBuffer.String()

fmt.Println(decrypted)

Output:

Hello, World!

func SimpleOFBStream 

func SimpleOFBStream(keyPassphrase string) Stream

SimpleOFBStream creates a new AES-256-OFB stream cipher from the given key and iv using the DefaultProvider.

An Aes256 key for encryption/decryption will be derived from the arbitrary keyPassphrase string via scrypt.

The iv will be a random value.

See also: NewOFBStream for more control.

type StringCodec 

type StringCodec = codec.StringCodec

StringCodec is an interface that provides encoding and decoding functions for ciphertexts. See codec.StringCodec for details.

Source Files

View all Source files

Directories

Path Synopsis
Package codec defines an interface for encoding / decoding strings.
 Package codec defines an interface for encoding / decoding strings.
Package dontpanic provides utilities to recover from panics and convert them to error values.
 Package dontpanic provides utilities to recover from panics and convert them to error values.
Package kdf defines the KeyDerivation interface for key derivation functions.
 Package kdf defines the KeyDerivation interface for key derivation functions.
Package pkcs7 implements PKCS#7 padding
 Package pkcs7 implements PKCS#7 padding

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.