BSV.SymmetricKey (bsv_sdk v1.1.0)

Copy Markdown View Source

AES-256-GCM symmetric encryption.

Migration Notice (v0.2)

The IV size was changed from 32 bytes to the standard 12 bytes for GCM. Decryption automatically detects the IV size of the ciphertext:

  • New ciphertexts use 12-byte IVs (standard, secure)
  • Legacy ciphertexts with 32-byte IVs are still decryptable

Encryption always uses the new 12-byte IV format. To migrate legacy data, decrypt with the old key and re-encrypt — the new format is used automatically.

Summary

Types

t()

Functions

decrypt(key, encrypted)

Decrypt ciphertext with a 32-byte key using AES-256-GCM.

decrypt(arg1, encrypted, aad)

Decrypt with explicit Additional Authenticated Data (AAD).

encrypt(key, plaintext)

Encrypt plaintext with a 32-byte key using AES-256-GCM (12-byte IV).

encrypt(arg1, plaintext, aad)

Encrypt with explicit Additional Authenticated Data (AAD).

new(arg)

Create a new SymmetricKey from a 32-byte binary.

to_bytes(symmetric_key)

Get the raw key bytes.

Types

t()

@type t() :: %BSV.SymmetricKey{raw: <<_::256>>}

Functions

decrypt(key, encrypted)

@spec decrypt(<<_::256>> | t(), binary()) ::
  {:ok, binary()} | {:error, :decrypt_failed}

Decrypt ciphertext with a 32-byte key using AES-256-GCM.

Automatically detects IV size: tries 12-byte (current) first, then falls back to 32-byte (legacy) for backward compatibility.

decrypt(arg1, encrypted, aad)

@spec decrypt(<<_::256>> | t(), binary(), binary()) ::
  {:ok, binary()} | {:error, :decrypt_failed}

Decrypt with explicit Additional Authenticated Data (AAD).

encrypt(key, plaintext)

@spec encrypt(<<_::256>> | t(), binary()) :: {:ok, binary()}

Encrypt plaintext with a 32-byte key using AES-256-GCM (12-byte IV).

The 2-arity version passes empty AAD (<<>>) for backward compatibility with BRC-78 and other implementations. Use encrypt/3 to supply custom Additional Authenticated Data for extra context binding.

encrypt(arg1, plaintext, aad)

@spec encrypt(<<_::256>> | t(), binary(), binary()) :: {:ok, binary()}

Encrypt with explicit Additional Authenticated Data (AAD).

new(arg)

@spec new(<<_::256>>) :: t()

Create a new SymmetricKey from a 32-byte binary.

to_bytes(symmetric_key)

@spec to_bytes(t()) :: <<_::256>>

Get the raw key bytes.