com.adaptris.security

Interface SecurityService

public interface SecurityService

Interface for handling encryption, signing and verification requests.

Before using this service, there are a number pre-requisites that have to be fulfilled. They are, in no particular order

• A keystore containing the local certificate (+key) and the remote party's certificate must exist
• If a symmetric key algorithm such as DESede is to be used, then it must be agreed with the remote party
• The Certificates in the keystore must be valid (i.e. not expired and not revoked by the CA

A code example follows

  
    SecurityService s = SecurityFactory.createService();
    KeyStoreLocation ksi = KeystoreFactory.getDefault()
            .create("file:///testKeyStore?type=JKS", 
                    "password".toCharArray());
    s.registerKeyStore(ksi);
    Alias src = new Alias("myalias", "mypassword");
    Alias partner = new Alias("theiralias");
    Output target = s.encrypt("abcdefg".getBytes(), src, partner);
    System.out.println(target.getAsString());
 
 

See Also:

KeystoreLocation

Method Summary

Modifier and Type	Method and Description
Output	encrypt(byte[] payload, Alias us, Alias partner) Encrypt the given string into the Output object.
Output	encrypt(java.lang.String payload, Alias us, Alias partner) Encrypt the given string into the Output object.
void	registerKeystore(ConfiguredKeystore k) Register a keystore object for use during encryption sign and verify.
void	removeKeystore(ConfiguredKeystore k) Remove a keystore from the underlying map.
void	setEncryptionAlgorithm(EncryptionAlgorithm a) Set the encryption algorithm.
Output	sign(byte[] payload, Alias us) Sign the payload with the private key specified by Alias .
Output	sign(byte[] payload, Alias us, Output target) Sign the payload with the private key specified by Alias .
Output	sign(java.lang.String payload, Alias us) Sign the payload with the private key specified by Alias .
Output	sign(java.lang.String payload, Alias us, Output target) Sign the payload with the private key specified by Alias .
Output	verify(byte[] payload, Alias us, Alias partner) Decrypt the given bytes into the Output object.
Output	verify(java.lang.String payload, Alias us, Alias partner) Decrypt the given string into the Output object.

Method Detail

setEncryptionAlgorithm

void setEncryptionAlgorithm(EncryptionAlgorithm a)
                     throws AdaptrisSecurityException

Set the encryption algorithm.

Using this method will override the algorithm that is specified by the partner's public key. Generally, assymmetric keys are considered computationally intensive, so a symmetric key is used to encrypt the payload and this key is encrypted assymmetrically and sent along with the message itself.

Parameters:

a - the algorithm to be used for encryption purposes.

Throws:

AdaptrisSecurityException - wrapping any underlying exception

See Also:

EncryptionAlgorithm

registerKeystore

void registerKeystore(ConfiguredKeystore k)
               throws AdaptrisSecurityException

Register a keystore object for use during encryption sign and verify.

If this method is called multiple times, then all keystores that have been registered will be searched for a matching certificate or private key.

Parameters:

k - the KeystoreLocation object to register.

Throws:

AdaptrisSecurityException - wrapping any underlying exception

See Also:

KeystoreLocation

removeKeystore

void removeKeystore(ConfiguredKeystore k)
             throws AdaptrisSecurityException

Remove a keystore from the underlying map.

Parameters:

k - the KeystoreLocation object to remove.

Throws:

AdaptrisSecurityException - wrapping any underlying exception

encrypt

Output encrypt(byte[] payload,
               Alias us,
               Alias partner)
        throws AdaptrisSecurityException

Encrypt the given string into the Output object.

Parameters:

payload - the unencrypted payload.

us - a reference to the alias within the keystore to be used

partner - a reference to the alias within the keystore to be used

Returns:

Output object appropriate for this service type

Throws:

AdaptrisSecurityException - wrapping any exception

See Also:

Alias, Output

encrypt

Output encrypt(java.lang.String payload,
               Alias us,
               Alias partner)
        throws AdaptrisSecurityException

Encrypt the given string into the Output object.

This is a convenience method that simply returns this.encrypt(payload.getBytes(), us, partner). No attempt is made to handle character encoding, the default is used.

Parameters:

payload - the unencrypted payload.

us - a reference to the alias within the keystore to be used

partner - a reference to the alias within the keystore to be used

Returns:

Output object appropriate for this service type

Throws:

AdaptrisSecurityException - wrapping any exception

See Also:

Alias, Output, encrypt(byte[], Alias, Alias)

verify

Output verify(java.lang.String payload,
              Alias us,
              Alias partner)
       throws AdaptrisSecurityException

Decrypt the given string into the Output object.

This is a convenience method that simply returns this.verify(payload.getBytes(), us, partner). No attempt is made to handle character encoding, the default is used.

Parameters:

payload - the payload in the appropriate format for this SecurityService instance.

us - a reference to the alias within the keystore to be used

partner - a reference to the alias within the keystore to be used

Returns:

Output object appropriate for this service type

Throws:

AdaptrisSecurityException - for any exception

See Also:

Alias, Output, verify(byte[], Alias, Alias)

verify

Output verify(byte[] payload,
              Alias us,
              Alias partner)
       throws AdaptrisSecurityException

Decrypt the given bytes into the Output object.

This will also verify that the signature (if provided is correct)

Parameters:

payload - the payload in the appropriate format for this SecurityService instance.

us - a reference to the alias within the keystore to be used

partner - a reference to the alias within the keystore to be used

Returns:

Output object appropriate for this service type

Throws:

AdaptrisSecurityException - for any exception

See Also:

Alias, Output

sign

Output sign(byte[] payload,
            Alias us,
            Output target)
     throws AdaptrisSecurityException

Sign the payload with the private key specified by Alias .

Parameters:

payload - the unencrypted data to be signed.

us - a reference to the alias within the keystore to be used for signing

target - the target which was returned by a previous encryption request

Returns:

Output object appropriate for this service type

Throws:

AdaptrisSecurityException - for any exception

See Also:

Alias, Output

sign

Output sign(java.lang.String payload,
            Alias us,
            Output target)
     throws AdaptrisSecurityException

Sign the payload with the private key specified by Alias .

This is a convenience method that simply returns this.sign(payload.getBytes(), us, target). No attempt is made to handle character encoding, the default is used.

Parameters:

payload - the unencrypted data to be signed.

us - a reference to the alias within the keystore to be used for signing

target - the target which was returned by a previous encryption request

Returns:

Output object appropriate for this service type

Throws:

AdaptrisSecurityException - for any exception

See Also:

Alias, Output, sign(byte[],Alias,Output)

sign

Output sign(byte[] payload,
            Alias us)
     throws AdaptrisSecurityException

Sign the payload with the private key specified by Alias .

Parameters:

payload - the unencrypted data to be signed.

us - a reference to the alias within the keystore to be used for signing

Returns:

Output object appropriate for this service type

Throws:

AdaptrisSecurityException - for any exception

See Also:

Alias, Output

sign

Output sign(java.lang.String payload,
            Alias us)
     throws AdaptrisSecurityException

Sign the payload with the private key specified by Alias .

This is a convenience method that simply returns this.sign(payload.getBytes(), us). No attempt is made to handle character encoding, the default is used.

Parameters:

payload - the unencrypted data to be signed.

us - a reference to the alias within the keystore to be used for signing

Returns:

Output object appropriate for this service type

Throws:

AdaptrisSecurityException - for any exception

See Also:

Alias, Output, sign(byte[], Alias)