Package org.wso2.carbon.crypto.api

Interface ExternalCryptoProvider

public interface ExternalCryptoProvider
The service contract for external crypto providers.

An external crypto provider is used for crypto needs which a WSO2 server come cross, when communicating with an external entity.

One example is signing a message which goes out from a WSO2 server. Another example is decrypting an encrypted message sent by an external entity to a WSO2 server.

An implementation which uses a Java key store file to carryout above tasks, is a sample implementation of this contract.

As per the design decisions, the contract should never be amended in a way that the secret keys are returned to the caller.

  • Method Details

    • sign

      byte[] sign(byte[] data, String algorithm, String javaSecurityAPIProvider, CryptoContext cryptoContext, PrivateKeyInfo privateKeyInfo) throws CryptoException
      Computes and returns the signature of given data.
      Parameters:
      data - The data whose signature is calculated.
      algorithm - The signature + hashing algorithm to be used in signing.
      javaSecurityAPIProvider - The Java Security API provider.
      cryptoContext - The context information was used to find discovery information about the private key.
      privateKeyInfo - The information which used to retrieve the private key. If this information is not sufficient the CryptoContext will be used to get more information.
      Returns:
      The digital signature of given data.
      Throws:
      CryptoException - If something unexpected happens during the signing operation.

    • decrypt

      byte[] decrypt(byte[] ciphertext, String algorithm, String javaSecurityAPIProvider, CryptoContext cryptoContext, PrivateKeyInfo privateKeyInfo) throws CryptoException
      Computes and returns the cleartext of the given ciphertext.
      Parameters:
      ciphertext - The ciphertext to be decrypted.
      algorithm - The signature + hashing algorithm to be used in signing.
      javaSecurityAPIProvider - The Java Security API provider.
      cryptoContext - The context information which was used to find discovery information about the private key.
      privateKeyInfo - The information which used to retrieve the private key. If this information is not sufficient the CryptoContext will be used to get more information.
      Returns:
      The cleartext
      Throws:
      CryptoException - If something unexpected happens during the decryption operation.

    • encrypt

      byte[] encrypt(byte[] data, String algorithm, String javaSecurityAPIProvider, CryptoContext cryptoContext, CertificateInfo certificateInfo) throws CryptoException
      Computes and returns the ciphertext of the given cleartext.
      Parameters:
      data - The cleartext to be encrypted.
      algorithm - The signature + hashing algorithm to be used in signing.
      javaSecurityAPIProvider - The Java Security API provider.
      cryptoContext - The context information which was used to find discovery information about the certificate of the external entity.
      certificateInfo - The information which is needed to retrieve the certificate. If this information is not sufficient the CryptoContext will be used to get more information.
      Returns:
      The cleartext
      Throws:
      CryptoException - If something unexpected happens during the encryption operation.

    • verifySignature

      boolean verifySignature(byte[] data, byte[] signature, String algorithm, String javaSecurityAPIProvider, CryptoContext cryptoContext, CertificateInfo certificateInfo) throws CryptoException
      Verifies whether given signature of the given data was generated by a trusted external party.
      Parameters:
      data - The data which was the signature generated on.
      signature - The signature bytes of data.
      algorithm - The signature + hashing algorithm to be used in signing.
      javaSecurityAPIProvider - The Java Security API provider.
      cryptoContext - The context information which is needed to discover the public key of the external entity.
      certificateInfo - The information which is needed to retrieve the certificate. If this information is not sufficient the CryptoContext will be used to get more information.
      Returns:
      true if signature can be verified, false otherwise.
      Throws:
      CryptoException - If something unexpected happens during the signature verification.

    • getCertificate

      Certificate getCertificate(CryptoContext cryptoContext, CertificateInfo certificateInfo) throws CryptoException
      Returns the Certificate based on the given CryptoContext.
      Parameters:
      cryptoContext - The context information which is used to discover the public key of the external entity.
      certificateInfo - The information which is needed to retrieve the certificate. If this information is not sufficient the CryptoContext will be used to get more information.
      Returns:
      The Certificate relates with the given context.
      Throws:
      CryptoException - If something unexpected happens during certificate discovery.

    • getPrivateKey

      PrivateKey getPrivateKey(CryptoContext cryptoContext, PrivateKeyInfo privateKeyInfo) throws CryptoException
      Returns the PrivateKey based on the given CryptoContext.
      Parameters:
      cryptoContext - The context information which is used to discover the applicable private key.
      privateKeyInfo - The information which is needed to retrieve the private key. If this information is not sufficient, the CryptoContext will be used to get more information.
      Returns:
      The Certificate relates with the given context.
      Throws:
      CryptoException - If something unexpected happens during private key discovery.

    • hybridEncrypt

      default HybridEncryptionOutput hybridEncrypt(HybridEncryptionInput hybridEncryptionInput, String symmetricAlgorithm, String asymmetricAlgorithm, String javaSecurityProvider, CryptoContext cryptoContext, CertificateInfo certificateInfo) throws CryptoException
      Computes and return a HybridEncryptionOutput based on provided HybridEncryptionInput.
      Parameters:
      hybridEncryptionInput - Input data for hybrid encryption.
      symmetricAlgorithm - The symmetric encryption/decryption algorithm.
      asymmetricAlgorithm - The asymmetric encryption/decryption algorithm.
      javaSecurityProvider - The Java Security API provider.
      cryptoContext - The context information which is used to discover the public key of the external entity.
      Returns:
      HybridEncryptionOutput cipher text with required parameters
      Throws:
      CryptoException

    • hybridDecrypt

      default byte[] hybridDecrypt(HybridEncryptionOutput hybridEncryptionOutput, String symmetricAlgorithm, String asymmetricAlgorithm, String javaSecurityProvider, CryptoContext cryptoContext, PrivateKeyInfo privateKeyInfo) throws CryptoException
      Computes and return clear data based on provided HybridEncryptionOutput.
      Parameters:
      hybridEncryptionOutput - HybridEncryptionOutput ciphered data with parameters.
      symmetricAlgorithm - The symmetric encryption/decryption algorithm.
      asymmetricAlgorithm - The asymmetric encryption/decryption algorithm.
      javaSecurityProvider - The Java Security API provider.
      cryptoContext - The context information which is used to discover the public key of the external entity.
      Returns:
      the decrypted data
      Throws:
      CryptoException