Class PkDecryption

java.lang.Object
io.github.fherbreteau.vodozemac.NativeHandle
io.github.fherbreteau.vodozemac.backup.PkDecryption
All Implemented Interfaces:
AutoCloseable
public final class PkDecryption extends NativeHandle
The decryption component of the PK Encryption module.

This implements the m.megolm_backup.v1.curve25519-aes-sha2 algorithm described in the Matrix specification. It is a hybrid encryption scheme utilizing Curve25519 and AES-CBC. X25519 ECDH is performed between an ephemeral key pair and a long-lived backup key pair to establish a shared secret, from which symmetric encryption and message authentication (MAC) keys are derived.

A PkDecryption holds a Curve25519 secret key that serves as the long-term key to derive individual message keys. The corresponding public key can be shared with others, allowing them to encrypt messages which can only be decrypted using this object.

Warning: The algorithm contains a critical flaw and does not provide authentication of the ciphertext. The MAC is computed over an empty message rather than the actual ciphertext, meaning tampering with the ciphertext will not be detected.

This class implements AutoCloseable and should be used in a try-with-resources block to ensure native resources are properly released.

Author:
François HERBRETEAU
See Also:

  • Constructor Details

    • PkDecryption

      public PkDecryption()
      Creates a new PkDecryption with a fresh random Curve25519 key pair.

  • Method Details

    • fromKey

      public static PkDecryption fromKey(String key)
      Creates a PkDecryption from a base64-encoded Curve25519 secret key.

      The secret key is used as the long-term key to derive individual message keys. The corresponding public key can be obtained via publicKey() after creation.

      Parameters:
      key - the base64-encoded Curve25519 secret key (32 bytes)
      Returns:
      a new PkDecryption instance
      Throws:
      ConversionException - if the key is not a valid 32-byte base64-encoded key

    • secretKey

      public String secretKey()
      Returns the Curve25519 secret key of this PkDecryption.

      If persistence is required, securely store this key. It can be used to reconstruct the PkDecryption object for decrypting associated messages via fromKey(String).

      Returns:
      the base64-encoded Curve25519 secret key
      Throws:
      IllegalStateException - if this PkDecryption has been closed

    • publicKey

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

      This key can be shared with others to allow them to create a PkEncryption object and encrypt messages that only this PkDecryption can decrypt.

      Returns:
      the base64-encoded Curve25519 public key
      Throws:
      IllegalStateException - if this PkDecryption has been closed

    • decrypt

      public byte[] decrypt(PkMessage message)
      Decrypts a PkMessage that was encrypted for this PkDecryption.

      The decryption performs X25519 ECDH between the secret key and the message's ephemeral key to derive the symmetric keys, then verifies the MAC and decrypts the AES-CBC ciphertext.

      Parameters:
      message - the PkMessage to decrypt
      Returns:
      the decrypted plaintext bytes
      Throws:
      IllegalStateException - if this PkDecryption has been closed
      KeyException - if the ephemeral key in the message is invalid
      DecryptionException - if the MAC verification fails or the padding is invalid

    • unpickleLegacy

      public static PkDecryption unpickleLegacy(String pickleData, byte[] pickleKey)
      Restores a PkDecryption from a legacy libolm pickle format. The pickle must be encrypted with the provided key.
      Parameters:
      pickleData - the libolm pickle data
      pickleKey - the key used to encrypt the pickle data
      Returns:
      a restored PkDecryption
      Throws:
      PickleException - if the data cannot be decrypted or deserialized

    • pickleLegacy

      public String pickleLegacy(byte[] pickleKey)
      Pickles this PkDecryption into the legacy libolm pickle format. The pickle is encrypted with the provided key.
      Parameters:
      pickleKey - the key used to encrypt the pickle data
      Returns:
      the libolm pickle data
      Throws:
      IllegalStateException - if this PkDecryption has been closed
      PickleException - if the pickling fails