Package com.wire.cryptobox

Class CryptoBox

  • public final class CryptoBox
extends java.lang.Object
    A CryptoBox is an opaque container of all the necessary key material needed for exchanging end-to-end encrypted messages with peers for a single, logical client or device. It maintains a pool of CryptoSessions for all remote peers.

    Every cryptographic session with a peer is represented by a CryptoSession. These sessions are pooled by a CryptoBox, i.e. if a session with the same session ID is requested multiple times, the same instance is returned. Consequently, CryptoSessions are kept in memory once loaded. They can be explicitly closed through closeSession(com.wire.cryptobox.CryptoSession) or closeAllSessions(). All loaded sessions are implicitly closed when the CryptoBox itself is closed via close(). Note that it is considered programmer error to let a CryptoBox become unreachable and thus eligible for garbage collection without having called close(), even though this class overrides Object.finalize() as an additional safety net for deallocating all native resources.

    A CryptoBox is thread-safe.

    See Also:
    CryptoSession

    • Method Detail

      • open

        public static CryptoBox open​(java.lang.String dir)
                      throws CryptoException
        Open a CryptoBox that operates on the given directory. The given directory must exist and be writeable.

        Note: Do not open multiple boxes that operate on the same or overlapping directories. Doing so results in undefined behaviour.

        Parameters:
        dir - The root storage directory of the box.
        Throws:
        CryptoException

      • openWith

        public static CryptoBox openWith​(java.lang.String dir,
                                 byte[] id,
                                 CryptoBox.IdentityMode mode)
                          throws CryptoException
        Open a CryptoBox that operates on the given directory, using an existing external identity. The given identity must match the (public or complete) identity that the CryptoBox already has, if any. The given directory must exist and be writeable.

        Note: Do not open multiple boxes that operate on the same or overlapping directories. Doing so results in undefined behaviour.

        Parameters:
        dir - The root storage directory of the box.
        id - The serialised external identity to use.
        mode - The desired local identity storage.
        Throws:
        CryptoException

      • getFingerprintFromPrekey

        public static byte[] getFingerprintFromPrekey​(PreKey preKey)
                                       throws CryptoException
        Get the public key fingerprint from a prekey.
        Returns:
        The HEX encoded fingerprint.
        Throws:
        CryptoException

      • getLocalFingerprint

        public byte[] getLocalFingerprint()
                           throws CryptoException
        Get the local fingerprint as a hex-encoded byte array.
        Throws:
        CryptoException

      • newPreKeys

        public PreKey[] newPreKeys​(int start,
                           int num)
                    throws CryptoException
        Generate a new batch of ephemeral prekeys. If start + num > MAX_PREKEY_ID the IDs wrap around and start over at 0. Thus after any valid invocation of this method, the last generated prekey ID is always (start + num) % (MAX_PREKEY_ID + 1). The caller can remember that ID and feed it back into newPreKeys(int, int) as the start ID when the next batch of ephemeral keys needs to be generated.
        Parameters:
        start - The ID (>= 0 and <= MAX_PREKEY_ID) of the first prekey to generate.
        num - The total number of prekeys to generate (> 0 and <= MAX_PREKEY_ID).
        Throws:
        CryptoException

      • initSessionFromPreKey

        public CryptoSession initSessionFromPreKey​(java.lang.String sid,
                                           PreKey prekey)
                                    throws CryptoException
        Initialise a CryptoSession using the prekey of a peer.

        This is the entry point for the initiator of a session, i.e. the side that wishes to send the first message.

        Parameters:
        sid - The ID of the new session.
        prekey - The prekey of the peer.
        Throws:
        CryptoException

      • initSessionFromMessage

        public SessionMessage initSessionFromMessage​(java.lang.String sid,
                                             byte[] message)
                                      throws CryptoException
        Initialise a CryptoSession using a received encrypted message.

        This is the entry point for the recipient of an encrypted message.

        Parameters:
        sid - The ID of the new session.
        message - The encrypted (prekey) message.
        Throws:
        CryptoException

      • closeSession

        public void closeSession​(CryptoSession sess)
        Close a session.

        Note: After a session has been closed, any operations other than closeSession are considered programmer error and result in an IllegalStateException.

        If the session is already closed, this is a no-op.

        Parameters:
        sess - The session to close.

      • deleteSession

        public void deleteSession​(java.lang.String sid)
                   throws CryptoException
        Delete a session. If the session is currently loaded, it is automatically closed before being deleted.

        Note: After a session has been deleted, further messages received from the peer can no longer be decrypted.

        Parameters:
        sid - The ID of the session to delete.
        Throws:
        CryptoException

      • close

        public void close()
        Close the CryptoBox.

        Note: After a box has been closed, any operations other than close are considered programmer error and result in an IllegalStateException.

        If the box is already closed, this is a no-op.

      • isClosed

        public boolean isClosed()