Certificates for interface use

Using the Vero API interface services requires a client certificate issued by the Finnish Tax Administration's certificate service. The authentication method used is client certificate authentication, which is a form of strong authentication. This means that during the establishment of a secure connection in the SSL or TLS handshake, the existence of the client certificate is verified. During the handshake, the server checks that the caller possesses the private key associated with the certificate. The certificate is used to identify and authorize the organization using the interface.

Tax Administration cannot give detailed instructions on how to attach the certificate to a service call because it is done based what technology solutions user's application is using. Further details can be found with popular search engines with keywords “client certificate authentication”. However, one way to add a certificate to an call has been published on the Code examples page, you can use the example for your own implementation.

More information about the certificates can be found in Testing and Production pages.

When building integration with Vero API services you must test most common use cases in Vero API test environment using a test certificate. Typical use cases include reacting appropriately to response status codes received from service when sent message was valid and when message contained input errors or business validations failed. Also, the client software should handle unexpected errors or service down time gracefully.

An interface-specific production access requires test scenarios to be executed in the API portal. Test scenarios are executed by calling interfaces with the integration verification endpoint with a production certificate.

Key Pair and Certificate

Key pairs and certificates are central concepts in PKI technology. A key pair consists of a private key and a public key. The client generates the key pair themselves according to the instructions of the certificate authority (CA).

The private key is secret and is used for signing messages and decrypting encrypted messages. The private key must be kept secure and never sent to anyone. The public key is used for encrypting messages.

The certificate contains the client's public key, which has been signed by the certificate authority (CA). The signed certificate proves that the public key belongs to a specific entity. When using the Vero API interfaces, the server also ensures during the handshake that the user of the interface possesses the private key associated with the client certificate. This ensures that the certificate is used by its rightful owner.

SSL Handshake and Client Certificate Authentication

When establishing a connection between the client's system and the Vero API, i.e., during the SSL/TLS handshake, the following occurs when performing client certificate authentication, in a simplified description:

  • 1

    Client Hello

  • The client initiates the handshake by sending a message to the server, which includes supported TLS versions, cipher suites, and a random number.
  • 2

    Server Hello

  • The server responds with a "Server Hello" message, selecting the TLS version and cipher suite. The server sends its certificate to the client, which verifies its trustworthiness using the certificate authority (CA). The server also sends its own random number.
  • 3

    Client Certificate

  • The server requests the client to send its own certificate. The client sends its certificate (public part) and a piece of random data signed with its private key to the server. The server verifies the client's certificate by ensuring it can decrypt the signed data, confirming that the client possesses the private key associated with the certificate.
  • 4

    Key Exchange

  • The client and server exchange keys related to the encryption of the connection, derived from the random numbers and public keys. These encryption keys are used to encrypt and decrypt the actual data during the entire session.
  • 5

    Finish

  • The client and server send each other a message confirming that the handshake was successful and that a secure connection has been established.
    In this process, the client proves its identity to the server by sending its certificate, and the server verifies its trustworthiness. This ensures that the connection is secure and that both parties are trustworthy.

General instructions on PKI technology, key pairing, certificate signing request can be found on the following vero.fi pages and using search engines:

  • Instructions for the Tax Administration's certificate service: Technical guidance - vero.fi
  • Using a certificate to connect to your own code: Code examples - vero.fi
  • You can search for instructions on search engines using the keyword "What is a public key infrastructure (PKI)?"
Page last updated 1/8/2025