Class Ecies

java.lang.Object
io.github.fherbreteau.vodozemac.NativeHandle
io.github.fherbreteau.vodozemac.ecies.Ecies
All Implemented Interfaces:
AutoCloseable
public final class Ecies extends NativeHandle
An unestablished ECIES (Elliptic Curve Integrated Encryption Scheme) session.

ECIES is a hybrid encryption scheme that uses elliptic curve Diffie-Hellman (X25519) for shared secret establishment and ChaCha20-Poly1305 for symmetric encryption of individual messages. HMAC-SHA256 is used as the key derivation function.

ECIES allows a party (the initiator) to establish a communication channel toward another party (the recipient) given knowledge of only its public key. The initiator's key pair is ephemeral and generated anew for each new channel. The initiator must send their ephemeral public key to the recipient so that the recipient can complete the channel establishment on their end.

Since the initiator's key is unauthenticated, the recipient has no way of knowing who is contacting them. To protect against active man-in-the-middle (MITM) attacks, an out-of-band confirmation is required after channel establishment using the CheckCode facility.

This class implements AutoCloseable and should be used in a try-with-resources block to ensure native resources are properly released. Once a channel is established via establishOutboundChannel(String, byte[]) or establishInboundChannel(String), this Ecies object is consumed and can no longer be used.

Author:
François HERBRETEAU

  • Constructor Details

    • Ecies

      public Ecies()
      Creates a new, random, unestablished ECIES session.

      This method uses the MATRIX_QR_CODE_LOGIN application info prefix. If you are using this for a different purpose, consider using withInfo(String) instead.

  • Method Details

    • withInfo

      public static Ecies withInfo(String info)
      Creates a new, random, unestablished ECIES session with the given application info.

      The application info is used to derive the various secrets and provide domain separation. Both parties must use the same application info to successfully establish a channel.

      Parameters:
      info - the application info string
      Returns:
      a new Ecies session

    • publicKey

      public String publicKey()
      Returns the ephemeral Curve25519 public key associated with this session.

      This public key needs to be sent to the other side so that they can establish an ECIES channel.

      Returns:
      the base64-encoded public key
      Throws:
      IllegalStateException - if this Ecies has been closed or consumed by channel establishment

    • establishOutboundChannel

      public OutboundCreationResult establishOutboundChannel(String theirPublicKey, byte[] initialPlaintext)
      Establishes an outbound ECIES channel using the other side's Curve25519 public key and an initial plaintext message.

      After the channel has been established, the returned EstablishedEcies can be used to encrypt and decrypt further messages. The other side uses the initial message to establish the same channel on their end via establishInboundChannel(String).

      This method consumes the Ecies object — after this call, the Ecies is invalidated and can no longer be used. The native resources are transferred to the returned OutboundCreationResult.

      Parameters:
      theirPublicKey - a base64-encoded Curve25519 public key
      initialPlaintext - the initial plaintext message to encrypt
      Returns:
      an OutboundCreationResult containing the established channel and the initial message
      Throws:
      IllegalStateException - if this Ecies has been closed or consumed
      KeyException - if the given public key is invalid or cannot be decoded
      EciesException - if channel establishment fails, e.g. due to a non-contributory key

    • establishInboundChannel

      public InboundCreationResult establishInboundChannel(String message)
      Establishes an inbound ECIES channel from an initial message encrypted by the other side.

      The initial message is obtained from OutboundCreationResult.initialMessage() and contains the sender's ephemeral public key along with the ciphertext. After the channel has been established, the returned EstablishedEcies can be used to encrypt and decrypt further messages.

      This method consumes the Ecies object — after this call, the Ecies is invalidated and can no longer be used. The native resources are transferred to the returned InboundCreationResult.

      Parameters:
      message - the initial message received from the initiator, as produced by OutboundCreationResult.initialMessage()
      Returns:
      an InboundCreationResult containing the established channel and the decrypted plaintext
      Throws:
      IllegalStateException - if this Ecies has been closed or consumed
      EciesException - if channel establishment fails, e.g. due to a non-contributory key or a malformed message