Instructions on the testing certificate

Key terms

Project
The project to establish a positive credit register answers for the development of the register. The project provides stakeholder support during testing.

Certificate Signing Request (CSR)
A PKCS#10 certificate signing request is sent to the certificate service API. The certificate service then generates a certificate, which can be retrieved through the certificate service API.

Certificate
An electronic identifier issued by the Incomes Register Unit to identify the user.

A testing certificate is for use in the stakeholder testing environment. Access rights and certificates for the API that will be used when the Positive credit register is rolled out to production at the beginning of 2024 must be requested separately before the rollout.

Testing organisation
A company or organisation participating in the stakeholder testing of the Positive credit register.

Technical contact person
A person who is specified by the testing organisation in the testing start notification and to whom the information needed to retrieve a testing certificate is sent.

Testing start notification
A testing start notification is submitted with an online form. In the notification, the stakeholder gives the Positive credit register the information needed to start testing, specifies the services to be tested, and accepts the terms and conditions of the testing environment.

More terminology in the instructions on stakeholder testing and in the Positive credit register’s glossary (Suomi.fi).

1 Introduction

This document provides instructions on the testing certificate used in the Positive credit register’s stakeholder testing. Instructions on stakeholder testing provide a general description of how the stakeholder testing is implemented.

In order that the APIs of the Positive credit register could be used, the party calling the API must be identified. The API user is identified based on a certificate. The certificates acceptable in the service are issued by the Tax Administration.

The certificate that will be used in production is different from the one used in testing. The stakeholders have received separate instructions on the certificate needed in the production environment. Read the instructions on the production certificate.

2 Certificate service

The Positive credit register uses the Incomes Register's certificate service in its stakeholder testing. The certificate service is based on a PKI solution (Public Key Infrastructure).

The customer is identified and the API access right verified based on a certificate. The Incomes Register Unit issues certificates to a specific organisation for specific purposes, and the certificates cannot be used for any other purposes. The certificate user must accept the terms and conditions of use for stakeholder testing and comply with them.

2.1 Certificate types

The APIs for reporting data and for requesting data are used with different types of certificates. If the service user is both a data notifier and a data user, they need different types of certificates for the different purposes of use. One operator can have several certificates. The certificates can be of the same type or of different types.

If the testing organisation tests both the reporting and the requesting of data, it needs different types of certificates.

• Two types of certificates are used in the Positive credit register: a certificate for reporting data and a certificate for requesting data.
• Each testing certificate is connected to an artificial Business ID and an artificial organisation name. The information is delivered to the person who filled in the testing start notification. If the testing organisation tests only the reporting of data or only the requesting of data, it needs one certificate and one artificial Business ID.
• If the testing organisation tests both the reporting and the requesting of data, it needs two different types of certificates, at least one of each type. In other words, the organisation needs one certificate for reporting data and one for requesting data. The same artificial Business ID is connected to both certificates. However, the testing organisation may have several artificial Business IDs and associated certificates, if needed. This may be necessary, for example, when the organisation tests the reporting of data on behalf of several stakeholders. The testing organisation can request additional certificates or artificial Business IDs by filling in the contact form for stakeholder testing.

The Incomes Register Unit is the issuer of the certificates it grants. Because of this, the issuer information about these certificates cannot be found in the distribution of commercial off-the-shelf software. The testing organisation ensures the technical reliability of the certificates in its own system by downloading the root certificates and issuer certificates of the certificates granted by the Tax Administration from the website. Once the organisation has installed the downloaded certificates in its own system, a trusted relationship with the Tax Administration’s certificates is established and the APIs can be used securely.

The root and issuer certificates can also be downloaded from the links below:

Certificate for data notifier: Data Providers Test Issuing CA v1 (ZIP)

Certificate for data user: PCR Credit Data Users Test Issuing CA v2 (ZIP)

Read more in the interface description of the certificate service.

3 Generating a new testing certificate

In order to retrieve a new testing certificate, the testing organisation must first sign up for stakeholder testing. Instructions on how to sign up for stakeholder testing are found in the instructions on stakeholder testing.

Once the project has processed the signing up, the certificate service sends the technical contact person the information needed to retrieve a certificate. The information is sent to the technical contact person by secure email. The contact person can open the email message with a code sent by text message. For this reason, the technical contact person's contact information must contain an email address that is not a distribution list or a shared mailbox, and a telephone number on which text messages can be received. The telephone number must include the country prefix.

The technical contact person can retrieve the certificate from the Incomes Register Unit’s certificate service after receiving the transfer ID and one-time password sent for the certificate request. The one-time password is valid for 14 days. If the certificate is not retrieved within this time period, the one-time password expires. In that case, the testing organisation must request a new certificate by filling in the contact form for stakeholder testing.

The technical contact person retrieves the certificate through the Web Service interface of the certificate service. The certificate is retrieved by using two different API calls: certificate request and certificate retrieval request. Once the API has received the certificate request, it responds to the call by returning a certificate retrieval ID. The technical contact person saves the retrieval ID and uses it to send a certificate retrieval request. The certificate service then returns a certificate in response to the certificate retrieval request.

The diagram below depicts the technical process. Each phase is explained in more detail after the diagram.

Figure 1. Process diagram for certificate retrieval.

In the following description of the certificate retrieval process depicted in the diagram, the numbering refers to the numbers used in the diagram. Points 2–7 refer to the APIs and their elements mentioned in the interface description of the certificate service. Instructions on how to sign up for testing and request additional certificates are found in the instructions for stakeholder testing.

1. To get a new testing certificate, the testing organisation must submit a testing start notification in the portal. The technical contact person who retrieves the certificate is specified in the start notification. The technical contact person must have sufficient technical competence for certificate retrieval.

If the organisation has already retrieved one testing certificate and wants to request additional certificates, it must fill in the contact form for stakeholder testing. The additional certificates are retrieved in the same way as the first certificate.

2. Once the testing start notification has been processed, the certificate service sends the technical contact person specified in the notification a secure email message containing two unique identifiers: a transfer ID (TransferId) and a one-time password (TransferPassword). The email message can be opened with a PIN code. The technical contact person is first sent an email message that contains a link to open the secure email message. When the technical contact person clicks the link, the PIN code needed to open the message is sent to their mobile phone by text message.

The transfer ID and the one-time password are valid for 14 days from the date the messages were sent. The certificate must be retrieved during that period. If the certificate is not retrieved within the period, the certificate order expires and the testing organisation must request a new testing certificate.

3. The technical contact person generates a 2,048-bit key pair by the RSA algorithm for the certificate request. In addition, the technical contact person creates a PKCS#10 certificate signing request (CSR) signed with a private key. Section 5.3 describes the information to be entered in the signing request.

4. The technical contact person sends a certificate request to the certificate service's Web Service interface. Service calls are sent to https://pkiws-testi.vero.fi/2017/10/CertificateServices. The certificate request is a SignNewCertificateRequest. In addition to the newly formed CSR, the message contains a transfer ID (TransferId) received by secure email and a one-time password (TransferPassword). Further, the artificial Business ID (CustomerId) and name (CustomerName) provided by the project for the organisation during the processing of the notification are included in the message.

Service calls are sent to https://pkiws-testi.vero.fi/2017/10/CertificateServices.

• • The service call must be made using the HTTP POST method. In addition, the following HTTP headers must be set:

Content-Type: "text/xml;charset=UTF-8"
Content-Length: "VALUE"
SOAPAction: "signNewCertificate"

The value of Content-Length is the length of the message in question, i.e. "calculated value". You must calculate the length when sending the message.

The value of SOAPAction must be the value of the API operation in question. These values can be found in the WSDL description. You can download a dynamic WSDL description from the address https://pkiws-testi.vero.fi/2017/10/CertificateServices.wsdl. The WSDL description and XML schemas can also be downloaded from the Incomes Register's website.

• • SOAP messages cannot be sent from a web browser (at least not without browser extensions and plugins); instead, software that can send SOAP messages must be used.

The certificate service receives the signing request and returns a response message.

5. The technical contact person receives a certificate retrieval ID (RetrievalId) in the SignNewCertificateResponse. It is important to save the retrieval ID before moving on to the next phase.

Generating a certificate takes a few seconds, so you must wait 30–60 seconds before you send a certificate retrieval request. If you try to retrieve the certificate before it has been generated, the retrieval fails. In that case, it is important that you have saved the retrieval ID so that you can make a new attempt.

6. The technical contact person sends the certificate retrieval request (GetCertificateRequest) to the API of the certificate service. The certificate retrieval ID (RetrievalId) received in the response to the previous call must be included in the message. In addition, the message must contain the same artificial Business ID and name as the previous message.

The certificate service returns a certificate in the response message.

7. In the GetCertificateResponse, the technical contact person receives the certificate generated for the organisation by the certificate service. After this, the organisation can use the certificate in its API calls by connecting the certificate to the private key it has generated.

If the certificate retrieval needs to be repeated, the same RetrievalId must be used.

For more detailed technical instructions on how to retrieve a certificate, see the interface description of the certificate service.

4 Other situations

4.1 Requesting additional certificates

If additional testing certificates are needed for an API that is being tested, the testing organisation can request a new certificate by filling in the contact form. The organisation must specify on the form whether the certificate is needed for reporting data or for requesting data, and whether the same or different artificial Business ID as in the previous certificates should be connected to the new certificate. It is possible to connect several certificates of the same type (for example, several certificates for reporting data) to the same artificial Business ID.

4.2 Testing on behalf of a stakeholder

If stakeholder testing is performed by a party other than the stakeholder, the certificate can be requested for the party performing the testing. Before submitting a testing start notification, the stakeholder must check who in the testing organisation will act as the technical contact person and retrieve the certificate. The contact information of this person must be reported in the testing start notification to make sure the information needed for certificate retrieval is sent to the correct person.

If the stakeholder also wants to perform testing, it can request a separate certificate for itself by filling in the contact form. The stakeholder can also agree on a shared test certificate with the testing party.

4.2.1 The certificate processes for testing and production are different

In the Positive credit register, only a party with the reporting obligation or a party with the right to use data can sign up as a data notifier or request a data permission for requesting data. Only such operators can request and obtain a production certificate required for reporting and requesting data.

Read more:

Procedures applicable to the use of the Positive credit register’s certificate
Instructions on the certificate used in production

The present instruction document describes the use of testing certificates only.

4.3 Renewing a testing certificate

A testing certificate is valid for two years. You can check the period of validity in the certificate. Certificates are renewed through the certificate service API. There is a separate service for renewals (RenewCertificate) in the API.

Certificates can be renewed at the earliest 60 days before expiry. If the certificate expires, the testing organisation must request and retrieve a completely new certificate. In this case, the new certificate is requested and retrieved in the same way as when a certificate is requested for the first time.

Read more about renewing a certificate in the interface description of the certificate service.

4.4 Closing a testing certificate

When the testing organisation no longer needs a testing certificate or wants to close the certificate for some other reason, it must fill in the contact form for stakeholder testing, indicating that the reason for filling in the form is ‘Ordering of testing certificates, other matters related to testing certificates’. The serial number of the certificate to be closed must be specified on the form.

5 Frequently asked questions

Below you can find some frequently asked questions about certificate retrieval.

5.1 What Business ID and customer name should be used in a GetCertificateRequest?

Below is an example of a GetCertificateRequest and the Business ID and customer name to be used.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:cer="https://pkiws-testi.vero.fi/2017/10/CertificateServices">
<soapenv:Header/>
<soapenv:Body>
<cer:GetCertificateRequest>
<Environment>TEST</Environment>
<CustomerId>Artifical Business ID received from the Positive credit register</CustomerId>
<!--Optional:-->
<CustomerName>Artificial organisation name received from the Positive credit register</CustomerName>
<RetrievalId>Certificate retrieval ID (RetrievalId) received in the SignNewCertificateResponse</RetrievalId>
</cer:GetCertificateRequest>
</soapenv:Body>
</soapenv:Envelope>

5.2 What data is used in the certificate signing request?

When creating a certificate signing request (CSR), the testing organisation provides information on an artificial organisation requesting a certificate (Subject). The following details on the artificial organisation must be entered in the CSR:

Common Name (CN), enter the artificial Business ID received from the Positive credit register.
Organization (O), enter the artificial organisation name received from the Positive credit register.
Country (C), enter FI.

In the test environment, the artificial information provided to the organisation for testing purposes is used. The organisation's own information is used only in production.

5.3 How to connect CSR data to a SignNewCertificate operation

Enter the base64-encoded certificate signing request (CSR) contained in the CertificateRequest element without the begin and end tags.

-----BEGIN CERTIFICATE REQUEST-----
base64-encoded CSR-----
END CERTIFICATE REQUEST-----

5.4 How to save a certificate from the GetCertificate operation in a file

If the certificate contained in the response message is saved in a file manually, the begin and end tags should be added to the base64-enconded data contained in the Certificate element such that the tags are on their own lines and the certificate data is between the tags:

-----BEGIN CERTIFICATE-----
base64-encoded certificate
-----END CERTIFICATE-----

5.5 Testing of certificate retrieval

It is possible to test the retrieval of a certificate in the test bench of the Incomes Register's certificate service. The test bench of the certificate service is a separate service that has separate addresses and is designed only for certificate testing.

In the test bench, the technical contact person can test the accuracy of the messages sent to the certificate service’s API without that a certificate is generated. Testing stakeholders can also use the test bench to develop an application calling the certificate service API.

Please note that the testing certificate needed in stakeholder testing cannot be retrieved from the test bench. Further, the addresses and data used in the test bench should not be used when the testing certificate is retrieved.

Read the instructions on the certificate service's test bench (pdf)
Download the certificate service’s test data (zip)

6 Error situations

As a rule, the certificate service returns information on errors immediately when responding to an API call. However, some errors are not detected until the certificate request is processed, in which case the certificate service responds to an API call related to a certificate retrieval request by returning an error message instead of a certificate.

Information on an error is returned immediately in the acknowledgement of receipt of a service call, when

• the service call does not comply with the service schema
• the transfer IDs are invalid
• a certificate signing request connected to the request is incorrect in form
• some other technical error caused by an exceptional situation is detected.

The returned error codes and their descriptions are found in the interface description of the certificate service.

6.1 An error occurs when a certificate retrieval request is being sent

If the certificate generation fails, any errors (e.g. invalid identifiers) must be corrected. After this, a new API call must be made to request a certificate. An exception is a situation where the system has not yet processed the certificate request before an attempt is made to retrieve the certificate. If a certificate retrieval request is sent too soon after the certificate request, certificate retrieval may fail. Always save the retrieval ID (RetrievalId) and try again after a while. Allow 30–60 seconds for processing and then try again with the same retrieval ID.

The returned error codes and their descriptions are found in the interface description of the certificate service.

In most cases, errors in certificate retrieval take place in points 4–6 of figure 1. Before retrieving a certificate, read the instructions carefully.

6.2 The certificate was not retrieved in time

The technical contact person must retrieve the certificate within 14 days from the date when they received a secure email message containing information for certificate retrieval. If the certificate is not retrieved within this time period, the testing organisation must request a new testing certificate by filling in the contact form for stakeholder testing.

7 Further information and support

The technical documentation used in stakeholder testing has been published on the Documentation page.

Certificate service – Interface description (pdf)
General instructions for application developers (pdf)
Testing instructions for stakeholders

Technical errors can be reported with the observation form for stakeholder testing. If you need additional testing certificates, fill in the contact form.

Forms for stakeholder testing