# gizlang:crypto

Modern cryptographic primitives in Gizlang (RFC 5869/8439/7748/8032). SHA-256 blocks run in the runtime on the CPU's SHA instructions where it has them, and AES-GCM in libcrypto. Length contracts are public. Secret arithmetic uses fixed loops and masks.

```gizlang
import * as Crypto from "gizlang:crypto";
```

## Types

### `Sha256`

```gizlang
type Sha256
```

Only a partial block is copied; full blocks are read directly. Digest preserves the hasher.

Opaque: create and use it through this module's functions.

### `Md5`

```gizlang
type Md5
```

RFC 1321 interoperability checksum, not a collision-resistant security
primitive. Only a partial block is buffered, just as in Sha256.

Opaque: create and use it through this module's functions.

### `Sha512`

```gizlang
type Sha512
```

Only a partial block is copied; full blocks are read directly. The schedule
is allocated once per hasher, reused in place; digest preserves the hasher.

Opaque: create and use it through this module's functions.

### `Validity`

```gizlang
type Validity = { from: i64; until: i64; }
```

A certificate's validity period, in milliseconds since the epoch.

- `from`: `i64`
- `until`: `i64`

### `Digest`

```gizlang
type Digest
```

A digest in progress (an EVP_MD_CTX); digest() ends it.

Opaque: create and use it through this module's functions.

### `Hmac`

```gizlang
type Hmac
```

An HMAC computation in progress: feed it bytes, then take the MAC.

Opaque: create and use it through this module's functions.

### `CipherInfo`

```gizlang
type CipherInfo = { name: string; nid: i64; blockSize: i64; ivLength: i64; keyLength: i64; mode: string; }
```

What a cipher is: its name, numeric id, block size, IV length, key length and mode.

- `name`: `string`
- `nid`: `i64`
- `blockSize`: `i64`
- `ivLength`: `i64`
- `keyLength`: `i64`
- `mode`: `string`

### `Cipher`

```gizlang
type Cipher
```

A cipher in progress (an EVP_CIPHER_CTX): update() as much as you like, then final().

Opaque: create and use it through this module's functions.

### `Key`

```gizlang
type Key
```

An asymmetric key or key pair (an EVP_PKEY, reference counted).

Opaque: create and use it through this module's functions.

### `Param`

```gizlang
type Param = { name: string; kind: i64; text: string; data: bytes; }
```

One key parameter: a text (PARAM_TEXT, "group"), a big number (PARAM_NUMBER, "n") or an octet string (PARAM_OCTET, "pub").

- `name`: `string`
- `kind`: `i64`
- `text`: `string`
- `data`: `bytes`

## Functions

### `equal`

```gizlang
function equal(a: bytes, b: bytes): bool
```

Scans all bytes for equal public lengths, including on a mismatch.

Effects: fail.

### `newSha256`

```gizlang
function newSha256(): Sha256
```

A SHA-256 hash of no data.

Effects: fail.

### `sha256`

```gizlang
function sha256(data: bytes): bytes
```

The SHA-256 hash of DATA (32 bytes).

Effects: fail.

### `sha224`

```gizlang
function sha224(data: bytes): bytes
```

FIPS 180-4 SHA-224: SHA-256 from its own initial words, cut to 28 bytes.

Effects: fail.

### `newMd5`

```gizlang
function newMd5(): Md5
```

An MD5 hash of no data. MD5 is broken for security; use it only where a format asks for it.

Effects: fail.

### `md5`

```gizlang
function md5(data: bytes): bytes
```

The MD5 hash of DATA (16 bytes). MD5 is broken for security; use it only where a format asks for it.

Effects: fail.

### `md5Crypt`

```gizlang
function md5Crypt(password: bytes, salt: bytes, magic: string): string
```

The MD5-based password hash of Poul-Henning Kamp (`$1$`), and Apache's variant `$apr1$` (htpasswd -m): `magic` is "$1$" or "$apr1$".
The result is `magic + salt + "$" + 22 characters`. It is a stored-password check for old htpasswd files, not a hash to choose.

Effects: fail.

### `bcrypt`

```gizlang
function bcrypt(password: bytes, setting: string): string
```

The bcrypt hash (`$2a$`, `$2b$` or `$2y$`, htpasswd -B) of PASSWORD under SETTING: a stored hash or its first 29 bytes
(`$2y$10$` and 22 characters of salt). The result is the 60-character hash, or "" for a setting that is not one, so it
never equals a stored hash. The cost is 2^N rounds of key schedule, about 50 ms at 10: check a credential once, not per request.

Effects: fail.

### `sha1`

```gizlang
function sha1(data: bytes): bytes
```

RFC 3174 SHA-1, for protocols that name it (the WebSocket handshake, RFC
6455), not a collision-resistant security primitive.

Effects: fail.

### `hmacSha256`

```gizlang
function hmacSha256(key: bytes, data: bytes): bytes
```

The HMAC-SHA-256 of DATA with KEY (32 bytes).

Effects: fail.

### `jwtSign`

```gizlang
function jwtSign(key: bytes, claims: Json): string
```

A JSON Web Token (RFC 7519) of CLAIMS, a JSON object, signed by KEY with HMAC-SHA256 (alg HS256).

Effects: fail.

### `jwtClaims`

```gizlang
function jwtClaims(key: bytes, token: string, now: i64): Option<Json>
```

The claims of TOKEN when KEY signed it with HS256 and it is valid at NOW (seconds since 1970): not after its "exp"
and not before its "nbf". A token without "exp" does not expire.

Effects: fail.

### `jwtPart`

```gizlang
function jwtPart(segment: string): Option<Json>
```

One part of a JSON Web Token (its header or claims), unverified: its base64url JSON, when it is that.

Effects: fail.

### `newSha512`

```gizlang
function newSha512(): Sha512
```

A SHA-512 hash of no data.

Effects: fail.

### `sha512`

```gizlang
function sha512(data: bytes): bytes
```

The SHA-512 hash of DATA (64 bytes).

Effects: fail.

### `sha384`

```gizlang
function sha384(data: bytes): bytes
```

FIPS 180-4 SHA-384: SHA-512 from its own initial words, cut to 48 bytes.

Effects: fail.

### `hmacSha512`

```gizlang
function hmacSha512(key: bytes, data: bytes): bytes
```

The HMAC-SHA-512 of DATA with KEY (64 bytes).

Effects: fail.

### `hkdfSha256`

```gizlang
function hkdfSha256(secret: bytes, salt: bytes, info: bytes, length: i64): bytes requires length> = 0 requires length <= 8160
```

RFC 5869 extract then expand, at most 255 SHA-256 blocks.

Effects: fail.

### `pbkdf2Sha256`

```gizlang
function pbkdf2Sha256(password: bytes, salt: bytes, iterations: i64, length: i64): bytes requires iterations> = 1 requires length> = 1 requires length <= 8160 { let k = password
```

RFC 8018 PBKDF2 with HMAC-SHA256: `length` bytes of a key stretched from
`password` under `salt` by `iterations` rounds, as a stored password's
hash (OWASP asks 600000 rounds). The keyed hasher states are made once, so a
round is two compressions.

Effects: fail.

### `chacha20Poly1305Seal`

```gizlang
function chacha20Poly1305Seal(key32: bytes, nonce12: bytes, plaintext: bytes, aad: bytes): bytes requires key32.length === 32 requires nonce12.length === 12
```

RFC 8439: ciphertext followed by the 16-byte tag. Never reuse a key/nonce pair.

Effects: fail.

### `chacha20Poly1305Open`

```gizlang
function chacha20Poly1305Open(key32: bytes, nonce12: bytes, sealed: bytes, aad: bytes): Option<bytes> requires key32.length === 32 requires nonce12.length === 12
```

The plaintext of SEALED (ciphertext and its 16-byte tag) under ChaCha20-Poly1305 with KEY32, NONCE12 and AAD; none
when the tag does not match.

Effects: fail.

### `aes256GcmSeal`

```gizlang
function aes256GcmSeal(key32: bytes, nonce12: bytes, plaintext: bytes, aad: bytes): bytes requires key32.length === 32 requires nonce12.length === 12
```

NIST SP 800-38D with a 96-bit nonce: ciphertext followed by the 16-byte
tag. Never reuse a key/nonce pair.

Effects: fail.

### `aes256GcmOpen`

```gizlang
function aes256GcmOpen(key32: bytes, nonce12: bytes, sealed: bytes, aad: bytes): Option<bytes> requires key32.length === 32 requires nonce12.length === 12
```

The plaintext of SEALED (ciphertext and its 16-byte tag) under AES-256-GCM with KEY32, NONCE12 and AAD; none when
the tag does not match.

Effects: fail.

### `x25519`

```gizlang
function x25519(scalar32: bytes, point32: bytes): bytes requires scalar32.length === 32 requires point32.length === 32
```

RFC 7748 decoding masks the high coordinate bit and clamps the scalar.
A low-order input gives all-zero output; protocols must reject that secret.

Effects: fail.

### `x25519Base`

```gizlang
function x25519Base(scalar32: bytes): bytes requires scalar32.length === 32
```

The X25519 public key of the private SCALAR32.

Effects: fail.

### `ed25519PublicKey`

```gizlang
function ed25519PublicKey(seed32: bytes): bytes requires seed32.length === ED25519_SEED_BYTES
```

The 32-byte Ed25519 public key of the private SEED32.

Effects: fail.

### `ed25519Sign`

```gizlang
function ed25519Sign(seed32: bytes, message: bytes): bytes requires seed32.length === ED25519_SEED_BYTES
```

The 64-byte Ed25519 signature of MESSAGE with the private SEED32.

Effects: fail.

### `ed25519Verify`

```gizlang
function ed25519Verify(publicKey32: bytes, message: bytes, signature64: bytes): bool
```

Whether SIGNATURE64 is a valid Ed25519 signature of MESSAGE by PUBLICKEY32.

Effects: fail.

### `p256Key`

```gizlang
function p256Key(sys: System): bytes throws IoError
```

A uniformly sampled P-256 private scalar.

Effects: fail, io.

### `p256PublicKey`

```gizlang
function p256PublicKey(key32: bytes): Option<bytes>
```

Public point as the 64-byte x || y, in big-endian order.

Effects: fail.

### `es256Sign`

```gizlang
function es256Sign(key32: bytes, message: bytes): Option<bytes>
```

RFC 6979 SHA-256 ECDSA; RFC 7518 raw 32-byte r || 32-byte s.

Effects: fail.

### `es256Verify`

```gizlang
function es256Verify(publicKey64: bytes, message: bytes, signature64: bytes): bool
```

Whether SIGNATURE64 (r and s, 32 bytes each) is a valid ES256 signature of MESSAGE by the P-256 key PUBLICKEY64 (x and y, 32 bytes each).

Effects: fail.

### `p256Jwk`

```gizlang
function p256Jwk(publicKey64: bytes): Json requires publicKey64.length === 64
```

RFC 7638 canonical public JWK and its SHA-256 thumbprint.

Effects: fail.

### `p256Thumbprint`

```gizlang
function p256Thumbprint(publicKey64: bytes): string requires publicKey64.length === 64
```

The RFC 7638 SHA-256 thumbprint of the P-256 key, in base64url.

Effects: fail.

### `der`

```gizlang
function der(tag: u64, contents: bytes): bytes requires tag <256u { let out = b""
```

DER tag and definite length. Callers supply the contents.

Effects: fail.

### `derInteger`

```gizlang
function derInteger(data: bytes): bytes
```

DATA (a big-endian unsigned integer) as a DER INTEGER: leading zeros dropped, one zero kept before a high bit.

Effects: fail.

### `es256Der`

```gizlang
function es256Der(signature64: bytes): bytes requires signature64.length === 64
```

The DER form (an ASN.1 sequence of two integers) of a 64-byte ES256 signature.

Effects: fail.

### `p1363ToDer`

```gizlang
function p1363ToDer(signature: bytes): bytes
```

An ECDSA or DSA signature r||s of two equal halves (IEEE P1363) as its DER SEQUENCE of two INTEGERs.

Effects: fail.

### `derToP1363`

```gizlang
function derToP1363(der: bytes, size: i64): bytes
```

A DER ECDSA or DSA signature as r||s (IEEE P1363) of SIZE-byte halves; DER unchanged when it is not such a SEQUENCE.

Effects: fail.

### `p256PrivatePem`

```gizlang
function p256PrivatePem(key32: bytes): Option<string>
```

PKCS#8 private key, suitable for Tls credentials.

Effects: fail.

### `pemEncode`

```gizlang
function pemEncode(label: string, data: bytes): string
```

DATA as PEM text under LABEL, in lines of 64 base64 characters.

Effects: fail.

### `p256Csr`

```gizlang
function p256Csr(key32: bytes, domains: Vec<string>): Option<bytes>
```

PKCS#10 DER request with CN and SAN dNSNames. Refuse non-ASCII DNS names.

Effects: fail.

### `dnsName`

```gizlang
function dnsName(name: string): bool
```

Whether NAME is an ASCII DNS name: at most 253 bytes, labels of 1 to 63 letters, digits or hyphens, with no hyphen at either end.

Effects: fail.

### `certificateValidity`

```gizlang
function certificateValidity(chain: bytes): Option<Validity>
```

The validity period of the first certificate of a PEM CHAIN, or none when it is not a bounded, well-formed certificate. It checks no trust.

Effects: fail.

### `passphraseCallback`

```gizlang
function passphraseCallback(buffer: u64, size: i64, flag: i64, user: u64): i64
```

The passphrase a key reader gets: the C string given as `user`, or no passphrase (-1) when it is empty.

Effects: fail.

### `lastError`

```gizlang
function lastError(): string
```

The last OpenSSL error as text, the queue cleared.

Effects: fail.

### `hasDigest`

```gizlang
function hasDigest(name: string): bool
```

Whether NAME is a digest libcrypto knows ("sha256", "RSA-SHA256", "shake128", ...).

### `digestSize`

```gizlang
function digestSize(name: string): Option<i64>
```

The output size in bytes of the digest NAME, or none when libcrypto does not know it.

### `newDigest`

```gizlang
function newDigest(name: string): Option<Digest>
```

A hash with the libcrypto digest NAME, or none when libcrypto does not know it.

Effects: fail.

### `digest`

```gizlang
function digest(name: string, data: bytes): Option<bytes>
```

The hash of DATA with the libcrypto digest NAME, or none when libcrypto does not know it.

Effects: fail.

### `newHmac`

```gizlang
function newHmac(name: string, key: bytes): Option<Hmac>
```

An HMAC with the libcrypto digest NAME and KEY, or none when libcrypto does not know the digest.

### `hmac`

```gizlang
function hmac(name: string, key: bytes, data: bytes): Option<bytes>
```

The HMAC of DATA with the libcrypto digest NAME and KEY, or none when libcrypto does not know the digest.

Effects: fail.

### `pbkdf2`

```gizlang
function pbkdf2(name: string, password: bytes, salt: bytes, iterations: i64, length: i64): Option<bytes>
```

PBKDF2 with the named digest.

Effects: fail.

### `scrypt`

```gizlang
function scrypt(password: bytes, salt: bytes, n: i64, r: i64, p: i64, maxMemory: i64, length: i64): Option<bytes>
```

scrypt (RFC 7914); none when the parameters exceed MAXMEMORY bytes.

Effects: fail.

### `hkdf`

```gizlang
function hkdf(name: string, key: bytes, salt: bytes, info: bytes, length: i64): Option<bytes>
```

HKDF (RFC 5869) with the named digest.

Effects: fail.

### `randomBytes`

```gizlang
function randomBytes(n: i64): bytes
```

N random bytes from libcrypto's generator.

Effects: fail.

### `cipherInfo`

```gizlang
function cipherInfo(name: string): Option<CipherInfo>
```

The key, IV and block sizes and the mode of the cipher NAME, or none when libcrypto does not know it.

Effects: fail.

### `cipherInfoByNid`

```gizlang
function cipherInfoByNid(nid: i64): Option<CipherInfo>
```

The key, IV and block sizes and the mode of the cipher with the object id NID, or none when libcrypto does not know
it.

Effects: fail.

### `cipherAccepts`

```gizlang
function cipherAccepts(name: string, keyLength: i64, ivLength: i64): bool
```

Whether a key or iv length is one the cipher takes: a test init with that length.

Effects: fail.

### `newCipher`

```gizlang
function newCipher(name: string, encrypt: bool, key: bytes, iv: bytes, authTagLength: i64): Cipher throws string
```

The cipher NAME with KEY and IV, encrypting or decrypting. An AEAD mode takes any iv length and, for CCM (and
OCB), the tag length (AUTHTAGLENGTH; -1 keeps the default). Errors name what libcrypto refused.

Effects: fail.

### `rawKey`

```gizlang
function rawKey(kind: string, data: bytes, isPrivate: bool): Option<Key>
```

A key of KIND (ed25519, ed448, x25519, x448) from its raw bytes.

Effects: fail.

### `parsePrivateKey`

```gizlang
function parsePrivateKey(data: bytes, format: i64, keyType: i64, passphrase: string): Key throws string
```

A private key from PEM or DER (FORMAT_*) of TYPE (-1: any PEM, else keyType TYPE_PKCS1/PKCS8/SEC1 for DER), decrypted
with PASSPHRASE when it is one.

Effects: fail.

### `parsePublicKey`

```gizlang
function parsePublicKey(data: bytes, format: i64, keyType: i64, passphrase: string): Key throws string
```

A public key from PEM (any of SPKI, PKCS1 "RSA PUBLIC KEY", a certificate, or the public half of a private key)
or DER of TYPE (TYPE_SPKI or TYPE_PKCS1).

Effects: fail.

### `curveNid`

```gizlang
function curveNid(name: string): i64
```

The curve nid of NAME (its short name or NIST name).

### `nidName`

```gizlang
function nidName(nid: i64): string
```

The short name of the object id NID ("SHA256", "prime256v1").

### `generateKey`

```gizlang
function generateKey(kind: string, bits: i64, curve: string, exponent: i64, qBits: i64, generator: i64): Key throws string
```

A new key pair: KIND is rsa, rsa-pss, dsa, dh, ec, ed25519, ed448, x25519 or x448; BITS the modulus (rsa, dsa,
dh prime) length, CURVE the EC curve or DH group name, EXPONENT the RSA public exponent.

Effects: fail.

### `sign`

```gizlang
function sign(key: Key, digestName: string, data: bytes, padding: i64, saltLength: i64): bytes throws string
```

DATA signed with KEY, after the named digest (empty: none, as Ed25519 wants). RSA takes PADDING and, for PSS,
SALTLENGTH (-1: the digest size, -2: the most).

Effects: fail.

### `verify`

```gizlang
function verify(key: Key, digestName: string, data: bytes, signature: bytes, padding: i64, saltLength: i64): bool throws string
```

Whether SIGNATURE is KEY's over DATA (the options of sign).

Effects: fail.

### `rsaCipher`

```gizlang
function rsaCipher(key: Key, encrypt: bool, isPrivate: bool, data: bytes, padding: i64, oaepDigest: string, label: bytes): bytes throws string
```

RSA encryption or decryption of DATA with KEY (ENCRYPT), with PADDING; OAEP takes the digest and label.

Effects: fail.

### `derive`

```gizlang
function derive(key: Key, peer: Key): bytes throws string
```

The shared secret of KEY with PEER (ECDH, X25519, DH).

Effects: fail.

### `randomPrime`

```gizlang
function randomPrime(bits: i64, safe: bool): Option<bytes>
```

A random prime of BITS bits (SAFE: (p-1)/2 prime too), big-endian.

Effects: fail.

### `isPrime`

```gizlang
function isPrime(data: bytes): bool
```

Whether the big-endian number DATA is (probably) prime.

### `textParam`

```gizlang
function textParam(name: string, text: string): Param
```

A key parameter NAME with a text value.

### `numberParam`

```gizlang
function numberParam(name: string, data: bytes): Param
```

A key parameter NAME with a big number value, in the bytes that Key.numberParam gives.

### `octetParam`

```gizlang
function octetParam(name: string, data: bytes): Param
```

A key parameter NAME with a byte-string value.

### `keyFromParams`

```gizlang
function keyFromParams(kind: string, selection: i64, params: Vec<Param>): Key throws string
```

A key of KIND ("RSA", "EC", "DH", "DSA") assembled from PARAMS; an EC private key without its public point gets the point computed.

Effects: fail.

### `generateFromParams`

```gizlang
function generateFromParams(params: Key): Key throws string
```

A fresh key pair over the domain parameters of PARAMS (a DH or DSA parameter key).

Effects: fail.

### `curves`

```gizlang
function curves(): Vec<string>
```

The names of the built-in EC curves.

Effects: fail.

### `digests`

```gizlang
function digests(): Vec<string>
```

The digest names libcrypto answers to, sorted. The candidates are OpenSSL's own name table; a name outside it is not listed.

Effects: fail.

### `ciphers`

```gizlang
function ciphers(): Vec<string>
```

The cipher names libcrypto answers to, sorted.

Effects: fail.

### `emptyKey`

```gizlang
function emptyKey(): Key
```

No key (handle 0): the placeholder a key holder starts with.

### `emptyDigest`

```gizlang
function emptyDigest(): Digest
```

A digest holder's placeholder: no context, no size.

### `ecKeyFromPrivate`

```gizlang
function ecKeyFromPrivate(curve: string, priv: bytes): Key throws string
```

An EC key pair of CURVE from its private scalar alone: the public point is priv·G (fromdata wants both).

Effects: fail.

## Methods

### `Sha256.update`

```gizlang
function Sha256.update(self: mut Sha256, data: bytes): void
```

Adds DATA to the hash.

Effects: fail.

### `Sha256.digest`

```gizlang
function Sha256.digest(self: Sha256): bytes
```

The 32-byte hash of the data added so far. The hash can take more data after this.

Effects: fail.

### `Md5.update`

```gizlang
function Md5.update(self: mut Md5, data: bytes): void
```

Adds DATA to the hash.

Effects: fail.

### `Md5.digest`

```gizlang
function Md5.digest(self: Md5): bytes
```

The 16-byte hash of the data added so far. The hash can take more data after this.

Effects: fail.

### `Sha512.update`

```gizlang
function Sha512.update(self: mut Sha512, data: bytes): void
```

Adds DATA to the hash.

Effects: fail.

### `Sha512.digest`

```gizlang
function Sha512.digest(self: Sha512): bytes
```

The 64-byte hash of the data added so far. The hash can take more data after this.

Effects: fail.

### `Digest.update`

```gizlang
function Digest.update(self: Digest, data: bytes): void
```

Adds DATA to the hash.

Effects: fail.

### `Digest.size`

```gizlang
function Digest.size(self: Digest): i64
```

The output size in bytes.

### `Digest.isXof`

```gizlang
function Digest.isXof(self: Digest): bool
```

Whether the digest has an output of any length (SHAKE).

### `Digest.copy`

```gizlang
function Digest.copy(self: Digest): Digest
```

A copy at the same state, so one prefix digests to several ends.

### `Digest.digest`

```gizlang
function Digest.digest(self: Digest, length: i64): bytes
```

The digest, LENGTH bytes of it for an XOF (-1: the algorithm's size); the context is freed.

Effects: fail.

### `Hmac.update`

```gizlang
function Hmac.update(self: Hmac, data: bytes): void
```

Adds DATA to the HMAC.

Effects: fail.

### `Hmac.digest`

```gizlang
function Hmac.digest(self: Hmac): bytes
```

The HMAC of the data added so far.

Effects: fail.

### `Cipher.info`

```gizlang
function Cipher.info(self: Cipher): CipherInfo
```

The sizes and the mode of the cipher.

### `Cipher.isAead`

```gizlang
function Cipher.isAead(self: Cipher): bool
```

Whether the cipher is an AEAD mode (GCM, CCM, OCB, ChaCha20-Poly1305).

### `Cipher.isCcm`

```gizlang
function Cipher.isCcm(self: Cipher): bool
```

Whether the cipher is a CCM mode, which needs the whole length before the data.

### `Cipher.setPadding`

```gizlang
function Cipher.setPadding(self: Cipher, on: bool): bool
```

Turns block padding on or off; false when the cipher refuses.

### `Cipher.setAad`

```gizlang
function Cipher.setAad(self: Cipher, aad: bytes, plaintextLength: i64): bool
```

Associated data of an AEAD cipher, before any update; CCM needs the plaintext length first.

### `Cipher.tag`

```gizlang
function Cipher.tag(self: Cipher): bytes
```

The tag of a finished AEAD encryption.

### `Cipher.setTag`

```gizlang
function Cipher.setTag(self: mut Cipher, tag: bytes): bool
```

The tag to check, before final() of an AEAD decryption.

### `Cipher.update`

```gizlang
function Cipher.update(self: Cipher, data: bytes): Option<bytes>
```

Encrypts or decrypts DATA; the output so far, or none when libcrypto refuses.

Effects: fail.

### `Cipher.final`

```gizlang
function Cipher.final(self: mut Cipher): Option<bytes>
```

The last block and, for AEAD encryption, the tag kept for tag(); the context is freed. None when the data or
the tag is wrong.

Effects: fail.

### `Key.release`

```gizlang
function Key.release(self: Key): void
```

Gives the key back to libcrypto. The key must not be used after this.

### `Key.handle`

```gizlang
function Key.handle(self: Key): u64
```

The EVP_PKEY pointer of the key, for a native call.

### `Key.share`

```gizlang
function Key.share(self: Key): Key
```

A second reference to the same key. Each reference is released on its own.

### `Key.kind`

```gizlang
function Key.kind(self: Key): string
```

The key's kind as Node names it: rsa, rsa-pss, dsa, dh, ec, ed25519, ed448, x25519, x448.

### `Key.bits`

```gizlang
function Key.bits(self: Key): i64
```

The size of the key in bits (the modulus of RSA, the curve of EC).

### `Key.size`

```gizlang
function Key.size(self: Key): i64
```

The largest size in bytes of a signature or ciphertext with the key.

### `Key.equals`

```gizlang
function Key.equals(self: Key, other: Key): bool
```

Whether the two keys hold the same key material.

### `Key.textParam`

```gizlang
function Key.textParam(self: Key, name: string): Option<string>
```

A text parameter of the key ("group" of an EC key), if it has it.

Effects: fail.

### `Key.intParam`

```gizlang
function Key.intParam(self: Key, name: string): Option<i64>
```

An integer parameter of the key, if it has it.

### `Key.numberParam`

```gizlang
function Key.numberParam(self: Key, name: string): Option<bytes>
```

A big-number parameter ("n", "e", "p", "g", ...) as big-endian bytes.

Effects: fail.

### `Key.octetParam`

```gizlang
function Key.octetParam(self: Key, name: string): Option<bytes>
```

A byte-string parameter of the key ("pub" of an EC key), if it has it.

Effects: fail.

### `Key.raw`

```gizlang
function Key.raw(self: Key, isPrivate: bool): Option<bytes>
```

The raw public (or private) key bytes of an Edwards or Montgomery key.

Effects: fail.

### `Key.write`

```gizlang
function Key.write(self: Key, isPrivate: bool, format: i64, keyType: i64, cipher: string, passphrase: bytes): bytes throws string
```

The key written in FORMAT as TYPE; a private key encrypted with CIPHER and PASSPHRASE when CIPHER is one.

Effects: fail.

### `Key.setTextParam`

```gizlang
function Key.setTextParam(self: Key, name: string, value: string): bool
```

Sets a text parameter of the key ("point-format": "compressed", "uncompressed" or "hybrid" for EC keys).

## Constants

### `SHA256_DIGEST_BYTES`

```gizlang
const SHA256_DIGEST_BYTES = 32
```

The size of a SHA-256 digest in bytes.

### `ED25519_SEED_BYTES`

```gizlang
const ED25519_SEED_BYTES = 32
```

The size of an Ed25519 seed in bytes.

### `ED25519_PUBLIC_KEY_BYTES`

```gizlang
const ED25519_PUBLIC_KEY_BYTES = 32
```

The size of an Ed25519 public key in bytes.

### `ED25519_SIGNATURE_BYTES`

```gizlang
const ED25519_SIGNATURE_BYTES = 64
```

The size of an Ed25519 signature in bytes.

### `FORMAT_PEM`

```gizlang
const FORMAT_PEM = 0
```

The key encoding PEM, 0.

### `FORMAT_DER`

```gizlang
const FORMAT_DER = 1
```

The key encoding DER, 1.

### `TYPE_PKCS1`

```gizlang
const TYPE_PKCS1 = 0
```

The key structure PKCS1, 0.

### `TYPE_PKCS8`

```gizlang
const TYPE_PKCS8 = 1
```

The key structure PKCS8, 1.

### `TYPE_SPKI`

```gizlang
const TYPE_SPKI = 2
```

The key structure SPKI, 2.

### `TYPE_SEC1`

```gizlang
const TYPE_SEC1 = 3
```

The key structure SEC1, 3.

### `RSA_PKCS1_PADDING`

```gizlang
const RSA_PKCS1_PADDING = 1
```

The RSA padding mode rsa pkcs1 padding, 1.

### `RSA_NO_PADDING`

```gizlang
const RSA_NO_PADDING = 3
```

The RSA padding mode rsa no padding, 3.

### `RSA_PKCS1_OAEP_PADDING`

```gizlang
const RSA_PKCS1_OAEP_PADDING = 4
```

The RSA padding mode rsa pkcs1 oaep padding, 4.

### `RSA_PKCS1_PSS_PADDING`

```gizlang
const RSA_PKCS1_PSS_PADDING = 6
```

The RSA padding mode rsa pkcs1 pss padding, 6.

### `PARAM_TEXT`

```gizlang
const PARAM_TEXT = 0
```

The kind of a key parameter: text, 0.

### `PARAM_NUMBER`

```gizlang
const PARAM_NUMBER = 1
```

The kind of a key parameter: number, 1.

### `PARAM_OCTET`

```gizlang
const PARAM_OCTET = 2
```

The kind of a key parameter: octet, 2.

### `SELECT_PARAMETERS`

```gizlang
const SELECT_PARAMETERS = 132
```

What a key built from parameters holds (EVP_PKEY_* selections).

### `SELECT_PUBLIC`

```gizlang
const SELECT_PUBLIC = 134
```

The key selection public, 134.

### `SELECT_KEYPAIR`

```gizlang
const SELECT_KEYPAIR = 135
```

The key selection keypair, 135.

gizlang:crypto

Modern cryptographic primitives in Gizlang (RFC 5869/8439/7748/8032). SHA-256 blocks run in the runtime on the CPU's SHA instructions where it has them, and AES-GCM in libcrypto. Length contracts are public. Secret arithmetic uses fixed loops and masks.

gizlang

import * as Crypto from "gizlang:crypto";

Types

`Sha256`

gizlang

type Sha256

Only a partial block is copied; full blocks are read directly. Digest preserves the hasher.

Opaque: create and use it through this module's functions.

`Md5`

gizlang

type Md5

RFC 1321 interoperability checksum, not a collision-resistant security primitive. Only a partial block is buffered, just as in Sha256.

Opaque: create and use it through this module's functions.

`Sha512`

gizlang

type Sha512

Only a partial block is copied; full blocks are read directly. The schedule is allocated once per hasher, reused in place; digest preserves the hasher.

Opaque: create and use it through this module's functions.

`Validity`

gizlang

type Validity = { from: i64; until: i64; }

A certificate's validity period, in milliseconds since the epoch.

from: i64
until: i64

`Digest`

gizlang

type Digest

A digest in progress (an EVP_MD_CTX); digest() ends it.

Opaque: create and use it through this module's functions.

`Hmac`

gizlang

type Hmac

An HMAC computation in progress: feed it bytes, then take the MAC.

Opaque: create and use it through this module's functions.

`CipherInfo`

gizlang

type CipherInfo = { name: string; nid: i64; blockSize: i64; ivLength: i64; keyLength: i64; mode: string; }

What a cipher is: its name, numeric id, block size, IV length, key length and mode.

name: string
nid: i64
blockSize: i64
ivLength: i64
keyLength: i64
mode: string

`Cipher`

gizlang

type Cipher

A cipher in progress (an EVP_CIPHER_CTX): update() as much as you like, then final().

Opaque: create and use it through this module's functions.

`Key`

gizlang

type Key

An asymmetric key or key pair (an EVP_PKEY, reference counted).

Opaque: create and use it through this module's functions.

`Param`

gizlang

type Param = { name: string; kind: i64; text: string; data: bytes; }

One key parameter: a text (PARAM_TEXT, "group"), a big number (PARAM_NUMBER, "n") or an octet string (PARAM_OCTET, "pub").

name: string
kind: i64
text: string
data: bytes

Functions

`equal`

gizlang

function equal(a: bytes, b: bytes): bool

Scans all bytes for equal public lengths, including on a mismatch.

Effects: fail.

`newSha256`

gizlang

function newSha256(): Sha256

A SHA-256 hash of no data.

Effects: fail.

`sha256`

gizlang

function sha256(data: bytes): bytes

The SHA-256 hash of DATA (32 bytes).

Effects: fail.

`sha224`

gizlang

function sha224(data: bytes): bytes

FIPS 180-4 SHA-224: SHA-256 from its own initial words, cut to 28 bytes.

Effects: fail.

`newMd5`

gizlang

function newMd5(): Md5

An MD5 hash of no data. MD5 is broken for security; use it only where a format asks for it.

Effects: fail.

`md5`

gizlang

function md5(data: bytes): bytes

The MD5 hash of DATA (16 bytes). MD5 is broken for security; use it only where a format asks for it.

Effects: fail.

`md5Crypt`

gizlang

function md5Crypt(password: bytes, salt: bytes, magic: string): string

The MD5-based password hash of Poul-Henning Kamp ( $1$ ), and Apache's variant $apr1$ (htpasswd -m): magic is "$1$" or "$apr1$". The result is magic + salt + "$" + 22 characters. It is a stored-password check for old htpasswd files, not a hash to choose.

Effects: fail.

`bcrypt`

gizlang

function bcrypt(password: bytes, setting: string): string

The bcrypt hash ( $2a$ , $2b$ or $2y$ , htpasswd -B) of PASSWORD under SETTING: a stored hash or its first 29 bytes ($2y$10$ and 22 characters of salt). The result is the 60-character hash, or "" for a setting that is not one, so it never equals a stored hash. The cost is 2^N rounds of key schedule, about 50 ms at 10: check a credential once, not per request.

Effects: fail.

`sha1`

gizlang

function sha1(data: bytes): bytes

RFC 3174 SHA-1, for protocols that name it (the WebSocket handshake, RFC 6455), not a collision-resistant security primitive.

Effects: fail.

`hmacSha256`

gizlang

function hmacSha256(key: bytes, data: bytes): bytes

The HMAC-SHA-256 of DATA with KEY (32 bytes).

Effects: fail.

`jwtSign`

gizlang

function jwtSign(key: bytes, claims: Json): string

A JSON Web Token (RFC 7519) of CLAIMS, a JSON object, signed by KEY with HMAC-SHA256 (alg HS256).

Effects: fail.

`jwtClaims`

gizlang

function jwtClaims(key: bytes, token: string, now: i64): Option<Json>

The claims of TOKEN when KEY signed it with HS256 and it is valid at NOW (seconds since 1970): not after its "exp" and not before its "nbf". A token without "exp" does not expire.

Effects: fail.

`jwtPart`

gizlang

function jwtPart(segment: string): Option<Json>

One part of a JSON Web Token (its header or claims), unverified: its base64url JSON, when it is that.

Effects: fail.

`newSha512`

gizlang

function newSha512(): Sha512

A SHA-512 hash of no data.

Effects: fail.

`sha512`

gizlang

function sha512(data: bytes): bytes

The SHA-512 hash of DATA (64 bytes).

Effects: fail.

`sha384`

gizlang

function sha384(data: bytes): bytes

FIPS 180-4 SHA-384: SHA-512 from its own initial words, cut to 48 bytes.

Effects: fail.

`hmacSha512`

gizlang

function hmacSha512(key: bytes, data: bytes): bytes

The HMAC-SHA-512 of DATA with KEY (64 bytes).

Effects: fail.

`hkdfSha256`

gizlang

function hkdfSha256(secret: bytes, salt: bytes, info: bytes, length: i64): bytes requires length> = 0 requires length <= 8160

RFC 5869 extract then expand, at most 255 SHA-256 blocks.

Effects: fail.

`pbkdf2Sha256`

gizlang

function pbkdf2Sha256(password: bytes, salt: bytes, iterations: i64, length: i64): bytes requires iterations> = 1 requires length> = 1 requires length <= 8160 { let k = password

RFC 8018 PBKDF2 with HMAC-SHA256: length bytes of a key stretched from password under salt by iterations rounds, as a stored password's hash (OWASP asks 600000 rounds). The keyed hasher states are made once, so a round is two compressions.

Effects: fail.

`chacha20Poly1305Seal`

gizlang

function chacha20Poly1305Seal(key32: bytes, nonce12: bytes, plaintext: bytes, aad: bytes): bytes requires key32.length === 32 requires nonce12.length === 12

RFC 8439: ciphertext followed by the 16-byte tag. Never reuse a key/nonce pair.

Effects: fail.

`chacha20Poly1305Open`

gizlang

function chacha20Poly1305Open(key32: bytes, nonce12: bytes, sealed: bytes, aad: bytes): Option<bytes> requires key32.length === 32 requires nonce12.length === 12

The plaintext of SEALED (ciphertext and its 16-byte tag) under ChaCha20-Poly1305 with KEY32, NONCE12 and AAD; none when the tag does not match.

Effects: fail.

`aes256GcmSeal`

gizlang

function aes256GcmSeal(key32: bytes, nonce12: bytes, plaintext: bytes, aad: bytes): bytes requires key32.length === 32 requires nonce12.length === 12

NIST SP 800-38D with a 96-bit nonce: ciphertext followed by the 16-byte tag. Never reuse a key/nonce pair.

Effects: fail.

`aes256GcmOpen`

gizlang

function aes256GcmOpen(key32: bytes, nonce12: bytes, sealed: bytes, aad: bytes): Option<bytes> requires key32.length === 32 requires nonce12.length === 12

The plaintext of SEALED (ciphertext and its 16-byte tag) under AES-256-GCM with KEY32, NONCE12 and AAD; none when the tag does not match.

Effects: fail.

`x25519`

gizlang

function x25519(scalar32: bytes, point32: bytes): bytes requires scalar32.length === 32 requires point32.length === 32

RFC 7748 decoding masks the high coordinate bit and clamps the scalar. A low-order input gives all-zero output; protocols must reject that secret.

Effects: fail.

`x25519Base`

gizlang

function x25519Base(scalar32: bytes): bytes requires scalar32.length === 32

The X25519 public key of the private SCALAR32.

Effects: fail.

`ed25519PublicKey`

gizlang

function ed25519PublicKey(seed32: bytes): bytes requires seed32.length === ED25519_SEED_BYTES

The 32-byte Ed25519 public key of the private SEED32.

Effects: fail.

`ed25519Sign`

gizlang

function ed25519Sign(seed32: bytes, message: bytes): bytes requires seed32.length === ED25519_SEED_BYTES

The 64-byte Ed25519 signature of MESSAGE with the private SEED32.

Effects: fail.

`ed25519Verify`

gizlang

function ed25519Verify(publicKey32: bytes, message: bytes, signature64: bytes): bool

Whether SIGNATURE64 is a valid Ed25519 signature of MESSAGE by PUBLICKEY32.

Effects: fail.

`p256Key`

gizlang

function p256Key(sys: System): bytes throws IoError

A uniformly sampled P-256 private scalar.

Effects: fail, io.

`p256PublicKey`

gizlang

function p256PublicKey(key32: bytes): Option<bytes>

Public point as the 64-byte x || y, in big-endian order.

Effects: fail.

`es256Sign`

gizlang

function es256Sign(key32: bytes, message: bytes): Option<bytes>

RFC 6979 SHA-256 ECDSA; RFC 7518 raw 32-byte r || 32-byte s.

Effects: fail.

`es256Verify`

gizlang

function es256Verify(publicKey64: bytes, message: bytes, signature64: bytes): bool

Whether SIGNATURE64 (r and s, 32 bytes each) is a valid ES256 signature of MESSAGE by the P-256 key PUBLICKEY64 (x and y, 32 bytes each).

Effects: fail.

`p256Jwk`

gizlang

function p256Jwk(publicKey64: bytes): Json requires publicKey64.length === 64

RFC 7638 canonical public JWK and its SHA-256 thumbprint.

Effects: fail.

`p256Thumbprint`

gizlang

function p256Thumbprint(publicKey64: bytes): string requires publicKey64.length === 64

The RFC 7638 SHA-256 thumbprint of the P-256 key, in base64url.

Effects: fail.

`der`

gizlang

function der(tag: u64, contents: bytes): bytes requires tag <256u { let out = b""

DER tag and definite length. Callers supply the contents.

Effects: fail.

`derInteger`

gizlang

function derInteger(data: bytes): bytes

DATA (a big-endian unsigned integer) as a DER INTEGER: leading zeros dropped, one zero kept before a high bit.

Effects: fail.

`es256Der`

gizlang

function es256Der(signature64: bytes): bytes requires signature64.length === 64

The DER form (an ASN.1 sequence of two integers) of a 64-byte ES256 signature.

Effects: fail.

`p1363ToDer`

gizlang

function p1363ToDer(signature: bytes): bytes

An ECDSA or DSA signature r||s of two equal halves (IEEE P1363) as its DER SEQUENCE of two INTEGERs.

Effects: fail.

`derToP1363`

gizlang

function derToP1363(der: bytes, size: i64): bytes

A DER ECDSA or DSA signature as r||s (IEEE P1363) of SIZE-byte halves; DER unchanged when it is not such a SEQUENCE.

Effects: fail.

`p256PrivatePem`

gizlang

function p256PrivatePem(key32: bytes): Option<string>

PKCS#8 private key, suitable for Tls credentials.

Effects: fail.

`pemEncode`

gizlang

function pemEncode(label: string, data: bytes): string

DATA as PEM text under LABEL, in lines of 64 base64 characters.

Effects: fail.

`p256Csr`

gizlang

function p256Csr(key32: bytes, domains: Vec<string>): Option<bytes>

PKCS#10 DER request with CN and SAN dNSNames. Refuse non-ASCII DNS names.

Effects: fail.

`dnsName`

gizlang

function dnsName(name: string): bool

Whether NAME is an ASCII DNS name: at most 253 bytes, labels of 1 to 63 letters, digits or hyphens, with no hyphen at either end.

Effects: fail.

`certificateValidity`

gizlang

function certificateValidity(chain: bytes): Option<Validity>

The validity period of the first certificate of a PEM CHAIN, or none when it is not a bounded, well-formed certificate. It checks no trust.

Effects: fail.

`passphraseCallback`

gizlang

function passphraseCallback(buffer: u64, size: i64, flag: i64, user: u64): i64

The passphrase a key reader gets: the C string given as user, or no passphrase (-1) when it is empty.

Effects: fail.

`lastError`

gizlang

function lastError(): string

The last OpenSSL error as text, the queue cleared.

Effects: fail.

`hasDigest`

gizlang

function hasDigest(name: string): bool

Whether NAME is a digest libcrypto knows ("sha256", "RSA-SHA256", "shake128", ...).

`digestSize`

gizlang

function digestSize(name: string): Option<i64>

The output size in bytes of the digest NAME, or none when libcrypto does not know it.

`newDigest`

gizlang

function newDigest(name: string): Option<Digest>

A hash with the libcrypto digest NAME, or none when libcrypto does not know it.

Effects: fail.

`digest`

gizlang

function digest(name: string, data: bytes): Option<bytes>

The hash of DATA with the libcrypto digest NAME, or none when libcrypto does not know it.

Effects: fail.

`newHmac`

gizlang

function newHmac(name: string, key: bytes): Option<Hmac>

An HMAC with the libcrypto digest NAME and KEY, or none when libcrypto does not know the digest.

`hmac`

gizlang

function hmac(name: string, key: bytes, data: bytes): Option<bytes>

The HMAC of DATA with the libcrypto digest NAME and KEY, or none when libcrypto does not know the digest.

Effects: fail.

`pbkdf2`

gizlang

function pbkdf2(name: string, password: bytes, salt: bytes, iterations: i64, length: i64): Option<bytes>

PBKDF2 with the named digest.

Effects: fail.

`scrypt`

gizlang

function scrypt(password: bytes, salt: bytes, n: i64, r: i64, p: i64, maxMemory: i64, length: i64): Option<bytes>

scrypt (RFC 7914); none when the parameters exceed MAXMEMORY bytes.

Effects: fail.

`hkdf`

gizlang

function hkdf(name: string, key: bytes, salt: bytes, info: bytes, length: i64): Option<bytes>

HKDF (RFC 5869) with the named digest.

Effects: fail.

`randomBytes`

gizlang

function randomBytes(n: i64): bytes

N random bytes from libcrypto's generator.

Effects: fail.

`cipherInfo`

gizlang

function cipherInfo(name: string): Option<CipherInfo>

The key, IV and block sizes and the mode of the cipher NAME, or none when libcrypto does not know it.

Effects: fail.

`cipherInfoByNid`

gizlang

function cipherInfoByNid(nid: i64): Option<CipherInfo>

The key, IV and block sizes and the mode of the cipher with the object id NID, or none when libcrypto does not know it.

Effects: fail.

`cipherAccepts`

gizlang

function cipherAccepts(name: string, keyLength: i64, ivLength: i64): bool

Whether a key or iv length is one the cipher takes: a test init with that length.

Effects: fail.

`newCipher`

gizlang

function newCipher(name: string, encrypt: bool, key: bytes, iv: bytes, authTagLength: i64): Cipher throws string

The cipher NAME with KEY and IV, encrypting or decrypting. An AEAD mode takes any iv length and, for CCM (and OCB), the tag length (AUTHTAGLENGTH; -1 keeps the default). Errors name what libcrypto refused.

Effects: fail.

`rawKey`

gizlang

function rawKey(kind: string, data: bytes, isPrivate: bool): Option<Key>

A key of KIND (ed25519, ed448, x25519, x448) from its raw bytes.

Effects: fail.

`parsePrivateKey`

gizlang

function parsePrivateKey(data: bytes, format: i64, keyType: i64, passphrase: string): Key throws string

A private key from PEM or DER (FORMAT_*) of TYPE (-1: any PEM, else keyType TYPE_PKCS1/PKCS8/SEC1 for DER), decrypted with PASSPHRASE when it is one.

Effects: fail.

`parsePublicKey`

gizlang

function parsePublicKey(data: bytes, format: i64, keyType: i64, passphrase: string): Key throws string

A public key from PEM (any of SPKI, PKCS1 "RSA PUBLIC KEY", a certificate, or the public half of a private key) or DER of TYPE (TYPE_SPKI or TYPE_PKCS1).

Effects: fail.

`curveNid`

gizlang

function curveNid(name: string): i64

The curve nid of NAME (its short name or NIST name).

`nidName`

gizlang

function nidName(nid: i64): string

The short name of the object id NID ("SHA256", "prime256v1").

`generateKey`

gizlang

function generateKey(kind: string, bits: i64, curve: string, exponent: i64, qBits: i64, generator: i64): Key throws string

A new key pair: KIND is rsa, rsa-pss, dsa, dh, ec, ed25519, ed448, x25519 or x448; BITS the modulus (rsa, dsa, dh prime) length, CURVE the EC curve or DH group name, EXPONENT the RSA public exponent.

Effects: fail.

`sign`

gizlang

function sign(key: Key, digestName: string, data: bytes, padding: i64, saltLength: i64): bytes throws string

DATA signed with KEY, after the named digest (empty: none, as Ed25519 wants). RSA takes PADDING and, for PSS, SALTLENGTH (-1: the digest size, -2: the most).

Effects: fail.

`verify`

gizlang

function verify(key: Key, digestName: string, data: bytes, signature: bytes, padding: i64, saltLength: i64): bool throws string

Whether SIGNATURE is KEY's over DATA (the options of sign).

Effects: fail.

`rsaCipher`

gizlang

function rsaCipher(key: Key, encrypt: bool, isPrivate: bool, data: bytes, padding: i64, oaepDigest: string, label: bytes): bytes throws string

RSA encryption or decryption of DATA with KEY (ENCRYPT), with PADDING; OAEP takes the digest and label.

Effects: fail.

`derive`

gizlang

function derive(key: Key, peer: Key): bytes throws string

The shared secret of KEY with PEER (ECDH, X25519, DH).

Effects: fail.

`randomPrime`

gizlang

function randomPrime(bits: i64, safe: bool): Option<bytes>

A random prime of BITS bits (SAFE: (p-1)/2 prime too), big-endian.

Effects: fail.

`isPrime`

gizlang

function isPrime(data: bytes): bool

Whether the big-endian number DATA is (probably) prime.

`textParam`

gizlang

function textParam(name: string, text: string): Param

A key parameter NAME with a text value.

`numberParam`

gizlang

function numberParam(name: string, data: bytes): Param

A key parameter NAME with a big number value, in the bytes that Key.numberParam gives.

`octetParam`

gizlang

function octetParam(name: string, data: bytes): Param

A key parameter NAME with a byte-string value.

`keyFromParams`

gizlang

function keyFromParams(kind: string, selection: i64, params: Vec<Param>): Key throws string

A key of KIND ("RSA", "EC", "DH", "DSA") assembled from PARAMS; an EC private key without its public point gets the point computed.

Effects: fail.

`generateFromParams`

gizlang

function generateFromParams(params: Key): Key throws string

A fresh key pair over the domain parameters of PARAMS (a DH or DSA parameter key).

Effects: fail.

`curves`

gizlang

function curves(): Vec<string>

The names of the built-in EC curves.

Effects: fail.

`digests`

gizlang

function digests(): Vec<string>

The digest names libcrypto answers to, sorted. The candidates are OpenSSL's own name table; a name outside it is not listed.

Effects: fail.

`ciphers`

gizlang

function ciphers(): Vec<string>

The cipher names libcrypto answers to, sorted.

Effects: fail.

`emptyKey`

gizlang

function emptyKey(): Key

No key (handle 0): the placeholder a key holder starts with.

`emptyDigest`

gizlang

function emptyDigest(): Digest

A digest holder's placeholder: no context, no size.

`ecKeyFromPrivate`

gizlang

function ecKeyFromPrivate(curve: string, priv: bytes): Key throws string

An EC key pair of CURVE from its private scalar alone: the public point is priv·G (fromdata wants both).

Effects: fail.

Methods

`Sha256.update`

gizlang

function Sha256.update(self: mut Sha256, data: bytes): void

Adds DATA to the hash.

Effects: fail.

`Sha256.digest`

gizlang

function Sha256.digest(self: Sha256): bytes

The 32-byte hash of the data added so far. The hash can take more data after this.

Effects: fail.

`Md5.update`

gizlang

function Md5.update(self: mut Md5, data: bytes): void

Adds DATA to the hash.

Effects: fail.

`Md5.digest`

gizlang

function Md5.digest(self: Md5): bytes

The 16-byte hash of the data added so far. The hash can take more data after this.

Effects: fail.

`Sha512.update`

gizlang

function Sha512.update(self: mut Sha512, data: bytes): void

Adds DATA to the hash.

Effects: fail.

`Sha512.digest`

gizlang

function Sha512.digest(self: Sha512): bytes

The 64-byte hash of the data added so far. The hash can take more data after this.

Effects: fail.

`Digest.update`

gizlang

function Digest.update(self: Digest, data: bytes): void

Adds DATA to the hash.

Effects: fail.

`Digest.size`

gizlang

function Digest.size(self: Digest): i64

The output size in bytes.

`Digest.isXof`

gizlang

function Digest.isXof(self: Digest): bool

Whether the digest has an output of any length (SHAKE).

`Digest.copy`

gizlang

function Digest.copy(self: Digest): Digest

A copy at the same state, so one prefix digests to several ends.

`Digest.digest`

gizlang

function Digest.digest(self: Digest, length: i64): bytes

The digest, LENGTH bytes of it for an XOF (-1: the algorithm's size); the context is freed.

Effects: fail.

`Hmac.update`

gizlang

function Hmac.update(self: Hmac, data: bytes): void

Adds DATA to the HMAC.

Effects: fail.

`Hmac.digest`

gizlang

function Hmac.digest(self: Hmac): bytes

The HMAC of the data added so far.

Effects: fail.

`Cipher.info`

gizlang

function Cipher.info(self: Cipher): CipherInfo

The sizes and the mode of the cipher.

`Cipher.isAead`

gizlang

function Cipher.isAead(self: Cipher): bool

Whether the cipher is an AEAD mode (GCM, CCM, OCB, ChaCha20-Poly1305).

`Cipher.isCcm`

gizlang

function Cipher.isCcm(self: Cipher): bool

Whether the cipher is a CCM mode, which needs the whole length before the data.

`Cipher.setPadding`

gizlang

function Cipher.setPadding(self: Cipher, on: bool): bool

Turns block padding on or off; false when the cipher refuses.

`Cipher.setAad`

gizlang

function Cipher.setAad(self: Cipher, aad: bytes, plaintextLength: i64): bool

Associated data of an AEAD cipher, before any update; CCM needs the plaintext length first.

`Cipher.tag`

gizlang

function Cipher.tag(self: Cipher): bytes

The tag of a finished AEAD encryption.

`Cipher.setTag`

gizlang

function Cipher.setTag(self: mut Cipher, tag: bytes): bool

The tag to check, before final() of an AEAD decryption.

`Cipher.update`

gizlang

function Cipher.update(self: Cipher, data: bytes): Option<bytes>

Encrypts or decrypts DATA; the output so far, or none when libcrypto refuses.

Effects: fail.

`Cipher.final`

gizlang

function Cipher.final(self: mut Cipher): Option<bytes>

The last block and, for AEAD encryption, the tag kept for tag(); the context is freed. None when the data or the tag is wrong.

Effects: fail.

`Key.release`

gizlang

function Key.release(self: Key): void

Gives the key back to libcrypto. The key must not be used after this.

`Key.handle`

gizlang

function Key.handle(self: Key): u64

The EVP_PKEY pointer of the key, for a native call.

`Key.share`

gizlang

function Key.share(self: Key): Key

A second reference to the same key. Each reference is released on its own.

`Key.kind`

gizlang

function Key.kind(self: Key): string

The key's kind as Node names it: rsa, rsa-pss, dsa, dh, ec, ed25519, ed448, x25519, x448.

`Key.bits`

gizlang

function Key.bits(self: Key): i64

The size of the key in bits (the modulus of RSA, the curve of EC).

`Key.size`

gizlang

function Key.size(self: Key): i64

The largest size in bytes of a signature or ciphertext with the key.

`Key.equals`

gizlang

function Key.equals(self: Key, other: Key): bool

Whether the two keys hold the same key material.

`Key.textParam`

gizlang

function Key.textParam(self: Key, name: string): Option<string>

A text parameter of the key ("group" of an EC key), if it has it.

Effects: fail.

`Key.intParam`

gizlang

function Key.intParam(self: Key, name: string): Option<i64>

An integer parameter of the key, if it has it.

`Key.numberParam`

gizlang

function Key.numberParam(self: Key, name: string): Option<bytes>

A big-number parameter ("n", "e", "p", "g", ...) as big-endian bytes.

Effects: fail.

`Key.octetParam`

gizlang

function Key.octetParam(self: Key, name: string): Option<bytes>

A byte-string parameter of the key ("pub" of an EC key), if it has it.

Effects: fail.

`Key.raw`

gizlang

function Key.raw(self: Key, isPrivate: bool): Option<bytes>

The raw public (or private) key bytes of an Edwards or Montgomery key.

Effects: fail.

`Key.write`

gizlang

function Key.write(self: Key, isPrivate: bool, format: i64, keyType: i64, cipher: string, passphrase: bytes): bytes throws string

The key written in FORMAT as TYPE; a private key encrypted with CIPHER and PASSPHRASE when CIPHER is one.

Effects: fail.

`Key.setTextParam`

gizlang

function Key.setTextParam(self: Key, name: string, value: string): bool

Sets a text parameter of the key ("point-format": "compressed", "uncompressed" or "hybrid" for EC keys).

Constants

`SHA256_DIGEST_BYTES`

gizlang

const SHA256_DIGEST_BYTES = 32

The size of a SHA-256 digest in bytes.

`ED25519_SEED_BYTES`

gizlang

const ED25519_SEED_BYTES = 32

The size of an Ed25519 seed in bytes.

`ED25519_PUBLIC_KEY_BYTES`

gizlang

const ED25519_PUBLIC_KEY_BYTES = 32

The size of an Ed25519 public key in bytes.

`ED25519_SIGNATURE_BYTES`

gizlang

const ED25519_SIGNATURE_BYTES = 64

The size of an Ed25519 signature in bytes.

`FORMAT_PEM`

gizlang

const FORMAT_PEM = 0

The key encoding PEM, 0.

`FORMAT_DER`

gizlang

const FORMAT_DER = 1

The key encoding DER, 1.

`TYPE_PKCS1`

gizlang

const TYPE_PKCS1 = 0

The key structure PKCS1, 0.

`TYPE_PKCS8`

gizlang

const TYPE_PKCS8 = 1

The key structure PKCS8, 1.

`TYPE_SPKI`

gizlang

const TYPE_SPKI = 2

The key structure SPKI, 2.

`TYPE_SEC1`

gizlang

const TYPE_SEC1 = 3

The key structure SEC1, 3.

`RSA_PKCS1_PADDING`

gizlang

const RSA_PKCS1_PADDING = 1

The RSA padding mode rsa pkcs1 padding, 1.

`RSA_NO_PADDING`

gizlang

const RSA_NO_PADDING = 3

The RSA padding mode rsa no padding, 3.

`RSA_PKCS1_OAEP_PADDING`

gizlang

const RSA_PKCS1_OAEP_PADDING = 4

The RSA padding mode rsa pkcs1 oaep padding, 4.

`RSA_PKCS1_PSS_PADDING`

gizlang

const RSA_PKCS1_PSS_PADDING = 6

The RSA padding mode rsa pkcs1 pss padding, 6.

`PARAM_TEXT`

gizlang

const PARAM_TEXT = 0

The kind of a key parameter: text, 0.

`PARAM_NUMBER`

gizlang

const PARAM_NUMBER = 1

The kind of a key parameter: number, 1.

`PARAM_OCTET`

gizlang

const PARAM_OCTET = 2

The kind of a key parameter: octet, 2.

`SELECT_PARAMETERS`

gizlang

const SELECT_PARAMETERS = 132

What a key built from parameters holds (EVP_PKEY_* selections).

`SELECT_PUBLIC`

gizlang

const SELECT_PUBLIC = 134

The key selection public, 134.

`SELECT_KEYPAIR`

gizlang

const SELECT_KEYPAIR = 135

The key selection keypair, 135.