be.ehealth.technicalconnector.service.kgss

Interface KgssService

All Known Implementing Classes:

KgssServiceImpl

public interface KgssService

Service interface for the eHealth-platform Key Generation and Storage Service (KGSS).

The KGSS exposes two core operations:

• getNewKey — generates a new key and stores it on the eHealth platform.
• getKey — retrieves a previously stored key by its identifier.

All business payloads exchanged with the KGSS are protected using the eHealth End-to-End Encryption (ETEE) approach for addressed messages. This service encapsulates both the encryption of outgoing requests and the decryption of incoming responses, so callers do not need to handle ETEE directly.

Default implementation: KgssServiceImpl

See Also:

KgssServiceImpl

Method Summary

Modifier and Type	Method and Description
KeyResult	getKey(GetKeyRequestContent request, byte[] kgssETK, SessionItemView session) Retrieves an existing key from the KGSS using the credentials contained in the given session.
GetKeyResponseContent	getKey(GetKeyRequestContent request, Credential encryption, Credential serviceCredential, Element samlAssertion, Map<String,PrivateKey> decryptionKeys, byte[] etk) Retrieves an existing key from the KGSS using explicit credentials and a raw SAML assertion.
GetKeyResponseContent	getKey(GetKeyRequestContent request, SAMLTokenContainer tokenContainer, KgssMessageBuilder builder) Retrieves an existing key from the KGSS using a SessionItemView and a caller-supplied KgssMessageBuilder.
GetKeyResponseContent	getKey(GetKeyRequestContent request, SAMLToken token, KgssMessageBuilder builder) Retrieves an existing key from the KGSS using a pre-built SAMLToken and a caller-supplied KgssMessageBuilder.
KeyResult	getNewKey(GetNewKeyRequestContent request, byte[] kgssETK) Convenience method that asks the KGSS to generate and store a new key using the current Session.
GetNewKeyResponseContent	getNewKey(GetNewKeyRequestContent request, Credential encryptionCredential, Map<String,PrivateKey> decryptionKeys, byte[] kgssETK) Asks the KGSS to generate and store a new key, returning the full response content.

Method Detail

getNewKey

KeyResult getNewKey(GetNewKeyRequestContent request,
                    byte[] kgssETK)
             throws TechnicalConnectorException

Convenience method that asks the KGSS to generate and store a new key using the current Session.

Encryption and decryption credentials are resolved automatically from the active session. Use getNewKey(GetNewKeyRequestContent, Credential, Map, byte[]) when you need explicit control over those credentials.

Parameters:

request - the business content describing the key to generate; must not be null.

kgssETK - the End-To-End encryption key (ETK) of the KGSS, as retrieved from the Key Depot getETK operation; must not be null.

Returns:

a KeyResult containing the generated SecretKey and its Base64-encoded identifier.

Throws:

TechnicalConnectorException - if the web service call fails, the response status is not a success code, or decryption of the response fails.

getNewKey

GetNewKeyResponseContent getNewKey(GetNewKeyRequestContent request,
                                   Credential encryptionCredential,
                                   Map<String,PrivateKey> decryptionKeys,
                                   byte[] kgssETK)
                            throws TechnicalConnectorException

Asks the KGSS to generate and store a new key, returning the full response content.

The following steps are executed internally:

1. Seal (encrypt) the GetNewKeyRequestContent using the ETEE addressed-message approach with the provided KGSS ETK.
2. Invoke the getNewKey web service operation.
3. Unseal (decrypt) the GetNewKeyResponseContent using the provided decryption keys.
4. Return the decrypted response.

Parameters:

request - the business content describing the key to generate; must not be null.

encryptionCredential - the credential used to seal the request — the certificate seals the payload and the private key is embedded in the request; must not be null.

decryptionKeys - the private keys available for unsealing the KGSS response, keyed by their identifier. Retrieve these from your KeyStore using the ETEE tooling; must not be null or empty.

kgssETK - the ETK of the KGSS, as retrieved from the Key Depot getETK operation; must not be null.

Returns:

the decrypted GetNewKeyResponseContent, including the generated key and its identifier.

Throws:

TechnicalConnectorException - if sealing, the web service call, or unsealing fails, or if the response contains error messages.

getKey

KeyResult getKey(GetKeyRequestContent request,
                 byte[] kgssETK,
                 SessionItemView session)
          throws TechnicalConnectorException

Retrieves an existing key from the KGSS using the credentials contained in the given session.

The session provides the encryption credential, decryption keys, and SAML token required to authenticate and process the request. Use getKey(GetKeyRequestContent, Credential, Credential, Element, Map, byte[]) when you need explicit control over those values.

Parameters:

request - the business content identifying the key to retrieve, including its identifier; must not be null.

kgssETK - the ETK of the KGSS, as retrieved from the Key Depot getETK operation; must not be null.

session - the active session supplying encryption credentials, decryption keys, and a SAML token; must not be null.

Returns:

a KeyResult containing the retrieved SecretKey and its identifier.

Throws:

TechnicalConnectorException - if the web service call fails or the response cannot be decrypted.

getKey

GetKeyResponseContent getKey(GetKeyRequestContent request,
                             Credential encryption,
                             Credential serviceCredential,
                             Element samlAssertion,
                             Map<String,PrivateKey> decryptionKeys,
                             byte[] etk)
                      throws TechnicalConnectorException

Retrieves an existing key from the KGSS using explicit credentials and a raw SAML assertion.

The following steps are executed internally:

1. Wrap the samlAssertion and serviceCredential in a SAMLToken.
2. Seal (encrypt) the GetKeyRequestContent using the ETEE addressed-message approach with the provided KGSS ETK.
3. Invoke the authenticated getKey web service operation.
4. Unseal (decrypt) the GetKeyResponseContent using the provided decryption keys.
5. Return the decrypted response.

Parameters:

request - the business content identifying the key to retrieve; must not be null.

encryption - the credential used to seal the request — the certificate seals the payload and the private key is embedded in the request; must not be null.

serviceCredential - the credential combined with the SAML assertion to authenticate the web service call; must not be null.

samlAssertion - the SAML assertion obtained from STS to authenticate the request; must not be null.

decryptionKeys - the private keys available for unsealing the KGSS response, keyed by their identifier; must not be null or empty.

etk - the ETK of the KGSS, as retrieved from the Key Depot getETK operation; must not be null.

Returns:

the decrypted GetKeyResponseContent containing the requested key.

Throws:

TechnicalConnectorException - if sealing, the web service call, or unsealing fails, or if the response contains error messages.

getKey

GetKeyResponseContent getKey(GetKeyRequestContent request,
                             SAMLToken token,
                             KgssMessageBuilder builder)
                      throws TechnicalConnectorException

Retrieves an existing key from the KGSS using a pre-built SAMLToken and a caller-supplied KgssMessageBuilder.

Use this method when you have already constructed the SAML token and message builder, for example in scenarios where they are reused across multiple calls.

Parameters:

request - the business content identifying the key to retrieve; must not be null.

token - the SAML token used to authenticate the web service call; must not be null.

builder - the message builder responsible for sealing the request and unsealing the response; must not be null.

Returns:

the decrypted GetKeyResponseContent containing the requested key.

Throws:

TechnicalConnectorException - if the web service call fails or the response cannot be decrypted.

getKey

GetKeyResponseContent getKey(GetKeyRequestContent request,
                             SAMLTokenContainer tokenContainer,
                             KgssMessageBuilder builder)
                      throws TechnicalConnectorException

Retrieves an existing key from the KGSS using a SessionItemView and a caller-supplied KgssMessageBuilder.

The session view provides the SAML token container used to authenticate the web service call, while the builder handles sealing and unsealing of the message payload. This overload is useful when a lightweight session view is available instead of a full SessionItem.

Parameters:

request - the business content identifying the key to retrieve; must not be null.

tokenContainer - the session view supplying the SAML token container; must not be null.

builder - the message builder responsible for sealing the request and unsealing the response; must not be null.

Returns:

the decrypted GetKeyResponseContent containing the requested key.

Throws:

TechnicalConnectorException - if the web service call fails or the response cannot be decrypted.