crypto

package
v0.0.0-...-22e1697 Latest Latest
Warning

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

 Go to latest Published: Mar 22, 2024 License: AGPL-3.0 Imports: 16 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 = KeySize256

	// AEADNonceSize is the size of the nonce used with the AES-256-GCM
	// variant of this AEAD, in bytes.
	AEADNonceSize = 12
)
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 (
	// KeySize128 is the size in bytes of a 128 bits key
	KeySize128 = 32
	// 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
)
View Source 
const (
	Size96  = 12
	Size128 = 16
	Size256 = 32
	Size512 = 64
)

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:     KeySize256,
}

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 ConstantTimeCompare 

func ConstantTimeCompare(x, y []byte) bool

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

func Decrypt 

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

DecryptWithNonce is an helper function to symetrically decrypt a piece of data using AES-256-GCM The nonce should be at the begining of the ciphertext

func DecryptWithNonce 

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

DecryptWithNonce is an helper function to symetrically decrypt a piece of data using AES-256-GCM taking the nonce as a separate piece of input

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 Encrypt 

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

Encrypt is an helper function to symetrically encrypt a piece of data using AES-256-GCM the nonce is prepended to the ciphertext in the returned buffer

func EncryptWithNonce 

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

Encrypt is an helper function to symetrically encrypt a piece of data using AES-256-GCM returning the nonce separatly

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 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 Mac 

func Mac(key, data []byte, macSize uint8) ([]byte, error)

Mac use the blake2b funciton in MAC mode

func NewAEAD 

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

NewAEAD returns a AES-256-GCM AEAD that uses the given 256-bit key.

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 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(max int64) (int64, error)

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

func RandInt64Between 

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

RandInt64Between 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 NewEd25519PrivateKeyFromBytes 

func NewEd25519PrivateKeyFromBytes(key []byte) (privateKey Ed25519PrivateKey, err error)

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) Bytes 

func (privateKey Ed25519PrivateKey) Bytes() []byte

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 NewEd25519PublicKeyFromBytes 

func NewEd25519PublicKeyFromBytes(key []byte) (publicKey Ed25519PublicKey, err error)

func (Ed25519PublicKey) Bytes 

func (publicKey Ed25519PublicKey) Bytes() []byte

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

Directories

Path Synopsis
Package chacha implements some low-level functions of the ChaCha cipher family.
 Package chacha implements some low-level functions of the ChaCha cipher family.
Package chacha20 implements the ChaCha20 / XChaCha20 stream chipher.
 Package chacha20 implements the ChaCha20 / XChaCha20 stream chipher.
internal
blake3
Package blake3 implements the BLAKE3 cryptographic hash function.
 Package blake3 implements the BLAKE3 cryptographic hash function.

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.