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.

Why am I getting an error message when logging in? I am using a downloaded certificate (21/03/2018)

The requests appear to stop at the verification of the XML signature. Checks are also run on the record, so they would also return an error after that point.

The data in the request (at least CreatorId and SenderId) should be changed to correspond to the business ID in the certificate.

Working solutions have been found for the creation of the XML signature in accordance with the practices described in the instructions. One solution has been to implement a processor in the Web Service implementation to perform the XML signature implementation just before sending the call.

Overview of signature implementation:

  • read the first Body child element in the SOAP message and generate a new XML document from it
  • generate an XML signature from this new document according to the documentation, using the key associated with the certificate
  • replace the first Body child element that was in the envelope with this signed version of it
  • any other measures required by the software library for replacing the outgoing message with this signed one.

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.

What is the address of the SFTP channel? (21/03/2018)

The address is 131.207.14.21, and it can also be found in the name service by the name sftp-testi.tulorekisteri.fi. The production address will be sftp.tulorekisteri.fi.

How should I authenticate myself in the SFTP channel? (03/04/2018)

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 e-mail after the testing organisation has retrieved the testing certificate. Authentication in the SFTP channel is 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.

What are the correct attributes for using the signature node? (21/03/2018)

<CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />

<SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />

<Reference URI="">

<Transforms>

<Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />

<Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />

</Transforms>

<DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />

Is it necessary to generate a public key, private key and PCKS#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 PCKS#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. (21/03/2018)

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.

Can you provide a practical example of / tool for generating a key pair and creating a PCKS#10 certificate file and linking a public key to it? (21/03/2018)

We intend to publish instructions for this as soon as possible.

What would be the best way to manage customers’ own public/private keys and PCKS#10 certificate files? (21/03/2018)

Management is highly dependent on the system and environment; it is difficult to provide customer-specific instructions. It is a good idea for the party that manages the system to create the key pairs and certificate signing requests as well as managing the certificates.

Is this test bench address – https://pkiws-testi.vero.fi/DEV/2017/10/CertificateServices – in operation yet? (11/05/2018)

The test bench is in operation. The test bench’s interface is used in the same way as the certificate service’s interface. This means that the interface’s call must be made using the HTTP POST method. The test bench service’s WSDL can be retrieved using the GET method from https://pkiws-testi.vero.fi/DEV/2017/10/CertificateServices.wsdl

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.

How can I designate another person to be the technical contact person? Do we need to sign a new agreement? (09/04/2018)

No new agreement is needed; the person who signed the original agreement can report the change by e-mail to YHT_Tulorekisteri_testaus@vero.fi.

If we don’t have time to retrieve the certificate within two weeks, can the retrieval deadline be extended? (09/04/2018)

The retrieval deadline cannot be extended, but a new certificate subscription can be made. Report this on the observation form. 

The current test certificate cannot be linked to the private key. Is it possible to delete the current test certificate and create a new certificate request? (09/04/2018)

It is not possible to delete the test certificate, but a new certificate subscription can be made, which will provide transfer IDs for making a new certificate request. 

I have received an e-mail message containing a link to a website for which I need to provide a PIN code. I realised that my telephone number may be incorrect if the format is 420 xxx xxx xxx. The dialling code for the Czech Republic is +420 or 00420. I also sent you a report via your website, but I couldn’t write any message. Could you please correct my telephone number to 0042 xxx xxx xxx so that I can receive the PIN code? (09/04/2018)

The telephone number was in the correct format, but the foreign operator in question had forbidden the reception of the message, probably because the message does not originate from a regular telephone number but a messaging service.

If you notice any problems with secure e-mail messages or SMS messages, please contact us using the observation form.

The documentation for “Employer's separate report” contains the following text in the section “Earnings-related pension provider code”: The value of the data item must be the same as the first two characters of the value of the Pension policy number data item. However, some of the earnings-related pension provider codes begin with a 5-character code. 

If the data item must simultaneously be a codes-compliant PensionProvldCode and consistent with the first two characters of the Pension policy number, how should we proceed with such five-character codes? (09/04/2018)

This section of the documentation for “Employer’s separate report” has not been updated. In the schema description for the earnings payment report, the text is as follows: The value of the data item must be the same as the first two/five characters of the value of the Pension policy number data item. 

This will be corrected in the next version of the schema documentation for the Employer’s separate report.

How can an accounting firm / direct customer / end customer obtain a one-time password and transfer code when a technical interface is used? Is there any need for the end customer to authorise the accounting firm? (07/05/2018)

The accounting firm / end customer 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 e-mail to the specified e-mail address and a PIN code to their phone number for opening the secure e-mail, 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.  

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.

What are the business IDs on the PDF list needed for in stakeholder testing, if certificates cannot be retrieved against them? (07/05/2018)

Each testing organisation will be provided with 40 business IDs and 200 personal identification numbers. Stakeholders are free to choose the number of income earners per payer with a business ID in the earners 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. 

https://www.vero.fi/globalassets/tulorekisteri/liite1_testausohje_en_final.pdf

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

https://www.vero.fi/globalassets/tulorekisteri/liite7_ohje-testiaineiston-anonymisoinnista_en_final.pdf 

There are several legal companies in our travel expense system in the same environment (server software, database). These companies will have their own certificates in production use. We need to be able to test a situation in which the software that we use to create earnings payment reports is launched at a preset time and finds the right certificate from the right company. In other words, we want to test the generation of parallel earnings payment reports from the same database and same server for different companies. 

We want to use the business IDs in the PDF in our test environment, retrieve a test certificate for each, and generate earnings payment records for the Incomes Register’s test environment. Is this possible? (07/05/2018)

Unfortunately, you can only use the artificial business ID (CustomerID) and the associated organisation name (CustomerName) already sent to you for generating test certificates.

However, you are free to generate several certificates in the name of this particular organisation. This means that you can operate with several certificates, but the certificate holder is the organisation mentioned in the message below.

As there is only a limited number of test certificates available, we are unable to provide you with several test certificate organisations.

We received from you a PDF document about test organisations (Business IDs) and persons (personal identity codes). The Business ID provided to us for use in test certificate retrieval is not included on the list we received.

What are the Business IDs on this PDF list needed for in stakeholder testing if certificates cannot be retrieved with them? (11/05/2018)

Each testing organisation will be provided with 40 Business IDs and 200 personal identity codes. The IDs and codes will be picked at random. Stakeholders are free to choose the number of income earners per payer with a Business ID. Personal identity codes can also be linked to Business IDs as desired.

There are several legal companies in our travel expense system in the same environment (server software, database). These companies will have their own certificates in production use. We need to be able to test a situation in which the software used to create a record containing earnings payment reports is launched at a preset time and finds the right certificate from the right company; in other words, parallel earnings payment reports are generated from the same database and same server but for different companies. We want to use the Business IDs in the PDF in our test environment, retrieve a test certificate for each, and generate earnings payment records for the Incomes Register’s test environment. Is this possible? (11/05/2018)

Only the artificial Business ID (CustomerID) and the related organisation name (CustomerName), which have already been sent to you, can be used to generate test certificates. However, you are free to generate several certificates in the name of this particular organisation. In other words, you can operate with several certificates, but the certificate holder is the organisation mentioned in the message. There is a limited amount of test IDs, which is why you cannot have any more test organisations.

Our customers surely will need to run tests on more than one payer’s Business ID. Can the group make more than one testing agreement at the company level, so that each company receives their own ID from you? (25/05/2018)

At the moment, concluding more than one testing agreement at the company level is not possible, but we are exploring the opportunities to enable this in the future.

Would it be possible to get Business IDs with the payer’s own suborganisation's identifier for use in testing? (25/05/2018)

You can use the Business IDs that we have provided for use in testing. If you want to use the payer’s own suborganisation's identifier, you can generate the identifiers yourself. Please note that these are the payer’s own codes, which will not be checked in the Incomes Register. The type of payer's suborganisation's identifier (in the codes as PayerSubOrgType) is 2 = Payer’s own codes.

 

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.

How should the processing rules concerning the record owner, record creator and record submitter, as defined in section 2.1 “Record data” of the instruction “Data delivery – Schemas – Earnings payment reports”, be interpreted in the following situation:

  • The payer has a customer identifier, which means that it is the record owner, Company A.

  • The record is generated by the provider of external payroll management services, Company B.

  • The file is submitted by the provider of regulatory reporting services, Company C. (11/5/2018)

The payer (A) must be the owner. The creator and submitter must be the same party, i.e. the party whose certificate is used to submit the file. The situation described in the question is not possible.

How can we test a situation in which the payer, the creator and the submitter have different Business IDs? (25/05/2018)

The payer must be the owner. The creator and submitter must be the same party, meaning the party whose certificate is used to submit the file. The situation described in the question is not possible.

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.

Does a new key pair need to be generated? (21/03/2018)

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? (21/03/2018)

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

Do the requirements for the conversion of special characters in practice apply to the customer’s name (CustomerName), if it is transmitted via the interface? For example, there would be no need to perform character conversion for the transfer ID (TransferId) and one-time password (TransferPassword)? (21/03/2018)

UTF-8 characters must be used in the interface service. If the data submitted uses these characters, no data conversion is required.

We successfully retrieved the test certificates from the service https://pkiws-testi.vero.fi/2017/10/CertificateServices.wsdl, but when we tested the other services provided
https://ws-testi.tulorekisteri.fi/20170526/InvalidationService.svc
https://ws-testi.tulorekisteri.fi/20170526/PayerSummaryReportService.svc
https://ws-testi.tulorekisteri.fi/20170526/StatusService.svc
https://ws-testi.tulorekisteri.fi/20170526/WageReportService.svc
only an HTTP 403 Forbidden error was returned with no additional explanation, both via a browser or when making a full Web Service call through code. Have any other testers had the same problem, or what could be the cause? Does one of our IPs need to be whitelisted? (13/04/2018)

In the test environment, the certificate retrieved from the certificate service is also used as the SSL certificate. Authentication was successful using this certificate.

To my understanding, the test servers do not require a separate SSL certificate, which will only be available in production use, and even then, if it is missing, the error would be HTTP 401? (13/04/2018)

Authentication with a customer certificate is enabled in the test environment as in production. This means that stakeholders must configure their software to use the certificate in authentication.

Signing certificate files

Could you provide a practical example of what is required from the certificate service for signing / the signing process in general? (21/03/2018)

The instructions for signing can be found in the application guidelines for the technical interface. The certificate service signs the Web Service response messages with its own certificate. The customer or customer’s system can check this signature, if they wish, to ensure that the response originates from the certificate service. There is no requirement to perform this check.

XML tips for record subscriptions (21/03/2018)

  • DeliveryDataOwner/ = payer ID, if one is available. If the payer has no customer identifier and the service provider submits the data on behalf of the payer: the owner must be the identifier of the service provider
  • Creator/Sender = these must include the certificate’s artificial business ID
  • DeliveryChannelCode = this must be 1, i.e. the distribution channel is SFTP
  • ValidFrom = the date cannot be in the past
  • ModifiedTimespanEnd = this data cannot be entered for a recurrent subscription. In recurrent subscriptions, the query time range always ends at the time of the query, which is then the start of the query time range for the following subscription
  • QueryDataSchemaVersion = information on the schema versions used (earnings payment reports and employer's separate reports):
    • http://www.tulorekisteri.fi/2017/1/WageReportsFromIR
    • http://www.tulorekisteri.fi/2017/1/PayerSummaryReportsFromIR
    • In the XML for the record subscription <QueryDataSchemaVersion>http://www.tulorekisteri.fi/2017/1/WageReportsFromIR</
      QueryDataSchemaVersion>
  • QueryProfile = the employer's separate report profile xx is used on record type 306
  • Profile xx is used in earnings payment report subscriptions (300, 303...)
  • Mandatory search parameters for a record type 303 subscription: List of payers, List of income earners
  • The signature of the Signature element must be generated using the retrieved certificate. The address of the SFTP service is sftp-testi.tulorekisteri.fi.