Module BSV::Primitives::ECIES ¶

Elliptic Curve Integrated Encryption Scheme (ECIES) using the Electrum/BIE1 protocol.

Provides authenticated encryption using an ephemeral ECDH shared secret. The sender generates a random key pair, derives a shared secret with the recipient's public key, then encrypts with AES-128-CBC and authenticates with HMAC-SHA-256 (encrypt-then-MAC).

@example Encrypt and decrypt a message

alice = BSV::Primitives::PrivateKey.generate
bob   = BSV::Primitives::PrivateKey.generate

ciphertext = BSV::Primitives::ECIES.encrypt('hello', bob.public_key)
plaintext  = BSV::Primitives::ECIES.decrypt(ciphertext, bob)

Constants¶

MAGIC ¶

BIE1 magic bytes identifying the Electrum ECIES format.

Public Class Methods¶

bitcore_decrypt(data, private_key) ¶

Decrypt a message encrypted with the Bitcore ECIES variant. - @param data [String] the encrypted payload (Bitcore ECIES format) - @param private_key [PrivateKey] the recipient's private key - @raise [ArgumentError] if the data is too short - @raise [DecryptionError] if HMAC verification or AES decryption fails - @return [String] the decrypted plaintext

bitcore_encrypt(message, public_key, private_key: = nil) ¶

Encrypt a message using the Bitcore ECIES variant.

Differs from the Electrum variant: no magic prefix, AES-256-CBC (not AES-128), random IV prepended to ciphertext, and HMAC covers the ciphertext (not the ephemeral pubkey).

Wire format: +ephemeral_pub(33) + IV(16) + ciphertext + HMAC(32)+ - @param message [String] the plaintext message - @param public_key [PublicKey] the recipient's public key - @param private_key [PrivateKey, nil] optional ephemeral key (random if omitted) - @return [String] encrypted payload

decrypt(data, private_key, sender_public_key: = nil) ¶

Decrypt an ECIES-encrypted message with a private key.

Verifies the HMAC before attempting decryption (encrypt-then-MAC).

The ephemeral public key may be embedded in the payload (compressed or uncompressed), or absent entirely (when the payload was encrypted with +no_key: true+). When absent, sender_public_key must be provided.

If a key is found in the payload and sender_public_key is also given, the payload key takes precedence (matching TS SDK behaviour). - @param data [String] the encrypted payload (BIE1 format) - @param private_key [PrivateKey] the recipient's private key - @param sender_public_key [PublicKey, nil] sender's public key (required when no key in payload) - @raise [ArgumentError] if the data is too short, has invalid magic, or has no key and none provided - @raise [DecryptionError] if HMAC verification or AES decryption fails - @return [String] the decrypted plaintext

encrypt(message, public_key, private_key: = nil, no_key: = false) ¶

Encrypt a message for a recipient's public key. - @param message [String] the plaintext message - @param public_key [PublicKey] the recipient's public key - @param private_key [PrivateKey, nil] optional ephemeral key (random if omitted) - @param no_key [Boolean] when +true+, omit the ephemeral public key from the payload - @return [String] encrypted payload: BIE1 magic + [ephemeral pubkey] + ciphertext + HMAC