# 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.