A reminder on how to use ID-Card in your webservers applications

How does ID card authentication work?

Estonian ID card authentication is configured on the web server to be invisible to client applications. This is essentially how it works:

1)  The web server requests a certificate from the visitor (i.e. their browser).
(how the visitor’s browser requests this from the visitor depends on the specific browser)

2) After receiving the certificate from the client’s browser, the web server checks the following:

• the certificate MUST BE signed by  AS Sertifitseerimiskeskus
• the certificate MUST NOT BE included in the revocation lists of certificates issued by AS Sertifitseerimiskeskus

Only when these 2 steps have been successfully completed, will the contents of the protected directory be displayed, or the PHP application started on the web server.

What are revocation lists and how are they updated?

Revocation lists are files containing all the Estonian ID-card certificates that have been suspended at any point in time.

According to the Certification Centre, it can take up to 12 hours to update the revocation lists. So, there might be a situation where a certificate has already been suspended but has not reached the revocation lists. Therefore, for higher security applications, it is always advisable to additionally ask the visitor to use a password.

New revocation lists are downloaded to the Zone web servers every full hour.

What do I need to use my ID card in web server applications?

NB! To use an ID card, you need a dedicated IP address. A dedicated IP address is available with the PRO service package and must be activated by contacting our help desk.

The added IP has to be connected with the appropriate host from the server control panel (the root domain of the virtual server, or one of its subdomains).

Then, a .htaccess file containing 2 lines must be added  in the directory that the visitor is only allowed to access with an authentic ID card. .htaccess lines which must be added are the following:

SSLVerifyClient require
SSLVerifyDepth 2

For example, to add ID card support to https://companyname.ee/myapplication/, you need to make a file /secure/htdocs/myapplication/.htaccess and include the above lines.

How do I get visitor’s ID card information from PHP?

Assuming that you have got the ID card support working in the desired directory, you would now also need to get information about the visitor’s ID card in the applications. This is passed from the web server to PHP via environment variables.

PHP has a function getenv() to read the environment variables.

To identify the client, there is a variable SSL_CLIENT_S_DN. This contains the visitor’s first name, surname and ID.

You can easily see all the variables with phpinfo(). Variables related to the ID card certificate are in the Apache Environment section with the SSL_CLIENT_* prefix.

The personal details on the certificate are encoded in UCS-2/UTF-16 format. This allows for non-ASCII characters like ‘š’ ja ‘ž’ to be used in a persons name. The resulting sequence then has all special characters replaced by two slashes and a character code in the HEX system.

Data encoded in this way can be converted to the widely used UTF-8 encoding using the following script:

<?php
function certstr2utf8 ($str) {
$str = preg_replace_callback("/\\\\x([0-9ABCDEF]{1,2})/", function ($s) { return chr(hexdec($s[1])); }, $str);

$result="";

$encoding=mb_detect_encoding($str,"ASCII, UCS2, UTF8");

if ($encoding=="ASCII") {

$result=mb_convert_encoding($str, "UTF-8", "ASCII");

} else {

if (substr_count($str,chr(0))>0) {
$result=mb_convert_encoding($str, "UTF-8", "UCS2");
} else {
$result=$str;
}
}

return $result;
}

header ("Content-Type: text/html; charset=UTF-8");

$s = getenv ('SSL_CLIENT_S_DN');
$l = preg_split ('|/|', $s, -1, PREG_SPLIT_NO_EMPTY);

foreach ($l as $e) {
list ($n, $v) = explode ('=', $e, 2);
echo $n . '=' . certstr2utf8 ($v) . "<br />";
}
?>