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
- Variables
- func ConstantTimeCompare(x, y []byte) bool
- func Decrypt(key, ciphertext, additionalData []byte) (plaintext []byte, err error)
- func DecryptWithNonce(key, nonce, ciphertext, additionalData []byte) (plaintext []byte, err error)
- func DeriveKeyFromKey(key, info []byte, keySize uint8) ([]byte, error)
- func DeriveKeyFromPassword(password, salt []byte, params DeriveKeyFromPasswordParams) ([]byte, error)
- func Encrypt(key, plaintext, additionalData []byte) (ciphertext []byte, err error)
- func EncryptWithNonce(key, plaintext, additionalData []byte) (ciphertext, nonce []byte, err error)
- func GenerateCurve25519KeyPair() (publicKey Curve25519PublicKey, privateKey Curve25519PrivateKey, err error)
- func GenerateEd25519KeyPair() (Ed25519PublicKey, Ed25519PrivateKey, error)
- func HashPassword(password []byte, params HashPasswordParams) (hash string)
- func Mac(key, data []byte, macSize uint8) ([]byte, error)
- func NewAEAD(key []byte) (aeadCipher cipher.AEAD, err error)
- func NewAEADKey() []byte
- func NewAEADNonce() []byte
- func NewRandomGenerator() *rand.Rand
- func RandBytes(n uint64) []byte
- func RandInt64Between(min, max int64) (int64, error)
- func VerifyPasswordHash(password []byte, hash string) bool
- func Zeroize(buffer []byte)
- type Curve25519PrivateKey
- func (privateKey Curve25519PrivateKey) Decrypt(fromPublicKey Curve25519PublicKey, nonce []byte, ciphertext []byte) (plaintext []byte, err error)
- func (privateKey Curve25519PrivateKey) DecryptEphemeral(ephemeralPublicKey Curve25519PublicKey, ciphertext []byte) (plaintext []byte, err error)
- func (privateKey Curve25519PrivateKey) KeyExchange(publicKey Curve25519PublicKey) (sharedSecret []byte, err error)
- func (privateKey Curve25519PrivateKey) Public() (publicKey Curve25519PublicKey, err error)
- type Curve25519PublicKey
- func (publicKey Curve25519PublicKey) Encrypt(fromPrivateKey Curve25519PrivateKey, nonce []byte, message []byte) (ciphertext []byte, err error)
- func (publicKey Curve25519PublicKey) EncryptEphemeral(message []byte) (ciphertext []byte, ephemeralPublicKey Curve25519PublicKey, err error)
- func (publicKey Curve25519PublicKey) KeyExchange(privateKey Curve25519PrivateKey) (sharedSecret []byte, err error)
- type DeriveKeyFromPasswordParams
- type Ed25519PrivateKey
- func (privateKey Ed25519PrivateKey) Bytes() []byte
- func (privateKey Ed25519PrivateKey) Public() Ed25519PublicKey
- func (privateKey Ed25519PrivateKey) Seed() []byte
- func (privateKey Ed25519PrivateKey) Sign(rand io.Reader, message []byte, opts crypto.SignerOpts) (signature []byte, err error)
- func (privateKey Ed25519PrivateKey) ToCurve25519PrivateKey() Curve25519PrivateKey
- type Ed25519PublicKey
- type HashPasswordParams
- type HashSize
- type RandSource
Constants ¶
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 )
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 = 32 )
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) )
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 )
const ( Size96 = 12 Size128 = 16 Size256 = 32 Size512 = 64 )
Variables ¶
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") )
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.
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 ¶
ConstantTimeCompare returns true if the 2 buffer are equals and false otherwise
func Decrypt ¶
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 ¶
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 ¶
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 ¶
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 ¶
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)
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 NewRandomGenerator ¶
func NewRandomGenerator() *rand.Rand
func RandBytes ¶
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 RandInt64Between ¶
RandInt64Between returns a uniform random value in [min, max).
func VerifyPasswordHash ¶
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.
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 ¶
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
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 RandSource ¶
type RandSource struct { }
func (RandSource) Uint64 ¶
func (source RandSource) Uint64() uint64
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. |