tokencrypt

README

tokencrypt (3ncr.org)

3ncr.org is a standard for string encryption/decryption (algorithms + storage format). Originally it was intended for encryption tokens in configuration files.

3ncr.org v1 uses modern cryptographic primitives (SHA3-256, AES-256-GCM) and is fairly simple:

    header + base64(iv + data + tag) 

Encrypted data looks like this 3ncr.org/1#pHRufQld0SajqjHx+FmLMcORfNQi1d674ziOPpG52hqW5+0zfJD91hjXsBsvULVtB017mEghGy3Ohj+GgQY5MQ

This is a golang implementation.

Usage

Pick a constructor based on the kind of secret you have:

Recommended: Argon2id (low-entropy secrets)

For passwords or passphrases, use NewArgon2idTokenCrypt. It uses the parameters recommended by the 3ncr.org v1 spec: m=19456 KiB, t=2, p=1. The salt must be at least 16 bytes.

tokenCrypt, err := tokencrypt.NewArgon2idTokenCrypt(secret, salt)

Recommended: raw 32-byte key (high-entropy secrets)

If you already have a 32-byte AES-256 key (random key, API token hashed to 32 bytes via SHA3-256, etc.), skip the KDF and pass it in directly.

key := make([]byte, 32)
if _, err := rand.Read(key); err != nil { /* ... */ }     // or: load from env / secret store
tokenCrypt, err := tokencrypt.NewRawTokenCrypt(key)

Legacy: PBKDF2-SHA3 constructor

The original (secret, salt, iterations) constructor is kept for backward compatibility with data encrypted by earlier versions. It is deprecated — prefer NewArgon2idTokenCrypt or NewRawTokenCrypt for new code.

tokenCrypt, err := tokencrypt.NewTokenCrypt(secret, salt, 1000)

secret and salt are encryption inputs (technically one of them is the key, the other is the salt, but you need to store them both somewhere, preferably in different places).

You can store them in any preferred places: environment variables, files, shared memory, derived from hardware serial numbers or MAC addresses. Be creative.

Encrypt / decrypt

After you created an instance, you can just use Encrypt3ncr and DecryptIf3ncr methods:

token := "08019215-B205-4416-B2FB-132962F9952F"; // your secret you want to encrypt 
encryptedSecretToken, _ := tokenCrypt.Encrypt3ncr(token);
// now encryptedSecretToken == "3ncr.org/1#pHRufQld0SajqjHx+FmLMcORfNQi1d674ziOPpG52hqW5+0zfJD91hjXsBsvULVtB017mEghGy3Ohj+GgQY5MQ"

// ... some time later in another context ...  

decryptedSecretToken, _ = tokenCrypt.DecryptIf3ncr(encryptedSecretToken); 
// now decryptedSecretToken == "08019215-B205-4416-B2FB-132962F9952F";

Method DecryptIf3ncr returns the same string if supplied argument does not start with 3ncr.org value. It is safe to pass through it all values from your configuration file.

Command line utility

tokencrypt-cmd is an interactive command-line utility that does encryption/decryption

Documentation

Index

• type EncToken
  • func NewArgon2idTokenCrypt(secret []byte, salt []byte) (*EncToken, error)
  • func NewRawTokenCrypt(key []byte) (*EncToken, error)
  • func NewTokenCrypt(secret []byte, salt []byte, iter int) (*EncToken, error)
  • func (c *EncToken) DecryptIf3ncr(source string) (string, error)
  • func (c *EncToken) Encrypt3ncr(source string) (string, error)

Types

type EncToken

type EncToken struct {
	// contains filtered or unexported fields
}

func NewArgon2idTokenCrypt

func NewArgon2idTokenCrypt(secret []byte, salt []byte) (*EncToken, error)

NewArgon2idTokenCrypt returns a new 3ncr.org encrypter / decrypter whose AES-256 key is derived from secret and salt using Argon2id with the parameters recommended by the 3ncr.org v1 spec for low-entropy secrets (m=19456 KiB, t=2, p=1). salt must be at least 16 bytes.

func NewRawTokenCrypt

func NewRawTokenCrypt(key []byte) (*EncToken, error)

NewRawTokenCrypt returns a new 3ncr.org encrypter / decrypter from a raw 32-byte AES-256 key. Derive the key however you prefer — Argon2id for passwords, a single SHA3-256 hash for high-entropy inputs (random keys, API tokens). See the 3ncr.org spec for recommended parameters.

func NewTokenCrypt

func NewTokenCrypt(secret []byte, salt []byte, iter int) (*EncToken, error)

NewTokenCrypt returns a new 3ncr.org encrypter / decrypter. It derives AES-256 key using PBKDF2 with SHA3-256.

Deprecated: PBKDF2-SHA3 is the legacy KDF, retained for decrypting existing 3ncr.org data. New callers should use NewArgon2idTokenCrypt for low-entropy secrets (passwords) or NewRawTokenCrypt for high-entropy keys (random 32-byte keys, SHA3-256 of an API token, etc.). See the 3ncr.org spec Key Derivation section.

func (*EncToken) DecryptIf3ncr

func (c *EncToken) DecryptIf3ncr(source string) (string, error)

DecryptIf3ncr decrypts a 3ncr.org string If the string does not starts with 3ncr.org header, it returns the argument unmodified and no error

func (*EncToken) Encrypt3ncr

func (c *EncToken) Encrypt3ncr(source string) (string, error)

Encrypt3ncr encrypts a string using most recent 3ncr.org version available