X-Road User Guide
This document is based on X-Road version 6 software, guidelines of the administration system of state information system (RIHA), and regulation No. 78 of 24/04/2008 of the Government of the Republic, Exchange Layer of Information Systems (in Estonian, English unofficial translation). The aim of the document is to explain to the members how to affiliate with X-Road version 6 and hot to use it.
In addition to the X-Road software, RIHA is used to manage X-Road. This means that to use X-Road, information on the X-Road member, the X-Road subsystem, data store providing the dataservice, and the dataservice must be entered into RIHA.
This guide has been created for planning activities required for affiliating membership and interfacing.
2. Affiliation of membership
2.1. Choosing an environment upon affiliation of membership
The Estonian X-Road includes three environments: production environment, test environment, and development environment. The purpose of these environments and technical parameters of the environments can be found here.
NB! In order to join the X-Road production environment, the member must adhere to all requirements that have been provided in the exchange layer of information systems regulation – these have been described in chapter ‘Obligations of an X-Road Member (in Estonian)’ of the application guide. This includes declaring a security measures system in RIHA, on the subsystem registration application (see clause 4).
2.2. Affiliation of X-Road membership (becoming a member)
A precondition for the affiliation of membership of the X-Road production environment is an up-to-date description of the data of the entity applying for the membership of X-Road – the institution and contact persons – in the state information system RIHA.
Differences in the development environment:
Submission of an application is not required in the state information system RIHA to join the X-Road development environment.
3. Installing and configuring a security server
In order to enable creating an X-Road secure data exchange channel, each X-Road member must follow the steps provided in figure 2. The corresponding sub-chapter gives more details for each step.
3.1. Preparations for installing a security server
Preconditions for installing a security server:
- Being a member (chapter 2)
- Owning a signature creation device (chapter 3.1.1)
- Having the opportunity to use trust services which adhere to the requirements of the X-Road governing authority (chapter 3.1.2)
3.1.1. Signature creation device and choosing one
The requirement for a signature creation device may come from the provider of the trust service.
E.g. SK ID Solutions AS requires a signature creation device when issuing an electronic seal certificate for the X-Road version 6 production environment.
The criteria for choosing a signature creation device can be found here.
It is not required to purchase a signature creation device which adheres to the requirements of QSCD to sign X-Road inquiries, because the signatures of X-Road inquiries are advanced electronic seals in the meaning of eIDAS, which are based on a qualified certificate (see more information in chapter 3.1.2).
RIA provides the requirement that the signature creation device should support the PKCS#10 protocol; in that case, it is compatible with the security server.
Differences in the development and test environment: a member is not obligated to use a signature creation device.
3.1.2. Choosing a trust service
The provider of the timestamp service used must be marked at the beginning of the configuration of the security server. Certificates can be applied for after the installation of a security server. Certificates can be purchased from all certifiers who are in the European trusted list if their trust services adhere to the technical requirements of X-Road (PS! The document was updated on 2 June 2016).
In order to ensure the integrity of data exchange and identify a connection between a message mediated by X-Road and an X-Road member, all the following services of qualified trust service providers adhering to the requirements of the X-Road governing authority must be configured and usable in the security server.
- Signature certificate of a member (the so-called SIGN certificate) – of electronic seals, certificates that are intended to be created with a qualified electronic seal or qualified certificates of an advanced electronic seal are suitable for using. For a qualified electronic seal, eIDAS provides that the corresponding qualified certificate may have only been issued for QSCD. In the case of an advanced electronic seal, a signature creation device which adheres to the requirements of QSCD is not necessary – in that case, the provider of the trust service decides which terms and conditions are applied to issuing the certificate*. If a security server is being hosted, there could be several electronic seal certificates in one security server. In that case, the security server must include the electronic seal certificate of the owner of the security server, as well as one electronic seal certificate in one security server per each hosted member. The electronic seal certificates may be ordered separately.
- Authentication certificate of a security server (to authenticate the owner of the security server; the so-called AUTH certificate) – one per each security server.
- Online Certificate Status Protocol (OCSP) service. E.g. when ordering the OCSP service from SK ID Solutions AS, it must be noted that this is a closed service, i.e. when entering into an OCSP agreement, IPs must be determined that can be used to access the services. The IPs provided must be unique.
- Timestamp service.
- Common Criteria certification pursuant to standard EN 419 211 or
- Federal Information Processing Standards Publication 140-2 level 2 or higher.
*E.g. in the case of advanced electronic seals of SK ID Solutions AS, one of the following requirements must be fulfilled (requirements which enter into force as of 1 July can be found here):
The interval of using a validation and timestamp service cannot be longer than four hours. The actual volume of timestamp and validation services is dependent on the number of security servers and signature certificates: a validation inquiry per each AUTH and SIGN certificate is done every 48 minutes and each security server makes a timestamp inquiry every 48 minutes. The default configuration of the security server also follows this principle.
E.g. the OCSP service volume for a member who maintains one security server for themselves (1 SIGN certificate, 1 AUTH certificate), is 1860 inquiries per month. The volume of the timestamp service is 930 inquiries per month.
Service volume is not contingent upon the number of partners, services, or messages.
Differences in the development and test environment
- Test certificates of trust service providers must be used in the test environment.
- Depending on the trust service provider the method for obtaining test sertificates may be different from obtaining normal certificates. For example test sertificates can be obtained from SK ID Solutions AS as follows:
- Test certificate for authentication can be ordered by marking the "Order test certificate" checkbox from here.
- Test certificate for electronic seal can be ordered by marking "Order test certificate" checkbox from here.
NB: If You're using test certificates issued by SK ID Solutions AS, then You have to manually upload them to SK's OCSP demo environment.
- In the case of test certificates of certain trust service providers, it may be required to add the test certificates manually to the test OCSP list (e.g. in the case of services of SK ID Solutions AS, it can be done here).
- Testing in the development environment can be done with certificates issued by RIA (same as with version 5).
- The intervals of validation and timestamping in the development and test environment are different from the ones in the production environment, see more here.
- It is not mandatory to use a signature creation device in the development and test environment. This is supplemented by a soft token in the security server.
3.2. Installing a security server
- Security server software is installed based on the installation guide.
- The configuration anchor of the corresponding environment must be downloaded and it is available here.
- A signature creation device must be installed in the security server (using a signature creation device is not mandatory in the development and test environment).
- The requirements of the Estonian X-Road environment must be adhered to upon installation; the
requirements have been provided here.
NB! If the security server owner or hosted client is a foreign organization (not Estonian), then the "NEE" Member Class must be selected in the security server.
The Member Code must be formed as follows:
1) NTR - Prefix of the legal entity identifier according to ETSI EN 319 412-1 clause 5.1.4.
2) COUNTRY CODE - Country code according to ISO 3166 (Alpha 2)
3) - hyphen
4) REGISTRY CODE - Organizational registry code in the organization's country
Lexbyte Digital Limited, a registered organization in Malta
Member Name: Lexbyte Digital Limited
Member Class: NEE
Member Code: NTRMT-C56249
Such requirements to the NEE Member Code are necessary to ensure the uniqueness of the Member Code of foreign organizations on X-Road (X-tee). In addition, the Member Code of X-Road members must correspond to the Organization Identifier (188.8.131.52) field in the SK ID Solutions AS e-Seal certificate profile.
- SK ID Solutions AS certificate profile: https://sk.ee/upload/files/SK-CPR-KLASS3-EN-v8_0-20171130.pdf
- ETSI EN 319 412-1: http://www.etsi.org/deliver/etsi_en/319400_319499/31941201/01.01.00_30/en_31941201v010100v.pdf
- Alpha 2 country code: https://www.iso.org/obp/ui/#search
- Malta company register http://rocsupport.mfsa.com.mt/pages/SearchCompanyInformation.aspx
3.2.1. Changing the IP of the security server
If a member has to change the IP address of the production environment, they must act as follows.
- The member must submit a signed application to the X-Road governing authority (contact person marked in RIHA as having the rights of X-Road system administrator or a person having the right of representation of the company) to change the IP address in the central server. The application must be sent to firstname.lastname@example.org. The application form can be found here. In the course of processing the application, all necessary activities and time for changing the IP address must be agreed upon with the member.
- The member must notify the trust service provider about the need to change the IP address (to ensure the operation of OSCP and timestamp service).
- The X-Road governing authority must notify the member about the outcome of the application.
Differences in the development and test environment
- In order to change the IP address in the development and test environment, a request must be sent to the X-Road governing authority to email@example.com, including the following information: name and registry code of the company, security server code, environment for which the IP address is changed, old and new IP of the secure server, information of the contact person (name, e-mail, phone number).
- The trust service provider must also be notified about the need to change the IP address.
3.3. Configuration of trust services
- In order to order an authentication certificate of security server (AUTH) and an electronic seal certificate (SIGN) from the trust service provider, certificate inquiries in the security sever must be generated following the security server user guide.
- All certification inquiries must be saved and forwarded to the provider of the trust service.
- The trust service provider will issue a certificate that must be configured in the secure server based on the secure server user guide, including marking an external IP address (for an AUTH certificate).
- The member must send to the X-Road governing authority at firstname.lastname@example.org (after applying for an authentication certificate for a security server through the security server interface) an application for registration of a security server, including the following information: request for registration of a security server, name of the company, registry code of the company, and information of the contact person.
Information on configuration of the timestamp service in the security server and generating a request for an authentication and signature certificate of the security server can be found in the security server user guide (System Parameters, Security Server Registration).
Differences in the development and test environment: in order to apply for a development environment certificate, a certificate application (AUTH and SIGN csrs) must be sent via e-mail to email@example.com.
E.g. when applying for production and test certificates from SK ID Solutions AS, orders can be made through their e-service environment www.sk.ee.
- Order X-Road security server client certificates. If you are not the owner of the security server and you procure a security server hosting service, order the services as a security server client.
- Order X-Road security server host certificates. If you operate your own X-Road security server, order the services as a host of security server.
The person who formulates the order must sign the application.
3.4. Registering a security server on X-Road
- Apply for registration of a security server through the security server interface (registration of an AUTH
certificate) based on the security server user manual. Management of X-Road version 6 security server certificates is not
carried out through RIHA.
NB! If you use the services of SK ID Solutions AS or another trust service provider, the AUTH certificate of the X-Road test environment must be sent to the X-Road governing authority (RIA) at firstname.lastname@example.org.
- The X-Road governing authority will notify the X-Road system administrator (contact person entered into RIHA) about the registration of a security server. Registration information is also available in the security server.
Information on security server registration can be found in user guides (Registering the security server in the X-road Governing Authority)
4. Registration of an X-Road subsystem (interfacing with X-Road)
In the 6th version of X-Road, providing and using data services is carried
out through the subpart of an information system belonging to a company which
has joined X-Road – the X-Road subsystem (security server object SUBSYSTEM).
Unlike the 5th version of X-Road, access rights are only granted to subsystems of X-Road members, not X-Road members as companies.
The information systems of X-Road members and security server points of interface that can be determined as the provider or user of a data service are registered as subsystems of X-Road.
Each company defines the X-Road subsystem(s), taking into account the complete information system of the company. In defining X-Road subsystem(s), the first thing to consider is how the company could best decompose and distribute their information systems (which provide or use services) in terms of handling, considering the following aspects:
- systems which operate on the same legal basis
- systems with a same security level access
- systems which operate on the same technical principals (e.g. are hosted externally).
We recommend only using this if the information system of your company is small and there are no objective bases for dividing the company in the information system. In all other cases, we recommend decomposing your information system in X-Road into better addressed parts.
For example: the services used by the RIA State Portal www.eesti.ee can be handled separately by X-Road subsystems:
- In security server 'EE / GOV / 70006317 /
riigiportaal-citizen' – services open to citizens.
Registered as a subsystem 70006317-riigiportaal-citizen in RIHA.
- In security server 'EE / GOV / 70006317 /
riigiportaal-official' – services open to officials.
Registered as a subsystem 70006317-riigiportaal-official in RIHA.
- In security server 'EE / GOV / 70006317 / riigiportaal-system' – services necessary for the functioning of the State Portal (notification
calendar, official e-mail, etc.)
Registered as a subsystem 70006317-riigiportaal-system in RIHA.
Information regarding the management of information in a security server can be found in the user manuals ‘Security Server Clients’.
4.1. Describing and registering a subsystem of X-Road production environment in the state information system RIHA
Databases / information systems registered during X-Road v5, which were issued an X-Road v5 database certificate, are not subsystems of X-Road v6.
It is only possible to register X-Road subsystems in the X-Road centre of the X-Road production environment if:
- they have been described in the state information system RIHA (see chapter 4.1.1)
- a contact person responsible for the operation of the X-Road subsystem, the data of the administrator of the security server servicing the subsystem, and the security measures system of the X-Road subsystem have been assigned to them. State and local government institutions must determine a security class in accordance with the regulation established in clause 439 (1) 4) of the Public Information Act.
It is essential to keep this information updated in the state information system RIHA so that the data service providers would have a channel through which to identify the security system and security class of the users of the data service.
Differences in the development and test environment
- X-Road subsystems registered in a security server are not subject to checks.
- Subsystems are not registered in the state information system RIHA.
4.1.1. Registering a subsystem of the X-Road production environment (EE) in the state information system RIHA
Start describing an X-Road subsystem in the state information system RIHA here.
NB! Change/add an "Infosüsteemi märksõna" (Information system tag word) : X-tee alamüsteem (X-road subsystem)
In the case of foreign organizations (X-road Member Class is NEE) subsustem, in the RIHA field "Lühinimi" (Nickname): must use the X-road Member Code, see chapter 3.2
The Malta company's X-road Member Code is NTRMT-C56249, the subsystem's name is "ehma".
in the RIHA field "Lühinimi" must be NTRMT-C56249-ehma
The X-Road centre checks whether the data of an X-Road subsystem has been described in the state information system RIHA through a security server interface during the processing of an application for registering the subsystem. If the subsystem is not in the state information system RIHA or its description is not sufficient/complete, the X-Road centre shall not register it. Therefore, it is important to register a production environment subsystem in the state information system RIHA before submitting a registration application in the security server.
A list of X-Road production environment subsystems is available here.
4.2. Registering an X-Road subsystem in the X-Road (in the security server and X-Road centre)
NB! In the case of a production environment subsystem, clause 4.1.1 must be performed.
To provide and use X-Road data services, the X-Road subsystem must be registered in the X-Road centre. For this, the institution must add the X-Road subsystem to the security server and submit a registration application to the X-Road centre. If the X-Road member uses the security server’s hosting service, the owner of the security server shall register the X-Road subsystem.
The following will be entered to the subsystem in the security server in accordance with the user guide (Security Server Clients)
- Member Class.
- GOV - Estonian authorities
- COM - Estonian companies
- NGO - Estonian foundations and non-profit organisations
- NEE - institutions/companies of other countries
- Member Code – registry code of the institution of the subsystem owner
NB! if the subsystem is owned by a foreign company (NEE), see the Member Code formation rule in chapter 3.2
- Subsystem Code – name of the X-Road subsystem (lowercase characters).
The subsystem (short name registry code – name of the subsystem) of the production described in the state information system RIHA is entered in the security server without the registry code.
Example: name of subsystem in the state information system RIHA Lühinimi: ‘70006317-riha’ but in the security server SUBSYSTEM CODE ‘riha’.
The rules for naming DHX X-Road subsystems are available here: Reserved name DHX*
- Submit a registration application for an X-Road subsystem to the X-Road centre in accordance with the user guide (Registering a Security Server Client in the X-Road Governing Authority)
Differences in the development and test environment:
X-Road subsystems, which are being registered, do not have to be described in the state information system RIHA.
5. Development and registration of dataservices
On X-Road, exchange of data is carried out via dataservices. Realising dataservices is the right and obligation of members (providers of dataservices). Data/messages cannot be exchanged without a dataservice.
The X-Road governing authority only regulates the form of dataservices and information submitted regarding the dataservices. The X-Road governing authority does not regulate the contents of dataservices in any way.
All dataservices provided on X-Road must be described in RIHA along with a description of the dataservice which adheres to the requirements of the X-Road governing authority and is updated and relevant, including having information regarding a security device necessary for the use of the dataservice, considering the composition and nature of data included in the dataservice. The precondition for describing a dataservice in RIHA is that the system providing the service (data store, information system and/or their X-Road subsystem) has been registered in RIHA (see also chapter 4).
All dataservices provided in X-Road must be usable in the X-Road test environment.
Differences in the development and test environment: the X-Road governing authority does not apply checks to dataservices in the development environment.
6. Providing and using dataservices
Signing agreements for providing and using dataservices is an activity between X-Road members which the X-Road governing authority regulates to a minimum extent.
RIA recommends following this procedure when signing agreements for using and providing dataservices:
- analysing the need,
- identifying a suitable existing dataservice (e.g. through negotiations),
- if there is no dataservice, developing it and registering it in RIHA (see clauses 4 and 5),
- negotiations between the provider of the dataservice and the user, in the course of which, among others, the sufficient security level of the dataservice user’s X-Road subsystem is determined,
- signing an agreement for the use of the dataservice,
- granting the corresponding access right to the user of the dataservice for the dataservice provider’s security server (pursuant to the dataservice user agreement). Information regarding granting an access right can be found in the user guides,
- providing and using the dataservice pursuant to the dataservice user agreement.
Differences in the development and test environment: the X-Road governing authority does not regulate the provision and use of dataservices.