Package anbxj

Class AnB_Crypto_Wrapper

java.lang.Object
anbxj.AnB_Crypto_Wrapper
Direct Known Subclasses:
AnB_Session
public class AnB_Crypto_Wrapper extends Object
Cryptographic API: implements a class supporting cryptographic operations (a wrapper for the cryptographic engine)

  • Field Details

  • Constructor Details

  • Method Details

    • setLoggingExecTimeEnabled

      public static void setLoggingExecTimeEnabled(boolean enabled)
      Sets the logging state for performance measurements.
      Parameters:
      enabled - true to enable logging, false to disable logging.

    • isLoggingExecTimeEnabled

      public static boolean isLoggingExecTimeEnabled()
      Checks whether logging is currently enabled.
      Returns:
      true if logging is enabled, false otherwise.

    • getInfo

      public static void getInfo()
      Prints information about the cryptographic engine including supported algorithms
      See Also:

    • getKeyStoreSettings_Map

      public Crypto_KeyStoreSettings_Map getKeyStoreSettings_Map()
      Retrieve the default Crypto_KeyStoreSettings_Map for the current cryptographic engine
      Returns:
      the Crypto_KeyStoreSettings_Map
      See Also:

    • getCryptoEngine

      public Crypto_EncryptionEngine getCryptoEngine()
      Returns the cryptographic engine
      Returns:
      the Crypto_KeyStoreSettings_Map
      See Also:

    • getName

      public String getName()
      Returns the agent name associated with this for the current AnB_Crypto_Wrapper
      Returns:
      the agent's name

    • aliasExists

      public boolean aliasExists(String alias)
      Check is an agent's alias is stored in the key stores accessible to the cryptographic engine
      Parameters:
      alias - the agent's alias
      Returns:
      true if the agent's alias exists

    • getPublicKey

      public PublicKey getPublicKey(String alias, Crypto_KeyStoreType kst)
      Retrieve a public key associated to an agent's alias for a specified Crypto_KeyStoreType
      Parameters:
      alias - the agent's alias
      kst - the crypto key store type
      Returns:
      the public key

    • getRemoteCertificate

      protected Certificate getRemoteCertificate(String alias, Crypto_KeyStoreType kst)
      Retrieve the certificate associated to an agent's alias for a specified Crypto_KeyStoreType
      Parameters:
      alias - the agent's alias
      kst - the crypto key store type
      Returns:
      the certificate

    • getRemoteCertificates

      protected Map<Crypto_KeyStoreType,Certificate> getRemoteCertificates(String alias)
      Retrieve the certificates associated to an agent's alias
      Parameters:
      alias - the agent's alias
      Returns:
      the certificates

    • getMyIdentity

      protected AnBx_Agent getMyIdentity()
      Retrieve the identity of the current agent
      Returns:
      the identity

    • Send

      protected void Send(Object obj, Channel_Abstraction c)
      Send an object over a channel
      Parameters:
      obj - the object
      c - the channel abstraction

    • Receive

      protected Object Receive(Channel_Abstraction c)
      Receive an object from a channel
      Parameters:
      c - the channel abstraction
      Returns:
      the object

    • Send_Id

      protected void Send_Id(AnBx_Agent id, Channel_Abstraction c)
      Send the identity of an agent over a channel
      Parameters:
      id - the agent id
      c - the channel abstraction

    • Receive_RemoteId

      protected AnBx_Agent Receive_RemoteId(Channel_Abstraction c)
      Receive the identity of an agent from a channel
      Parameters:
      c - the channel abstraction
      Returns:
      the agent identity

    • encrypt

      public Crypto_SealedPair encrypt(Object object, String alias, Crypto_KeyStoreType pk)
      Encrypts an object with a public key retrieved from a specified key store associated to an user identified by an alias
      Parameters:
      object - the object to encrypt
      alias - the identifier of the agent
      pk - the specified key store
      Returns:
      the encrypted object as Crypto_SealedPair
      See Also:

    • decrypt

      public Object decrypt(Crypto_SealedPair sc)
      Decrypts a Crypto_SealedPair with the private key from the default key store associated to current agent
      Parameters:
      sc - the Crypto_SealedPair to decrypt
      Returns:
      the decrypted object
      See Also:

    • decrypt

      public Object decrypt(Crypto_SealedPair sc, Crypto_KeyStoreType pk)
      Decrypts a Crypto_SealedPair with the private key from a specified key store associated to current agent
      Parameters:
      sc - the Crypto_SealedPair to decrypt
      pk - the specified key store
      Returns:
      the decrypted object
      See Also:

    • decrypt

      public Object decrypt(Crypto_SealedPair sc, Crypto_KeyPair kp)
      Decrypts a Crypto_SealedPair with the private key from a specified key pair
      Parameters:
      sc - the Crypto_SealedPair to decrypt
      kp - the specified key pair
      Returns:
      the decrypted object
      See Also:

    • decrypt

      public Object decrypt(SealedObject so, SecretKey symmetricKey)
      Decrypts a SealedObject with a specified symmetric key
      Parameters:
      so - the SealedObject to encrypt
      symmetricKey - the specified symmetric key
      Returns:
      the encrypted object as SealedObject

    • verify

      public Object verify(SignedObject so, String alias)
      Verifies a SignedObject with a private key retrieved from the default key store associated to an agent identified by an alias
      Parameters:
      so - the SignedObject to verify
      alias - the identifier of the agent
      Returns:
      the verified object
      See Also:

    • verify

      public Object verify(SignedObject so, String alias, Crypto_KeyStoreType sk)
      Verifies a SignedObject with a private key retrieved from a specified key store associated to an agent identified by an alias
      Parameters:
      so - the SignedObject to verify
      alias - the identifier of the agent
      sk - the specified key store
      Returns:
      the verified object
      See Also:

    • verify

      public Object verify(SignedObject so, PublicKey pk)
      Verifies a SignedObject with a specified public key
      Parameters:
      so - the SignedObject to verify
      pk - the specified public key
      Returns:
      the verified object

    • getNonce

      public Crypto_ByteArray getNonce()
      Generates a fresh nonce
      Returns:
      the fresh nonce

    • getSeqNumber

      public Crypto_ByteArray getSeqNumber()
      Generates a sequence number
      Returns:
      the sequence number

    • getSymmetricKey

      public SecretKey getSymmetricKey()
      Generates a symmetric key
      Returns:
      the symmetric key

    • getSymmetricKey

      public SecretKey getSymmetricKey(Crypto_KeyMode km)
      Generates a symmetric key specifying a key mode
      Parameters:
      km - the key mode for key generation
      Returns:
      the symmetric key

    • getHmacKey

      public SecretKey getHmacKey()
      Generates a HMAC secret key
      Returns:
      the HMAC secret key

    • getTimeStamp

      public Instant getTimeStamp()
      Generates a time stamp
      Returns:
      the time stamp

    • getSymmetricKeyPBE

      public SecretKey getSymmetricKeyPBE(String password, String salt)
      Generates a symmetric key for Password Based Encryption (PBE)
      Parameters:
      password - the password
      salt - the salting argument
      Returns:
      the symmetric key

    • getKeyEx_KeyPair

      public KeyPair getKeyEx_KeyPair()
      Generates a key exchange key pair for the default key agreement algorithm
      Returns:
      the key exchange key pair

    • getKeyEx_PublicKey

      public PublicKey getKeyEx_PublicKey(KeyPair keyPair)
      Retrieves the public key from a specified key exchange key pair
      Parameters:
      keyPair - the specified key pair
      Returns:
      the key pair

    • getKeyEx_SecretKey

      public SecretKey getKeyEx_SecretKey(PublicKey publicKey, KeyPair keyPair)
      Retrieves the secret key from a specified key exchange key pair and associated public key
      Parameters:
      publicKey - the associated public key
      keyPair - the specified key pair
      Returns:
      the (symmetric) secret key

    • getKeyPair

      public Crypto_KeyPair getKeyPair()
      Generates a key pair for the default public key algorithm
      Returns:
      the key pair
      See Also:

    • getPublicKey

      public PublicKey getPublicKey(Crypto_KeyPair pair)
      Retrieves the public key from a specified key pair
      Parameters:
      pair - the specified key pair
      Returns:
      the public key
      See Also:

    • makeDigest

      public Crypto_ByteArray makeDigest(Object object)
      Computes the hash of a given object with the default hashing algorithm
      Parameters:
      object - the given object
      Returns:
      the hash value as Crypto_ByteArray

    • makeHmac

      public Crypto_ByteArray makeHmac(Object object, SecretKey sk)
      Computes the hmac of a given object with the default hashing algorithm and a specified secret key
      Parameters:
      object - the given object
      sk - the secret key
      Returns:
      the hmac value as Crypto_ByteArray
      See Also:

    • checkHmac

      public boolean checkHmac(Object object, Crypto_ByteArray hmac, SecretKey sk)
      Check a hmac value of a given object computed with the default hashing algorithm and a specified secret key
      Parameters:
      object - the given object
      hmac - the hmac value
      sk - the secret key
      Returns:
      the hmac value as Crypto_ByteArray
      See Also:

    • xor

      public Crypto_ByteArray xor(Crypto_ByteArray x1, Crypto_ByteArray x2)
      Computes the xor of two Crypto_ByteArrays
      Parameters:
      x1 - the first Crypto_ByteArray argument
      x2 - the second Crypto_ByteArray argument
      Returns:
      the computed xor value
      See Also:

    • writeObject

      public static void writeObject(Object object, String filename)
      Writes a serialised object to the file system
      Parameters:
      object - the given object
      filename - the specified destination file

    • readObject

      public static Object readObject(String filename)
      Writes a serialised object from the file system
      Parameters:
      filename - the specified source file
      Returns:
      the retrieved object

    • verifyMessage

      public byte[] verifyMessage(AnBx_WireFormats.SignedMessage sm, String alias)
      Verifies a AnBx_WireFormats.SignedMessage using the public key of the given alias (retrieved from the keystore). If verification succeeds, the original signed content bytes are returned.
      Parameters:
      sm - the signed message wrapper (must not be null)
      alias - the alias of the signer (must not be null)
      Returns:
      the original content bytes (the content field of the wrapper)
      Throws:
      SecurityException - if the signature does not verify
      AnBx_LibraryException - if verification fails due to a cryptographic error
      NullPointerException - if any argument is null

    • verifyMessage

      public byte[] verifyMessage(AnBx_WireFormats.SignedMessage sm, PublicKey publicKey)
      Verifies a AnBx_WireFormats.SignedMessage using the provided public key. If verification succeeds, the original signed content bytes are returned.

      This overload is used when the public key was received during the protocol (e.g., a freshly generated public key sent by the peer).

      Parameters:
      sm - the signed message wrapper (must not be null)
      publicKey - the public key to verify the signature (must not be null)
      Returns:
      the original content bytes (the content field of the wrapper)
      Throws:
      SecurityException - if the signature does not verify
      AnBx_LibraryException - if verification fails due to a cryptographic error
      NullPointerException - if any argument is null

    • unsealMessage

      public byte[] unsealMessage(AnBx_WireFormats.SealedMessage sealedMsg)
      Unseals (decrypts) a AnBx_WireFormats.SealedMessage using the local private key.

      This method reverses the hybrid encryption process:

      1. Decrypts the symmetric key using the local private key.
      2. Decrypts the message symmetrically with the recovered key.
      Parameters:
      sealedMsg - the sealed message wrapper (must not be null)
      Returns:
      the decrypted plaintext bytes
      Throws:
      AnBx_LibraryException - if decryption fails (e.g., corrupted ciphertext)
      NullPointerException - if sealedMsg is null

    • encryptSymmetric

      public byte[] encryptSymmetric(byte[] plaintext, SecretKey key)
      Encrypts the given plaintext using the provided symmetric key.

      This method performs raw symmetric encryption (no key transport). The cipher algorithm and mode are determined from the key's algorithm via the configuration mapping keyTypeToCipher. An appropriate initialisation vector (IV) is generated automatically for modes that require one (e.g., CBC, GCM).

      Parameters:
      plaintext - the raw bytes to encrypt (must not be null)
      key - the symmetric encryption key (must not be null)
      Returns:
      the ciphertext bytes
      Throws:
      AnBx_LibraryException - if encryption fails
      NullPointerException - if any argument is null

    • hmac

      public byte[] hmac(byte[] data, SecretKey key)
      Computes an HMAC (keyed-hash message authentication code) over the given data using the provided secret key.

      The HMAC algorithm is taken from the cryptographic configuration (hMacAlgorithm). This method is intended for raw byte-based HMAC operations in typed Protobuf mode.

      Parameters:
      data - the data to authenticate (must not be null)
      key - the HMAC secret key (must not be null)
      Returns:
      the HMAC value (raw bytes)
      Throws:
      AnBx_LibraryException - if HMAC computation fails
      NullPointerException - if any argument is null

    • toProtobufSigned

      public static AnBx_WireFormats.SignedMessage toProtobufSigned(Crypto_SignedObject obj)
      Converts a Crypto_SignedObject to its Protobuf AnBx_WireFormats.SignedMessage representation.

      This method simply delegates to the instance method Crypto_SignedObject.toSignedMessage().

      Parameters:
      obj - the signed object to convert (must not be null)
      Returns:
      the corresponding SignedMessage

    • fromProtobufSigned

      public static Crypto_SignedObject fromProtobufSigned(AnBx_WireFormats.SignedMessage msg)
      Reconstructs a Crypto_SignedObject from a Protobuf AnBx_WireFormats.SignedMessage.

      The three fields (content, signature, algorithm) are taken directly from the message and stored inside the new container.

      Parameters:
      msg - the Protobuf message (must not be null)
      Returns:
      the reconstructed container

    • sign

      public Crypto_SignedObject sign(Object object)
      Signs an object using the default private key of the current agent.

      The result is a serializer-neutral Crypto_SignedObject that can be used identically in all serialisation modes.

      Parameters:
      object - the object to sign
      Returns:
      a Crypto_SignedObject containing the signature

    • sign

      public Crypto_SignedObject sign(Object object, Crypto_KeyStoreType sk)
      Signs an object using a private key retrieved from the specified key store.
      Parameters:
      object - the object to sign
      sk - the key store type that identifies the signing key
      Returns:
      a serializer-neutral Crypto_SignedObject

    • sign

      public Crypto_SignedObject sign(Object object, Crypto_KeyPair kp)
      Signs an object using the private key contained in the specified key pair.
      Parameters:
      object - the object to sign
      kp - the key pair whose private key is used for signing
      Returns:
      a serializer-neutral Crypto_SignedObject

    • verify

      public Object verify(Crypto_SignedObject sig, String alias)
      Verifies a Crypto_SignedObject using the public key of the agent identified by the given alias.

      If the container holds a real SignedObject (JavaSer mode), the legacy verification path is used. Otherwise the raw content and signature are verified via verifyMessage(AnBx_WireFormats.SignedMessage, String) and the result is deserialised before being returned.

      Parameters:
      sig - the signed object to verify
      alias - the alias of the signer (used to look up the public key)
      Returns:
      the verified (and deserialised) original object
      Throws:
      AnBx_LibraryException - if verification or deserialisation fails

    • verify

      public Object verify(Crypto_SignedObject sig, PublicKey publicKey)
      Verifies a Crypto_SignedObject using a specific public key.

      The method behaves like verify(Crypto_SignedObject, String) but uses the supplied PublicKey instead of looking one up by alias.

      Parameters:
      sig - the signed object to verify
      publicKey - the public key to use for verification
      Returns:
      the verified (and deserialised) original object
      Throws:
      AnBx_LibraryException - if verification or deserialisation fails

    • toProtobufSealed

      public static AnBx_WireFormats.SealedMessage toProtobufSealed(Crypto_SealedObject obj)
      Converts a Crypto_SealedObject to its Protobuf AnBx_WireFormats.SealedMessage representation.

      This method simply delegates to the instance method Crypto_SealedObject.toSealedMessage().

      Parameters:
      obj - the sealed object to convert (must not be null)
      Returns:
      the corresponding SealedMessage

    • fromProtobufSealed

      public static Crypto_SealedObject fromProtobufSealed(AnBx_WireFormats.SealedMessage msg)
      Reconstructs a Crypto_SealedObject from a Protobuf AnBx_WireFormats.SealedMessage.

      The three fields (encrypted key, encrypted message, cipher scheme) are extracted from the message and used to construct the unified container.

      Parameters:
      msg - the Protobuf message (must not be null)
      Returns:
      the reconstructed container

    • encrypt

      public Crypto_SealedObject encrypt(Object object, String alias)
      Encrypts an object for the recipient identified by the given alias.

      The legacy Crypto_SealedPair produced by the engine is immediately wrapped in a Crypto_SealedObject for use in all serializers.

      Parameters:
      object - the object to encrypt
      alias - the alias of the recipient (the public key is retrieved from the default key store)
      Returns:
      a Crypto_SealedObject containing the encrypted data
      See Also:

    • encrypt

      public Crypto_SealedObject encrypt(Object object, PublicKey publicKey)
      Encrypts an object using the given public key.

      The legacy Crypto_SealedPair produced by the engine is immediately wrapped in a Crypto_SealedObject.

      Parameters:
      object - the object to encrypt
      publicKey - the recipient's public key
      Returns:
      a Crypto_SealedObject containing the encrypted data

    • encrypt

      public Crypto_SealedObject encrypt(Object object, Crypto_KeyPair kp)
      Encrypts an object using the public key extracted from the given key pair.

      The legacy Crypto_SealedPair produced by the engine is immediately wrapped in a Crypto_SealedObject.

      Parameters:
      object - the object to encrypt
      kp - the key pair whose public key is used for encryption
      Returns:
      a Crypto_SealedObject containing the encrypted data

    • decrypt

      public Object decrypt(Crypto_SealedObject sealedObj)
      Decrypts a Crypto_SealedObject.

      The method first tries to reconstruct a legacy Crypto_SealedPair and decrypt it using the Java serialisation path. If that fails (e.g., because the sealed object was built from raw bytes in ProtoBuf mode), it falls back to the Protobuf path via unsealMessage(AnBx_WireFormats.SealedMessage) and deserialises the result.

      Parameters:
      sealedObj - the sealed object to decrypt (must not be null)
      Returns:
      the decrypted (and deserialised) object
      Throws:
      AnBx_LibraryException - if decryption fails on both paths

    • encrypt

      public Crypto_SealedObject encrypt(Object object, SecretKey key)
      Symmetric encryption that works identically for all serialisers.

      The object is serialised, encrypted with the given key, and returned as a Crypto_SealedObject whose encryptedKey is null (symmetric mode).

      Parameters:
      object - the object to encrypt
      key - the symmetric key
      Returns:
      the sealed container (cipher scheme is taken from the crypto config)

    • decrypt

      public Object decrypt(Crypto_SealedObject sealedObj, SecretKey key)
      Symmetric decryption that works identically for all serialisers.

      The method expects a Crypto_SealedObject with a null encrypted key (symmetric mode). It decrypts the raw ciphertext and deserialises the result.

      Parameters:
      sealedObj - the sealed container (encryptedKey must be null)
      key - the symmetric key
      Returns:
      the deserialised original object
      Throws:
      AnBx_LibraryException - if the encryptedKey is not null or decryption/deserialisation fails

    • decrypt

      public Object decrypt(Crypto_SealedObject sealedObj, Crypto_KeyPair kp)
      Decrypts a Crypto_SealedObject using the private key from the specified key pair.

      If the container holds a legacy Crypto_SealedPair, that pair is used directly; otherwise the raw bytes are extracted and the Protobuf path is taken.

      Parameters:
      sealedObj - the sealed object to decrypt (must not be null)
      kp - the key pair whose private key is used for decryption
      Returns:
      the decrypted (and deserialised) object
      Throws:
      AnBx_LibraryException - if decryption fails

    • decrypt

      public Object decrypt(Crypto_SealedObject sealedObj, Crypto_KeyStoreType pk)
      Decrypts a Crypto_SealedObject using a specific key store type.

      If the container holds a legacy Crypto_SealedPair, that pair is used directly with the provided key store; otherwise the raw bytes are extracted and the Protobuf path is taken (the key store is ignored for symmetric / pure byte-based objects).

      Parameters:
      sealedObj - the sealed object to decrypt (must not be null)
      pk - the key store type that identifies the private key to use
      Returns:
      the decrypted (and deserialised) object
      Throws:
      AnBx_LibraryException - if decryption fails