SDK 9.2.

2: SSL functions

Page 1 of 40

SDK 9.2.2
Modules | Functions | Defines | Typedefs

SSL functions
TCPIP

Presentation
This module contains all the SSL definitions. Please have a look to SSL Security Guidance The sample project under (SDKInstallationDirectory) \SDK\Samples\SSL helps you using SSL feature. Introduction The package SSL is a static library which implements an API to use the dynamic SSL library. It must be linked with the application. It is composed of two API header files ( < SSL_.h>, <X509_.h>) and a library "SSL _.lib" compiled with the three compilers (GCC, RVD and SDT) supported by the Telium SDK. The package provides all the services to monitor the SSL client facility : SSL connection (simple or double authentication). SSL configuration profile monitoring X509 certificate management //... Developers shall read the [SMO-SFO-ICO-PE-046-GU-EN_PackSSL_SecurityGuidance_UserGuide.pdf] which describes best practises for implementing SSL/TLS enabled applications, according to the requirements of the POS Terminal Security Program (PTS) and of the PCI PTS v3 "Open Protocols" module. Be careful, do not forget to load the dynamic SSL library (3620xxxx.LDF/SGN) in your terminal. Each function makes a reset with EXIT_DLL_SSL_NOT_INITIALIZED value if the dynamic SSL library is not loaded in the terminal. Certificates A certificate is a digitally signed statement from an entity certifying that information about an other entity are true. A certificate is an information set, signed by an issuer entity. The signature algorithms are based on asymmetric key cryptography (generally RSA). The issuer entity signs by enciphering the information set with its private key (known only by itself). The other entities can verified the signature by deciphering the information set with the public key of the issuer. SSL uses the certificate principle to operate the authentication of the entities (client and server). These certificates are coded according to the X509 standard. This standard defines what information can contain a certificate, and describes the data format how to write it down. All X.509 certificates contain the following data, in addition to the signature:

Version: This identifies which version of the X509 standard is used to code the certificate. It affects

mk:@MSITStore:C:\Users\tiberiup\Desktop\ssl_lib.chm::/group___k_s_f_a_m___s_s_l.ht... 22/1/2014

SDK 9.2.2: SSL functions

Page 2 of 40

mainly what information can be stored in the certificate.

Serial Number: This identifies the certificate. It is given by the issuer entity. It serves to distinguish the certificate from the other ones issued by the same issuer entity. This information is used for example when the certificate is revoked ; in this case, its serial number is placed in a Certificate Revocation List (CRL). Signature Algorithm Identifier: This identifies the algorithm used by the issuer entity to sign the certificate. Issuer Name: The name of the issuer entity. Normally, it corresponds to a Certification Authority (CA). Using this certificate implies trusting the entity that issued the certificate. Validity Period: A certificate is valid only for a limited period of time. This period is described by a start date and an end date. The validity period is the expected period that the entities can rely on the information of the certificate. This period is chosen by the issuer. It depends on the strength of the signature algorithm, or mainly the willing of issuer to sell its certificates. Subject Name: The name of the entity whose the certificate identifies. Subject Public Key Information: This is the public key of the subject entity. This information identifies also the cryptographic algorithm associated to the key.

The names of the issuer entity and of the subject entity are coded according to the X500 standard. They are intended to be unique across the Internet. A X500 name is composed of fields, for example : "CN=EFT30, OU=DSEC, O=Ingenico France, C=FR" refer respectively to the subject's Common Name, Organisational Unit, Company and Country). There are two ways to generate a certificate:

1. You can create one yourself using special tools (for example those provided with OpenSSL) 2. You can ask a Certification Authority (CA) to get one directly or generate a request (named CSR for Certification Signature Request) and ask the CA for its signature.

SSL SSL stands for Secure Socket Layer. The protocol's name is now officially TLS but SSL is still the better known name. SSL was designed to permit applications and servers to exchange sensitive information and prevent programs that could access the network traffic from reading the sensitive data. SSL uses the notion of client and server. Its operational scheme does not require the client and the server to share a secrete key. SSL uses asymmetric encryption algorithms to secure the transaction. These algorithms uses pair of keys (public and private). The public key is freely available and known for anybody. The private key is only known by the entity (the client or the server). These keys have to main properties :

1. Data encrypted by the public key can only decrypted by the private key. As the public is freely known, anybody can transfer secured data to the entity owner of the private key. 2. Data encrypted by the private key can be only decrypted by using the public key. This property is used

mk:@MSITStore:C:\Users\tiberiup\Desktop\ssl_lib.chm::/group___k_s_f_a_m___s_s_l.ht... 22/1/2014

SDK 9.2.2: SSL functions

Page 3 of 40

for authentication. Only the entity owner of the private key is able to generate a message which can be decrypted with the public key. In the SSL scheme, the client contacts the server and sends the first SSL message. This message starts the SSL negotiation : an encryption algorithm is chosen and a secured key is generated to the current connection. After the success of this negotiation, the two entities can exchange secured data at will. The SSL negotiation (named SSL Handshake) involves an authentication process. At least , the server is authenticated by the client (case of simple authentication). The server can also request the client to be authenticated (case of mutual authentication). The SSL authentication scheme is based on the use of certificates. Below is the description of the message sequence to operate the SSL handshake.

SSL Message Sequence Diagram

mk:@MSITStore:C:\Users\tiberiup\Desktop\ssl_lib.chm::/group___k_s_f_a_m___s_s_l.ht... 22/1/2014

SDK 9.2.2: SSL functions

Page 4 of 40

Profiles Management The SSL library defines the notion of profile. A profile is a data set which contains all the configuration useful to perform a connection SSL. The library allows to have several profiles. All the profiles are stored in a file in flash.

Profiles Management Illustration

mk:@MSITStore:C:\Users\tiberiup\Desktop\ssl_lib.chm::/group___k_s_f_a_m___s_s_l.ht... 22/1/2014