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 Summary

Modifier and Type	Method and Description
byte[]	decrypt(byte[] ciphertext, String algorithm, String javaSecurityAPIProvider, CryptoContext cryptoContext, PrivateKeyInfo privateKeyInfo) Computes and returns the cleartext of the given ciphertext.
byte[]	encrypt(byte[] data, String algorithm, String javaSecurityAPIProvider, CryptoContext cryptoContext, CertificateInfo certificateInfo) Computes and returns the ciphertext of the given cleartext.
Certificate	getCertificate(CryptoContext cryptoContext, CertificateInfo certificateInfo) Returns the Certificate based on the given CryptoContext.
PrivateKey	getPrivateKey(CryptoContext cryptoContext, PrivateKeyInfo privateKeyInfo) Returns the PrivateKey based on the given CryptoContext.
default byte[]	hybridDecrypt(HybridEncryptionOutput hybridEncryptionOutput, String symmetricAlgorithm, String asymmetricAlgorithm, String javaSecurityProvider, CryptoContext cryptoContext, PrivateKeyInfo privateKeyInfo) Computes and return clear data based on provided HybridEncryptionOutput.
default HybridEncryptionOutput	hybridEncrypt(HybridEncryptionInput hybridEncryptionInput, String symmetricAlgorithm, String asymmetricAlgorithm, String javaSecurityProvider, CryptoContext cryptoContext, CertificateInfo certificateInfo) Computes and return a HybridEncryptionOutput based on provided HybridEncryptionInput.
byte[]	sign(byte[] data, String algorithm, String javaSecurityAPIProvider, CryptoContext cryptoContext, PrivateKeyInfo privateKeyInfo) Computes and returns the signature of given data.
boolean	verifySignature(byte[] data, byte[] signature, String algorithm, String javaSecurityAPIProvider, CryptoContext cryptoContext, CertificateInfo certificateInfo) Verifies whether given signature of the given data was generated by a trusted external party.

Method Detail

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