crypto

package
v0.0.0-...-a0bf06b Latest Latest
Warning

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

 Go to latest Published: May 15, 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 (
	// 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 (
	// PublicKeySize is the size, in bytes, of public keys as used in this package.
	PublicKeySize = ed25519.PublicKeySize

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

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

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

	// PrivateKeySignerOpts must be used for `PrivateKey.Sign`
	PrivateKeySignerOpts = crypto.Hash(0)
)

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 ConstantTimeCompare 

func ConstantTimeCompare(x, y []byte) bool

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 GenerateKeyPair 

func GenerateKeyPair(rand io.Reader) (PublicKey, PrivateKey, error)

GenerateKeyPair generates a public/private key pair using entropy from rand. If rand is nil, crypto/rand.Reader will be used.

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

type PrivateKey 

type PrivateKey ed25519.PrivateKey

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

func NewPrivateKeyFromSeed 

func NewPrivateKeyFromSeed(seed []byte) (PrivateKey, error)

NewPrivateKeyFromSeed 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 (PrivateKey) Public 

func (priv PrivateKey) Public() crypto.PublicKey

Public returns the PublicKey corresponding to priv.

func (PrivateKey) Seed 

func (priv PrivateKey) 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 (PrivateKey) Sign 

func (priv PrivateKey) 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.PrivateKeySignerOpts as the value for opts.

func (PrivateKey) ToCurve25519PrivateKey 

func (priv PrivateKey) ToCurve25519PrivateKey() []byte

ToCurve25519PrivateKey returns a corresponding Curve25519 private key.

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

type PublicKey 

type PublicKey ed25519.PublicKey

PublicKey is the type of Ed25519 public keys.

func (PublicKey) ToCurve25519PublicKey 

func (public PublicKey) ToCurve25519PublicKey() []byte

ToCurve25519PublicKey returns the corresponding Curve25519 public key.

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

func (PublicKey) Verify 

func (public PublicKey) 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.

Source Files

View all Source files

Directories

Path Synopsis
lowlevel
box
// Copyright 2012 The Go Authors.
 // Copyright 2012 The Go Authors.

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.