be.ehealth.technicalconnector.service.kgss.impl

## Class KgssServiceImpl

- java.lang.Object
- - be.ehealth.technicalconnector.service.kgss.impl.KgssServiceImpl

- All Implemented Interfaces:
    ConfigurationModuleBootstrap.ModuleBootstrapHook, KgssService

      public class KgssServiceImpl
      extends Object
      implements KgssService, ConfigurationModuleBootstrap.ModuleBootstrapHook

  Implementation of `KgssService`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `EHEALTH_SUCCESS_CODE_100` The eHealth success codes.
    `static String` | `EHEALTH_SUCCESS_CODE_200` The eHealth success codes.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `KgssServiceImpl()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `bootstrap()`
    `static boolean` | `checkReplyStatus(String responseCode)` Check reply status of the web service call, return true when OK.
    `KeyResult` | `getKey(GetKeyRequestContent request, byte[] etkKGSS, SessionItemView session)` Retrieves an existing key from the KGSS using the credentials contained in the given session.
    `GetKeyResponseContent` | `getKey(GetKeyRequestContent request, Credential encryption, Credential service, Element samlAssertion, Map<String,PrivateKey> decryptionKeys, byte[] etkKGSS)` Retrieves an existing key from the KGSS using explicit credentials and a raw SAML assertion.
    `GetKeyResponseContent` | `getKey(GetKeyRequestContent request, SAMLTokenContainer container, 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 encryption, Map<String,PrivateKey> decryptionKeys, byte[] etkKGSS)` Asks the KGSS to generate and store a new key, returning the full response content.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### EHEALTH_SUCCESS_CODE_100

          public static final String EHEALTH_SUCCESS_CODE_100

      The eHealth success codes.
      See Also:
        Constant Field Values

    - #### EHEALTH_SUCCESS_CODE_200

          public static final String EHEALTH_SUCCESS_CODE_200

      The eHealth success codes.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### KgssServiceImpl

          public KgssServiceImpl()

  - ### Method Detail

    - #### getNewKey

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

      Description copied from interface: `KgssService`
      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 `KgssService.getNewKey(GetNewKeyRequestContent, Credential, Map, byte[])` when you need explicit control over those credentials.

      Specified by:
        `getNewKey` in interface `KgssService`
      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

          public GetNewKeyResponseContent getNewKey(GetNewKeyRequestContent request,
                                                    Credential encryption,
                                                    Map<String,PrivateKey> decryptionKeys,
                                                    byte[] etkKGSS)
                                             throws TechnicalConnectorException

      Description copied from interface: `KgssService`
      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.
      Specified by:
        `getNewKey` in interface `KgssService`
      Parameters:
        `request` - the business content describing the key to generate; 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`.
        `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.
        `etkKGSS` - 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

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

      Description copied from interface: `KgssService`
      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 `KgssService.getKey(GetKeyRequestContent, Credential, Credential, Element, Map, byte[])` when you need explicit control over those values.

      Specified by:
        `getKey` in interface `KgssService`
      Parameters:
        `request` - the business content identifying the key to retrieve, including its identifier; must not be `null`.
        `etkKGSS` - 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

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

      Description copied from interface: `KgssService`
      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.
      Specified by:
        `getKey` in interface `KgssService`
      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`.
        `service` - 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.
        `etkKGSS` - 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

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

      Description copied from interface: `KgssService`
      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.

      Specified by:
        `getKey` in interface `KgssService`
      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

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

      Description copied from interface: `KgssService`
      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`.

      Specified by:
        `getKey` in interface `KgssService`
      Parameters:
        `request` - the business content identifying the key to retrieve; must not be `null`.
        `container` - 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.

    - #### checkReplyStatus

          public static boolean checkReplyStatus(String responseCode)
                                          throws TechnicalConnectorException

      Check reply status of the web service call, return true when OK.
      Parameters:
        `responseCode` - the response code
      Returns:
        true, if successful
      Throws:
        `TechnicalConnectorException` - the technical connector exception

    - #### bootstrap

          public void bootstrap()

      Specified by:
        `bootstrap` in interface `ConfigurationModuleBootstrap.ModuleBootstrapHook`

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