std/crypto
On this page
Index
- type
Hash- method
Hash.size
- method
- type
Hasher- method
Hasher.write - method
Hasher.sum - method
Hasher.written
- method
- type
Aead- method
Aead.nonce_size - method
Aead.overhead
- method
- type
AeadKey- method
AeadKey.alg - method
AeadKey.seal_random - method
AeadKey.open_random - method
AeadKey.seal - method
AeadKey.open
- method
- type
AeadErr- method
AeadErr.display
- method
- type
PemBlock - type
KeyErr- method
KeyErr.display
- method
- type
KeyAlg - type
PublicKey- method
PublicKey.alg
- method
- type
PrivateKey- method
PrivateKey.alg - method
PrivateKey.public_key
- method
- fn
sha256 - fn
hmac_sha256 - fn
equal - fn
random_bytes - fn
token - fn
hash_password_argon2id - fn
hash_password - fn
verify_password - fn
ed25519_public_key - fn
ed25519_sign - fn
ed25519_verify - fn
digest - fn
hmac - fn
hasher - fn
hmac_hasher - fn
aead_key - fn
hkdf_extract - fn
hkdf_expand - fn
hkdf - fn
parse_public_key - fn
marshal_public_key - fn
jwk_public_key - fn
parse_private_key - fn
marshal_private_key - fn
ecdsa_private_key - fn
pem_decode - fn
pem_encode - fn
verify - fn
verify_pss - fn
verify_raw_ecdsa - fn
sign - fn
sign_pss - fn
sign_raw_ecdsa - fn
generate_key
Types
Hash
enum Hash {
Md5
Sha1
Sha224
Sha256
Sha384
Sha512
Sha3_256
Sha3_512
}The hashes of digest, hmac, and Hasher (decision 0279). Md5 and
Sha1 are broken for collision resistance; they are here for protocols
that require them (HMAC-SHA1 signatures, TOTP, Postgres MD5
authentication, Content-MD5).
Hash.size
fn (h: Hash) size() -> IntThe digest’s size in bytes: 16, 20, 28, 32, 48, 64, 32, 64.
Hasher
struct Hasher {}A hash being computed a piece at a time: a value, so copies are
independent (var x = crypto.hasher(Sha256), then x.write(chunk)).
Hasher.write
fn (var x: Hasher) write(data: Bytes)Hasher.sum
fn (x: Hasher) sum() -> BytesThe digest (or MAC) of what was written so far; writing may continue.
Hasher.written
fn (x: Hasher) written() -> IntThe bytes written so far.
Aead
enum Aead {
AesGcm
ChaCha20Poly1305
}An authenticated cipher with associated data (Go’s cipher.AEAD): it
encrypts and authenticates a message, and authenticates aad alongside
it without encrypting it.
Aead.nonce_size
fn (a: Aead) nonce_size() -> IntThe nonce’s size in bytes: 12 for both.
Aead.overhead
fn (a: Aead) overhead() -> IntThe bytes a sealed message is longer than its plaintext: 16 (the tag).
AeadKey
struct AeadKey {}A key ready to seal and open messages: its key schedule is made once,
so keep one for many messages. It never displays, prints, or encodes its
key (no Display, no derive Json), as a Secret[T].
AeadKey.alg
fn (k: AeadKey) alg() -> AeadAeadKey.seal_random
fn (k: AeadKey) seal_random(r: Rand, plaintext: Bytes, aad: Bytes = b"") -> Bytes uses randplaintext sealed under a random nonce from r, the nonce first: the
way to seal unless a protocol counts nonces (Go’s
cipher.NewGCMWithRandomNonce). Open it with open_random.
AeadKey.open_random
fn (k: AeadKey) open_random(sealed: Bytes, aad: Bytes = b"") -> Bytes ! AeadErrA message from seal_random, checked and decrypted.
AeadKey.seal
fn (k: AeadKey) seal(nonce: Bytes, plaintext: Bytes, aad: Bytes = b"") -> Bytesplaintext encrypted and authenticated with aad under nonce (exactly
nonce_size() bytes, else a fault): the ciphertext, then the 16 byte tag.
A nonce must never be used twice with one key: a repeat breaks both the
confidentiality and the authenticity of every message under the key.
AeadKey.open
fn (k: AeadKey) open(nonce: Bytes, sealed: Bytes, aad: Bytes = b"") -> Bytes ! AeadErrsealed checked and decrypted; Err (and no plaintext) when it was changed, the nonce or aad differ, or it is shorter than the tag.
AeadErr
struct AeadErr {
msg: Str
}An AEAD error: cipher: message authentication failed for every
sealed message that does not open (whatever check failed), or a key
size error from aead_key.
AeadErr.display
fn (e: AeadErr) display() -> StrPemBlock
struct PemBlock {
kind: Str
headers: Map[Str, Str]
bytes: Bytes
}A PEM block (encoding/pem): its type (PUBLIC KEY), headers, and
decoded bytes.
KeyErr
struct KeyErr {
msg: Str
}Go’s error texts (x509: failed to parse public key, …).
KeyErr.display
fn (e: KeyErr) display() -> StrKeyAlg
enum KeyAlg {
Rsa
EcdsaP224
EcdsaP256
EcdsaP384
EcdsaP521
Ed25519
}PublicKey
struct PublicKey {}A public key: ==; Debug text <publickey>.
PublicKey.alg
fn (k: PublicKey) alg() -> KeyAlgPrivateKey
struct PrivateKey {}A private key: Debug text <privatekey>, never key material.
PrivateKey.alg
fn (k: PrivateKey) alg() -> KeyAlgPrivateKey.public_key
fn (k: PrivateKey) public_key() -> PublicKeyFunctions
sha256
fn sha256(data: Bytes) -> Byteshmac_sha256
fn hmac_sha256(key: Bytes, msg: Bytes) -> Bytesequal
fn equal(a: Bytes, b: Bytes) -> BoolConstant time in the contents (not the lengths) of a and b.
random_bytes
fn random_bytes(r: Rand, n: Int) -> Bytes uses randtoken
fn token(r: Rand, n: Int = 32) -> Str uses randn random bytes as unpadded URL safe base64.
hash_password_argon2id
fn hash_password_argon2id(r: Rand, password: Str, memory_kib: Int = 19456, iterations: Int = 2, parallelism: Int = 1) -> Str uses randArgon2id (RFC 9106) with a 16 byte random salt and a 32 byte key, in the
PHC format $argon2id$v=19$m=<memory_kib>,t=<iterations>,p=<parallelism>$<salt>$<key>.
The defaults are the OWASP minimum (19 MiB, 2 passes, 1 lane). The
recommended password hash (std.md 11).
hash_password
fn hash_password(r: Rand, password: Str, iterations: Int = 600000) -> Str uses randPBKDF2-HMAC-SHA256 with a 16 byte random salt; the result is
pbkdf2-sha256$<iterations>$<salt>$<key> (std.md 11).
verify_password
fn verify_password(password: Str, hash: Str) -> BoolChecks a result of hash_password_argon2id or hash_password, told apart
by the prefix.
ed25519_public_key
fn ed25519_public_key(seed: Bytes) -> BytesEd25519 (RFC 8032, decision 0189): the 32 byte public key of the
private key seed (32 bytes; faults otherwise).
ed25519_sign
fn ed25519_sign(seed: Bytes, msg: Bytes) -> BytesThe 64 byte Ed25519 signature of msg by the private key seed: the
32 byte seed, or Go’s 64 byte private key (the seed, then its public
key, which signing then uses as stored and need not compute); faults
on any other length. Deterministic: the same seed and message give the
same signature.
ed25519_verify
fn ed25519_verify(public_key: Bytes, msg: Bytes, sig: Bytes) -> BoolWhether sig is a valid Ed25519 signature of msg by public_key; false for a key that is not 32 bytes or a signature that is not 64.
digest
fn digest(h: Hash, data: Bytes) -> BytesThe digest of data with h (Go’s md5.Sum, sha1.Sum, sha256.Sum224, …).
hmac
fn hmac(h: Hash, key: Bytes, msg: Bytes) -> BytesHMAC (RFC 2104) of msg keyed with key, over h (Go’s crypto/hmac).
hasher
fn hasher(h: Hash) -> Hasherhmac_hasher
fn hmac_hasher(h: Hash, key: Bytes) -> HasherA Hasher computing HMAC over h keyed with key.
aead_key
fn aead_key(alg: Aead, key: Bytes) -> AeadKey ! AeadErralg’s key; Err when key is not a length alg takes.
hkdf_extract
fn hkdf_extract(h: Hash, secret: Bytes, salt: Bytes = b"") -> BytesHKDF-Extract (RFC 5869, Go’s hkdf.Extract): the pseudorandom key,
h.size() bytes, from secret and salt (empty: h.size() zero bytes).
hkdf_expand
fn hkdf_expand(h: Hash, prk: Bytes, info: Bytes, n: Int) -> BytesHKDF-Expand (Go’s hkdf.Expand): n bytes of keying material from a
pseudorandom key and info. Faults when n is negative or over 255
times h.size().
hkdf
fn hkdf(h: Hash, secret: Bytes, salt: Bytes, info: Bytes, n: Int) -> BytesHKDF, extract then expand (Go’s hkdf.Key).
parse_public_key
fn parse_public_key(der: Bytes) -> PublicKey ! KeyErrPKIX SubjectPublicKeyInfo (x509.ParsePKIXPublicKey) or PKCS #1 RSAPublicKey DER.
marshal_public_key
fn marshal_public_key(k: PublicKey) -> BytesPKIX DER (x509.MarshalPKIXPublicKey).
jwk_public_key
fn jwk_public_key(jwk: Str) -> PublicKey ! KeyErrA JWK’s public key (RFC 7517; kty RSA, EC with crv P-256, P-384, or P-521, OKP with crv Ed25519; private members ignored).
parse_private_key
fn parse_private_key(der: Bytes) -> PrivateKey ! KeyErrPKCS #8, PKCS #1, or SEC 1 EC DER, as Go’s parsers tell them apart.
marshal_private_key
fn marshal_private_key(k: PrivateKey) -> Bytesk as PKCS #8 DER (Go’s MarshalPKCS8PrivateKey), which parse_private_key reads back; pem_encode it as a “PRIVATE KEY” block to save it.
ecdsa_private_key
fn ecdsa_private_key(alg: KeyAlg, d: Bytes) -> PrivateKey ! KeyErrAn ECDSA key from its private scalar d, big endian and as long as the
curve’s order (32 bytes for EcdsaP256; 66 for EcdsaP521), as Go’s
ecdsa.ParseRawPrivateKey: 0 and d at or above the order are KeyErr
(ecdsa: invalid public key encoding, Go’s text), a wrong length is
invalid scalar length, and any other alg is KeyErr. public_key() of
the result is the public point (AWS SigV4a derives its key this way).
pem_decode
fn pem_decode(text: Str) -> List[PemBlock]Every PEM block in text, in order (pem.Decode repeated on the rest); text outside blocks and malformed blocks are skipped.
pem_encode
fn pem_encode(b: PemBlock) -> Str ! KeyErrpem.EncodeToMemory: KeyErr for a header key holding a colon.
verify
fn verify(k: PublicKey, h: Hash, msg: Bytes, sig: Bytes) -> BoolRSA PKCS #1 v1.5 or ECDSA (ASN.1 DER) over msg hashed with h, or Ed25519 over msg itself; false for a key, hash, or signature that does not fit.
verify_pss
fn verify_pss(k: PublicKey, h: Hash, msg: Bytes, sig: Bytes) -> BoolRSA PSS, any salt length (PSSSaltLengthAuto).
verify_raw_ecdsa
fn verify_raw_ecdsa(k: PublicKey, h: Hash, msg: Bytes, sig: Bytes) -> BoolECDSA with the fixed size r || s of JWS (RFC 7518 3.4).
sign
fn sign(r: Rand, k: PrivateKey, h: Hash, msg: Bytes) -> Bytes ! KeyErr uses randRSA PKCS #1 v1.5, ECDSA (ASN.1 DER, a hedged nonce from r), or Ed25519.
sign_pss
fn sign_pss(r: Rand, k: PrivateKey, h: Hash, msg: Bytes) -> Bytes ! KeyErr uses randRSA PSS with a salt as long as the hash, from r.
sign_raw_ecdsa
fn sign_raw_ecdsa(r: Rand, k: PrivateKey, h: Hash, msg: Bytes) -> Bytes ! KeyErr uses randECDSA as the fixed size r || s of JWS.
generate_key
fn generate_key(r: Rand, alg: KeyAlg, bits: Int = 2048) -> PrivateKey ! KeyErr uses randA new key from r (Go’s GenerateKey): an ECDSA or Ed25519 key, or an RSA
key of bits (1024 to 8192, exponent 65537; other algorithms ignore
it). The same r gives the same key on every backend.