Download the PHP package sk-id-solutions/smart-id-php-client without Composer

Smart-ID PHP client

Introduction

The Smart-ID PHP client can be used for easy integration of the Smart-ID solution to information systems or e-services.

Features

• Simple interface for user authentication

Smart-ID PHP client works with PHP 7.4 and PHP 8+

This PHP client cannot be used to create digitally signed containers because PHP does not have a library like DigiDoc4J.

Installation

The recommended way to install Smart-ID PHP Client is through Composer:

See packagist for latest published version and changelog for details.

How to use it

Configure client details and https pinning

Used to prevent man-in-the-middle attacks. More on man in the middle attacks in case of using smart id.

Setting the client to trust specific public keys. Production SSL certificates used can be found here and demo environment certificates are here.

The setPublicSslKeys method requires a string of sha256 hashes of the public keys used delimited with ";". You can extract hashes from certificates using next openssl command.

The supplied string should be of format sha256//sha256-hash-of-the-public-key;

Authenticating with semantics identifier

Following example also demonstrates how to validate authentication result and how to handle exceptions.

Validate authentication result

To validate the authentication result (that it was signed by Smart-ID and not some man-in-the-middle or accidentally connecting to demo environment from production). You need to create directory trusted_certificates and place smart-id certificates in there. You can get the needed certificates from links that are described in the "https pinning" chapter above.

Example path to resource directory: $resourceLocation = '/path/to/resource'; where it will look for directory named trusted_certificates and read certs from there. If no path is specified it will take trusted certs, that are provided by client itself. They are located at src/resources/trusted_certificates.

Note about verification code and validating the signature

This what happens behind the scenes (all the steps besides step #5 are performed by this library):

1. For every new authentication the library generates a random value (stored into variable 'dataToSign')
2. A digest (SHA-512, SHA-384 or SHA-256) is calculated out of this random value (stored into variable 'hash')
3. Verification code that is displayed to the end user is calculated out of this digest.
4. The authentication request (together with value of 'hash') is sent out to the server.
5. Now signing process takes place in user's the phone and the Smart-ID REST service returns the signature and the authentication certificate of the user.
6. The library verifies that the signature value that was returned is really a valid signature. (For the verification it uses the value of 'dataToSign' (and not the digest that is stored in 'hash') together with the authentication signature.)

Extract date of birth of the authenticated person

All Estonian and Lithuanian national identity numbers contain date-of-birth info ant his is why getDateOfBirth() function always returns a correct value for them. Also birthdate info is present within old type of Latvian national identity numbers.

For persons with new type of Latvian national identity number the date-of-birth is parsed from a separate field of the certificate but for some older Smart-id accounts (issued between 2017-07-01 and 2021-05-20) the value might be missing.

More info about the availability of this separate field in the certificates: https://github.com/SK-EID/smart-id-documentation/wiki/FAQ#where-can-i-find-users-date-of-birth

Authenticating with document number

It might be needed to use document number instead of semantics identifier when you are (for some reason) re-authenticating the user in a short period of time and you want the user to use the same device as previously.

If user has several Smart-ID accounts (for example one in phone and one in tablet) then when authenticating with semantics identifier both of the devices initiate the flow (user can pick either one of the devices and type in PIN there). Since document number is device-specific then when you use document number only one of user devices starts the authentication flow.

You get the documentNumber of the user after successful authentication. See the example above where documentNumber is logged out in the end.

Authenticate with polling every 5 seconds

Previous examples block until the user has typed in PIN code or pressed cancel or authentication has failed for some other reason (like timeout). This example demonstrates polling the status every 5 seconds.