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

    All Methods Instance Methods Abstract Methods
    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.

Connector Packaging OTMOBILITYIMPROVEMENT 4.9.5 API
Copyright © {inceptionYear}-2026 eHealth. All Rights Reserved.