Questions and answers about certificates

Technical questions about the certificate

Which business ID and customer name should be used at GetCertificateRequest?

Here is an example of this section and a response at CustomerID:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cer="http://certificates.vero.fi/2017/10/certificateservices">

<soapenv:Header/>

<soapenv:Body>

<cer:GetCertificateRequest>

<Environment>TEST</Environment>

<CustomerId>Artificial business ID in the message ”Incomes Register testing agreement processed”</CustomerId>

<!--Optional:-->

<CustomerName>Artificial customer name in the message ”Incomes Register testing agreement processed</CustomerName>

<RetrievalId>RetrivalId received from certificate service</RetrievalId>

</cer:GetCertificateRequest>

</soapenv:Body>

</soapenv:Envelope>

Are any checks run for the values contained in the Certificate Signing Request (CSR), such as common name? Are there any restrictions, for example does the data contained in the CSR have to correspond to that of the original certificate when the certificate is renewed, or does the data have to correspond in some way to the data on the company retrieving the certificate?

Technically, the CSR is only used to provide a public key. Its integrity is checked, but the actual data fields are not used on the certificate. However, because the use of data in other contexts, such as fault reporting, has not been excluded, fairly accurate data should be entered.

What kind of data is contained in the Certificate Signing Request?

When a Certificate Signing Request (CSR) is generated, data is requested on the retrieving organisation (Subject). Of this organisational data, the following should be entered in the CSR:

  • Common Name (CN), enter an artificial business ID
  • Organization (O), enter the given customer organisation name
  • Country (C), enter FI

Production uses the company’s own data, and the testing environment uses the test organisation's data given to the company.

How should CSR data be attached to the signNewCertificate operation?

Enter the base64-encoded Certificate Signing Request (CSR) contained in the CertificateRequest element without begin and end tags.

-----BEGIN CERTIFICATE REQUEST-----

base64 encoded CSR-----

END CERTIFICATE REQUEST-----

How should a certificate retrieved from the getCertificate operation be saved in a file?

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

-----BEGIN CERTIFICATE-----

base64 encoded certificate

-----END CERTIFICATE-----

Why does SSLHandshakeException (Incomes Register and certificate service interface) appear when using Web Service?

The problem is probably related to the TLS/SSL version used by the customer software and related crypto libraries. The Incomes Register and certificate service's Web Service interfaces use a TLSv1.2 protocol and the client software must use the same version. Known problems: 

  1. Java 7 and older versions → Upgrade to Java 8 or a later version.
  2. SoapUI OpenSource, version 5.3.0 and older use an outdated Java version. → Upgrade SoapUI to version 5.4.0 or update/replace Java packaged by SoapUI to version 8.

What is the certificate service address in the stakeholder testing environment and where are service calls delivered?

– This service call must be made using the HTTP POST method and the following HTTP headers should be set as well (headers)

– Content-Type: text/xml;charset=UTF-8

– SOAPAction: "getCertificate"

  • SOAPAction must be
    the action of that operation and they can be found in the WSDL description.
    - Typically, SOAP messages cannot be sent over a web browser, at least without extensions and plugins. Instead, a software capable of sending SOAP messages must be used.

Retrieval of certificate

When you retrieve a requested or renewed certificate using GetCertificateRequest, the returned error codes do not seem to have a code for a situation in which the certificate generation request is still being processed. (Certificate service, General description, Figure 2 mentions a processing time). Will there be an error code for this, such as “Certificate request is being processed”?

This is being considered in the production environment, but there is currently no separate error code for this.

How long is the processing time when a requested or renewed certificate using GetCertificateRequest is retrieved?

The time specified in the documentation is 5 minutes, but in practice it takes less than 30 seconds, and often much less than that.

Why does retrieval of certificate fail?

Failure to retrieve a certificate may be due to for example the wrong RetrievalId.

When retrieving a certificate, note that the request to sign (SignNewCertificate) may only be performed once with the transfer credentials (TransferId and TransferPassword). Retrieval of certificate (GetCertificate) can be done with the same retrieval ID (RetrievalId) several times. There is a delay between the signing request and retrieval, so wait for a while.

Certificate and stakeholder testing

Our organisation wants to use several different certificates in Incomes Register stakeholder testing. Is a single testing agreement concluded for each certificate for the purposes of stakeholder testing?

No. Each organisation concludes one testing agreement for the purposes of stakeholder testing. If the organisation knows that it needs multiple certificates in testing, a request is attached to the email, in which a signed and scanned testing agreement and terms and conditions of use for the testing environment are sent to the Tax Administration’s Incomes Register Project. The attachment should specify the number of certificates required and their purposes of use. If different certificates have different technical contact persons, their details must also be provided.

If a testing agreement has already been approved or testing is in progress, a software house can request multiple certificates by means of an observation form. A link to the form will be sent to the testing organisation after the testing agreement has been processed. A request sent on an observation form should include the details of the technical contact person, the type of certificate required, and the artificial Business ID (CustomerID) and artificial organisation name related to the Business ID (CustomerName), which have been sent to the testing organisation previously.

The software house must use two different softwares, both of which have their own intermediary services. Both softwares will be tested, but testing will start at different times and the other certificate will not be needed until later. Will a software house conclude a single testing agreement or two separate ones? Is it possible to obtain additional certificates later on?

A software house concludes a single agreement and can test different softwares simultaneously, using the same certificate. If a software house has a legitimate need to use more than one certificate, a request for another certificate can be sent at a later stage on an observation form. A link to the form will be sent to the testing organisation after the testing agreement has been processed.

A request sent on an observation form should include the details of the technical contact person, the type of certificate required, artificial Business ID (CustomerID) and artificial organisation name related to the Business ID (CustomerName), which have been sent to the testing organisation previously.

The Incomes Register Project will process the request sent within two weeks. New transfer IDs will be delivered to the technical contact person, enabling the other certificate to be retrieved. The transfer IDs are valid for 14 days. A new testing agreement does not need to be concluded.

When a certificate is retrieved in the testing environment, for how long is the one-time password (OTP, TransferPassword) for retrieving the certificate valid?

The requisite transfer IDs for obtaining a certificate are valid for 14 days.

There are several softwares under our Group, which we need to test. Testing will be carried out at different times and via different softwares. We therefore need two certificates, even though we are one large Group. How should we proceed? Can we conclude separate stakeholder testing agreements for each of the softwares?

A Group concludes a single testing agreement. It is possible to obtain different certificates for different softwares, if there is a legitimate need for this. If the certificates are obtained before testing, at the same time as the testing agreement is concluded the organisation should draw up a free-form request and attach it to the email in which it sends the Incomes Register Project the testing agreement and terms and conditions of use of the testing environment. The attachment should specify the number of certificates required and their purposes of use. If different certificates have different technical contact persons, their details must also be provided.

If the testing of the softwares is started at different times, a request for a certificate is sent by means of an observation form. A request sent on an observation form should include the details of the technical contact person, the type of certificate required, artificial Business ID (CustomerID) and artificial organisation name related to the Business ID (CustomerName), which have been sent to the testing organisation previously.

A production agreement cannot be concluded by a software house. A certificate that can be used in production is issued to an accounting firm or company. In production, however, the end customer can decide who may act as the technical contact person on behalf of the company and technically manage certificates.

How is renewal of a certificate tested? A certificate is valid for 2 years and can be renewed no earlier than 60 days before expiration.  

At present, it is not possible to test certificate renewal, but we aim to develop functionalities in such a way as to enable testing of certificate renewal.

When functionalities relating to certificate lifecycle management can be tested, the Incomes Register Project will provide notification of this separately.

Can our technical contact person receive messages relating to certificate retrieval in English?

The certificate service sends messages to technical contact persons in three languages (Finnish, Swedish and English).

Is a separate request made to the interface for the revocation of a certificate?

In production, a request to revoke a certificate is made during office hours to the Incomes Register authority, and outside office hours to the helpdesk. 

During stakeholder testing, a revocation request is made to the Incomes Register’s testing organisation if a certificate is issued for testing.

A software house does not have a Finnish Business ID. Can it conclude a testing agreement?

Yes, it can. The company’s foreign identifier is reported in the section ‘Business ID’ of the testing agreement.

A software house wants to test the integration of travel cost reimbursements in the Incomes Register. Should a technical interface also be implemented connecting the travel expense invoice system to the certificate service? In other words, is it the case that a certificate cannot be delivered for testing by any means other than through the certificate service’s interface? (In production use, the certificate is retrieved by another IT system of the data provider.)

A testing certificate can be delivered only through the certificate service’s interface. 

A private key linked to a certificate is possessed only by the software related to the Incomes Register, which means that it must be generated by the customer. Because the certificate service’s interface is a Web Service interface, the retrieval of a certificate can be closely integrated with customer software or the certificate can be retrieved by means of separate Web Service software, such as SoapUI or Postman.

Certificate in production

Can a customer have multiple certificates in use at the same time? A customer has several softwares in use.

A customer may have several softwares in use at the same time. At the beginning of production use, the customer can order certificates for its organisation, via the Incomes Register’s e-service. Equally, the customer may use the same certificate in different softwares.

Can a customer manage certificates on the incomesregister.fi website, for example, can they download a certificate file and import it to their desired software?

A certificate is generated in accordance with the technical instructions at https://www.vero.fi/en/incomes-register/software-developers/certificate-service/ .

During production, a customer may view a list of the certificates in use by the organisation via the Incomes Register’s e-service.

Can our technical contact person receive messages relating to certificate retrieval in English?

Messages are sent by the certificate service to technical contact persons in three languages (Finnish, Swedish and English).

If software supplier X obtains its own certificate, can all accounting firms using the software use software X’s certificate after this?

Software supplier X operates as a software house. Each customer using software X, such as an accounting firm or company, must obtain their own certificate for production use of the Incomes Register.

Should every software house implementing a technical interface with the Incomes Register also implement a technical interface with the certificate service?

The customer company (accounting firm or company) of a software house should obtain a certificate that can be used in production. In practice, however, a solution must be implemented in the software whereby the certificate is retrieved and saved for use by the software.

Certificates and accounting firms

A software house’s customers are accounting firms which manage the financial administration and payrolls of their own customers in financial administration software X. If an accounting firm sends an Incomes Register report on behalf of a customer company, is it possible to use software X’s certificate? Does the accounting firm itself need to have a certificate of any kind related to software X?

Software supplier X operates as a software house. Each accounting firm using software X must obtain its own certificate that can be used in production. Accounting firms therefore need their own respective certificates. A certificate is required by the company or accounting firm that uses the financial administration software.

A production agreement for the Incomes Register is concluded by the accounting firm. Production agreements can be concluded from autumn 2018. Although the accounting firm concludes the agreement it may, by agreement, designate, say, a representative of the software house as the technical contact person, who in such a case will receive the data related to the certificate retrieval and can thereby retrieve the certificate on the accounting firm’s behalf.

How are certificates obtained and how are they used in accounting firms?

For example,

Accounting firm A, which has customers:
Customer 1 Oy
Customer 2 Oy
Customer 3 Oy

Accounting Firm B, which has customers:
Customer 2 Oy
Customer 4 Oy, wants to make record subscriptions itself

Which of these options are used?
1. Does each Customer retrieve a certificate themselves and make it available to the Accounting Firm?
2. Does the Accounting Firm retrieve a certificate on the behalf of the Customer?
3. Or does the Accounting Firm have a single certificate that is used for all Customers?

A person with the right to sign for the accounting firm concludes the service agreement with the Incomes Register and obtains a single certificate.

In conjunction with obtaining a certificate, a representative of the software house, for example, can be designated as the technical contact person who, in practice, retrieves a certificate for the accounting firm. In practice, the certificate can be generated for the accounting firm by the party whom the accounting firm’s authorised signatory has indicated as the technical contact person.

How should we proceed with respect to Customer 2 Oy, whose payrolls are managed by Accounting Firm A and Accounting Firm B?

Both accounting firms have their own certificates and handle transactions on behalf of their customers normally, as agreed with Customer 2 Oy.

How should we proceed with Customer 4 Oy, who wants to make record subscriptions itself, but with Accounting Firm B creating the reports?

Customer 4 Oy can use the e-service for record subscriptions, or obtain its own certificate. Accounting Firm B has its own certificate, which is used in reporting.

Do accounting firms and companies using payroll software need to obtain a certificate? Does a company or accounting firm need to authorise software X to send records on its behalf?

Companies and accounting firms using financial administration software require their own respective certificate. If a company’s transactions are handled by an accounting firm, the accounting firm requires a certificate which it uses in transactions on behalf of all its customers. A company that is the customer of an accounting firm does not therefore require its own certificate, unless it reports earnings payments itself via the interface.

When an accounting firm has undertaken to observe the terms and conditions of use of the Incomes Register, it can report data via the interface on behalf of the customer company it represents. In all cases, a certificate is required by the company or accounting firm that uses financial administration software.

Suomi.fi authorisations are not required for using the technical interface. On the other hand, the Incomes Register’s e-service uses Suomi.fi identification and the company must authorise the requisite persons and parties, by means of Suomi.fi authorisations, to transact business on its behalf.

How should we proceed if an accounting firm or company has several softwares that provide reports directly to the Incomes Register (for example, payroll and travel expense invoice system)?

The same certificate can be used in different softwares of the same accounting firm/customer company. The different softwares of an accounting firm or company can use the same certificate if the same type of certificate is compatible with the softwares’ requirements. Alternatively, an accounting firm or company can obtain a separate certificate for each software.

Certificates and Software as a Service (SaaS)

Use of the interface of the Incomes Register requires a company to obtain a certificate either for itself or for an accounting firm or other payroll administration partner doing business on its behalf.

What is the procedure if a company has purchased payroll services from a software supplier as a SaaS? Can the same server host the certificate of multiple companies for the Incomes Register?

The Incomes Register Project does not take a position on the number of certificates on the same server. The number is therefore unlimited.

In the case of a SaaS, too, each company reporting data obtains its own certificate. A representative of a SaaS provider can be designated as the certificate’s technical contact person, in which case he or she can retrieve the certificate on behalf of the company and install it.

Certificates and cloud-based products

Company Z has cloud-based products that are used by many end customers, for example, accounting firms. Is a certificate issued
1) to the organisation (=Company Z) sending data to the Incomes Register by means of the technical interface, or
2) to the end customer that generates the record, for example, an accounting firm?

The Incomes Register’s certificate is issued to the end customer. The certificate is issued to the accounting firm, but the end customer can designate a representative of Company Z as the certificate’s technical contact person, who, in practice, will retrieve the certificate.

Certificate renewal

When a certificate is renewed, will the new certificate replace the old one immediately, or will the old one remain valid until the original ‘valid to’ date? The documentation mentions that the old one should be replaced, but does not provide any specific details on whether the new certificate is a replacement or just a new certificate in practice. If the new certificate replaces the old one, will this occur when the certificate is generated or only when it is retrieved?

The old certificate will remain valid until it expires or a specific request is made to revoke it. While the new certificate is a replacement in the sense that it shares the same DN with the old one, the certificate itself is new.