# Module BSV::Primitives::ECIES <a id="module-BSV-Primitives-ECIES"></a>

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**
```ruby
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` <a id="constant-MAGIC"></a> <a id="MAGIC-constant"></a>
BIE1 magic bytes identifying the Electrum ECIES format.

## Public Class Methods
### `bitcore_decrypt(data, private_key)` <a id="method-c-bitcore_decrypt"></a> <a id="bitcore_decrypt-class_method"></a>
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, iv: = nil)` <a id="method-c-bitcore_encrypt"></a> <a id="bitcore_encrypt-class_method"></a>
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)
- **@param** `iv` [String, nil] optional 16-byte ASCII-8BIT IV. When omitted a random IV is
generated via +SecureRandom+. Supply a fixed value only for deterministic test
vectors — **never use a fixed IV in production**.
- **@raise** [ArgumentError] if +iv+ is supplied but is not exactly 16 bytes
- **@return** [String] encrypted payload

### `decrypt(data, private_key, sender_public_key: = nil)` <a id="method-c-decrypt"></a> <a id="decrypt-class_method"></a>
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)` <a id="method-c-encrypt"></a> <a id="encrypt-class_method"></a>
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