Skip to content
Goalchemy

lib/crypto

import "github.com/eugenioenko/goalchemy/lib/crypto"

Package crypto provides bounded native cryptographic capabilities.

Function c csharp go java python rust swift typescript
AES256GCMDecrypt yes yes yes yes yes yes yes yes
AES256GCMEncrypt yes yes yes yes yes yes yes yes
ECDH yes yes yes yes yes yes yes yes
ES256Sign yes yes yes yes yes yes yes yes
ES256Verify yes yes yes yes yes yes yes yes
ES384Sign yes yes yes yes yes yes yes yes
ES384Verify yes yes yes yes yes yes yes yes
ES512Sign yes yes yes yes yes yes yes yes
ES512Verify yes yes yes yes yes yes yes yes
GenerateP256 yes yes yes yes yes yes yes yes
GenerateP384 yes yes yes yes yes yes yes yes
GenerateP521 yes yes yes yes yes yes yes yes
GenerateRSA2048 yes yes yes yes yes yes yes yes
GenerateRSA4096 yes yes yes yes yes yes yes yes
HKDFSHA256 yes yes yes yes yes yes yes yes
HMACSHA256 yes yes yes yes yes yes yes yes
HMACSHA256Verify yes yes yes yes yes yes yes yes
ImportPEM yes yes yes yes yes yes yes yes
Key.Close yes yes yes yes yes yes yes yes
Key.PrivatePEM yes yes yes yes yes yes yes yes
Key.PublicJWK yes yes yes yes yes yes yes yes
Key.PublicPEM yes yes yes yes yes yes yes yes
RS256Sign yes yes yes yes yes yes yes yes
RS256Verify yes yes yes yes yes yes yes yes
RS384Sign yes yes yes yes yes yes yes yes
RS384Verify yes yes yes yes yes yes yes yes
RS512Sign yes yes yes yes yes yes yes yes
RS512Verify yes yes yes yes yes yes yes yes
RSAOAEPDecrypt yes yes yes yes yes yes yes yes
RSAOAEPEncrypt yes yes yes yes yes yes yes yes
Random yes yes yes yes yes yes yes yes
SHA256 yes yes yes yes yes yes yes yes

AES256GCMDecrypt

Section titled “AES256GCMDecrypt”
func AES256GCMDecrypt(key, nonce, data, aad []byte) ([]byte, error)

Authenticated AES-256-GCM decryption of ciphertext followed by its 16-byte tag.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: deterministic
  • Bounds: The key is exactly 32 bytes and the nonce exactly 12; data is ciphertext||tag of 16..64MiB+16 bytes; AAD is at most 64MiB. The output is len(data)-16 bytes.
  • Errors: A wrong key or nonce size, data shorter than the 16-byte tag, or oversized data or AAD returns nil and an error. A tag mismatch returns nil and an error; partial plaintext is never returned.
  • Contract: lib.crypto.aes256_gcm_decrypt 1.0.0

AES256GCMEncrypt

Section titled “AES256GCMEncrypt”
func AES256GCMEncrypt(key, nonce, data, aad []byte) ([]byte, error)

AES-256-GCM encryption returning ciphertext followed by the 16-byte tag, without the nonce.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: deterministic
  • Bounds: The key is exactly 32 bytes and the nonce exactly 12; plaintext and AAD are each at most 64MiB. The output is len(data)+16 bytes; the nonce is not prepended.
  • Errors: A wrong key or nonce size, or plaintext or AAD over 64MiB, returns nil and an error.
  • Contract: lib.crypto.aes256_gcm_encrypt 1.0.0

ECDH

Section titled “ECDH”
func ECDH(privateKey, publicKey *Key) ([]byte, error)

The raw ECDH shared secret (the x-coordinate) of two keys on the same NIST curve, before any KDF.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: deterministic
  • Bounds: The private key must be a P-256, P-384 or P-521 private key; the public key must be on the same curve (a private key uses its public half). The secret is 32, 48 or 66 bytes respectively.
  • Errors: A private key that is not an EC private key, or a public key that is not on the same curve, returns nil and an error; so does a host ECDH failure. A nil or closed key on either side returns an error.
  • Contract: lib.crypto.ecdh 1.1.0

ES256Sign

Section titled “ES256Sign”
func ES256Sign(k *Key, data []byte) ([]byte, error)

An ECDSA P-256 SHA-256 (ES256) signature over data as raw 32-byte R followed by 32-byte S.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: nondeterministic
  • Bounds: Requires a P-256 private key. data is at most 64MiB; the signature is 64 bytes and randomized.
  • Errors: A key that is not a P-256 private key, or data over 64MiB, returns nil and an error. A nil or closed key returns an error.
  • Contract: lib.crypto.es256_sign 1.1.0

ES256Verify

Section titled “ES256Verify”
func ES256Verify(k *Key, data, sig []byte) (bool, error)

Whether signature is a valid ES256 raw R||S signature of data.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: deterministic
  • Bounds: Requires a P-256 key (a private key uses its public half). data is at most 64MiB; signature is exactly 64 bytes.
  • Errors: A correctly sized signature that does not verify returns false, nil. A key that is not on P-256, data over 64MiB or a signature that is not 64 bytes returns false and an error. A nil or closed key returns an error.
  • Contract: lib.crypto.es256_verify 1.1.0

ES384Sign

Section titled “ES384Sign”
func ES384Sign(k *Key, data []byte) ([]byte, error)

An ECDSA P-384 SHA-384 (ES384) signature over data as raw 48-byte R followed by 48-byte S.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: nondeterministic
  • Bounds: Requires a P-384 private key. data is at most 64MiB; the signature is 96 bytes and randomized.
  • Errors: A non-P-384 or public-only key, or data over 64MiB, returns nil and an error. A nil or closed key returns an error.
  • Contract: lib.crypto.es384_sign 1.0.0

ES384Verify

Section titled “ES384Verify”
func ES384Verify(k *Key, data, sig []byte) (bool, error)

Whether signature is a valid ES384 raw R||S signature of data.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: deterministic
  • Bounds: Requires a P-384 key (a private key uses its public half). data is at most 64MiB; signature is exactly 96 bytes.
  • Errors: A correctly sized signature that does not verify returns false, nil. A non-P-384 key, data over 64MiB or a signature that is not 96 bytes returns false and an error. A nil or closed key returns an error.
  • Contract: lib.crypto.es384_verify 1.0.0

ES512Sign

Section titled “ES512Sign”
func ES512Sign(k *Key, data []byte) ([]byte, error)

An ECDSA P-521 SHA-512 (ES512) signature over data as raw 66-byte R followed by 66-byte S.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: nondeterministic
  • Bounds: Requires a P-521 private key. data is at most 64MiB; the signature is 132 bytes and randomized.
  • Errors: A non-P-521 or public-only key, or data over 64MiB, returns nil and an error. A nil or closed key returns an error.
  • Contract: lib.crypto.es512_sign 1.0.0

ES512Verify

Section titled “ES512Verify”
func ES512Verify(k *Key, data, sig []byte) (bool, error)

Whether signature is a valid ES512 raw R||S signature of data.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: deterministic
  • Bounds: Requires a P-521 key (a private key uses its public half). data is at most 64MiB; signature is exactly 132 bytes.
  • Errors: A correctly sized signature that does not verify returns false, nil. A non-P-521 key, data over 64MiB or a signature that is not 132 bytes returns false and an error. A nil or closed key returns an error.
  • Contract: lib.crypto.es512_verify 1.0.0

GenerateP256

Section titled “GenerateP256”
func GenerateP256() (*Key, error)

A new random NIST P-256 private key handle.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: nondeterministic
  • Errors: A host key-generation failure returns a nil key and an error.
  • Contract: lib.crypto.generate_p256 1.0.0

GenerateP384

Section titled “GenerateP384”
func GenerateP384() (*Key, error)

A new random NIST P-384 private key handle.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: nondeterministic
  • Errors: A host key-generation failure returns a nil key and an error.
  • Contract: lib.crypto.generate_p384 1.0.0

GenerateP521

Section titled “GenerateP521”
func GenerateP521() (*Key, error)

A new random NIST P-521 private key handle.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: nondeterministic
  • Errors: A host key-generation failure returns a nil key and an error.
  • Contract: lib.crypto.generate_p521 1.0.0

GenerateRSA2048

Section titled “GenerateRSA2048”
func GenerateRSA2048() (*Key, error)

A new random RSA-2048 private key handle.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: nondeterministic
  • Bounds: The modulus is 2048 bits.
  • Errors: A host key-generation failure returns a nil key and an error.
  • Contract: lib.crypto.generate_rsa2048 1.0.0

GenerateRSA4096

Section titled “GenerateRSA4096”
func GenerateRSA4096() (*Key, error)

A new random RSA-4096 private key handle.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: nondeterministic
  • Bounds: The modulus is 4096 bits.
  • Errors: A host key-generation failure returns a nil key and an error.
  • Contract: lib.crypto.generate_rsa4096 1.0.0

HKDFSHA256

Section titled “HKDFSHA256”
func HKDFSHA256(secret, salt, info []byte, n int) ([]byte, error)

N bytes of RFC 5869 HKDF-SHA256 (extract then expand) output from secret, salt and info.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: deterministic
  • Bounds: The secret, salt and info are each at most 64MiB and may be empty; n is 0..8160 (255 * 32).
  • Errors: An oversized input or n outside 0..8160 returns nil and an error.
  • Contract: lib.crypto.hkdf_sha256 1.0.0

HMACSHA256

Section titled “HMACSHA256”
func HMACSHA256(key, data []byte) ([]byte, error)

The 32-byte HMAC-SHA256 of data under key.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: deterministic
  • Bounds: The key and data are each at most 64MiB; any key length, including empty, is accepted. The MAC is 32 bytes.
  • Errors: A key or data input over 64MiB returns nil and an error.
  • Contract: lib.crypto.hmac_sha256 1.0.0

HMACSHA256Verify

Section titled “HMACSHA256Verify”
func HMACSHA256Verify(key, data, mac []byte) (bool, error)

Constant-time check that mac is the HMAC-SHA256 of data under key.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: deterministic
  • Bounds: Each key/data input <=64MiB; MAC exactly 32 bytes.
  • Errors: Well-formed MAC mismatch returns false,nil. Invalid byte bounds or a MAC whose length is not 32 return false,error.
  • Contract: lib.crypto.hmac_sha256_verify 1.0.0

ImportPEM

Section titled “ImportPEM”
func ImportPEM(data string) (*Key, error)

A key handle from exactly one unencrypted PEM block holding an RSA key or a NIST P-256, P-384 or P-521 key.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: deterministic
  • Bounds: Input is at most 64KiB. Exactly one PEM block with no headers and no other content apart from surrounding whitespace. Accepted block types: PUBLIC KEY (SPKI), PRIVATE KEY (PKCS#8), RSA PUBLIC KEY and RSA PRIVATE KEY (PKCS#1), and CERTIFICATE, whose public key is used without any trust check. RSA keys must have a 2048, 3072 or 4096-bit modulus and an odd exponent of at least 3; EC keys must be on the named P-256, P-384 or P-521 curve with a valid point.
  • Errors: Oversized input, malformed or multiple blocks, PEM headers, unsupported block types, encrypted keys, other key types or sizes, and inconsistent private keys return a nil key and an error.
  • Contract: lib.crypto.import_pem 1.1.0

Key.Close

Section titled “Key.Close”
func (k *Key) Close()

Release the key handle and invalidate every alias of it.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: deterministic
  • Errors: Close has no declared error return. Unexpected native adapter or cleanup faults remain host faults and do not fabricate resource settlement.
  • Contract: lib.crypto.close 1.0.0

Key.PrivatePEM

Section titled “Key.PrivatePEM”
func (k *Key) PrivatePEM() (string, error)

The private key as a PKCS#8 PRIVATE KEY PEM block.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: deterministic
  • Bounds: Requires a supported RSA or EC private key.
  • Errors: A public-only key returns an empty string and an error. A nil or closed key returns an error.
  • Contract: lib.crypto.private_pem 1.1.0

Key.PublicJWK

Section titled “Key.PublicJWK”
func (k *Key) PublicJWK() ([]string, error)

The key’s public JWK members as [kty, crv, n, e, x, y], with no JSON encoding.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: deterministic
  • Bounds: Always six strings. RSA: kty RSA, crv empty, n and e as unpadded base64url big-endian bytes, x and y empty. EC: kty EC, crv P-256, P-384 or P-521, n and e empty, x and y as unpadded base64url coordinates of 32, 48 or 66 bytes. No private members.
  • Errors: A nil or closed key returns an error.
  • Contract: lib.crypto.public_jwk 1.1.0

Key.PublicPEM

Section titled “Key.PublicPEM”
func (k *Key) PublicPEM() (string, error)

The key’s public half as a PKIX (SPKI) PUBLIC KEY PEM block.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: deterministic
  • Bounds: Accepts any supported RSA or EC key, private or public.
  • Errors: A nil or closed key returns an error.
  • Contract: lib.crypto.public_pem 1.1.0

RS256Sign

Section titled “RS256Sign”
func RS256Sign(k *Key, data []byte) ([]byte, error)

An RSASSA-PKCS1-v1_5 SHA-256 (RS256) signature over data.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: deterministic
  • Bounds: Requires an RSA key with a 2048, 3072 or 4096-bit modulus as a private key. data is at most 64MiB; the signature is as long as the modulus in bytes.
  • Errors: A non-RSA or public-only key, or data over 64MiB, returns nil and an error. A nil or closed key returns an error.
  • Contract: lib.crypto.rs256_sign 1.1.0

RS256Verify

Section titled “RS256Verify”
func RS256Verify(k *Key, data, sig []byte) (bool, error)

Whether signature is a valid RS256 (RSASSA-PKCS1-v1_5 SHA-256) signature of data.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: deterministic
  • Bounds: Requires an RSA key with a 2048, 3072 or 4096-bit modulus (a private key uses its public half). data is at most 64MiB; signature is exactly as long as the modulus in bytes.
  • Errors: A correctly sized signature that does not verify returns false, nil. A non-RSA key, data over 64MiB or a signature that is not the modulus length returns false and an error. A nil or closed key returns an error.
  • Contract: lib.crypto.rs256_verify 1.1.0

RS384Sign

Section titled “RS384Sign”
func RS384Sign(k *Key, data []byte) ([]byte, error)

An RSASSA-PKCS1-v1_5 SHA-384 (RS384) signature over data.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: deterministic
  • Bounds: Requires an RSA key with a 2048, 3072 or 4096-bit modulus as a private key. data is at most 64MiB; the signature is as long as the modulus in bytes.
  • Errors: A non-RSA or public-only key, or data over 64MiB, returns nil and an error. A nil or closed key returns an error.
  • Contract: lib.crypto.rs384_sign 1.0.0

RS384Verify

Section titled “RS384Verify”
func RS384Verify(k *Key, data, sig []byte) (bool, error)

Whether signature is a valid RS384 (RSASSA-PKCS1-v1_5 SHA-384) signature of data.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: deterministic
  • Bounds: Requires an RSA key with a 2048, 3072 or 4096-bit modulus (a private key uses its public half). data is at most 64MiB; signature is exactly as long as the modulus in bytes.
  • Errors: A correctly sized signature that does not verify returns false, nil. A non-RSA key, data over 64MiB or a signature that is not the modulus length returns false and an error. A nil or closed key returns an error.
  • Contract: lib.crypto.rs384_verify 1.0.0

RS512Sign

Section titled “RS512Sign”
func RS512Sign(k *Key, data []byte) ([]byte, error)

An RSASSA-PKCS1-v1_5 SHA-512 (RS512) signature over data.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: deterministic
  • Bounds: Requires an RSA key with a 2048, 3072 or 4096-bit modulus as a private key. data is at most 64MiB; the signature is as long as the modulus in bytes.
  • Errors: A non-RSA or public-only key, or data over 64MiB, returns nil and an error. A nil or closed key returns an error.
  • Contract: lib.crypto.rs512_sign 1.0.0

RS512Verify

Section titled “RS512Verify”
func RS512Verify(k *Key, data, sig []byte) (bool, error)

Whether signature is a valid RS512 (RSASSA-PKCS1-v1_5 SHA-512) signature of data.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: deterministic
  • Bounds: Requires an RSA key with a 2048, 3072 or 4096-bit modulus (a private key uses its public half). data is at most 64MiB; signature is exactly as long as the modulus in bytes.
  • Errors: A correctly sized signature that does not verify returns false, nil. A non-RSA key, data over 64MiB or a signature that is not the modulus length returns false and an error. A nil or closed key returns an error.
  • Contract: lib.crypto.rs512_verify 1.0.0

RSAOAEPDecrypt

Section titled “RSAOAEPDecrypt”
func RSAOAEPDecrypt(k *Key, data []byte) ([]byte, error)

RSA OAEP decryption with SHA-1, MGF1-SHA1 and an empty label.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: deterministic
  • Bounds: Requires an RSA key with a 2048, 3072 or 4096-bit modulus as a private key. Ciphertext is exactly the modulus length in bytes.
  • Errors: A non-RSA or public-only key, or ciphertext that is not the modulus length, returns nil and an error. A padding or decryption failure returns nil and an error. A nil or closed key returns an error.
  • Contract: lib.crypto.rsa_oaep_decrypt 1.1.0

RSAOAEPEncrypt

Section titled “RSAOAEPEncrypt”
func RSAOAEPEncrypt(k *Key, data []byte) ([]byte, error)

RSA OAEP encryption with SHA-1, MGF1-SHA1 and an empty label.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: nondeterministic
  • Bounds: Requires an RSA key with a 2048, 3072 or 4096-bit modulus (a private key uses its public half). Plaintext is at most the modulus length in bytes minus 42 (214 bytes for RSA-2048); the ciphertext is as long as the modulus and randomized.
  • Errors: A non-RSA key or plaintext over the limit returns nil and an error. A nil or closed key returns an error.
  • Contract: lib.crypto.rsa_oaep_encrypt 1.1.0

Random

Section titled “Random”
func Random(n int) ([]byte, error)

N bytes from the host cryptographically secure random generator.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: nondeterministic
  • Bounds: n is 0..64MiB; the output has exactly n bytes.
  • Errors: A negative n or n above 64MiB returns nil and an error; a host RNG failure returns nil and its error.
  • Contract: lib.crypto.random 1.0.0

SHA256

Section titled “SHA256”
func SHA256(data []byte) ([]byte, error)

The 32-byte SHA-256 digest of data.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: deterministic
  • Bounds: The data is at most 64MiB; the digest is 32 bytes.
  • Errors: Data over 64MiB returns nil and an error.
  • Contract: lib.crypto.sha256 1.0.0