Package be.ehealth.technicalconnector.service.kgss

# Interface KgssService

All Known Implementing Classes:
  `KgssServiceImpl`

public interface KgssService
The eHealth-platform Key Generation and Storage Service (KGSS) provides a web service interface to create a new key using the getNewKey operation and to retrieve an existing key using the getKey operation. The services provided via this technical connector allow the invocation of both operations based on a specific set of input criteria. For security reasons is the business payload of the information exchanged with the KGSS encrypted suing the eHealth-platform End-to-End Encryption approach for addressed messages. In contradiction to the other technical services provided as part of his technical API encapsulates this service the actual encryption and decryption of the business message payload. Default impl : `KgssServiceImpl`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `KeyResult`
  `getKey(GetKeyRequestContent request, byte[] kgssETK, SessionItem session)`
  Gets the key.
  `GetKeyResponseContent`
  `getKey(GetKeyRequestContent request, Credential encryption, Credential serviceCredential, Element samlAssertion, Map<String,PrivateKey> decryptionKeys, byte[] etk)`
  Ask the eHealth-platform Key Generation and Storage Service (KGSS) to retrieve a key, based on a given key identifier.
  `KeyResult`
  `getNewKey(GetNewKeyRequestContent request, byte[] kgssETK)`
  Asks KGSS to generate and store a new key.
  `GetNewKeyResponseContent`
  `getNewKey(GetNewKeyRequestContent request, Credential encryptionCredential, Map<String,PrivateKey> decryptionKeys, byte[] kgssETK)`
  Ask the eHealth-platform Key Generation and Storage Service (KGSS) to generate and store a new key, and return the identifier.

- ## Method Details

  - ### getNewKey

    KeyResult getNewKey(GetNewKeyRequestContent request, byte[] kgssETK) throws TechnicalConnectorException
    Asks KGSS to generate and store a new key. It returns the Key with the Key Identifier
    Parameters:
      `request` - the request
      `kgssETK` - the kgss etk
    Returns:
      the new key
    Throws:
      `TechnicalConnectorException` - the technical connector exception

  - ### getKey

    KeyResult getKey(GetKeyRequestContent request, byte[] kgssETK, SessionItem session) throws TechnicalConnectorException
    Gets the key.
    Parameters:
      `request` - the request
      `kgssETK` - the kgss etk
      `session` - the session
    Returns:
      the key
    Throws:
      `TechnicalConnectorException` - the technical connector exception

  - ### getNewKey

    GetNewKeyResponseContent getNewKey(GetNewKeyRequestContent request, Credential encryptionCredential, Map<String,PrivateKey> decryptionKeys, byte[] kgssETK) throws TechnicalConnectorException
    Ask the eHealth-platform Key Generation and Storage Service (KGSS) to generate and store a new key, and return the identifier. The following sequential steps are executed as part of this operation: 1. Encryption of the business message (GetNewKeyRequest) using the ETEE approach for addressed messages using the provided KGSS ETK. 2. Invocation of the getNewKey web service operation. 3. Decryption of the business message (GetNewKeyResponse) using the ETEE approach for addressed messages using the provided ETK of the invoking application/organization (included within GetNewKeyRequest). 4. Return decrypted GetNewKeyResponse.
    Parameters:
      `request` - Business content to request a new key.
      `encryptionCredential` - The credential to use for sealing the message contents, the certificate is used to seal the request, the private key is embedded in the request
      `decryptionKeys` - The decrypion keys available for decrypting the received message from KGSS, you can use the ETEE tool to retrieve the decryption keys from your KeyStore
      `kgssETK` - ETK of the KGSS as retrieved via the Key Depot getETK operation
    Returns:
      The generated key, including its identifier.
    Throws:
      `TechnicalConnectorException` - When a technical exception occurs

  - ### getKey

    GetKeyResponseContent getKey(GetKeyRequestContent request, Credential encryption, Credential serviceCredential, Element samlAssertion, Map<String,PrivateKey> decryptionKeys, byte[] etk) throws TechnicalConnectorException
    Ask the eHealth-platform Key Generation and Storage Service (KGSS) to retrieve a key, based on a given key identifier. The following sequential steps are executed as part of this operation: 1. Encryption of the business message (GetKeyRequest) using the ETEE approach for addressed messages using the provided KGSS ETK. 2. Invocation of the getKey web service operation. 3. Decryption of the business message (GetKeyResponse) using the ETEE approach for addressed messages using the provided ETK of the invoking application/organization (included within GetKeyRequest). 4. Return decrypted GetKeyResponse.
    Parameters:
      `request` - Business content to request a key.
      `encryption` - The credential to use for sealing the message contents, the certificate is used to seal the request, the private key is embedded in the request
      `serviceCredential` - The credential to use in combination with your SAML assertion
      `samlAssertion` - The SAML assertion you got back from STS to authenticate your request
      `decryptionKeys` - The decrypion keys available for decrypting the received message from KGSS, you can use the ETEE tool to retrieve the decryption keys from your KeyStore
      `etk` - ETK of the KGSS as retrieved via the Key Depot getETK operation
    Returns:
      The requested key
    Throws:
      `TechnicalConnectorException` - When a technical exception occurs