Questions and answers about certificates

Technical questions about certificates

How do I revoke a certificate?

A request to revoke a certificate is made during office hours to the Incomes Register Unit, and outside office hours to the Helpdesk.

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).

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

A customer may have several software programs in use at the same time. Equally, the customer may use the same certificate in different software programs.

Can certificates be managed in the Incomes Register's e-service, for example, can a certificate file be downloaded?

The signatory of the organisation may view a list of the certificates in use by the organisation in the Incomes Register’s e-service. In addition, the signatory can request new certificates in the e-service.

The technical process of requesting certificates and retrieving them is done according to the certificate service instructions. More detailed instructions are sent to the technical contact person via secure email.

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 a 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.

What is the address of the SFTP channel?

The address sftp.tulorekisteri.fi is for the Incomes Register's production use.

Testing environment: sftp-testi-2.tulorekisteri.fi

How should I authenticate myself in the SFTP channel?

The SFTP user ID format is, for example, 0ac1ee931da7cf1ce_PW. The user ID will be sent to the testing contact person and technical contact person by email after the testing organisation has retrieved the testing certificate. Authentication in the SFTP channel is done with SSH authentication, using the user ID and private key from the key pair that the stakeholder used for signing the Certificate Signing Request (CSR). No password is used.

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:

Java 7 and older versions → Upgrade to Java 8 or a later version.

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.

Certificate and stakeholder testing

How can I designate another person to be the certificate's technical contact person? Do we need to sign a new agreement?

No new agreement is needed; the person who signed the original agreement can change the certificate's technical contact person by updating the certificate's details in the Incomes Register's e-service.

How can I test the renewal of a certificate?

Renewing a certificate can be tested in the certificate service's test bench. For more information, see the instructions Certificate service - test bench.

How can I revoke a certificate?

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

What are the Business IDs on the PDF list needed for in stakeholder testing, if certificates cannot be retrieved against them?

Each testing organisation will be provided with 40 Business IDs and 200 personal identity codes. Stakeholders are free to choose the number of income earners per payer with a Business ID in the earnings payment record. Personal identity codes can also be linked to Business IDs as desired. The Incomes Register Project will provide more test customers if necessary.

You can also report a limited number of your own test IDs to the Incomes Register that you want to be added to the Incomes Register's stakeholder testing.

For more instructions on testing, see the documents for stakeholder testing

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 required transfer IDs for obtaining a certificate are valid for 14 days.

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

Dynamic WSDL can be downloaded from the address https://pkiws-testi.vero.fi/2017/10/CertificateServices.wsdl
The same WSDL and XML schemas can also be downloaded from the Incomes Register site
When an interface is used to retrieve a certificate, the service calls must be sent to the address https://pkiws-testi.vero.fi/2017/10/CertificateServices

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.

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>

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

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

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

</cer:GetCertificateRequest>

</soapenv:Body>

</soapenv:Envelope>

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, specify on a testing start notification 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 a testing contact form.

Testing forms

Should a technical interface also be implemented connecting a 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?

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.

Signing certificates

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 the Business ID

Organization (O), enter the 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.

What are the correct attributes for using the signature node?

The technical specifications used in signing are found in the interface documentation for the Incomes Register: Technical interface – Application guidelines.

</Transforms>

How is a key pair generated? How is a PKCS#10 certificate file created and a public key linked to it?

The solutions depend on the technology used by the party. One possible way of creating a PKCS#10 certificate signing request (CSR) in the certificate service's testing environment is described in Section 5 of the instructions Certificate service - test bench.

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-----

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.

Certificate retrieval

When should a certificate be retrieved?

A certificate must be retrieved within 14 days of its generation. The retrieval deadline cannot be extended. If the retrieval deadline expires, the organisation must make a new certificate subscription and retrieve the certificate on time.

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.

The certificate generation request, retrieved by using GetCertificateRequest, is still being processed. Is there a specific error code for this situation?

There is no separate error code. The time lapse of certificate retrieval has been made longer for GetCerfiticateRequest. Therefore, situations where processing is still in progress should not occur as often anymore.

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.

How can an accounting firm obtain a one-time password and transfer ID when a technical interface is used? Is there any need for the end customer to authorise the accounting firm?

The accounting firm should conclude a service contract for using the interface via the Incomes Register’s e-service and report the contact person for the certificate when concluding the contract.

The contact person for the certificate will receive a secure email to the specified email address and a PIN code to their phone number for opening the secure email, which contains the transfer IDs associated with the certificate request (TransferID and TransferPassword).

The accounting firm must have a valid contract and the authorisation to act on behalf of its customer.

Is it necessary to generate a public key, private key and PKCS#10 certificate request separately for each customer in order to create a new certificate? Wouldn’t it be enough to have just one shared public/private key and PKCS#10 certificate request file that could be used for all customers? In this case, the transfer ID and one-time password that you provided to the customer would be sufficient to uniquely identify the customers in order to generate the retrieval ID for a new certificate and your XML signature.

If this is an accounting firm, the firm can use its own certificate and generate the records and report the data on behalf of its customers. If this relates only to forwarding records, an individual key pair and certificate signing request must be generated individually for each customer, and these are then used to generate the certificates.

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-----

Certificate renewal

When and how should a certificate be renewed? Can it be renewed automatically?

An organisation can see the certificate's period of validity in the Incomes Register's e-service or on the certificate itself. The organisation sends the certificate renewal request via the Incomes Register's technical interface no earlier than 60 days before its last date of validity. If the certificate expires before it is renewed, the organisation must make a new certificate application in the Incomes Register's e-service.

The possibility to renew a certificate automatically depends on the practices of the software house.

When a certificate is renewed, will the new certificate replace the old one immediately, or will the old one remain valid until its original ‘valid to’ date?

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.

Does a new key pair need to be generated?

Yes. The renewal of the key is intended to reduce the risk of the key falling into the wrong hands.

How is an XML signature generated with a private key?

The specification for the XML signature has been published in the interface documentation for the Incomes Register.

What characters should be used in the interface services?

UTF-8 characters must be used in the interface service.

Why does the certificate renewal request (RenewCertificate) result in the error Signature verification failed? According to the log, erroneous renewal requests result in the error code PKI010.

Check that, in the outgoing renewal request, namespace is specified in the RenewCertificateRequest element of Soap-body instead of Soap-envelope.

Certificates and Software as a Service (SaaS)

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 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 they can retrieve the certificate on behalf of the company and install it.

Certificates and accounting firms

How are certificates retrieved and how are they used in accounting firms? Does an accounting firm have a single certificate that is used for all customers?

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

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

In conjunction with retrieving 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 firms 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 submitting 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 wages 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 necessary persons and parties, by means of Suomi.fi authorisations, to act on its behalf.

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

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

Page last updated 9/6/2021