crypto

package
v0.0.0-...-c19cbcf Latest Latest
Warning

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

 Go to latest Published: Nov 18, 2020 License: GPL-3.0 Imports: 17 Imported by: 0

Documentation

Overview

Package crypto provides a high level, secure, easy to use, and hard to misuse API to common cryptographic operations.

KDF

KDF (Key Derivation Function) functions should be used to derives encryption keys from passwords or other keys.

Pasword

Only th efunction `HashPassword` should be used for password hashing.

AEAD

AEAD (Authenticated Encryption with Associated Data) is used for secret key (symmetric) cryptography.

Hash

hash functions (`Hash{256,384,512}`, `NewHash`) should be used to hashs files or other kind of data. NOT FOR PASSWORD.

Index

Constants

View Source 
const (
	// AEADKeySize is the size of the key used by this AEAD, in bytes.
	AEADKeySize = chacha20poly1305.KeySize

	// AEADNonceSize is the size of the nonce used with the XChaCha20-Poly1305
	// variant of this AEAD, in bytes.
	AEADNonceSize = chacha20poly1305.NonceSizeX
)
View Source 
const (
	// Curve25519PublicKeySize is the size, in bytes, of public keys as used in this package.
	Curve25519PublicKeySize = curve25519.PointSize

	// Curve25519PrivateKeySize is the size, in bytes, of private keys as used in this package.
	Curve25519PrivateKeySize = curve25519.ScalarSize

	// X25519SharedSecretSize is the size, in bytes of the shared secret of a x25519 key exchange
	X25519SharedSecretSize = 32
)
View Source 
const (
	// Ed25519PublicKeySize is the size, in bytes, of public keys as used in this package.
	Ed25519PublicKeySize = ed25519.PublicKeySize

	// Ed25519PrivateKeySize is the size, in bytes, of private keys as used in this package.
	Ed25519PrivateKeySize = ed25519.PrivateKeySize

	// Ed25519SignatureSize is the size, in bytes, of signatures generated and verified by this package.
	Ed25519SignatureSize = ed25519.SignatureSize

	// Ed25519SeedSize is the size, in bytes, of private key seeds. These are the private key representations used by RFC 8032.
	Ed25519SeedSize = ed25519.SeedSize

	// Ed25519SignerOpts must be used for `PrivateKey.Sign`
	Ed25519SignerOpts = crypto.Hash(0)
)
View Source 
const (
	// KeySize256 is the size in bytes of a 256 bits key
	KeySize256 = 32
	// KeySize384 is the size in bytes of a 384 bits key
	KeySize384 = 48
	// KeySize512 is the size in bytes of a 512 bits key
	KeySize512 = 64
	// KeySize1024 is the size in bytes of a 1024 bits key
	KeySize1024 = 128
	// KeySize2048 is the size in bytes of a 2048 bits key
	KeySize2048 = 256
	// KeySize4096 is the size in bytes of a 4096 bits key
	KeySize4096 = 512
)

Variables

View Source 
var (
	// ErrInvalidPasswordHash in returned by ComparePasswordAndHash if the provided
	// hash isn't in the expected format.
	ErrInvalidPasswordHash = errors.New("crypto: hash is not in the correct format")

	// ErrIncompatiblePasswordHashVersion in returned by ComparePasswordAndHash if the
	// provided hash was created using a different version of Argon2.
	ErrIncompatiblePasswordHashVersion = errors.New("crypto: incompatible version of argon2")
)
View Source 
var DefaultDeriveKeyFromPasswordParams = &DeriveKeyFromPasswordParams{
	Memory:      64 * 1024,
	Iterations:  5,
	Parallelism: 2,
	KeySize:     KeySize512,
}

DefaultDeriveKeyFromPasswordParams provides some sane default parameters for deriving keys passwords. You are encouraged to change the Memory, Iterations and Parallelism parameters to values appropriate for the environment that your code will be running in.

View Source 
var DefaultHashPasswordParams = &HashPasswordParams{
	Memory:      64 * 1024,
	Iterations:  3,
	Parallelism: 2,
	SaltLength:  KeySize512,
	KeyLength:   KeySize512,
}

DefaultHashPasswordParams provides some sane default parameters for hashing passwords. You are encouraged to change the Memory, Iterations and Parallelism parameters to values appropriate for the environment that your code will be running in.

Functions

func AEADDecrypt 

func AEADDecrypt(key, nonce, ciphertext, additionalData []byte) (plaintext []byte, err error)

AEADDecrypt is an helper function to symetrically decrypt a piece of data using XChaCha20-Poly1305

func AEADEncrypt 

func AEADEncrypt(key, plaintext, additionalData []byte) (ciphertext, nonce []byte, err error)

AEADEncrypt is an helper function to symetrically encrypt a piece of data using XChaCha20-Poly1305

func ConstantTimeCompare 

func ConstantTimeCompare(x, y []byte) bool

ConstantTimeCompare returns true if the 2 buffer are equals and false otherwise

func DeriveKeyFromKey 

func DeriveKeyFromKey(key, info []byte, keySize uint8) ([]byte, error)

DeriveKeyFromKey derives a key from a high entropy key using the blake2b function

func DeriveKeyFromPassword 

func DeriveKeyFromPassword(password, salt []byte, params *DeriveKeyFromPasswordParams) ([]byte, error)

DeriveKeyFromPassword derives a key from a human provided password using the argon2id Key Derivation Function

func GenerateCurve25519KeyPair 

func GenerateCurve25519KeyPair() (publicKey Curve25519PublicKey, privateKey Curve25519PrivateKey, err error)

GenerateCurve25519KeyPair generates a public/private Curve25519 key pair

func GenerateEd25519KeyPair 

func GenerateEd25519KeyPair() (Ed25519PublicKey, Ed25519PrivateKey, error)

GenerateEd25519KeyPair generates a public/private Ed25519 key pair

func Hash256 

func Hash256(data []byte) []byte

Hash256 returns the BLAKE2b-256 checksum of the data.

func Hash384 

func Hash384(data []byte) []byte

Hash384 returns the BLAKE2b-384 checksum of the data.

func Hash512 

func Hash512(data []byte) []byte

Hash512 returns the BLAKE2b-512 checksum of the data.

func HashPassword 

func HashPassword(password []byte, params *HashPasswordParams) (hash string, err error)

HashPassword returns a Argon2id hash of a plain-text password using the provided algorithm parameters. The returned hash follows the format used by the Argon2 reference C implementation and contains the base64-encoded Argon2id d derived key prefixed by the salt and parameters. It looks like this: 

$argon2id$v=19$m=65536,t=3,p=2$c29tZXNhbHQ$RdescudvJCsgt3ub+b+dWRWJTmaaJObG

func NewAEAD 

func NewAEAD(key []byte) (cipher.AEAD, error)

NewAEAD returns a XChaCha20-Poly1305 AEAD that uses the given 256-bit key.

XChaCha20-Poly1305 is a ChaCha20-Poly1305 variant that takes a longer nonce, suitable to be generated randomly without risk of collisions. It should be preferred when nonce uniqueness cannot be trivially ensured, or whenever nonces are randomly generated.

func NewAEADKey 

func NewAEADKey() ([]byte, error)

NewAEADKey generates a new random secret key.

func NewAEADNonce 

func NewAEADNonce() ([]byte, error)

NewAEADNonce generates a new random nonce.

func NewHash 

func NewHash(size HashSize, key []byte) (hash.Hash, error)

NewHash returns a new `hash.Hash` computing the BLAKE2b checksum with a custom length. size can be a value between 1 and 64. It is highly recommended to use values equal or greater than 32.

func RandAlphabet 

func RandAlphabet(alphabet []byte, n uint64) ([]byte, error)

RandAlphabet returns a buffer a size n filled with random values taken from alphabet

func RandBytes 

func RandBytes(n uint64) ([]byte, error)

RandBytes returns securely generated random bytes. It will return an error if the system's secure random number generator fails to function correctly, in which case the caller should not continue.

func RandInt64 

func RandInt64(min, max int64) (int64, error)

RandInt64 returns a uniform random value in [min, max).

func RandReader 

func RandReader() io.Reader

RandReader returns a cryptographically secure source of entropy which implements the `io.Reader` interface.

func VerifyPasswordHash 

func VerifyPasswordHash(password []byte, hash string) bool

VerifyPasswordHash performs a constant-time comparison between a plain-text password and Argon2id hash, using the parameters and salt contained in the hash. It returns true if they match, otherwise it returns false.

func Zeroize 

func Zeroize(buffer []byte)

Zeroize set all bytes of buffer to 0

Types

type Curve25519PrivateKey 

type Curve25519PrivateKey []byte

Curve25519PrivateKey is the type of Curve25519 private keys.

func (Curve25519PrivateKey) Decrypt 

func (privateKey Curve25519PrivateKey) Decrypt(fromPublicKey Curve25519PublicKey, nonce []byte, ciphertext []byte) (plaintext []byte, err error)

Decrypt performs a x25519 key exchange, and decrypt the ciphertext using `XChaCha20-Poly1305` with the shared secret as key and nonce as nonce.

func (Curve25519PrivateKey) DecryptEphemeral 

func (privateKey Curve25519PrivateKey) DecryptEphemeral(ephemeralPublicKey Curve25519PublicKey, ciphertext []byte) (plaintext []byte, err error)

DecryptEphemeral generates a noce with `blake2b(size=AEADNonceSize, message=ephemeralPublicKey || privateKey.PublicKey())` and decrypt the `ciphertext` using `Decrypt`

func (Curve25519PrivateKey) KeyExchange 

func (privateKey Curve25519PrivateKey) KeyExchange(publicKey Curve25519PublicKey) (sharedSecret []byte, err error)

KeyExchange performs a x25519 key exchange with the given public key

func (Curve25519PrivateKey) Public 

func (privateKey Curve25519PrivateKey) Public() (publicKey Curve25519PublicKey, err error)

Public returns the Curve25519PublicKey corresponding to privateKey.

type Curve25519PublicKey 

type Curve25519PublicKey []byte

Curve25519PublicKey is the type of Curve25519 public keys.

func (Curve25519PublicKey) Encrypt 

func (publicKey Curve25519PublicKey) Encrypt(fromPrivateKey Curve25519PrivateKey, nonce []byte,
	message []byte) (ciphertext []byte, err error)

Encrypt performs a x25519 key exchange, and encrypt the message using `XChaCha20-Poly1305` with the shared secret as key and nonce as nonce.

func (Curve25519PublicKey) EncryptEphemeral 

func (publicKey Curve25519PublicKey) EncryptEphemeral(message []byte) (ciphertext []byte, ephemeralPublicKey Curve25519PublicKey, err error)

EncryptEphemeral generates an ephemeral Curve25519KeyPair and `Encrypt` message using the public key, the ephemeral privateKey and `blake2b(size=AEADNonceSize, message=ephemeralPublicKey || publicKey)` as nonce

func (Curve25519PublicKey) KeyExchange 

func (publicKey Curve25519PublicKey) KeyExchange(privateKey Curve25519PrivateKey) (sharedSecret []byte, err error)

KeyExchange performs a x25519 key exchange with the given private key

type DeriveKeyFromPasswordParams 

type DeriveKeyFromPasswordParams struct {
	// The amount of memory used by the algorithm (in kibibytes).
	Memory uint32

	// The number of iterations over the memory.
	Iterations uint32

	// The number of threads (or lanes) used by the algorithm.
	Parallelism uint8

	// Size of the generated key. 32 bytes or more is recommended.
	KeySize uint32
}

DeriveKeyFromPasswordParams describes the input parameters used by the Argon2id algorithm.

type Ed25519PrivateKey 

type Ed25519PrivateKey ed25519.PrivateKey

Ed25519PrivateKey is the type of Ed25519 private keys. It implements crypto.Signer.

func NewEd25519PrivateKeyFromSeed 

func NewEd25519PrivateKeyFromSeed(seed []byte) (Ed25519PrivateKey, error)

NewEd25519PrivateKeyFromSeed calculates a private key from a seed. It will panic if len(seed) is not SeedSize. This function is provided for interoperability with RFC 8032. RFC 8032's private keys correspond to seeds in this package.

func (Ed25519PrivateKey) Public 

func (privateKey Ed25519PrivateKey) Public() Ed25519PublicKey

Public returns the Ed25519PublicKey corresponding to priv.

func (Ed25519PrivateKey) Seed 

func (privateKey Ed25519PrivateKey) Seed() []byte

Seed returns the private key seed corresponding to priv. It is provided for interoperability with RFC 8032. RFC 8032's private keys correspond to seeds in this package.

func (Ed25519PrivateKey) Sign 

func (privateKey Ed25519PrivateKey) Sign(rand io.Reader, message []byte, opts crypto.SignerOpts) (signature []byte, err error)

Sign signs the given message with priv. Ed25519 performs two passes over messages to be signed and therefore cannot handle pre-hashed messages. Thus opts.HashFunc() must return zero to indicate the message hasn't been hashed. This can be achieved by passing crypto.Ed25519SignerOpts as the value for opts.

func (Ed25519PrivateKey) ToCurve25519PrivateKey 

func (privateKey Ed25519PrivateKey) ToCurve25519PrivateKey() Curve25519PrivateKey

ToCurve25519PrivateKey returns a corresponding Curve25519 private key.

See here for more details: https://blog.filippo.io/using-ed25519-keys-for-encryption

type Ed25519PublicKey 

type Ed25519PublicKey ed25519.PublicKey

Ed25519PublicKey is the type of Ed25519 public keys.

func (Ed25519PublicKey) ToCurve25519PublicKey 

func (publicKey Ed25519PublicKey) ToCurve25519PublicKey() Curve25519PublicKey

ToCurve25519PublicKey returns the corresponding Curve25519 public key.

See here for more details: https://blog.filippo.io/using-ed25519-keys-for-encryption

func (Ed25519PublicKey) Verify 

func (publicKey Ed25519PublicKey) Verify(message, signature []byte) (bool, error)

Verify reports whether sig is a valid signature of message by publicKey. returns true if signature is valid. false otherwise.

type HashPasswordParams 

type HashPasswordParams struct {
	// The amount of memory used by the algorithm (in kibibytes).
	Memory uint32

	// The number of iterations over the memory.
	Iterations uint32

	// The number of threads (or lanes) used by the algorithm.
	Parallelism uint8

	// Length of the random salt. 16 bytes is recommended for password hashing.
	SaltLength uint32

	// Length of the generated key. 32 bytes or more is recommended.
	KeyLength uint32
}

HashPasswordParams describes the input parameters used by the Argon2id algorithm. The Memory and Iterations parameters control the computational cost of hashing the password. The higher these figures are, the greater the cost of generating the hash and the longer the runtime. It also follows that the greater the cost will be for any attacker trying to guess the password. If the code is running on a machine with multiple cores, then you can decrease the runtime without reducing the cost by increasing the Parallelism parameter. This controls the number of threads that the work is spread across. Important note: Changing the value of the Parallelism parameter changes the hash output.

For guidance and an outline process for choosing appropriate parameters see https://tools.ietf.org/html/draft-irtf-cfrg-argon2-04#section-4

type HashSize 

type HashSize uint32

HashSize is the size of a hash, in bytes. 

const (
	// HashSize256 is the size in bytes of a 256 bits hash
	HashSize256 HashSize = 32
	// HashSize384 is the size in bytes of a 384 bits hash
	HashSize384 HashSize = 48
	// HashSize512 is the size in bytes of a 512 bits hash
	HashSize512 HashSize = 64
)

Source Files

View all Source files

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.