Class BSV::Primitives::SymmetricKey ¶

Inherits: Object

AES-256-GCM symmetric encryption.

Provides authenticated encryption matching the interface used by the TS, Go, and Python reference SDKs. The wire format is:

|--- 32-byte IV ---|--- ciphertext ---|--- 16-byte auth tag ---|

All three reference SDKs use a 32-byte IV (non-standard but cross-SDK compatible) and 16-byte authentication tag.

@example Round-trip encryption

key = BSV::Primitives::SymmetricKey.from_random
encrypted = key.encrypt('hello world')
key.decrypt(encrypted) #=> "hello world"

Constants¶

IV_SIZE ¶

Not documented.

KEY_SIZE ¶

Not documented.

TAG_SIZE ¶

Not documented.

Public Class Methods¶

from_ecdh(private_key, public_key) ¶

Derive a symmetric key from an ECDH shared secret.

Computes the shared point between the two parties and uses the X-coordinate as the key material. The X-coordinate may be 31 or 32 bytes; shorter values are left-zero-padded automatically. - @param private_key [PrivateKey] one party's private key - @param public_key [PublicKey] the other party's public key - @return [SymmetricKey]

@example Alice and Bob derive the same key

alice_key = SymmetricKey.from_ecdh(alice_priv, bob_pub)
bob_key   = SymmetricKey.from_ecdh(bob_priv, alice_pub)
alice_key.to_bytes == bob_key.to_bytes #=> true

from_random() ¶

Generate a random symmetric key. - @return [SymmetricKey]

Public Instance Methods¶

decrypt(data) ¶

Decrypt an AES-256-GCM encrypted message.

Expects the wire format: IV (32) + ciphertext + auth tag (16). - @param data [String] the encrypted message - @raise [ArgumentError] if the data is too short - @raise [OpenSSL::Cipher::CipherError] if authentication fails (wrong key or tampered data) - @return [String] the decrypted plaintext (binary)

encrypt(plaintext) ¶

Encrypt a message with AES-256-GCM.

Generates a random 32-byte IV per call. Returns the concatenation of IV, ciphertext, and 16-byte authentication tag. - @param plaintext [String] the message to encrypt - @return [String] binary string: IV (32) + ciphertext + auth tag (16)

initialize(key_bytes) ¶

• @param key_bytes [String] 32-byte binary key (shorter keys are left-zero-padded)
• @raise [ArgumentError] if key is empty or longer than 32 bytes
• @return [SymmetricKey] a new instance of SymmetricKey

to_bytes() ¶

Return the raw key bytes. - @return [String] 32-byte binary key