General technical description
The Suomi.fi Data Exchange Layer is a data exchange system that enables organisations that have joined the service to transfer data between their information systems. Data exchange in the Data Exchange Layer is based on X-Road technology that originated in Estonia and its most recent version 7.
Data in the Data Exchange Layer is transmitted in an encrypted form over the public Internet. Data transmission is based on separate, physical or virtual Security Servers. The data are encrypted while being transferred by means of the cryptographic protocol TLS (SSL), and all the information is signed with certificates. The implementation of the Security Servers interface in the X-Road software uses the XML-based Simple Object Access Protocol (SOAP) data traffic protocol or the REST architectural style.
Read more about the Data Exchange Layer as a service.
Read more about X-Road technologyOpens in a new window..
Exchange of messages in the Data Exchange Layer
The central component of the X-Road software is the security server, which is a physical or virtual server. The security server connects the organisation’s systems to the Data Exchange Layer. All messages sent to or received from the Data Exchange Layer are routed through the security server, and therefore each organisation to be connected needs a security server. Among other things, it is used for transmission of service calls, security handshakes for service calls, encryption of data communications and messages, the keeping of logs and access right management.
In other words, security servers ensure the security of the Data Exchange Layer, as the traffic between them is encrypted by default. The security server may be located either in a data centre or in a cloud environment. It is possible to use either a Linux-based RHEL or Ubuntu security server or a Docker containerised security server in the Data Exchange Layer.
The customer organisation is responsible for encrypting the connection between the security server and the Information System and for general information security. If all connections are not encrypted, the security of the connection is reduced remarkably. Therefore, we recommend that you always use the HTTPS protocol between the security server and the customer organisation’s background system.
Certificates
Four types of certificates are used in the Data Exchange Layer:
- Authentication Certificate: The certificate is used to verify the authenticity of the security server, i.e., that the security server is trusted by the Data Exchange Layer. The certificate is unique for each security server.
- Signing Certificate: The certificate is used to verify that the organisation is trusted by the Data Exchange Layer. This certificate is used to sign and encrypt messages sent by systems. The certificate is unique for each organisation.
- TLS Client Certificate/Internal Certificate: The certificate is used by the security server to authenticate the Information System as trusted. The certificate encrypts the connection between the organisation’s information system and the security server. The certificate is used for HTTPS connections, i.e., it is mandatory if the security server is shared between several organisations. The Client Certificate is unique for each subsystem.
- The Security Server’s own certificate: The certificate is used by the Information System to authenticate the security server as trusted.
Authentication and Signing Certificates use certificates issued by the Digital and Population Data Services Agency. Authentication and Signing Certificates must be renewed annually. See how to verify the validity of certificates from the security server.
Data transfer
To connect to the Data Exchange Layer, the information system must either be capable of sending and receiving SOAP messages in the format required by X-Road or comply with the REST architecture for the implementation of interfaces. In practice this means that the SOAP messages must contain certain heading data as defined by the X-Road data transfer protocol. In addition, the request and response parameters must also be contained in the body of the SOAP message in the manner specified by the X-Road protocol. X-Road version 7 uses SOAP version 1.1. Whether the service used through the Data Exchange Layer uses SOAP or REST technology depends on the organisation providing the service.
When using the SOAP protocol, X-Road also requires a description of the services to be connected to it in WSDL (Web Service Description Language). The schemes that describe the structure of request and response messages may be contained in the WSDL description or, alternatively, in separate files referred to in the WSDL description using the import specification. The schema must make use of namespaces and unambiguous element names. When using REST interfaces, we recommend that the services be described according to the OpenAPI 3 specification. The WSDL and OpenAPI descriptions of the services offered through the Data Exchange Layer are available in the API Catalogue.