📄 emUSB-Device User Guide & Reference Manual
📄 emUSB-Host User Guide & Reference Manual
📄 emWeb User Guide & Reference Manual
📄 IoT Toolkit User Guide & Reference Manual
📄 SEGGER Assembler User Guide & Reference Manual
📄 SEGGER Floating-point Library User Guide & Reference Manual
📄 SEGGER Linker User Guide & Reference Manual
📄 SEGGER Runtime Library User Guide & Reference Manual
📄 embOS & embOS-MPU Real-Time Operating System User Guide & Reference Manual
📄 emCompress-Embed User Guide & Reference Manual
📄 emCompress-Flex User Guide & Reference Manual
📄 emCompress-ToGo User Guide & Reference Manual
📄 emCrypt User Guide & Reference Manual
📄 emDropbox User Guide & Reference Manual
📄 emFile User Guide & Reference Manual
📄 emNet User Guide & Reference Manual
📄 emSecure-ECDSA User Guide & Reference Manual
📄 emSecure-RSA User Guide & Reference Manual
📄 emSSH User Guide & Reference Manual
📄 emSSL User Guide & Reference Manual

emSSL User Guide & Reference Manual

Secure Sockets Library.

Introduction to emSSL

This section presents an overview of emSSL, its structure, and its capabilities.

What is emSSL?

emSSL is a software library that enables you to create secure connections between a client and a server, typically over the Internet using TCP/IP.

In this manual we use the term SSL to indicate a protocol supported by emSSL. SSL is the original acronym for Secure Sockets Layer, which is now more accurately known as Transport layer Security or TLS. It may seem confusing to use the old acronym SSL when talking of TLS, but SSL is so well established that the term endures in literature and product names alike: emSSL is no different.

Although SSL is usually associated with secure connections to a website using TCP/IP, the SSL specification makes no mention of TCP/IP. In fact, you can use emSSL to run an SSL session over any bidirectional channel, for instance a serial line or wireless link, and provide a secure connection.

emSSL is both hardware independent and transport independent, and integrates seamlessly with embOS/IP. For interoperability, emSSL has support for TLS versions 1.0, 1.1, and 1.2 with mandatory and extended cipher suites. Support for SSL 2 and SSL 3 is absent as these protocols are now proven insecure.

Design goals

emSSL is designed with the following goals in mind:

We believe all design goals are achieved by emSSL.

Features

emSSL is written in ANSI C and can be used on virtually any CPU. Here is a list of emSSL features:

Package content

emSSL is provided in source code and contains everything required. The following table shows the content of the emSSL Package:

Files Description
Application emSSL sample applications for bare metal and embOS.
Config Configuration header files.
CRYPTO Shared cryptographic library source code.
Doc emSSL documentation.
Sample/Config Example emSSL user configuration.
SEGGER SEGGER software component source code used in emSSL.
SSL emSSL implementation source code.
Windows/SSL emSSL sample applications for Windows.

Include directories

You should make sure that the include path contains the following directories (the order of inclusion is of no importance):

Always make sure that you have only one version of each file.

Note

It is frequently a major problem when updating to a new version of emSSL if you have old files included and therefore mix different versions. If you keep emSSL in the directories as suggested (and only in these), this type of problem cannot occur. When updating to a newer version, you should be able to keep your configuration files and leave them unchanged. For safety reasons, we recommend backing up (or at least renaming) the emSSL directories before updating.

Exploring emSSL

This chapter describes how to try out emSSL on a PC and embedded hardware with minimal effort. We highly recommend that you try out a working version of emSSL, shipped by SEGGER, with a known-good setup, preferably on an emPower board, before attempting to add it to your own application.

Using a PC to try emSSL

emSSL is shipped with a precompiled example that demonstrate a simple SSL web server. You can run the example and connect to the local web server on port 443.

C:> SSL_SimpleWebServer.exe

(c) 2014-2017 SEGGER Microcontroller GmbH & Co. KG    www.segger.com
emSSL Simple Secure Web Server V2.50 compiled May 25 2017 16:22:36

Waiting for connection on port 443...
_

When you run this, Windows Firewall will present a dialog asking whether to grant network access to the application:

Windows Firewall dialog

Proceed and grant access otherwise you will not be able to serve web pages to clients.

The web server application is waiting for a client to connect to it such that it can serve its small web page. Now start a web browser and open the URL “https://127.0.0.1/”. This example uses Internet Explorer 11:

Windows Firewall dialog

The warning shown by the browser indicates that the certificate presented is invalid — and it is, according to the browser, because you are browsing your own PC using a self-signed certificate rather than a fully-authenticated certificate for a website on the Internet.

You will notice that the server has accepted the connection, negotiated the connection, and then closed the connection and is waiting for a new connection:

C:> SSL_SimpleWebServer.exe

(c) 2014-2017 SEGGER Microcontroller GmbH & Co. KG    www.segger.com
emSSL Simple Secure Web Server V2.40 compiled May 25 2017 16:22:36

Waiting for connection on port 443...
Connection made, attempting to upgrade to secure...
Session is now secured by TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
Session closed.

Waiting for connection on port 443...
_

In Internet Explorer, click “Continue to this website” or, if you are using another browser, accept the certificate or click “Advanced” and “Proceed to 127.0.0.1” and you should be greeted with a short web page served by emSSL on your PC:

Page served by emSSL

The browser makes two additional connections to the server to gather the web page and any favicon. Refeshing the page in the browser will cause only one secure connection to be made to the server.

Type Ctrl+C to close the emSSL web server:

C:> SSL_SimpleWebServer.exe

(c) 2014-2017 SEGGER Microcontroller GmbH & Co. KG    www.segger.com
emSSL Simple Secure Web Server V2.40 compiled May 25 2017 16:22:36

Waiting for connection on port 443...
Connection made, attempting to upgrade to secure...
Session is now secured by TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
Session closed.

Waiting for connection on port 443...
Connection made, attempting to upgrade to secure...
Session is now secured by TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
Session closed.

Waiting for connection on port 443...
Connection made, attempting to upgrade to secure...
Session is now secured by TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
Socket closed by server.

Waiting for connection on port 443...
^C
C:> _

This shows that both sides of the TLS connection are working correctly and the cipher suite that was agreed between them is TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256.

Scanning websites with emSSL

The previous section demonstrated emSSL running in server mode. emSSL is shipped with a precompiled example that demonstrates client mode.

Open a command line window and navigate to the Windows/SSL directory that contains the SSL_Scan.exe application. Once there, run SSL_Scan.exe on www.segger.com and you should see something similar to this:

C:> ssl_scan www.segger.com

(c) 2014-2017 SEGGER Microcontroller GmbH & Co. KG    www.segger.com
emSSL TLS Scan V2.40 compiled May 25 2017 17:22:32

Scanning cipher suites for www.segger.com:443...

0084 RSA_WITH_CAMELLIA_256_CBC_SHA            TLS 1.2  RSA      72 ms
0041 RSA_WITH_CAMELLIA_128_CBC_SHA            TLS 1.2  RSA      73 ms
009D RSA_WITH_AES_256_GCM_SHA384              TLS 1.2  RSA      74 ms
003D RSA_WITH_AES_256_CBC_SHA256              TLS 1.2  RSA      73 ms
0035 RSA_WITH_AES_256_CBC_SHA                 TLS 1.2  RSA      74 ms
009C RSA_WITH_AES_128_GCM_SHA256              TLS 1.2  RSA      74 ms
003C RSA_WITH_AES_128_CBC_SHA256              TLS 1.2  RSA      71 ms
002F RSA_WITH_AES_128_CBC_SHA                 TLS 1.2  RSA      73 ms
000A RSA_WITH_3DES_EDE_CBC_SHA                TLS 1.2  RSA      74 ms
C030 ECDHE_RSA_WITH_AES_256_GCM_SHA384        TLS 1.2  RSA      75 ms
C028 ECDHE_RSA_WITH_AES_256_CBC_SHA384        TLS 1.2  RSA      80 ms
C014 ECDHE_RSA_WITH_AES_256_CBC_SHA           TLS 1.2  RSA      79 ms
C02F ECDHE_RSA_WITH_AES_128_GCM_SHA256        TLS 1.2  RSA      78 ms
C027 ECDHE_RSA_WITH_AES_128_CBC_SHA256        TLS 1.2  RSA      76 ms
C013 ECDHE_RSA_WITH_AES_128_CBC_SHA           TLS 1.2  RSA      78 ms
C012 ECDHE_RSA_WITH_3DES_EDE_CBC_SHA          TLS 1.2  RSA      77 ms
0088 DHE_RSA_WITH_CAMELLIA_256_CBC_SHA        TLS 1.2  RSA     179 ms
0045 DHE_RSA_WITH_CAMELLIA_128_CBC_SHA        TLS 1.2  RSA     177 ms
009F DHE_RSA_WITH_AES_256_GCM_SHA384          TLS 1.2  RSA     176 ms
006B DHE_RSA_WITH_AES_256_CBC_SHA256          TLS 1.2  RSA     174 ms
0039 DHE_RSA_WITH_AES_256_CBC_SHA             TLS 1.2  RSA     177 ms
009E DHE_RSA_WITH_AES_128_GCM_SHA256          TLS 1.2  RSA     178 ms
0067 DHE_RSA_WITH_AES_128_CBC_SHA256          TLS 1.2  RSA     175 ms
0033 DHE_RSA_WITH_AES_128_CBC_SHA             TLS 1.2  RSA     179 ms
0016 DHE_RSA_WITH_3DES_EDE_CBC_SHA            TLS 1.2  RSA     180 ms

25 common cipher suites out of 106 tested

C:> _

This shows that emSSL has made 25 successful connections to www.segger.com out of 106 different protocols attempted. Reading the columns from left to right we see:

For a different set of cipher suites, scan Facebook:

C:> scan www.facebook.com

(c) 2014-2017 SEGGER Microcontroller GmbH & Co. KG    www.segger.com
emSSL TLS Scan V2.40 compiled May 25 2017 17:22:32

Scanning cipher suites for www.facebook.com:443...

0005 RSA_WITH_RC4_128_SHA                     TLS 1.2  RSA      68 ms
009D RSA_WITH_AES_256_GCM_SHA384              TLS 1.2  RSA      81 ms
0035 RSA_WITH_AES_256_CBC_SHA                 TLS 1.2  RSA      66 ms
009C RSA_WITH_AES_128_GCM_SHA256              TLS 1.2  RSA      72 ms
002F RSA_WITH_AES_128_CBC_SHA                 TLS 1.2  RSA      68 ms
000A RSA_WITH_3DES_EDE_CBC_SHA                TLS 1.2  RSA      69 ms
C011 ECDHE_RSA_WITH_RC4_128_SHA               TLS 1.2  RSA      76 ms
C030 ECDHE_RSA_WITH_AES_256_GCM_SHA384        TLS 1.2  RSA      73 ms
C014 ECDHE_RSA_WITH_AES_256_CBC_SHA           TLS 1.2  RSA      72 ms
C02F ECDHE_RSA_WITH_AES_128_GCM_SHA256        TLS 1.2  RSA      75 ms
C013 ECDHE_RSA_WITH_AES_128_CBC_SHA           TLS 1.2  RSA      78 ms
C012 ECDHE_RSA_WITH_3DES_EDE_CBC_SHA          TLS 1.2  RSA      73 ms
C007 ECDHE_ECDSA_WITH_RC4_128_SHA             TLS 1.2  ECDSA    94 ms
C02C ECDHE_ECDSA_WITH_AES_256_GCM_SHA384      TLS 1.2  ECDSA    84 ms
C00A ECDHE_ECDSA_WITH_AES_256_CBC_SHA         TLS 1.2  ECDSA    80 ms
C02B ECDHE_ECDSA_WITH_AES_128_GCM_SHA256      TLS 1.2  ECDSA    83 ms
C009 ECDHE_ECDSA_WITH_AES_128_CBC_SHA         TLS 1.2  ECDSA    80 ms
C008 ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA        TLS 1.2  ECDSA    84 ms

18 common cipher suites out of 106 tested

C:> _

Many of the cipher suites are the same as before, with new ECDHE-ECDSA suites appearing. In fact, most servers on the Internet use only a small subset of the vast range of cipher suites, key sizes, and elliptic curves that are available to be negotiated.

Moving to embedded hardware

When starting to run emSSL on embedded hardware, we recommend that you use one of the “Start” projects suppied in the BSP for your target system to begin with and gain confidence with a working system before progressing to add emSSL to your own application.

The following sections describe this process using SEGGER Embedded Studio, but the principles are the same for any embedded development or workstation environment. The target hardware is an SEGGER emPower board which is supplied with Embedded Studio PRO or available separately from SEGGER and through authorized distributors.

Start Embedded Studio and load the SEGGER emPower start project:

Start project in Embedded Studio

Once you have loaded your start project, you can test it out by choosing Debug > Go which flashes it into your target and starts running it under control of the debugger.

The Debug Terminal will show the configured IP address of the emPower board and you will be able to use a browser to show web pages serverd from the embedded target in the same way as the PC application above. If you do not see the Debug Terminal, choose View > Debug Terminal. The terminal output will look something similar to this:

Log output in Debug Terminal

emSSL will then display its configuration and indicate that it’s waiting for a connection:

emSSL initialized and waiting for a connection

At this point you will be able to use Internet Explorer, or your favorite web browser, to view secure content served by the emPower board.

Using emSSL

This chapter presents a simple secure client and server that demonstrates how to integrate emSSL into your application.

In this section we assume that you will use a PC or have a fully-functioning embOS/IP project that is able to connect to the network and all that is required is to add emSSL to the project.

Sample applications

emSSL ships with a number of sample applications that demonstrate how to integrate SSL into your application.

The sample applications are:

Application Description
SSL_ROT13Server.c A server that provides a ROT13 service.
SSL_ROT13Client.c A client that uses the ROT13 service.
SSL_SimpleWebServer.c A minimal web server.
SSL_SimpleWebClient.c A client that retrieves web content.

In this section we will describe only the ROT13 client and server.

A note on the samples

Each sample that presented in this section is written in a style that makes it easy to describe and that fits comfortably within the margins of printed paper. Therefore, it may well be that you would rewrite the sample to have a slightly different structure that fits better, but please keep in mind that these examples are written with clarity as the prime objective, and to that end we sacrifice some brevity and efficiency.

Where to find the sample code

All samples are included in the Application directory of the emSSL distribution.

What to expect

The following sections describe a client-server pair of applications that provode a “secure ROT13 service.” The ROT13 server accepts lines of text from a client, applies the ROT13 transform to each, and sends back the results to the client. For details of ROT13, see https://en.wikipedia.org/wiki/ROT13.

Run the server

Precompiled Windows executables for both client and server are provided in the Application folder. Open a command line window and run the SSL_ROT13Server application:

C:> SSL_ROT13Server.exe

(c) 2017 SEGGER Microcontroller GmbH & Co. KG    www.segger.com
emSSL ROT13 Server compiled May 26 2017 15:24:26

_

At this point the server is waiting for a connection from a client.

Run the client

Open a second command line window and run the SSL_ROT13Client application:

C:> SSL_ROT13Client.exe

(c) 2017 SEGGER Microcontroller GmbH & Co. KG    www.segger.com
emSSL ROT13 Client compiled May 26 2017 15:24:26

Sent: SEGGER - The Embedded Experts
Recv: FRTTRE - Gur Rzorqqrq Rkcregf
Sent: FRTTRE - Gur Rzorqqrq Rkcregf
Recv: SEGGER - The Embedded Experts
Sent: SEGGER - It simply works!
Recv: FRTTRE - Vg fvzcyl jbexf!
Sent: FRTTRE - Vg fvzcyl jbexf!
Recv: SEGGER - It simply works!

C:> _

What's happening?

From the client’s perspective it:

This shows that two successive applications of ROT13 restore the original text, so the ROT13 server can both “encipher” and “decipher” using ROT13.

The server also traces what it is doing:

C:> SSL_ROT13Server.exe

(c) 2017 SEGGER Microcontroller GmbH & Co. KG    www.segger.com
emSSL ROT13 Server compiled May 26 2017 15:24:26

Recv: SEGGER - The Embedded Experts!
Sent: FRTTRE - Gur Rzorqqrq Rkcregf!
Recv: FRTTRE - Gur Rzorqqrq Rkcregf!
Sent: SEGGER - The Embedded Experts!
Recv: SEGGER - It simply works!
Sent: FRTTRE - Vg fvzcyl jbexf!
Recv: FRTTRE - Vg fvzcyl jbexf!
Sent: SEGGER - It simply works!
_

From the server’s perspective it:

Although the connection is dropped by the client, the server does not exit, it continues executing awaiting another connection. To close the server, type Ctrl+C.

ROT13 server

The first application, SSL_ROT13Server.c, provides a service that will transform lines of text to their ROT13-encoded equivalent.

For a complete listing of this application, see SSL_ROT13Server.c complete listing.

Application entry

The main application task is responsible for setting up the environment ready to accept incoming SSL requests. This is simply boilerplate code that has no configuration:

void MainTask(void) {
  SSL_SESSION Session;
  int         BoundSocket;
  int         Socket;
  int         Status;
  //
  SEGGER_SYS_Init();  
  SEGGER_SYS_IP_Init();
  SSL_Init();  
  //
  SEGGER_SYS_IO_Printf("\n");  
  SEGGER_SYS_IO_Printf("(c) 2017 SEGGER Microcontroller GmbH & Co. KG"
                       "    www.segger.com\n");
  SEGGER_SYS_IO_Printf("emSSL ROT13 Server ");
  SEGGER_SYS_IO_Printf("compiled " __DATE__ " " __TIME__ "\n\n");
  //

  Initialize system components

The calls to SEGGER_SYS_Init() and SEGGER_SYS_IP_Init() use the SEGGER system abstraction layer to initialize services to the application.

How you open a socket to the remote server depends on the underlying networking API. To make connection as simple as possible, emSSL examples use a common API and emSSL ships with example implementations of the API for both Windows and embOS/IP.

The emSSL examples can run on a standard Windows or Linux host, or an embedded target using embOS/IP. All SEGGER portability wrapper preprocessor symbols and functions are prefixed with “SEGGER_SYS_”.

  Initialize SSL component

Before using any emSSL service you must initialize the SSL module. You do this by including the emSSL header SSL.h and by calling SSL_Init().

Configuration of the emSSL’s capabilities is carried out by SSL_X_Config() that is called as part of the SSL initialization carried out by SSL_Init(). SSL_X_Config() must be provided in your application as a function with external linkage and an example is shipped with emSSL. Specific configuration capabilities are not discussed in detail here, you can find extensive documentation on how to configure emSSL in Configuring emSSL.

  Display identification

When running the server, this code just shows that the server is up and ready for connections.

Accepting SSL connections

Once emSSL is correctly configured, the application in responsible for accepting connections:

//
// Bind application's ROT13 port.
//
BoundSocket = SEGGER_SYS_IP_Bind(19000);  
if (BoundSocket < 0) {
  SEGGER_SYS_OS_Halt(100);
}
//
for (;;) {
  //
  do {  
    Socket = SEGGER_SYS_IP_Accept(BoundSocket);
  } while (Socket < 0);
  //
  SSL_SESSION_Prepare(&Session, Socket, &_IP_Transport);  
  Status = SSL_SESSION_Accept(&Session);  
  //
  if (Status < 0) {
    SEGGER_SYS_IO_Printf("Can't negotiate a secure connection.\n\n");
    SEGGER_SYS_IP_Close(Socket);
  } else {
    do {
      Status = _Serve(&Session);  
    } while (Status >= 0);
    SSL_SESSION_Disconnect(&Session);  
    SEGGER_SYS_IP_CloseWait(Socket);
  }
}

  Bind the application port

There is no standard “secure ROT13 service” port, so application port 19000 is dedicated to the service.

The call to SEGGER_SYS_IP_Bind() uses the SEGGER abstraction layer to bind port 19000 and return a socket corresponding to that binding. If the port is already bound and cannot accept incoming connections, the application terminates.

  Accept an incoming connection

Once the port is bound, we listen for incoming connections. The call to SEGGER_SYS_IP_Accept() waits for an incoming connection and creates a socket for that connection.

  Prepare the SSL session for the connection

The call to SSL_SESSION_Prepare() initializes an SSL session. For this simple example we only deal with a single session and therefore the session is allocated in the stack frame.

SSL_SESSION_Prepare() is provided a set of function pointers, in a structure, that vector to the appropriate send and receive functions for a socket. In this example, we use the SEGGER abstraction layer to provide socket services:

static const SSL_TRANSPORT_API _IP_Transport = {
  SEGGER_SYS_IP_Send,
  SEGGER_SYS_IP_Recv,
  NULL
};

These are very thin “shims” to the underlying embOS/IP or Windows socket functions, with the shim providing a consistent function prototype that adapts between the various implementations available.

Although SSL is typically used over TCP/IP, it is not necessarily the only medium for SSL communications. For example, CANopen specifies a “shell” port that runs a user-defined protocol that could, quite literally, be secured by SSL. In this case, your application could use emSSL to service TCP/IP connections and CAN connections using the same code but with different transport APIs: one for TCP/IP and one for CAN. And, if you wish to secure a serial connection, you could add functions that read and write over (one or more) serial connections.

  Set up secure connection

SSL_SESSION_Accept() attempts to negotiate a secure session between client and server using the socket. If a the client and server can agree a common set of communication parameters, the secure connection is established and the server continues; if not, the connection is dropped and the socket is closed to terminate communication.

  Run the server

When the secure communication channel is successfully negotiated, processing is handed off to code that reads requests and writes responses one request at a time. This code is presented below. When the session is closed, the server exits the loop.

  Disconnect and close down

The session may close gracefully or abruptly, and when closed control returns from _Serve(). At this point, the session is disconnected (if it not already disconnected) and is fully closed from an API perspective, and no further calls should be made to the API using that closed session: doing so leads to undefined behavior.

Once the session is disconnected, the socket is closed.

Serving the connection

In the previous section, serving the established connection delegates to the function _Serve():

static void _Serve(SSL_SESSION *pSession) {  
  char aData[256];
  int  Status;
  //
  Status = _RdLine(pSession, aData, sizeof(aData));  
  if (Status >= 0) {
    SEGGER_SYS_IO_Printf("Recv: %s", aData);
    _ApplyROT13(aData, Status);  
    Status = SSL_SESSION_Send(pSession, &aData[0], Status);  
    if (Status >= 0) {
      SEGGER_SYS_IO_Printf("Sent: %s", aData);
    } else {
      SEGGER_SYS_IO_Printf("Error sending data: %s\n",
                           SSL_ERROR_GetText(Status));
    }
  } else {
    if (Status != SSL_ERROR_EOF) {  
      SEGGER_SYS_IO_Printf("Error receiving data: %s\n",
                           SSL_ERROR_GetText(Status));
    }
  }
  //
  return Status;  
}

  Receive parameters

The function is passed a pointer to the SSL session to serve.

  Read an incoming line

The process of reading a single line is delegated to a function. The incoming line is deposited into aData which is zero-terminated by _RdLine(). The value returned by _RdLine() indicates the number of characters read successfully and that the connection remains open, or whether there was an error on the connection and the connection is errored.

Note that the number of characters is stored in Status to be used later, the same with the error status.

  Apply ROT13 tranform

If the line is received without error, it’s transformed in-place using _ApplyROT13().

  Send response

Once transformed, the line is sent back to the client. The number of characters in the line is the result of _RdLine() which is stored in the Status variable.

  Handling errors

If reading the line results in an error, a diagnostic is printed. The status code SSL_ERROR_EOF is distinguished and indicates that the connection has been closed by the client end and is not reported as an error.

  Exit

Once processing is complete, the status of reading, transforming, and sending the line to the client is returned to the caller.

Reading a line of text

The client sends the server a line of text and terminates it by a newline character, ’\n’. Therefore, it is not known in advance how many characters there are in the line. The function _RdLine() must therefore read one character at a time and search for the newline:

static int _RdLine(SSL_SESSION *pSession, U8 *pData, unsigned DataLen) {
  unsigned Len;
  int      Status;
  U8       Char;
  //
  Len = 0;
  for (;;) {
    Status = SSL_SESSION_Receive(pSession, &Char, 1);  
    if (Status == 0) {  
      return SSL_ERROR_EOF;
    } else if (Status < 0) {  
      return Status;
    }
    pData[Len] = Char;  
    if (Len+1 < DataLen) {
      ++Len;
    }
    if (Char == '\n') {  
      pData[Len] = 0;
      return Len;
    }
  }
}

  Read a character

The function SSL_SESSION_Receive() reads data from the secure socket. In this case we pass in the session and provide a single-character buffer that we wish to fill.

  Deal with premature socket closure

The value returned from SSL_SESSION_Receive() indicates the status of the read. If the value is zero, the socket was gracefully closed without delivering any requested data—and in this case, because we have not received the newline, this is an unexpected state. When this happens, we elect to deliver an “end of file” error to the caller.

  Propagate protocol errors

If the value returned from SSL_SESSION_Receive() is negative, it indicates a protocol error. On receiving an error indication, _RdLine() propagates the error to the caller.

  Accumulate characters

Having dealt with premature socket closure and protocol errors, processing continues and the received character is added to the provided buffer ensuring there is enough space to hold the character and a required zero terminator.

  Finalize

Once the newline is found, the provided buffer is zero-terminated and the number of bytes deposited into the buffer, including the newline but excluding the zero terminator, is returned.

Transforming characters using ROT13

Now that the server part is covered, all that remains is to show the mechanics of the ROT13 transform. The code is not described further.

static void _ApplyROT13(U8 *pData, unsigned DataLen) {
  unsigned i;
  //
  for (i = 0; i < DataLen; ++i) {
    if ('a' <= pData[i] && pData[i] <= 'm') {
      pData[i] = pData[i] - 'a' + 'n';
    } else if ('n' <= pData[i] && pData[i] <= 'z') {
      pData[i] = pData[i] - 'n' + 'a';
    } else if ('A' <= pData[i] && pData[i] <= 'M') {
      pData[i] = pData[i] - 'A' + 'N';
    } else if ('N' <= pData[i] && pData[i] <= 'Z') {
      pData[i] = pData[i] - 'N' + 'A';
    } 
  }
}

SSL_ROT13Server.c complete listing

/*********************************************************************
*                   (c) SEGGER Microcontroller GmbH                  *
*                        The Embedded Experts                        *
*                           www.segger.com                           *
**********************************************************************

-------------------------- END-OF-HEADER -----------------------------

File        : SSL_ROT13Server.c
Purpose     : Simple server that provides a secure ROT13 service.

*/

/*********************************************************************
*
*       #include Section
*
**********************************************************************
*/

#include "SSL.h"
#include "SEGGER_SYS.h"
#include <stdio.h>
#include <stdlib.h>

/*********************************************************************
*
*             Static const data
*
**********************************************************************
*/

static const SSL_TRANSPORT_API _IP_Transport = {
  SEGGER_SYS_IP_Send,
  SEGGER_SYS_IP_Recv,
  NULL
};

/*********************************************************************
*
*             Static code
*
**********************************************************************
*/

/*********************************************************************
*
*       _RdLine()
*
*  Function description
*    Read text line terminated by newline.
*
*  Parameters
*    pSession - Pointer to SSL session.
*    pData    - Pointer to object that receives the data.
*    DataLen  - Octet length of the receiving object.
*
*  Return value
*    >= 0 - Success, number of octets received including newline.
*     < 0 - Failure.
*/
static int _RdLine(SSL_SESSION *pSession, char *pData, unsigned DataLen) {
  unsigned Len;
  int      Status;
  U8       Char;
  //
  Len = 0;
  for (;;) {
    Status = SSL_SESSION_Receive(pSession, &Char, 1);
    if (Status == 0) {
      return SSL_ERROR_EOF;
    } else if (Status < 0) {
      return Status;
    }
    pData[Len] = Char;
    if (Len+1 < DataLen) {
      ++Len;
    }
    if (Char == '\n') {
      pData[Len] = 0;
      return Len;
    }
  }
}

/*********************************************************************
*
*       _ApplyROT13()
*
*  Function description
*    Apply ROT13 transform.
*
*  Parameters
*    pData    - Pointer to object to transform.
*    DataLen  - Octet length of the object to transform.
*/
static void _ApplyROT13(char *pData, unsigned DataLen) {
  unsigned i;
  //
  for (i = 0; i < DataLen; ++i) {
    if ('a' <= pData[i] && pData[i] <= 'm') {
      pData[i] = pData[i] - 'a' + 'n';
    } else if ('n' <= pData[i] && pData[i] <= 'z') {
      pData[i] = pData[i] - 'n' + 'a';
    } else if ('A' <= pData[i] && pData[i] <= 'M') {
      pData[i] = pData[i] - 'A' + 'N';
    } else if ('N' <= pData[i] && pData[i] <= 'Z') {
      pData[i] = pData[i] - 'N' + 'A';
    } 
  }
}

/*********************************************************************
*
*       _Serve()
*
*  Function description
*    Process a single ROT13 line.
*
*  Parameters
*    pSession - Pointer to SSL session.
*
*  Return value
*    >= 0 - Success, number of characters read, session remains open.
*    <  0 - Session closed.
*/
static int _Serve(SSL_SESSION *pSession) {
  char aData[256];
  int  Status;
  //
  Status = _RdLine(pSession, aData, sizeof(aData));
  if (Status >= 0) {
    SEGGER_SYS_IO_Printf("Recv: %s", aData);
    _ApplyROT13(aData, Status);
    Status = SSL_SESSION_Send(pSession, &aData[0], Status);
    if (Status >= 0) {
      SEGGER_SYS_IO_Printf("Sent: %s", aData);
    } else {
      SEGGER_SYS_IO_Printf("Error sending data: %s\n", SSL_ERROR_GetText(Status));
    }
  } else {
    if (Status != SSL_ERROR_EOF) {
      SEGGER_SYS_IO_Printf("Error receiving data: %s\n", SSL_ERROR_GetText(Status));
    }
  }
  //
  return Status;
}

/*********************************************************************
*
*             Public code
*
**********************************************************************
*/

/*********************************************************************
*
*       MainTask()
*
*  Function description
*    Application entry point.
*/
void MainTask(void);
void MainTask(void) {
  SSL_SESSION Session;
  int         BoundSocket;
  int         Socket;
  int         Status;
  //
  SEGGER_SYS_Init();
  SEGGER_SYS_IP_Init();
  SSL_Init();
  //
  SEGGER_SYS_IO_Printf("\n");
  SEGGER_SYS_IO_Printf("%s    www.segger.com\n", SSL_GetCopyrightText());
  SEGGER_SYS_IO_Printf("emSSL ROT13 Server ");
  SEGGER_SYS_IO_Printf("compiled " __DATE__ " " __TIME__ "\n\n");
  //
  // Bind application's ROT13 port.
  //
  BoundSocket = SEGGER_SYS_IP_Bind(19000);
  if (BoundSocket < 0) {
    SEGGER_SYS_OS_Halt(100);
  }
  //
  for (;;) {
    //
    do {
      Socket = SEGGER_SYS_IP_Accept(BoundSocket);
    } while (Socket < 0);
    //
    SSL_SESSION_Prepare(&Session, Socket, &_IP_Transport);
    Status = SSL_SESSION_Accept(&Session);
    //
    if (Status < 0) {
      SEGGER_SYS_IO_Printf("Can't negotiate a secure connection.\n\n");
      SEGGER_SYS_IP_Close(Socket);
    } else {
      do {
        Status = _Serve(&Session);
      } while (Status >= 0);
      SSL_SESSION_Disconnect(&Session);
      SEGGER_SYS_IP_CloseWait(Socket);
    }
  }
}

/*************************** End of file ****************************/

ROT13 client

The second application, SSL_ROT13Client.c, uses the secure ROT13 server to transform lines of text to their ROT13-encoded equivalent.

The process can be broken down into a sequence of steps:

For a complete listing of this application, see SSL_ROT13Client.c complete listing.

Application entry

The main application task is responsible for setting up the environment ready to make outgoing SSL requests. This is simply boilerplate code that has no configuration:

void MainTask(void) {
  SSL_SESSION Session;
  int         Socket;
  //
  // Kick off networking and start SSL.
  //
  SEGGER_SYS_Init();  
  SEGGER_SYS_IP_Init();
  SSL_Init();  
  //
  SEGGER_SYS_IO_Printf("\n");  
  SEGGER_SYS_IO_Printf("(c) 2017 SEGGER Microcontroller GmbH & Co. KG"
                       "    www.segger.com\n");
  SEGGER_SYS_IO_Printf("emSSL ROT13 Client ");
  SEGGER_SYS_IO_Printf("compiled " __DATE__ " " __TIME__ "\n\n");

  Initialize system components

The calls to SEGGER_SYS_Init() and SEGGER_SYS_IP_Init() use the SEGGER system abstraction layer to initialize services to the application and are identical to the server application.

  Initialize SSL component

The call to SSL_Init() initialized emSSL for use and is identical to the server application.

  Display identification

When running the client, this code just shows that the client is up and ready to make connections.

Making SSL connections

With the application initialized, the code progresses to interact with the server:

Socket = SEGGER_SYS_IP_Open(ROT13_SERVER, ROT13_PORT);  
if (Socket < 0) {
  SEGGER_SYS_IO_Printf("Cannot open %s:%d!\n", ROT13_SERVER, ROT13_PORT);
  SEGGER_SYS_OS_Halt(100);
}
//
SSL_SESSION_Prepare(&Session, Socket, &_IP_Transport);  
if (SSL_SESSION_Connect(&Session, ROT13_SERVER) < 0) {
  SEGGER_SYS_IO_Printf("Cannot negotiate a secure connection to %s:%d!\n",
                       ROT13_SERVER, ROT13_PORT);
  SEGGER_SYS_OS_Halt(100);
}
//
_RequestROT13(&Session, "SEGGER - The Embedded Experts\n");  
_RequestROT13(&Session, "FRTTRE - Gur Rzorqqrq Rkcregf\n");
_RequestROT13(&Session, "SEGGER - It simply works!\n");
_RequestROT13(&Session, "FRTTRE - Vg fvzcyl jbexf!\n");
//
// Close the SSL connection.
//
SSL_SESSION_Disconnect(&Session);  
SEGGER_SYS_IP_Close(Socket);
//
SSL_Exit();  
SEGGER_SYS_IP_Exit();
SEGGER_SYS_OS_PauseBeforeHalt();
SEGGER_SYS_OS_Halt(0);

  Open plain socket to server

The socket connection function is SEGGER_SYS_IP_Open() which is provided in SEGGER_SYS.h. This function will resolve a host’s domain name and attempt to open a socket to the given port on the server. If everything goes without problems, the function result is a socket handle. If things go badly and the host is unreachable, or the port is refused, the function result is negative indicating an error.

By default the application opens a socket on the local host:

#define ROT13_SERVER  "127.0.0.1"
#define ROT13_PORT    19000

  Upgrade the socket to secure

To upgrade an open socket to secure, you use SSL_SESSION_Prepare() and SSL_SESSION_Connect(). The function SSL_SESSION_Prepare() will prepare a session and allow configuration of options before you negotiate an SSL connection using SSL_SESSION_Connect(). The function SSL_SESSION_Connect() returns a negative value if an SSL session cannot be established. An SSL connection may fail if the two peers cannot negotiate a common cipher suite or a common SSL version.

  Communicate with service

The application sends four separate requests to the ROT13 server for processing. The function _RequestROT13() which communicates with the server is presented below.

  Close the connection

Once you have finished with an SSL connection, or the peer closes the connection, you must release the resources associated with the connection using SSL_SESSION_Disconnect(). SSL disconnection terminates the connection between the peers but does not close the underlying socket. In order to close the socket that was established as the transport, you use SYS_IP_Close.

  Close SSL and IP

Closing down IP and SSL releases any resources that they hold.

Sending requests

The function _RequestROT13() send a request to the ROT13 server and accepts its reponse:

static void _RequestROT13(SSL_SESSION *pSession, const char *pData) {  
  U8  aResponse[256];
  int Status;
  //
  // Send data to server.
  //
  Status = SSL_SESSION_SendStr(pSession, (const U8 *)pData);  
  if (Status >= 0) {
    SEGGER_SYS_IO_Printf("Sent: %s", pData);
    Status = _RdLine(pSession, aResponse, sizeof(aResponse));  
    if (Status >= 0) {
      SEGGER_SYS_IO_Printf("Recv: %s", aResponse);
    } else {
      SEGGER_SYS_IO_Printf("Error receiving data: %s\n",
                           SSL_ERROR_GetText(Status));
    }
  } else {
    SEGGER_SYS_IO_Printf("Error sending data: %s\n", SSL_ERROR_GetText(Status));
  }
}

  Accept parameters

The parameters are the connected SSL session and the zero-terminated string to transform.

  Send request

The zero-terminated string is sent to the server using SSL_SESSION_SendStr(). If it was not zero terminated, the function SSL_SESSION_Send() takes a “compound parameter” that is the data to send and its length.

  Read response

The response is read by _RdLine() which is identical to the code in the ROT13 server.

All remainng code is for processing errors and echoing data sent and received and is not further explained.

SSL_ROT13Client.c complete listing

/*********************************************************************
*                   (c) SEGGER Microcontroller GmbH                  *
*                        The Embedded Experts                        *
*                           www.segger.com                           *
**********************************************************************

-------------------------- END-OF-HEADER -----------------------------

File        : SSL_ROT13Client.c
Purpose     : Simple client that uses a secure ROT13 service.

*/

/*********************************************************************
*
*       #include section
*
**********************************************************************
*/

#include "SSL.h"
#include "SEGGER_SYS.h"

/*********************************************************************
*
*       Defines, configurable
*
**********************************************************************
*/

#define ROT13_SERVER  "127.0.0.1"
#define ROT13_PORT    19000

/*********************************************************************
*
*             Static const data
*
**********************************************************************
*/

static const SSL_TRANSPORT_API _IP_Transport = {
  SEGGER_SYS_IP_Send,
  SEGGER_SYS_IP_Recv,
  NULL
};

/*********************************************************************
*
*       Static code
*
**********************************************************************
*/

/*********************************************************************
*
*       _RdLine()
*
*  Function description
*    Read text line terminated by newline.
*
*  Parameters
*    pSession - Pointer to SSL session.
*    pData    - Pointer to object that receives the data.
*    DataLen  - Octet length of the receiving object.
*
*  Return value
*    >= 0 - Success, number of octets received including newline.
*     < 0 - Failure.
*/
static int _RdLine(SSL_SESSION *pSession, U8 *pData, unsigned DataLen) {
  unsigned Len;
  int      Status;
  U8       Char;
  //
  Len = 0;
  for (;;) {
    Status = SSL_SESSION_Receive(pSession, &Char, 1);  
    if (Status == 0) {  
      return SSL_ERROR_EOF;
    } else if (Status < 0) {  
      return Status;
    }
    pData[Len] = Char;  
    if (Len+1 < DataLen) {
      ++Len;
    }
    if (Char == '\n') {  
      pData[Len] = 0;
      return Len;
    }
  }
}

/*********************************************************************
*
*       _RequestROT13()
*
*  Function description
*    Apply ROT13 transform using ROT13 server.
*
*  Parameters
*    pSession - Pointer to SSL session.
*    pData    - Pointer to text to transform.
*/
static void _RequestROT13(SSL_SESSION *pSession, const char *pData) {
  U8  aResponse[256];
  int Status;
  //
  // Send data to server.
  //
  Status = SSL_SESSION_SendStr(pSession, pData);
  if (Status >= 0) {
    SEGGER_SYS_IO_Printf("Sent: %s", pData);
    Status = _RdLine(pSession, aResponse, sizeof(aResponse));
    if (Status >= 0) {
      SEGGER_SYS_IO_Printf("Recv: %s", aResponse);
    } else {
      SEGGER_SYS_IO_Printf("Error receiving data: %s\n", SSL_ERROR_GetText(Status));
    }
  } else {
    SEGGER_SYS_IO_Printf("Error sending data: %s\n", SSL_ERROR_GetText(Status));
  }
}

/*********************************************************************
*
*       Public code
*
**********************************************************************
*/

/*********************************************************************
*
*       MainTask()
*
*  Function description
*    Ask ROT13 service to transform something.
*/
void MainTask(void);
void MainTask(void) {
  SSL_SESSION Session;
  int         Socket;
  //
  // Kick off networking and start SSL.
  //
  SEGGER_SYS_Init();
  SEGGER_SYS_IP_Init();
  SSL_Init();
  //
  SEGGER_SYS_IO_Printf("\n");
  SEGGER_SYS_IO_Printf("%s    www.segger.com\n", SSL_GetCopyrightText());
  SEGGER_SYS_IO_Printf("emSSL ROT13 Client ");
  SEGGER_SYS_IO_Printf("compiled " __DATE__ " " __TIME__ "\n\n");
  //
  // Open a plain socket to the server.
  //
  Socket = SEGGER_SYS_IP_Open(ROT13_SERVER, ROT13_PORT);
  if (Socket < 0) {
    SEGGER_SYS_IO_Printf("Cannot open %s:%d!\n", ROT13_SERVER, ROT13_PORT);
    SEGGER_SYS_OS_Halt(100);
  }
  //
  // Upgrade the connection to secure by negotiating a
  // session using SSL.
  //
  SSL_SESSION_Prepare(&Session, Socket, &_IP_Transport);
  if (SSL_SESSION_Connect(&Session, ROT13_SERVER) < 0) {
    SEGGER_SYS_IO_Printf("Cannot negotiate a secure connection to %s:%d!\n",
                         ROT13_SERVER, ROT13_PORT);
    SEGGER_SYS_OS_Halt(100);
  }
  //
  // We have established a secure connection, so send the server
  // some data.
  //
  _RequestROT13(&Session, "SEGGER - The Embedded Experts\n");
  _RequestROT13(&Session, "FRTTRE - Gur Rzorqqrq Rkcregf\n");
  _RequestROT13(&Session, "SEGGER - It simply works!\n");
  _RequestROT13(&Session, "FRTTRE - Vg fvzcyl jbexf!\n");
  //
  // Close the SSL connection.
  //
  SSL_SESSION_Disconnect(&Session);
  SEGGER_SYS_IP_Close(Socket);
  //
  // Finish up.
  //
  SSL_Exit();
  SEGGER_SYS_IP_Exit();
  SEGGER_SYS_OS_PauseBeforeHalt();
  SEGGER_SYS_OS_Halt(0);
}

/*************************** End of file ****************************/

Certificates

SSL uses a Public Key Infrastructure (PKI) to provide a chain of trust. The links in the chain are X.509 certificates which provide a trusted chain from the server’s certificate to a root, trusted certificate.

It’s beyond the scope of this document to describe how to acquire a certificate for a server hosted on the Internet, but we do describe how you integrate these certificates into emSSL such that your server can function securely on the Internet.

You will need to install a certificates when:

Types of certificate

There are three types of certificate that a Internet-facing server can provide:

You need to install certificates appropriate to the key agreement schemes that your server is configured to support.

RSA certificates are by far the most common type of public key certificate in use on servers today: certificate authorities issue them and they are universally accepted. There are arguments for and against both DSA and ECDSA certificates, and you should take some time to understand the advantages, disadvantages, and potential hazards with these.

Note

We recommend that you use RSA certificates when configuring emSSL to avoid any potential incompatibilities with SSL clients. It is beyond the scope of this document to describe the merits of RSA certificates as opposed to DSA and ECDSA certificates.

Self-signed certificates

In the following sections, we will describe how to configure emSSL with certificates by using OpenSSL to create self-signed certificates. A self-signed certificate has no chain of trust to a well-known certificate authority, it stands by itself, which is a great advantage when testing out emSSL: you don’t have to wait for a CA to issue you a certificate for testing.

Using a self-signed certificate for a web server, on an intranet or on the Internet, will cause warnings from all good web browsers. You’ll typically be asked whether you want to trust the connection by accepting the certificate. For servers that you don’t control, you would decline the certificate, but for your own test servers, it’s just fine to accept the certificate that you created and signed.

Creating certificates using OpenSSL

OpenSSL has the ability to generate X.509 certificates in multiple formats. This section describes how to use OpenSSL to create self-signed certificates that you can install into emSSL when running emSSL as a TLS server.

OpenSSL comes preinstalled on Mac OS X and with many Linux distributions. You may wish to use Windows binaries, in which case you will find appropriate information here:

https://www.openssl.org/related/binaries.html

We describe how to use OpenSSL using Mac OS X, but the steps are the same on Linux and Windows.

Creating RSA certificates

The process for creating an RSA certificate has two steps:

Generate the private key

First, generate a private RSA key file. The private key file contains the generated RSA private key for signing and the public key for signature verification and in this example we request a modulus length of 2048 bits:

MacBook:~ paul$ openssl genrsa -out rsakey.pem 2048
Generating RSA private key, 2048 bit long modulus
...+++
..................................+++
e is 65537 (0x10001)
MacBook:~ paul$ _

The file rsakey.pem contains an unencrypted private key that is used for signing combined with an unencrypted public key that is used for signature verification. Longer key sizes (with larger moduli) offer increased security. The recommendation at the time of publication is to use an RSA modulus of no less than 1024 bits, with 2048 bits being preferred.

Generate the certificate

We combine the public key from the key file, together with identity information, into a self-signed certificate for emSSL:

MacBook:~ paul$ openssl req -new -x509 -key rsakey.pem -outform DER -out rsacert.der
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:DE
State or Province Name (full name) [Some-State]:Nordrhein-Westfalen
Locality Name (eg, city) []:Hilden
Organization Name (eg, company) [Internet Widgits Pty Ltd]:SEGGER Microcontroller
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:emssl.segger.com
Email Address []:
MacBook:~ paul$ _

The file rsacert.der is a self-signed DER-encoded certificate that needs to be installed into the emSSL server, covered in Installing certificates and keys.

Prepare the private keys

Now we need to prepare the corresponding private key that the server will use to sign data during key exchange. The RSA keys were written in PEM format, but must be presented in DER format, so we need to convert them:

MacBook:~ paul$ openssl rsa -in rsakey.pem -outform DER -out rsakey.der
writing RSA key
MacBook:~ paul$ _

The file rsakey.der is a DER-encoded private key that needs to be installed into the emSSL server, covered in Installing certificates and keys.

Creating DSA certificates

The process of generating a DSA certificate is similar to generating an RSA certificate except that DSA has the ability to share domain parameters between users. We won’t discuss this particular feature here, we will simply explain what you need to do in order to create a DSA certificate.

Generate the private key

First, generate a private DSA key file which is a two-stage process:

First, ask OpenSSL to generate a set of DSA parameters using a strong 2048-bit prime:

MacBook:~ paul$ openssl dsaparam -out dsaparam.pem 2048
Generating DSA parameters, 2048 bit long prime
This could take some time
.......................+++++++++++++++++++++++++++++++++++++++++++++++++++*
.+.........+..+.........+.....+...+......+...++++++++++++++++++++++++++++++
+++++++++++++++++++++*
MacBook:~ paul$ _

This generates a set of DSA parameters that can be shared between users. In this case we will not be sharing the parameters, but they are still required to generate the private key. As with RSA, security scales with the length of the key.

Note

The emSSL DSA implementation follows the NIST standard which means that key lengths are limited: 1024, 2048, and 3072 bits. Sizes other than this will result in key files and certificates that are unusable, signaled by error statuses returned by the emSSL API.

Next, generate a DSA private key file. The private key file contains the private key for signing:

MacBook:~ paul$ openssl gendsa -out dsakey.pem dsaparam.pem
Generating DSA key, 2048 bits
MacBook:~ paul$ _

The file dsakey.pem now contains an unencrypted private key that can be used for signing.

Generate the certificate

We wrap the private key from the key file, together with identity information, to generate a self-signed certificate for emSSL:

MacBook:~ paul$ openssl req -new -x509-nodes -key dsakey.pem -outform DER
-out dsacert.der
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:DE
State or Province Name (full name) [Some-State]:Nordrhein-Westfalen
Locality Name (eg, city) []:Hilden
Organization Name (eg, company) [Internet Widgits Pty Ltd]:SEGGER Microcontroller
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:emssl.segger.com
Email Address []:
MacBook:~ paul$ _

The file dsacert.der is a self-signed DER-encoded certificate that needs to be installed into the emSSL server, covered in Installing certificates and keys.

Prepare the private keys

Now we need to prepare the DSA private key that the server will use to sign data during key exchange. The DSA keys were written in PEM format, but need to be presented in DER format, so we must convert them:

MacBook:~ paul$ openssl dsa -in dsakey.pem -outform DER -out dsakey.der
writing RSA key
MacBook:~ paul$ _

The file dsakey.der is a DER-encoded private key that needs to be installed into the emSSL server, covered in Installing certificates and keys.

Creating ECDSA certificates

The process of generating an ECDSA certificate is similar to generating an RSA certificate; no, this is not a mistake, the OpenSSL steps look more like RSA than DSA. The technical difference between ECDSA and DSA is the mathematical basis that underpins the signature and verification algorithms and the choice of key parameters.

Generate the private key

First, generate a private ECDSA key file using a strong 224-bit curve:

MacBook:~ paul$ openssl ecparam -out ecparam.pem -name secp224r1 -genkey
MacBook:~ paul$ _

This generates a set of ECDSA parameters with key.

The curves that are common to emSSL and OpenSSL are:

Both emSSL and OpenSSL support more curves than this, but the NIST curves have the advantage that they are standardized (however only three curves are common to both implementations).

Generate the certificate

We wrap the private key from the key file, together with identity information, to generate a self-signed certificate for emSSL:

MacBook:~ paul$ openssl req -new -x509 -nodes -key eckey.pem -outform DER -out eccert.der
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:DE
State or Province Name (full name) [Some-State]:Nordrhein-Westfalen
Locality Name (eg, city) []:Hilden
Organization Name (eg, company) [Internet Widgits Pty Ltd]:SEGGER Microcontroller
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:emssl.segger.com
Email Address []:
MacBook:~ paul$ _

The file eccert.der is a self-signed DER-encoded certificate that needs to be installed into the emSSL server, covered in Installing certificates and keys.

Prepare the private keys

Now we need to prepare the ECDSA private key that the server will use to sign data during key exchange. The ECDSA keys were written in PEM format, but need to be presented in DER format, so we must convert them:

MacBook:~ paul$ openssl ec -in eckey.pem -outform DER -out eckey.der
read EC key
writing EC key
MacBook:~ paul$

The file eckey.der is a DER-encoded private key that needs to be installed into the emSSL server, covered in Installing certificates and keys.

Installing certificates and keys

Once you have generated your certificates and keys in DER format, you must install them into emSSL. Typically you would store these such that they can be replaced just before they expire, for example on a file system managed by emFile. For simplicity, in this example, we will embed the RSA certificate and private key into the application as read-only arrays.

Installing a single RSA certificate and key

The SEGGER utility Bin2C supplied with emSSL will take a file and convert it to a C array:

C:> bin2c rsacert.der rsacert
C:> bin2c rsakey.der rsakey
C:> _

After running this command, the file rsacert.h contains a C array declaration and the file rsacert.c contains the corresponding definition:

/*
  C-file generated by Bin2C
  Compiled:    Aug  8 2014 at 14:50:47

  Copyright (C) 2013
  Segger Microcontroller GmbH & Co. KG
  www.segger.com

  Solutions for real time microcontroller applications
*/

static const unsigned char _rsacert[1352UL + 1] = {
  0x30, 0x82, 0x05, 0x44, 0x30, 0x82, 0x05, 0x02, 0xA0, 0x03, 0x02, 0x01, 0x02,
  ...

To integrate certificate and private key into emSSL, you provide an implementation for the certificate API. The certificate API has three functions that you must provide, one for certificate verification, one for retrieving a certificate, and one for retrieving the certificate’s private key:

static const SSL_CERTIFCATE_API _CertificateAPI = {
  NULL, /* Use default certificate verification */
  _GetCertificate,
  _GetPrivateKey,
};

In this example, we have a single RSA self-signed certificate and, therefore, we can only support key exchanges using RSA cipher suites. The implementation of the certificate function is straightforward:

static int _GetCertificate(SSL_SESSION * pSession,
                           unsigned      Index,
                           const U8   ** ppData,
                           unsigned    * pLen) {
  //
  // We only support a single self-signed certificate and
  // corresponding private key.
  //
  if (Index == 0) {
    *ppData = rsacert_file;
    *pLen   = RSACERT_SIZE;
    return 0;
  } else {
    *ppData = 0;
    *pLen   = 0;
    return -1;
  }
}

And so is the corresponding private key:

static int _GetPrivateKey(SSL_SESSION * pSession,
                          const U8   ** ppData,
                          unsigned    * pDataLen) {
  //
  // We only support a single self-signed certificate and
  // corresponding private key.
  //
  *ppData   = rsakey_file;
  *pDataLen = RSAKEY_SIZE;
  return 0;
}

The certificate API needs to be set for each session individually using SSL_SESSION_SetCertificateAPI:

SSL_SESSION_SetCertificateAPI(&Session, &_CertificateAPI);

Installing multiple certificate types

Because emSSL supports different key agreement protocols, it may well be necessary for you to install more than one type of certificate. In this case, the certificate that emSSL will serve will depend upon the cipher suite that is agreed between the client and server.

The two most common key agreement protocols in use today use RSA and Elliptic Curve Diffie-Hellman (to provide forward secrecy). For elliptic curve suites, you must provide an elliptic curve certificate and use a corresponding private key.

When emSSL asks for a certificate, you can examine the cipher suite that has been agreed, and propose a certificate to use:

static int _GetCertificate(SSL_SESSION * pSession,
                           unsigned      Index,
                           const U8   ** ppData,
                           unsigned    * pLen) {
  //
  // We support a self-signed certificate and corresponding
  // private key in two forms.
  //
  if (Index == 0) {
    if (SSL_SUITE_QueryRequiresECC(SSL_SESSION_GetSuite(pSession))) {
      *ppData = eccert_file;
      *pLen   = ECCERT_SIZE;
    } else {
      *ppData = rsacert_file;
      *pLen   = RSACERT_SIZE;
    }
    return 0;
  } else {
    *ppData = 0;
    *pLen   = 0;
    return -1;
  }
}

The same is true for the corresponding private key:

static int _GetPrivateKey(SSL_SESSION * pSession,
                          const U8   ** ppData,
                          unsigned    * pDataLen) {
  //
  // We support a self-signed certificate and corresponding
  // private key in two forms.
  //
  if (SSL_SUITE_QueryRequiresECC(SSL_SESSION_GetSuite(pSession))) {
    *ppData   = eckey_file;
    *pDataLen = ECKEY_SIZE;
  } else {
    *ppData   = rsakey_file;
    *pDataLen = RSAKEY_SIZE;
  }
  //
  return 0;
}

Installing root certificates

In order to authenticate the host that you are connecting to, the SSL server provides a certificate chain that has a trusted root. It’s common for web browsers to ship with a set of trusted roots which are automatically trusted when encountered.

By default emSSL has an empty trust store. To install trusted root certificates you must acquire these from the certificate authorities that you trust and use the PrintCert utility to convert the DER or PEM certificate to something that can be added to emSSL.

The file Sample/Config/SSL/SSL_X_TrustedCerts.c contains some preconverted root certificates from GeoTrust, GlobalSign, and VeriSign that are added to emSSL when running sample applications.

Note

We highly recommended that you source and convert your own selection of root certificates.

Example

The following shows how to convert a root certificate to a form that can be added to emSSL:

MacBook:~ paul$ PrintCert GeoTrust_Primary_CA.pem -p \
> SSL_CERTIFICATE_GeoTrust_Primary_CA >SSL_X_TrustedCerts.c

(c) 2015-2016 SEGGER Microcontroller GmbH & Co. KG    www.segger.com
emSSL PrintCert V2.30 compiled Aug  2 2016 22:00:12

Subject: GeoTrust Primary Certification Authority
Issuer:  GeoTrust Primary Certification Authority

MacBook:~ paul$ _

Certificate conversion utility reference

The certificate conversion utility converts a PEM or DER certificate to a form usable by emSSL.

Usage

PrintCert.exe [<Options>] <file>

emSSL PrintCert accepts the following command line options:

Option Description
-x Declare object with external storage.
-p string Set the object name prefix to string. Default is empty.

API reference

This chapter explains the API functions of emSSL which are needed for secure communication. The emSSL API is kept as simple as possible to provide a straightforward way to integrate emSSL into a product.

Preprocessor symbols

Version number

Description

Symbol expands to a number that identifies the specific emSSL release.

Definition

#define SSL_VERSION    25801

Symbols

Definition Description
SSL_VERSION Format is “Mmmrr” so, for example, 25401 corresponds to version 2.54a.

Cipher suite IDs

Description

Official IANA names for cipher suites, but using emSSL’s “SSL” prefix rather than “TLS”.

Definition

#define SSL_SUITE_ID_NULL_WITH_NULL_NULL                          0x0000
#define SSL_SUITE_ID_RSA_WITH_NULL_MD5                            0x0001
#define SSL_SUITE_ID_RSA_WITH_NULL_SHA                            0x0002
#define SSL_SUITE_ID_RSA_EXPORT_WITH_RC4_40_MD5                   0x0003
#define SSL_SUITE_ID_RSA_WITH_RC4_128_MD5                         0x0004
#define SSL_SUITE_ID_RSA_WITH_RC4_128_SHA                         0x0005
#define SSL_SUITE_ID_RSA_EXPORT_WITH_RC2_CBC_40_MD5               0x0006
#define SSL_SUITE_ID_RSA_WITH_IDEA_CBC_SHA                        0x0007
#define SSL_SUITE_ID_RSA_EXPORT_WITH_DES40_CBC_SHA                0x0008
#define SSL_SUITE_ID_RSA_WITH_DES_CBC_SHA                         0x0009
#define SSL_SUITE_ID_RSA_WITH_3DES_EDE_CBC_SHA                    0x000A
#define SSL_SUITE_ID_DH_DSS_EXPORT_WITH_DES40_CBC_SHA             0x000B
#define SSL_SUITE_ID_DH_DSS_WITH_DES_CBC_SHA                      0x000C
#define SSL_SUITE_ID_DH_DSS_WITH_3DES_EDE_CBC_SHA                 0x000D
#define SSL_SUITE_ID_DH_RSA_EXPORT_WITH_DES40_CBC_SHA             0x000E
#define SSL_SUITE_ID_DH_RSA_WITH_DES_CBC_SHA                      0x000F
#define SSL_SUITE_ID_DH_RSA_WITH_3DES_EDE_CBC_SHA                 0x0010
#define SSL_SUITE_ID_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA            0x0011
#define SSL_SUITE_ID_DHE_DSS_WITH_DES_CBC_SHA                     0x0012
#define SSL_SUITE_ID_DHE_DSS_WITH_3DES_EDE_CBC_SHA                0x0013
#define SSL_SUITE_ID_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA            0x0014
#define SSL_SUITE_ID_DHE_RSA_WITH_DES_CBC_SHA                     0x0015
#define SSL_SUITE_ID_DHE_RSA_WITH_3DES_EDE_CBC_SHA                0x0016
#define SSL_SUITE_ID_DH_anon_EXPORT_WITH_RC4_40_MD5               0x0017
#define SSL_SUITE_ID_DH_anon_WITH_RC4_128_MD5                     0x0018
#define SSL_SUITE_ID_DH_anon_EXPORT_WITH_DES40_CBC_SHA            0x0019
#define SSL_SUITE_ID_DH_anon_WITH_DES_CBC_SHA                     0x001A
#define SSL_SUITE_ID_DH_anon_WITH_3DES_EDE_CBC_SHA                0x001B
#define SSL_SUITE_ID_KRB5_WITH_DES_CBC_SHA                        0x001E
#define SSL_SUITE_ID_KRB5_WITH_3DES_EDE_CBC_SHA                   0x001F
#define SSL_SUITE_ID_KRB5_WITH_RC4_128_SHA                        0x0020
#define SSL_SUITE_ID_KRB5_WITH_IDEA_CBC_SHA                       0x0021
#define SSL_SUITE_ID_KRB5_WITH_DES_CBC_MD5                        0x0022
#define SSL_SUITE_ID_KRB5_WITH_3DES_EDE_CBC_MD5                   0x0023
#define SSL_SUITE_ID_KRB5_WITH_RC4_128_MD5                        0x0024
#define SSL_SUITE_ID_KRB5_WITH_IDEA_CBC_MD5                       0x0025
#define SSL_SUITE_ID_KRB5_EXPORT_WITH_DES_CBC_40_SHA              0x0026
#define SSL_SUITE_ID_KRB5_EXPORT_WITH_RC2_CBC_40_SHA              0x0027
#define SSL_SUITE_ID_KRB5_EXPORT_WITH_RC4_40_SHA                  0x0028
#define SSL_SUITE_ID_KRB5_EXPORT_WITH_DES_CBC_40_MD5              0x0029
#define SSL_SUITE_ID_KRB5_EXPORT_WITH_RC2_CBC_40_MD5              0x002A
#define SSL_SUITE_ID_KRB5_EXPORT_WITH_RC4_40_MD5                  0x002B
#define SSL_SUITE_ID_PSK_WITH_NULL_SHA                            0x002C
#define SSL_SUITE_ID_DHE_PSK_WITH_NULL_SHA                        0x002D
#define SSL_SUITE_ID_RSA_PSK_WITH_NULL_SHA                        0x002E
#define SSL_SUITE_ID_RSA_WITH_AES_128_CBC_SHA                     0x002F
#define SSL_SUITE_ID_DH_DSS_WITH_AES_128_CBC_SHA                  0x0030
#define SSL_SUITE_ID_DH_RSA_WITH_AES_128_CBC_SHA                  0x0031
#define SSL_SUITE_ID_DHE_DSS_WITH_AES_128_CBC_SHA                 0x0032
#define SSL_SUITE_ID_DHE_RSA_WITH_AES_128_CBC_SHA                 0x0033
#define SSL_SUITE_ID_DH_anon_WITH_AES_128_CBC_SHA                 0x0034
#define SSL_SUITE_ID_RSA_WITH_AES_256_CBC_SHA                     0x0035
#define SSL_SUITE_ID_DH_DSS_WITH_AES_256_CBC_SHA                  0x0036
#define SSL_SUITE_ID_DH_RSA_WITH_AES_256_CBC_SHA                  0x0037
#define SSL_SUITE_ID_DHE_DSS_WITH_AES_256_CBC_SHA                 0x0038
#define SSL_SUITE_ID_DHE_RSA_WITH_AES_256_CBC_SHA                 0x0039
#define SSL_SUITE_ID_DH_anon_WITH_AES_256_CBC_SHA                 0x003A
#define SSL_SUITE_ID_RSA_WITH_NULL_SHA256                         0x003B
#define SSL_SUITE_ID_RSA_WITH_AES_128_CBC_SHA256                  0x003C
#define SSL_SUITE_ID_RSA_WITH_AES_256_CBC_SHA256                  0x003D
#define SSL_SUITE_ID_DH_DSS_WITH_AES_128_CBC_SHA256               0x003E
#define SSL_SUITE_ID_DH_RSA_WITH_AES_128_CBC_SHA256               0x003F
#define SSL_SUITE_ID_DHE_DSS_WITH_AES_128_CBC_SHA256              0x0040
#define SSL_SUITE_ID_RSA_WITH_CAMELLIA_128_CBC_SHA                0x0041
#define SSL_SUITE_ID_DH_DSS_WITH_CAMELLIA_128_CBC_SHA             0x0042
#define SSL_SUITE_ID_DH_RSA_WITH_CAMELLIA_128_CBC_SHA             0x0043
#define SSL_SUITE_ID_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA            0x0044
#define SSL_SUITE_ID_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA            0x0045
#define SSL_SUITE_ID_DH_anon_WITH_CAMELLIA_128_CBC_SHA            0x0046
#define SSL_SUITE_ID_DHE_RSA_WITH_AES_128_CBC_SHA256              0x0067
#define SSL_SUITE_ID_DH_DSS_WITH_AES_256_CBC_SHA256               0x0068
#define SSL_SUITE_ID_DH_RSA_WITH_AES_256_CBC_SHA256               0x0069
#define SSL_SUITE_ID_DHE_DSS_WITH_AES_256_CBC_SHA256              0x006A
#define SSL_SUITE_ID_DHE_RSA_WITH_AES_256_CBC_SHA256              0x006B
#define SSL_SUITE_ID_DH_anon_WITH_AES_128_CBC_SHA256              0x006C
#define SSL_SUITE_ID_DH_anon_WITH_AES_256_CBC_SHA256              0x006D
#define SSL_SUITE_ID_RSA_WITH_CAMELLIA_256_CBC_SHA                0x0084
#define SSL_SUITE_ID_DH_DSS_WITH_CAMELLIA_256_CBC_SHA             0x0085
#define SSL_SUITE_ID_DH_RSA_WITH_CAMELLIA_256_CBC_SHA             0x0086
#define SSL_SUITE_ID_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA            0x0087
#define SSL_SUITE_ID_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA            0x0088
#define SSL_SUITE_ID_DH_anon_WITH_CAMELLIA_256_CBC_SHA            0x0089
#define SSL_SUITE_ID_PSK_WITH_RC4_128_SHA                         0x008A
#define SSL_SUITE_ID_PSK_WITH_3DES_EDE_CBC_SHA                    0x008B
#define SSL_SUITE_ID_PSK_WITH_AES_128_CBC_SHA                     0x008C
#define SSL_SUITE_ID_PSK_WITH_AES_256_CBC_SHA                     0x008D
#define SSL_SUITE_ID_DHE_PSK_WITH_RC4_128_SHA                     0x008E
#define SSL_SUITE_ID_DHE_PSK_WITH_3DES_EDE_CBC_SHA                0x008F
#define SSL_SUITE_ID_DHE_PSK_WITH_AES_128_CBC_SHA                 0x0090
#define SSL_SUITE_ID_DHE_PSK_WITH_AES_256_CBC_SHA                 0x0091
#define SSL_SUITE_ID_RSA_PSK_WITH_RC4_128_SHA                     0x0092
#define SSL_SUITE_ID_RSA_PSK_WITH_3DES_EDE_CBC_SHA                0x0093
#define SSL_SUITE_ID_RSA_PSK_WITH_AES_128_CBC_SHA                 0x0094
#define SSL_SUITE_ID_RSA_PSK_WITH_AES_256_CBC_SHA                 0x0095
#define SSL_SUITE_ID_RSA_WITH_SEED_CBC_SHA                        0x0096
#define SSL_SUITE_ID_DH_DSS_WITH_SEED_CBC_SHA                     0x0097
#define SSL_SUITE_ID_DH_RSA_WITH_SEED_CBC_SHA                     0x0098
#define SSL_SUITE_ID_DHE_DSS_WITH_SEED_CBC_SHA                    0x0099
#define SSL_SUITE_ID_DHE_RSA_WITH_SEED_CBC_SHA                    0x009A
#define SSL_SUITE_ID_DH_anon_WITH_SEED_CBC_SHA                    0x009B
#define SSL_SUITE_ID_RSA_WITH_AES_128_GCM_SHA256                  0x009C
#define SSL_SUITE_ID_RSA_WITH_AES_256_GCM_SHA384                  0x009D
#define SSL_SUITE_ID_DHE_RSA_WITH_AES_128_GCM_SHA256              0x009E
#define SSL_SUITE_ID_DHE_RSA_WITH_AES_256_GCM_SHA384              0x009F
#define SSL_SUITE_ID_DH_RSA_WITH_AES_128_GCM_SHA256               0x00A0
#define SSL_SUITE_ID_DH_RSA_WITH_AES_256_GCM_SHA384               0x00A1
#define SSL_SUITE_ID_DHE_DSS_WITH_AES_128_GCM_SHA256              0x00A2
#define SSL_SUITE_ID_DHE_DSS_WITH_AES_256_GCM_SHA384              0x00A3
#define SSL_SUITE_ID_DH_DSS_WITH_AES_128_GCM_SHA256               0x00A4
#define SSL_SUITE_ID_DH_DSS_WITH_AES_256_GCM_SHA384               0x00A5
#define SSL_SUITE_ID_DH_anon_WITH_AES_128_GCM_SHA256              0x00A6
#define SSL_SUITE_ID_DH_anon_WITH_AES_256_GCM_SHA384              0x00A7
#define SSL_SUITE_ID_PSK_WITH_AES_128_GCM_SHA256                  0x00A8
#define SSL_SUITE_ID_PSK_WITH_AES_256_GCM_SHA384                  0x00A9
#define SSL_SUITE_ID_DHE_PSK_WITH_AES_128_GCM_SHA256              0x00AA
#define SSL_SUITE_ID_DHE_PSK_WITH_AES_256_GCM_SHA384              0x00AB
#define SSL_SUITE_ID_RSA_PSK_WITH_AES_128_GCM_SHA256              0x00AC
#define SSL_SUITE_ID_RSA_PSK_WITH_AES_256_GCM_SHA384              0x00AD
#define SSL_SUITE_ID_PSK_WITH_AES_128_CBC_SHA256                  0x00AE
#define SSL_SUITE_ID_PSK_WITH_AES_256_CBC_SHA384                  0x00AF
#define SSL_SUITE_ID_PSK_WITH_NULL_SHA256                         0x00B0
#define SSL_SUITE_ID_PSK_WITH_NULL_SHA384                         0x00B1
#define SSL_SUITE_ID_DHE_PSK_WITH_AES_128_CBC_SHA256              0x00B2
#define SSL_SUITE_ID_DHE_PSK_WITH_AES_256_CBC_SHA384              0x00B3
#define SSL_SUITE_ID_DHE_PSK_WITH_NULL_SHA256                     0x00B4
#define SSL_SUITE_ID_DHE_PSK_WITH_NULL_SHA384                     0x00B5
#define SSL_SUITE_ID_RSA_PSK_WITH_AES_128_CBC_SHA256              0x00B6
#define SSL_SUITE_ID_RSA_PSK_WITH_AES_256_CBC_SHA384              0x00B7
#define SSL_SUITE_ID_RSA_PSK_WITH_NULL_SHA256                     0x00B8
#define SSL_SUITE_ID_RSA_PSK_WITH_NULL_SHA384                     0x00B9
#define SSL_SUITE_ID_RSA_WITH_CAMELLIA_128_CBC_SHA256             0x00BA
#define SSL_SUITE_ID_DH_DSS_WITH_CAMELLIA_128_CBC_SHA256          0x00BB
#define SSL_SUITE_ID_DH_RSA_WITH_CAMELLIA_128_CBC_SHA256          0x00BC
#define SSL_SUITE_ID_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA256         0x00BD
#define SSL_SUITE_ID_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256         0x00BE
#define SSL_SUITE_ID_DH_anon_WITH_CAMELLIA_128_CBC_SHA256         0x00BF
#define SSL_SUITE_ID_RSA_WITH_CAMELLIA_256_CBC_SHA256             0x00C0
#define SSL_SUITE_ID_DH_DSS_WITH_CAMELLIA_256_CBC_SHA256          0x00C1
#define SSL_SUITE_ID_DH_RSA_WITH_CAMELLIA_256_CBC_SHA256          0x00C2
#define SSL_SUITE_ID_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA256         0x00C3
#define SSL_SUITE_ID_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA256         0x00C4
#define SSL_SUITE_ID_DH_anon_WITH_CAMELLIA_256_CBC_SHA256         0x00C5
#define SSL_SUITE_ID_EMPTY_RENEGOTIATION_INFO_SCSV                0x00FF
#define SSL_SUITE_ID_AES_128_GCM_SHA256                           0x1301
#define SSL_SUITE_ID_AES_256_GCM_SHA384                           0x1302
#define SSL_SUITE_ID_CHACHA20_POLY1305_SHA256                     0x1303
#define SSL_SUITE_ID_AES_128_CCM_SHA256                           0x1304
#define SSL_SUITE_ID_AES_128_CCM_8_SHA256                         0x1305
#define SSL_SUITE_ID_FALLBACK_SCSV                                0x5600
#define SSL_SUITE_ID_ECDH_ECDSA_WITH_NULL_SHA                     0xC001
#define SSL_SUITE_ID_ECDH_ECDSA_WITH_RC4_128_SHA                  0xC002
#define SSL_SUITE_ID_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA             0xC003
#define SSL_SUITE_ID_ECDH_ECDSA_WITH_AES_128_CBC_SHA              0xC004
#define SSL_SUITE_ID_ECDH_ECDSA_WITH_AES_256_CBC_SHA              0xC005
#define SSL_SUITE_ID_ECDHE_ECDSA_WITH_NULL_SHA                    0xC006
#define SSL_SUITE_ID_ECDHE_ECDSA_WITH_RC4_128_SHA                 0xC007
#define SSL_SUITE_ID_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA            0xC008
#define SSL_SUITE_ID_ECDHE_ECDSA_WITH_AES_128_CBC_SHA             0xC009
#define SSL_SUITE_ID_ECDHE_ECDSA_WITH_AES_256_CBC_SHA             0xC00A
#define SSL_SUITE_ID_ECDH_RSA_WITH_NULL_SHA                       0xC00B
#define SSL_SUITE_ID_ECDH_RSA_WITH_RC4_128_SHA                    0xC00C
#define SSL_SUITE_ID_ECDH_RSA_WITH_3DES_EDE_CBC_SHA               0xC00D
#define SSL_SUITE_ID_ECDH_RSA_WITH_AES_128_CBC_SHA                0xC00E
#define SSL_SUITE_ID_ECDH_RSA_WITH_AES_256_CBC_SHA                0xC00F
#define SSL_SUITE_ID_ECDHE_RSA_WITH_NULL_SHA                      0xC010
#define SSL_SUITE_ID_ECDHE_RSA_WITH_RC4_128_SHA                   0xC011
#define SSL_SUITE_ID_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA              0xC012
#define SSL_SUITE_ID_ECDHE_RSA_WITH_AES_128_CBC_SHA               0xC013
#define SSL_SUITE_ID_ECDHE_RSA_WITH_AES_256_CBC_SHA               0xC014
#define SSL_SUITE_ID_ECDH_anon_WITH_NULL_SHA                      0xC015
#define SSL_SUITE_ID_ECDH_anon_WITH_RC4_128_SHA                   0xC016
#define SSL_SUITE_ID_ECDH_anon_WITH_3DES_EDE_CBC_SHA              0xC017
#define SSL_SUITE_ID_ECDH_anon_WITH_AES_128_CBC_SHA               0xC018
#define SSL_SUITE_ID_ECDH_anon_WITH_AES_256_CBC_SHA               0xC019
#define SSL_SUITE_ID_SRP_SHA_WITH_3DES_EDE_CBC_SHA                0xC01A
#define SSL_SUITE_ID_SRP_SHA_RSA_WITH_3DES_EDE_CBC_SHA            0xC01B
#define SSL_SUITE_ID_SRP_SHA_DSS_WITH_3DES_EDE_CBC_SHA            0xC01C
#define SSL_SUITE_ID_SRP_SHA_WITH_AES_128_CBC_SHA                 0xC01D
#define SSL_SUITE_ID_SRP_SHA_RSA_WITH_AES_128_CBC_SHA             0xC01E
#define SSL_SUITE_ID_SRP_SHA_DSS_WITH_AES_128_CBC_SHA             0xC01F
#define SSL_SUITE_ID_SRP_SHA_WITH_AES_256_CBC_SHA                 0xC020
#define SSL_SUITE_ID_SRP_SHA_RSA_WITH_AES_256_CBC_SHA             0xC021
#define SSL_SUITE_ID_SRP_SHA_DSS_WITH_AES_256_CBC_SHA             0xC022
#define SSL_SUITE_ID_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256          0xC023
#define SSL_SUITE_ID_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384          0xC024
#define SSL_SUITE_ID_ECDH_ECDSA_WITH_AES_128_CBC_SHA256           0xC025
#define SSL_SUITE_ID_ECDH_ECDSA_WITH_AES_256_CBC_SHA384           0xC026
#define SSL_SUITE_ID_ECDHE_RSA_WITH_AES_128_CBC_SHA256            0xC027
#define SSL_SUITE_ID_ECDHE_RSA_WITH_AES_256_CBC_SHA384            0xC028
#define SSL_SUITE_ID_ECDH_RSA_WITH_AES_128_CBC_SHA256             0xC029
#define SSL_SUITE_ID_ECDH_RSA_WITH_AES_256_CBC_SHA384             0xC02A
#define SSL_SUITE_ID_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256          0xC02B
#define SSL_SUITE_ID_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384          0xC02C
#define SSL_SUITE_ID_ECDH_ECDSA_WITH_AES_128_GCM_SHA256           0xC02D
#define SSL_SUITE_ID_ECDH_ECDSA_WITH_AES_256_GCM_SHA384           0xC02E
#define SSL_SUITE_ID_ECDHE_RSA_WITH_AES_128_GCM_SHA256            0xC02F
#define SSL_SUITE_ID_ECDHE_RSA_WITH_AES_256_GCM_SHA384            0xC030
#define SSL_SUITE_ID_ECDH_RSA_WITH_AES_128_GCM_SHA256             0xC031
#define SSL_SUITE_ID_ECDH_RSA_WITH_AES_256_GCM_SHA384             0xC032
#define SSL_SUITE_ID_ECDHE_PSK_WITH_RC4_128_SHA                   0xC033
#define SSL_SUITE_ID_ECDHE_PSK_WITH_3DES_EDE_CBC_SHA              0xC034
#define SSL_SUITE_ID_ECDHE_PSK_WITH_AES_128_CBC_SHA               0xC035
#define SSL_SUITE_ID_ECDHE_PSK_WITH_AES_256_CBC_SHA               0xC036
#define SSL_SUITE_ID_ECDHE_PSK_WITH_AES_128_CBC_SHA256            0xC037
#define SSL_SUITE_ID_ECDHE_PSK_WITH_AES_256_CBC_SHA384            0xC038
#define SSL_SUITE_ID_ECDHE_PSK_WITH_NULL_SHA                      0xC039
#define SSL_SUITE_ID_ECDHE_PSK_WITH_NULL_SHA256                   0xC03A
#define SSL_SUITE_ID_ECDHE_PSK_WITH_NULL_SHA384                   0xC03B
#define SSL_SUITE_ID_RSA_WITH_ARIA_128_CBC_SHA256                 0xC03C
#define SSL_SUITE_ID_RSA_WITH_ARIA_256_CBC_SHA384                 0xC03D
#define SSL_SUITE_ID_DH_DSS_WITH_ARIA_128_CBC_SHA256              0xC03E
#define SSL_SUITE_ID_DH_DSS_WITH_ARIA_256_CBC_SHA384              0xC03F
#define SSL_SUITE_ID_DH_RSA_WITH_ARIA_128_CBC_SHA256              0xC040
#define SSL_SUITE_ID_DH_RSA_WITH_ARIA_256_CBC_SHA384              0xC041
#define SSL_SUITE_ID_DHE_DSS_WITH_ARIA_128_CBC_SHA256             0xC042
#define SSL_SUITE_ID_DHE_DSS_WITH_ARIA_256_CBC_SHA384             0xC043
#define SSL_SUITE_ID_DHE_RSA_WITH_ARIA_128_CBC_SHA256             0xC044
#define SSL_SUITE_ID_DHE_RSA_WITH_ARIA_256_CBC_SHA384             0xC045
#define SSL_SUITE_ID_DH_anon_WITH_ARIA_128_CBC_SHA256             0xC046
#define SSL_SUITE_ID_DH_anon_WITH_ARIA_256_CBC_SHA384             0xC047
#define SSL_SUITE_ID_ECDHE_ECDSA_WITH_ARIA_128_CBC_SHA256         0xC048
#define SSL_SUITE_ID_ECDHE_ECDSA_WITH_ARIA_256_CBC_SHA384         0xC049
#define SSL_SUITE_ID_ECDH_ECDSA_WITH_ARIA_128_CBC_SHA256          0xC04A
#define SSL_SUITE_ID_ECDH_ECDSA_WITH_ARIA_256_CBC_SHA384          0xC04B
#define SSL_SUITE_ID_ECDHE_RSA_WITH_ARIA_128_CBC_SHA256           0xC04C
#define SSL_SUITE_ID_ECDHE_RSA_WITH_ARIA_256_CBC_SHA384           0xC04D
#define SSL_SUITE_ID_ECDH_RSA_WITH_ARIA_128_CBC_SHA256            0xC04E
#define SSL_SUITE_ID_ECDH_RSA_WITH_ARIA_256_CBC_SHA384            0xC04F
#define SSL_SUITE_ID_RSA_WITH_ARIA_128_GCM_SHA256                 0xC050
#define SSL_SUITE_ID_RSA_WITH_ARIA_256_GCM_SHA384                 0xC051
#define SSL_SUITE_ID_DHE_RSA_WITH_ARIA_128_GCM_SHA256             0xC052
#define SSL_SUITE_ID_DHE_RSA_WITH_ARIA_256_GCM_SHA384             0xC053
#define SSL_SUITE_ID_DH_RSA_WITH_ARIA_128_GCM_SHA256              0xC054
#define SSL_SUITE_ID_DH_RSA_WITH_ARIA_256_GCM_SHA384              0xC055
#define SSL_SUITE_ID_DHE_DSS_WITH_ARIA_128_GCM_SHA256             0xC056
#define SSL_SUITE_ID_DHE_DSS_WITH_ARIA_256_GCM_SHA384             0xC057
#define SSL_SUITE_ID_DH_DSS_WITH_ARIA_128_GCM_SHA256              0xC058
#define SSL_SUITE_ID_DH_DSS_WITH_ARIA_256_GCM_SHA384              0xC059
#define SSL_SUITE_ID_DH_anon_WITH_ARIA_128_GCM_SHA256             0xC05A
#define SSL_SUITE_ID_DH_anon_WITH_ARIA_256_GCM_SHA384             0xC05B
#define SSL_SUITE_ID_ECDHE_ECDSA_WITH_ARIA_128_GCM_SHA256         0xC05C
#define SSL_SUITE_ID_ECDHE_ECDSA_WITH_ARIA_256_GCM_SHA384         0xC05D
#define SSL_SUITE_ID_ECDH_ECDSA_WITH_ARIA_128_GCM_SHA256          0xC05E
#define SSL_SUITE_ID_ECDH_ECDSA_WITH_ARIA_256_GCM_SHA384          0xC05F
#define SSL_SUITE_ID_ECDHE_RSA_WITH_ARIA_128_GCM_SHA256           0xC060
#define SSL_SUITE_ID_ECDHE_RSA_WITH_ARIA_256_GCM_SHA384           0xC061
#define SSL_SUITE_ID_ECDH_RSA_WITH_ARIA_128_GCM_SHA256            0xC062
#define SSL_SUITE_ID_ECDH_RSA_WITH_ARIA_256_GCM_SHA384            0xC063
#define SSL_SUITE_ID_PSK_WITH_ARIA_128_CBC_SHA256                 0xC064
#define SSL_SUITE_ID_PSK_WITH_ARIA_256_CBC_SHA384                 0xC065
#define SSL_SUITE_ID_DHE_PSK_WITH_ARIA_128_CBC_SHA256             0xC066
#define SSL_SUITE_ID_DHE_PSK_WITH_ARIA_256_CBC_SHA384             0xC067
#define SSL_SUITE_ID_RSA_PSK_WITH_ARIA_128_CBC_SHA256             0xC068
#define SSL_SUITE_ID_RSA_PSK_WITH_ARIA_256_CBC_SHA384             0xC069
#define SSL_SUITE_ID_PSK_WITH_ARIA_128_GCM_SHA256                 0xC06A
#define SSL_SUITE_ID_PSK_WITH_ARIA_256_GCM_SHA384                 0xC06B
#define SSL_SUITE_ID_DHE_PSK_WITH_ARIA_128_GCM_SHA256             0xC06C
#define SSL_SUITE_ID_DHE_PSK_WITH_ARIA_256_GCM_SHA384             0xC06D
#define SSL_SUITE_ID_RSA_PSK_WITH_ARIA_128_GCM_SHA256             0xC06E
#define SSL_SUITE_ID_RSA_PSK_WITH_ARIA_256_GCM_SHA384             0xC06F
#define SSL_SUITE_ID_ECDHE_PSK_WITH_ARIA_128_CBC_SHA256           0xC070
#define SSL_SUITE_ID_ECDHE_PSK_WITH_ARIA_256_CBC_SHA384           0xC071
#define SSL_SUITE_ID_ECDHE_ECDSA_WITH_CAMELLIA_128_CBC_SHA256     0xC072
#define SSL_SUITE_ID_ECDHE_ECDSA_WITH_CAMELLIA_256_CBC_SHA384     0xC073
#define SSL_SUITE_ID_ECDH_ECDSA_WITH_CAMELLIA_128_CBC_SHA256      0xC074
#define SSL_SUITE_ID_ECDH_ECDSA_WITH_CAMELLIA_256_CBC_SHA384      0xC075
#define SSL_SUITE_ID_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256       0xC076
#define SSL_SUITE_ID_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384       0xC077
#define SSL_SUITE_ID_ECDH_RSA_WITH_CAMELLIA_128_CBC_SHA256        0xC078
#define SSL_SUITE_ID_ECDH_RSA_WITH_CAMELLIA_256_CBC_SHA384        0xC079
#define SSL_SUITE_ID_RSA_WITH_CAMELLIA_128_GCM_SHA256             0xC07A
#define SSL_SUITE_ID_RSA_WITH_CAMELLIA_256_GCM_SHA384             0xC07B
#define SSL_SUITE_ID_DHE_RSA_WITH_CAMELLIA_128_GCM_SHA256         0xC07C
#define SSL_SUITE_ID_DHE_RSA_WITH_CAMELLIA_256_GCM_SHA384         0xC07D
#define SSL_SUITE_ID_DH_RSA_WITH_CAMELLIA_128_GCM_SHA256          0xC07E
#define SSL_SUITE_ID_DH_RSA_WITH_CAMELLIA_256_GCM_SHA384          0xC07F
#define SSL_SUITE_ID_DHE_DSS_WITH_CAMELLIA_128_GCM_SHA256         0xC080
#define SSL_SUITE_ID_DHE_DSS_WITH_CAMELLIA_256_GCM_SHA384         0xC081
#define SSL_SUITE_ID_DH_DSS_WITH_CAMELLIA_128_GCM_SHA256          0xC082
#define SSL_SUITE_ID_DH_DSS_WITH_CAMELLIA_256_GCM_SHA384          0xC083
#define SSL_SUITE_ID_DH_anon_WITH_CAMELLIA_128_GCM_SHA256         0xC084
#define SSL_SUITE_ID_DH_anon_WITH_CAMELLIA_256_GCM_SHA384         0xC085
#define SSL_SUITE_ID_ECDHE_ECDSA_WITH_CAMELLIA_128_GCM_SHA256     0xC086
#define SSL_SUITE_ID_ECDHE_ECDSA_WITH_CAMELLIA_256_GCM_SHA384     0xC087
#define SSL_SUITE_ID_ECDH_ECDSA_WITH_CAMELLIA_128_GCM_SHA256      0xC088
#define SSL_SUITE_ID_ECDH_ECDSA_WITH_CAMELLIA_256_GCM_SHA384      0xC089
#define SSL_SUITE_ID_ECDHE_RSA_WITH_CAMELLIA_128_GCM_SHA256       0xC08A
#define SSL_SUITE_ID_ECDHE_RSA_WITH_CAMELLIA_256_GCM_SHA384       0xC08B
#define SSL_SUITE_ID_ECDH_RSA_WITH_CAMELLIA_128_GCM_SHA256        0xC08C
#define SSL_SUITE_ID_ECDH_RSA_WITH_CAMELLIA_256_GCM_SHA384        0xC08D
#define SSL_SUITE_ID_PSK_WITH_CAMELLIA_128_GCM_SHA256             0xC08E
#define SSL_SUITE_ID_PSK_WITH_CAMELLIA_256_GCM_SHA384             0xC08F
#define SSL_SUITE_ID_DHE_PSK_WITH_CAMELLIA_128_GCM_SHA256         0xC090
#define SSL_SUITE_ID_DHE_PSK_WITH_CAMELLIA_256_GCM_SHA384         0xC091
#define SSL_SUITE_ID_RSA_PSK_WITH_CAMELLIA_128_GCM_SHA256         0xC092
#define SSL_SUITE_ID_RSA_PSK_WITH_CAMELLIA_256_GCM_SHA384         0xC093
#define SSL_SUITE_ID_PSK_WITH_CAMELLIA_128_CBC_SHA256             0xC094
#define SSL_SUITE_ID_PSK_WITH_CAMELLIA_256_CBC_SHA384             0xC095
#define SSL_SUITE_ID_DHE_PSK_WITH_CAMELLIA_128_CBC_SHA256         0xC096
#define SSL_SUITE_ID_DHE_PSK_WITH_CAMELLIA_256_CBC_SHA384         0xC097
#define SSL_SUITE_ID_RSA_PSK_WITH_CAMELLIA_128_CBC_SHA256         0xC098
#define SSL_SUITE_ID_RSA_PSK_WITH_CAMELLIA_256_CBC_SHA384         0xC099
#define SSL_SUITE_ID_ECDHE_PSK_WITH_CAMELLIA_128_CBC_SHA256       0xC09A
#define SSL_SUITE_ID_ECDHE_PSK_WITH_CAMELLIA_256_CBC_SHA384       0xC09B
#define SSL_SUITE_ID_RSA_WITH_AES_128_CCM                         0xC09C
#define SSL_SUITE_ID_RSA_WITH_AES_256_CCM                         0xC09D
#define SSL_SUITE_ID_DHE_RSA_WITH_AES_128_CCM                     0xC09E
#define SSL_SUITE_ID_DHE_RSA_WITH_AES_256_CCM                     0xC09F
#define SSL_SUITE_ID_RSA_WITH_AES_128_CCM_8                       0xC0A0
#define SSL_SUITE_ID_RSA_WITH_AES_256_CCM_8                       0xC0A1
#define SSL_SUITE_ID_DHE_RSA_WITH_AES_128_CCM_8                   0xC0A2
#define SSL_SUITE_ID_DHE_RSA_WITH_AES_256_CCM_8                   0xC0A3
#define SSL_SUITE_ID_PSK_WITH_AES_128_CCM                         0xC0A4
#define SSL_SUITE_ID_PSK_WITH_AES_256_CCM                         0xC0A5
#define SSL_SUITE_ID_DHE_PSK_WITH_AES_128_CCM                     0xC0A6
#define SSL_SUITE_ID_DHE_PSK_WITH_AES_256_CCM                     0xC0A7
#define SSL_SUITE_ID_PSK_WITH_AES_128_CCM_8                       0xC0A8
#define SSL_SUITE_ID_PSK_WITH_AES_256_CCM_8                       0xC0A9
#define SSL_SUITE_ID_PSK_DHE_WITH_AES_128_CCM_8                   0xC0AA
#define SSL_SUITE_ID_PSK_DHE_WITH_AES_256_CCM_8                   0xC0AB
#define SSL_SUITE_ID_ECDHE_ECDSA_WITH_AES_128_CCM                 0xC0AC
#define SSL_SUITE_ID_ECDHE_ECDSA_WITH_AES_256_CCM                 0xC0AD
#define SSL_SUITE_ID_ECDHE_ECDSA_WITH_AES_128_CCM_8               0xC0AE
#define SSL_SUITE_ID_ECDHE_ECDSA_WITH_AES_256_CCM_8               0xC0AF
#define SSL_SUITE_ID_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256      0xCCA8
#define SSL_SUITE_ID_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256    0xCCA9
#define SSL_SUITE_ID_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256        0xCCAA

Session flags

Description

Flags set by the user or by emSSL.

Definition

#define SSL_SESSION_FLAG_REQUEST_CERTIFICATE                    0x0001u
#define SSL_SESSION_FLAG_CERTIFICATE_RECEIVED                   0x0002u
#define SSL_SESSION_FLAG_CERTIFICATE_REQUEST_RECEIVED           0x0004u
#define SSL_SESSION_FLAG_CERTIFICATE_SENT                       0x0008u
#define SSL_SESSION_FLAG_REQUEST_RESUME_SESSION_ID              0x0010u
#define SSL_SESSION_FLAG_REQUEST_RESUME_SESSION_TICKET          0x0020u
#define SSL_SESSION_FLAG_REQUEST_RESUME_CRITICAL                0x0040u
#define SSL_SESSION_FLAG_RESUME_GRANTED                         0x0080u
#define SSL_SESSION_FLAG_DISABLE_SESSION_TICKET                 0x0100u
#define SSL_SESSION_FLAG_SESSION_TICKET_EXPECTED                0x0200u
#define SSL_SESSION_FLAG_SESSION_TICKET_EXTENSION_ADVERTISED    0x0400u
#define SSL_SESSION_FLAG_SESSION_TICKET_RECEIVED                0x0800u
#define SSL_SESSION_FLAG_DISABLE_RSA_PMS_VERSION_CHECK          0x1000u
#define SSL_SESSION_FLAG_REQUEST_PREVENT_FALLBACK               0x2000u
#define SSL_SESSION_FLAG_PREFER_SERVER_ORDER                    0x4000u
#define SSL_SESSION_FLAG_REQUIRE_STRICT_TLS_CLOSE               0x8000u

Symbols

Definition Description
SSL_SESSION_FLAG_REQUEST_CERTIFICATE Set by user: emSSL Server must request a client certificate for mutual authentication.
SSL_SESSION_FLAG_CERTIFICATE_RECEIVED Set by emSSL: Client provided a valid certificate to emSSL server.
SSL_SESSION_FLAG_CERTIFICATE_REQUEST_RECEIVED Set by emSSL: Server requested certificate, if we have one.
SSL_SESSION_FLAG_CERTIFICATE_SENT Set by emSSL: Client sent a valid certificate as we have one.
SSL_SESSION_FLAG_REQUEST_RESUME_SESSION_ID Set by emSSL: Indicates session resumption is requested by session ID.
SSL_SESSION_FLAG_REQUEST_RESUME_SESSION_TICKET Set by emSSL: Indicates session resumption is requested by session ticket.
SSL_SESSION_FLAG_REQUEST_RESUME_CRITICAL Set by user: If session resumption is requested, it is critical that a session is resumed (no new session offered). If not, fail.
SSL_SESSION_FLAG_RESUME_GRANTED Set by emSSL: After connection completes, indicates that a session is successfully resumed.
SSL_SESSION_FLAG_DISABLE_SESSION_TICKET Set by user: Do not use session ticket even if configured.
SSL_SESSION_FLAG_SESSION_TICKET_EXPECTED Set by emSSL: The client knows the server supports session tickets.
SSL_SESSION_FLAG_SESSION_TICKET_EXTENSION_ADVERTISED Set by emSSL: The server indicates its willingness to issue session tickets.
SSL_SESSION_FLAG_SESSION_TICKET_RECEIVED Set by emSSL: The client has received a session ticket.
SSL_SESSION_FLAG_DISABLE_RSA_PMS_VERSION_CHECK Set by user: Disable TLS 1.0 version check [TLS1v2 https://tools.ietf.org/html/rfc5246#section-7.4.7.1].
SSL_SESSION_FLAG_REQUEST_PREVENT_FALLBACK Set by user: Request Fallback SCSV signaling cipher suite [RFC7507 https://tools.ietf.org/html/rfc7507].
SSL_SESSION_FLAG_PREFER_SERVER_ORDER Set by user: Prefer the server’s cipher suite order to the client’s preferred order.
SSL_SESSION_FLAG_REQUIRE_STRICT_TLS_CLOSE Set by user: Require a TLS close-notify from peer to close the session.

Logging flags

Description

Flags that control log output.

Definition

#define SSL_LOG_ERROR           (1uL <<  0)
#define SSL_LOG_RECORD          (1uL <<  1)
#define SSL_LOG_SIGNATURES      (1uL <<  2)
#define SSL_LOG_CERTIFICATES    (1uL <<  3)
#define SSL_LOG_VERIFY_DATA     (1uL <<  4)
#define SSL_LOG_STATES          (1uL <<  5)
#define SSL_LOG_KEYS            (1uL <<  6)
#define SSL_LOG_CIPHER          (1uL <<  7)
#define SSL_LOG_SOCKET_SEND     (1uL <<  8)
#define SSL_LOG_SOCKET_RECV     (1uL <<  9)
#define SSL_LOG_SUITES          (1uL << 10)
#define SSL_LOG_PRF             (1uL << 11)
#define SSL_LOG_HANDSHAKE       (1uL << 12)
#define SSL_LOG_MESSAGES        (1uL << 13)
#define SSL_LOG_CONFIG          (1uL << 14)
#define SSL_LOG_ALERT           (1uL << 15)
#define SSL_LOG_APP             (1uL << 31)

Symbols

Definition Description
SSL_LOG_ERROR Log all error status returns generated by emSSL.
SSL_LOG_RECORD Log record-layer protocol details.
SSL_LOG_SIGNATURES Log signature operations.
SSL_LOG_CERTIFICATES Log certificate-related information; usually used in conjunction with SSL_LOG_SIGNATURES.
SSL_LOG_VERIFY_DATA Log verification data; usually used in conjunction with SSL_LOG_HANDSHAKE.
SSL_LOG_STATES Log SSL state machine transitions.
SSL_LOG_KEYS Log key derivation for session bulk encryption keys; usually used in conjunction with SSL_LOG_CRYPTO.
SSL_LOG_CIPHER Log cipher encryption and decryption.
SSL_LOG_SOCKET_SEND Log raw data sent over an SSL connection.
SSL_LOG_SOCKET_RECV Log raw data received over an SSL connection.
SSL_LOG_SUITES Log agreed SSL cipher suite.
SSL_LOG_PRF Log inputs and outputs of the SSL PRF function.
SSL_LOG_HANDSHAKE Log data contributing to the SSL handshake when computing verification data.
SSL_LOG_MESSAGES Log decoded SSL messages.
SSL_LOG_CONFIG Log emSSL configuration on startup.
SSL_LOG_ALERT Log received alert messages.
SSL_LOG_APP Log application messages.

Additional information

Flags are added using SSL_AddLogFilter() and removed using SSL_RemoveLogFilter().

Warning flags

Description

Flags that control warning output.

Definition

#define SSL_WARN_CRYPTO     (1uL << 0)
#define SSL_WARN_IGNORE     (1uL << 1)
#define SSL_WARN_X509       (1uL << 2)
#define SSL_WARN_CONFIG     (1uL << 3)
#define SSL_WARN_TICKETS    (1uL << 4)

Symbols

Definition Description
SSL_WARN_CRYPTO Warn on cryptography-related errors such as bad message formatting or bad key parameters.
SSL_WARN_IGNORE Warn on purposely-ignored nonfatal conditions, such as SSL extensions that are not recognized by the current emSSL implementation which allow forward compatibility with TLS specifications.
SSL_WARN_X509 Warn on nonfatal X.509 certificate issues identified by emSSL which allow forward compatibility with new X.509 capabilities.
SSL_WARN_CONFIG Warn on configuration issues on startup.
SSL_WARN_TICKETS Warn on session ticket problems.

Additional information

Flags are added using SSL_AddWarnFilter() and removed using SSL_RemoveWarnFilter().

Information functions

The table below lists the functions that return emSSL information.

Function Description
SSL_GetVersionText() Get emSSL version as printable string.
SSL_GetCopyrightText() Get emSSL copyright as printable string.

SSL_GetVersionText()

Description

Get emSSL version as printable string.

Prototype

char *SSL_GetVersionText(void);

Return value

Zero-terminated version string.

SSL_GetCopyrightText()

Description

Get emSSL copyright as printable string.

Prototype

char *SSL_GetCopyrightText(void);

Return value

Zero-terminated copyright string.

Control functions

The table below lists the functions provided by the emSSL API. Detailed description of each function is found in the sections that follow.

Function Description
SSL_Exit() Finalize the SSL module.
SSL_Init() Initialize the SSL module.

SSL_Exit()

Description

Finalize the SSL module.

Prototype

void SSL_Exit(void);

Additional information

This function deinitializes the SSL module. Once finalized, no further calls must be made to the emSSL API.

SSL_Init()

Description

Initialize the SSL module.

Prototype

void SSL_Init(void);

Additional information

Before using an SSL service, you must call SSL_Init. As part of SSL initialization, emSSL ensures that the shared CRYPTO component is initialized.

Configuration functions

The table below lists the functions that configure emSSL for operation.

Function Description
SSL_CIPHER_Add() Add cipher to emSSL.
SSL_CLIENT_ConfigMutualAuth() Support mutual authentication, client mode.
SSL_CURVE_Add() Add elliptic curve to emSSL.
SSL_CURVE_Remove() Remove an elliptic curve.
SSL_CURVE_GetName() Return the standard name for an elliptic curve.
SSL_MAC_Add() Add MAC support to emSSL.
SSL_MEM_Add() Add memory to emSSL.
SSL_MEM_ConfigSystem() Configure the SSL memory allocator to use the C system heap.
SSL_MEM_GetContext() Get the default memory allocation context for the SSL module.
SSL_PROTOCOL_Add() Add TLS protocol to emSSL.
SSL_PROTOCOL_GetText() Decode the TLS protocol to a textual representation.
SSL_ROOT_CERTIFICATE_Add() Add root certificate to emSSL.
SSL_ROOT_CERTIFICATE_AddDER() Add root certificate from DER-encoded certificate.
SSL_ROOT_CERTIFICATE_LoadDER() Load root certificate from DER-encoded certificate.
SSL_SetDefaultCertificateAPI() Set default certificate API used by all SSL connections.
SSL_SERVER_ConfigMutualAuth() Support mutual authentication, server mode.
SSL_SIGNATURE_ALGORITHM_Add() Add signature algorithm to emSSL.
SSL_SIGNATURE_SIGN_Add() Add signature signer to emSSL.
SSL_SIGNATURE_VERIFY_Add() Add signature verifier to emSSL.
SSL_SUITE_Add() Add cipher suite to emSSL.

SSL_CIPHER_Add()

Description

Add cipher to emSSL.

Prototype

void SSL_CIPHER_Add(const SSL_CIPHER_API * pAPI);

Parameters

Parameter Description
pAPI Cipher API to add.

Additional information

Adds a bulk cipher to emSSL in support of cipher suites. This function must only be called during emSSL configuration.

Implemented ciphers

The following ciphers are provided by emSSL:

extern const SSL_CIPHER_API SSL_CIPHER_AES_128_CBC_API;
extern const SSL_CIPHER_API SSL_CIPHER_AES_256_CBC_API;
extern const SSL_CIPHER_API SSL_CIPHER_AES_128_GCM_API;
extern const SSL_CIPHER_API SSL_CIPHER_AES_256_GCM_API;
extern const SSL_CIPHER_API SSL_CIPHER_AES_128_CCM_API;
extern const SSL_CIPHER_API SSL_CIPHER_AES_256_CCM_API;
extern const SSL_CIPHER_API SSL_CIPHER_AES_128_CCM_8_API;
extern const SSL_CIPHER_API SSL_CIPHER_AES_256_CCM_8_API;
extern const SSL_CIPHER_API SSL_CIPHER_ARIA_128_CBC_API;
extern const SSL_CIPHER_API SSL_CIPHER_ARIA_256_CBC_API;
extern const SSL_CIPHER_API SSL_CIPHER_ARIA_128_GCM_API;
extern const SSL_CIPHER_API SSL_CIPHER_ARIA_256_GCM_API;
extern const SSL_CIPHER_API SSL_CIPHER_CAMELLIA_128_CBC_API;
extern const SSL_CIPHER_API SSL_CIPHER_CAMELLIA_256_CBC_API;
extern const SSL_CIPHER_API SSL_CIPHER_CAMELLIA_128_GCM_API;
extern const SSL_CIPHER_API SSL_CIPHER_CAMELLIA_256_GCM_API;
extern const SSL_CIPHER_API SSL_CIPHER_SEED_CBC_API;
extern const SSL_CIPHER_API SSL_CIPHER_DES_CBC_API;
extern const SSL_CIPHER_API SSL_CIPHER_3DES_EDE_CBC_API;
extern const SSL_CIPHER_API SSL_CIPHER_RC4_128_API;
extern const SSL_CIPHER_API SSL_CIPHER_CHACHA20_POLY1305_API;

See also

Adding ciphers.

SSL_CLIENT_ConfigMutualAuth()

Description

Support mutual authentication, client mode.

Prototype

void SSL_CLIENT_ConfigMutualAuth(void);

Additional information

This function adds support for mutual authentication for connections operating in client mode, i.e. to answer with a client certificate when the server requests one.

SSL_CURVE_Add()

Description

Add elliptic curve to emSSL.

Prototype

void SSL_CURVE_Add(const SSL_CURVE * pCurve);

Parameters

Parameter Description
pCurve Pointer to curve.

Additional information

Adds a single elliptic curve that will be offered by the server when using elliptic curve suites.

When agreeing cipher suites and parsing ECDSA certificates, both sides must support a common elliptic curve which defines the appropriate security. When parsing ECDSA certificates, you must ensure that appropriate elliptic curves are registered in order to extract and use the enclosed public keys.

Implemented curves

The following curves are provided by emSSL:

extern const SSL_CURVE SSL_CURVE_secp192k1;
extern const SSL_CURVE SSL_CURVE_secp192r1;
extern const SSL_CURVE SSL_CURVE_secp224k1;
extern const SSL_CURVE SSL_CURVE_secp224r1;
extern const SSL_CURVE SSL_CURVE_secp256k1;
extern const SSL_CURVE SSL_CURVE_secp256r1;
extern const SSL_CURVE SSL_CURVE_secp384r1;
extern const SSL_CURVE SSL_CURVE_secp521r1;
extern const SSL_CURVE SSL_CURVE_brainpoolP256r1;
extern const SSL_CURVE SSL_CURVE_brainpoolP384r1;
extern const SSL_CURVE SSL_CURVE_brainpoolP512r1;
extern const SSL_CURVE SSL_CURVE_Curve25519;

Although the underlying crypgraphic algorithm library offers more curves, the SSL protocol only supports a subset of all standardized elliptic curves.

See also

Adding elliptic curves.

SSL_CURVE_Remove()

Description

Remove an elliptic curve.

Prototype

void SSL_CURVE_Remove(const SSL_CURVE * pCurve);

Parameters

Parameter Description
pCurve Pointer to curve.

Additional information

Removes a single elliptic curve from the list of supported curves.

SSL_CURVE_GetName()

Description

Return the standard name for an elliptic curve.

Prototype

char *SSL_CURVE_GetName(unsigned ID);

Parameters

Parameter Description
ID SSL named curve ID.

Return value

Curve name or “UNKNOWN” if the curve ID is not known.

SSL_MAC_Add()

Description

Add MAC support to emSSL.

Prototype

void SSL_MAC_Add(const SSL_MAC_API * pAPI);

Parameters

Parameter Description
pAPI MAC API to add.

Additional information

Adds a hash/HMAC algorithm to emSSL in support of cipher suites.

Implemented MACs

The following hash/HMAC algorithms are provided by emSSL:

extern const SSL_MAC_API SSL_MAC_MD5_API;
extern const SSL_MAC_API SSL_MAC_SHA_API;
extern const SSL_MAC_API SSL_MAC_SHA224_API;
extern const SSL_MAC_API SSL_MAC_SHA256_API;
extern const SSL_MAC_API SSL_MAC_SHA384_API;
extern const SSL_MAC_API SSL_MAC_SHA512_API;

See also

Adding MACs.

SSL_MEM_Add()

Description

Add memory to emSSL.

Prototype

void SSL_MEM_Add(void     * pStore,
                 unsigned   NumBytesStore);

Parameters

Parameter Description
pStore Pointer to the first byte of memory to be added. This must be correctly aligned for the processor and compiler combination.
NumBytesStore Number of bytes in memory block.

Additional information

This function must be called a maximum of one time to add memory to emSSL. Once the memory is added, the heap implementation that manages it is selected. If emSSL is to use the C system heap, this function should not be called.

See also

RAM use.

SSL_MEM_ConfigSystem()

Description

Configure the SSL memory allocator to use the C system heap.

Prototype

void SSL_MEM_ConfigSystem(void);

Additional information

This function sets emSSL’s allocator to utilize the C system heap through calls to malloc(), free(), and realloc(). For workstation-class machines or PCs, where memory is plentiful, this allocator suffices.

If emSSL uses the C system heap, SSL_MEM_Add() must not be called.

SSL_MEM_GetContext()

Description

Get the default memory allocation context for the SSL module.

Prototype

void SSL_MEM_GetContext(SEGGER_MEM_CONTEXT ** ppMem);

Parameters

Parameter Description
ppMem Assigned pointer to default memory context.

SSL_PROTOCOL_Add()

Description

Add TLS protocol to emSSL.

Prototype

void SSL_PROTOCOL_Add(const SSL_PROTOCOL_API * pAPI);

Parameters

Parameter Description
pAPI Protocol API to add.

Additional information

Adds a single TLS protocol to emSSL.

Implemented protocols

The following protocols are provided by emSSL:

extern const SSL_PROTOCOL_API SSL_PROTOCOL_TLS1v0_API;
extern const SSL_PROTOCOL_API SSL_PROTOCOL_TLS1v1_API;
extern const SSL_PROTOCOL_API SSL_PROTOCOL_TLS1v2_API;

See also

Adding TLS protocols

SSL_PROTOCOL_GetText()

Description

Decode the TLS protocol to a textual representation.

Prototype

char *SSL_PROTOCOL_GetText(U16 Protocol);

Parameters

Parameter Description
Protocol TLS protocol ID.

Return value

Nonzero pointer to the protocol name.

SSL_ROOT_CERTIFICATE_Add()

Description

Add root certificate to emSSL.

Prototype

void SSL_ROOT_CERTIFICATE_Add(SSL_ROOT_CERTIFICATE * pCert);

Parameters

Parameter Description
pCert Pointer to certificate to add as a trusted root.

See also

Installing root certificates.

SSL_ROOT_CERTIFICATE_AddDER()

Description

Add root certificate from DER-encoded certificate.

Prototype

int SSL_ROOT_CERTIFICATE_AddDER(const U8       * pData,
                                      unsigned   DataLen);

Parameters

Parameter Description
pData Pointer to DER-encoded certificate data.
DataLen Octet length of the DER-encoded certificate data.

Return value

≥ 0 Certificate successfully loaded.
< 0 Error loading certificate.

Additional information

The DER-encoded certificate length must be exactly DataLen octets in size: data beyond the end of the valid DER-encoded certificate is not ignored and is considered an error.

SSL_ROOT_CERTIFICATE_LoadDER()

Description

Load root certificate from DER-encoded certificate.

Prototype

int SSL_ROOT_CERTIFICATE_LoadDER(      SSL_ROOT_CERTIFICATE * pRootCert,
                                 const U8                   * pData,
                                       unsigned               DataLen);

Parameters

Parameter Description
pRootCert Pointer to object that receives the root certificate.
pData Pointer to DER-encoded certificate data.
DataLen Octet length of the DER-encoded certificate data.

Return value

≥ 0 Certificate successfully loaded.
< 0 Error loading certificate.

Additional information

The DER-encoded certificate length must be exactly DataLen octets in size: data beyond the end of the valid DER-encoded certificate is not ignored and is considered an error.

SSL_SERVER_ConfigMutualAuth()

Description

Support mutual authentication, server mode.

Prototype

void SSL_SERVER_ConfigMutualAuth(void);

Additional information

This function adds support for mutual authentication for connections operating in server mode, i.e. to ask the for a certificate when the server requires one from the client.

Note that you must add server mutual authentication support if you intend to set the flag SSL_SESSION_FLAG_REQUEST_CERTIFICATE in server mode.

See also

SSL_SESSION_SetFlags.

SSL_SetDefaultCertificateAPI()

Description

Set default certificate API used by all SSL connections.

Prototype

void SSL_SetDefaultCertificateAPI(const SSL_CERTIFICATE_API * pAPI);

Parameters

Parameter Description
pAPI Pointer to certificate API that will be used by default for new connections.

Additional information

This function sets the default certificate API to use when establishing a connection. The default certificate API can be overridden on a per-session basis using the function SSL_SESSION_SetCertificateAPI().

SSL_SIGNATURE_ALGORITHM_Add()

Description

Add signature algorithm to emSSL.

Prototype

void SSL_SIGNATURE_ALGORITHM_Add(unsigned ID);

Parameters

Parameter Description
ID Signature algorithm to add.

Additional information

Adds a signature algorithm to emSSL in order to advertise it when negotiating a connection.

Implemented signature algorithms

The following signature algorithms are provided by emSSL:

RSA

SSL_SIGNATURE_MD5_WITH_RSA_ENCRYPTION
SSL_SIGNATURE_SHA_WITH_RSA_ENCRYPTION
SSL_SIGNATURE_SHA224_WITH_RSA_ENCRYPTION
SSL_SIGNATURE_SHA256_WITH_RSA_ENCRYPTION
SSL_SIGNATURE_SHA384_WITH_RSA_ENCRYPTION
SSL_SIGNATURE_SHA512_WITH_RSA_ENCRYPTION

DSA

SSL_SIGNATURE_SHA_WITH_DSA

ECDSA

SSL_SIGNATURE_SHA_WITH_ECDSA
SSL_SIGNATURE_SHA224_WITH_ECDSA
SSL_SIGNATURE_SHA256_WITH_ECDSA
SSL_SIGNATURE_SHA384_WITH_ECDSA
SSL_SIGNATURE_SHA512_WITH_ECDSA

See also

Adding signature algorithms.

SSL_SIGNATURE_SIGN_Add()

Description

Add signature signer to emSSL.

Prototype

void SSL_SIGNATURE_SIGN_Add(const SSL_SIGNATURE_SIGN_API * pAPI);

Parameters

Parameter Description
pAPI Signature signer API to add.

Additional information

Adds a signature signer to emSSL in support of cipher suites.

Implemented message signers

The following message signers are provided by emSSL:

extern const SSL_SIGNATURE_SIGN_API SSL_SIGNATURE_SIGN_RSA_API;
extern const SSL_SIGNATURE_SIGN_API SSL_SIGNATURE_SIGN_ECDSA_API;

See also

Adding public key message signers.

SSL_SIGNATURE_VERIFY_Add()

Description

Add signature verifier to emSSL.

Prototype

void SSL_SIGNATURE_VERIFY_Add(const SSL_SIGNATURE_VERIFY_API * pAPI);

Parameters

Parameter Description
pAPI Signature verification API to add.

Additional information

Adds a signature verifier to emSSL in support of cipher suites.

Implemented signature verifiers

The following signature verifiers are provided by emSSL:

extern const SSL_SIGNATURE_VERIFY_API SSL_SIGNATURE_VERIFY_RSA_API;
extern const SSL_SIGNATURE_VERIFY_API SSL_SIGNATURE_VERIFY_DSA_API;
extern const SSL_SIGNATURE_VERIFY_API SSL_SIGNATURE_VERIFY_ECDSA_API;

See also

Adding public key signature verifiers.

SSL_SUITE_Add()

Description

Add cipher suite to emSSL.

Prototype

void SSL_SUITE_Add(const SSL_SUITE * pSuite);

Parameters

Parameter Description
pSuite Pointer to cipher suite to add.

Additional information

The order in which suites are added defines the default preference order of suites in the negotiation phase of a client connection..

Implemented cipher suites

The following cipher suites are provided by emSSL:

extern const SSL_SUITE SSL_SUITE_ECDHE_ECDSA_WITH_NULL_SHA;
extern const SSL_SUITE SSL_SUITE_ECDHE_ECDSA_WITH_RC4_128_SHA;
extern const SSL_SUITE SSL_SUITE_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA;
extern const SSL_SUITE SSL_SUITE_ECDHE_ECDSA_WITH_AES_128_CBC_SHA;
extern const SSL_SUITE SSL_SUITE_ECDHE_ECDSA_WITH_AES_256_CBC_SHA;
extern const SSL_SUITE SSL_SUITE_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256;
extern const SSL_SUITE SSL_SUITE_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384;
extern const SSL_SUITE SSL_SUITE_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256;
extern const SSL_SUITE SSL_SUITE_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384;
extern const SSL_SUITE SSL_SUITE_ECDHE_ECDSA_WITH_AES_128_CCM;
extern const SSL_SUITE SSL_SUITE_ECDHE_ECDSA_WITH_AES_256_CCM;
extern const SSL_SUITE SSL_SUITE_ECDHE_ECDSA_WITH_AES_128_CCM_8;
extern const SSL_SUITE SSL_SUITE_ECDHE_ECDSA_WITH_AES_256_CCM_8;
extern const SSL_SUITE SSL_SUITE_ECDHE_ECDSA_WITH_ARIA_128_CBC_SHA256;
extern const SSL_SUITE SSL_SUITE_ECDHE_ECDSA_WITH_ARIA_256_CBC_SHA384;
extern const SSL_SUITE SSL_SUITE_ECDHE_ECDSA_WITH_ARIA_128_GCM_SHA256;
extern const SSL_SUITE SSL_SUITE_ECDHE_ECDSA_WITH_ARIA_256_GCM_SHA384;
extern const SSL_SUITE SSL_SUITE_ECDHE_ECDSA_WITH_CAMELLIA_128_CBC_SHA256;
extern const SSL_SUITE SSL_SUITE_ECDHE_ECDSA_WITH_CAMELLIA_256_CBC_SHA384;
extern const SSL_SUITE SSL_SUITE_ECDHE_ECDSA_WITH_CAMELLIA_128_GCM_SHA256;
extern const SSL_SUITE SSL_SUITE_ECDHE_ECDSA_WITH_CAMELLIA_256_GCM_SHA384;
extern const SSL_SUITE SSL_SUITE_ECDHE_RSA_WITH_NULL_SHA;
extern const SSL_SUITE SSL_SUITE_ECDHE_RSA_WITH_RC4_128_SHA;
extern const SSL_SUITE SSL_SUITE_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA;
extern const SSL_SUITE SSL_SUITE_ECDHE_RSA_WITH_AES_128_CBC_SHA;
extern const SSL_SUITE SSL_SUITE_ECDHE_RSA_WITH_AES_256_CBC_SHA;
extern const SSL_SUITE SSL_SUITE_ECDHE_RSA_WITH_AES_128_CBC_SHA256;
extern const SSL_SUITE SSL_SUITE_ECDHE_RSA_WITH_AES_128_GCM_SHA256;
extern const SSL_SUITE SSL_SUITE_ECDHE_RSA_WITH_AES_256_CBC_SHA384;
extern const SSL_SUITE SSL_SUITE_ECDHE_RSA_WITH_AES_256_GCM_SHA384;
extern const SSL_SUITE SSL_SUITE_ECDHE_RSA_WITH_ARIA_128_CBC_SHA256;
extern const SSL_SUITE SSL_SUITE_ECDHE_RSA_WITH_ARIA_128_GCM_SHA256;
extern const SSL_SUITE SSL_SUITE_ECDHE_RSA_WITH_ARIA_256_CBC_SHA384;
extern const SSL_SUITE SSL_SUITE_ECDHE_RSA_WITH_ARIA_256_GCM_SHA384;
extern const SSL_SUITE SSL_SUITE_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256;
extern const SSL_SUITE SSL_SUITE_ECDHE_RSA_WITH_CAMELLIA_128_GCM_SHA256;
extern const SSL_SUITE SSL_SUITE_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384;
extern const SSL_SUITE SSL_SUITE_ECDHE_RSA_WITH_CAMELLIA_256_GCM_SHA384;
extern const SSL_SUITE SSL_SUITE_ECDH_RSA_WITH_NULL_SHA;
extern const SSL_SUITE SSL_SUITE_ECDH_RSA_WITH_RC4_128_SHA;
extern const SSL_SUITE SSL_SUITE_ECDH_RSA_WITH_3DES_EDE_CBC_SHA;
extern const SSL_SUITE SSL_SUITE_ECDH_RSA_WITH_AES_128_CBC_SHA;
extern const SSL_SUITE SSL_SUITE_ECDH_RSA_WITH_AES_256_CBC_SHA;
extern const SSL_SUITE SSL_SUITE_ECDH_RSA_WITH_AES_128_CBC_SHA256;
extern const SSL_SUITE SSL_SUITE_ECDH_RSA_WITH_AES_128_GCM_SHA256;
extern const SSL_SUITE SSL_SUITE_ECDH_RSA_WITH_AES_256_CBC_SHA384;
extern const SSL_SUITE SSL_SUITE_ECDH_RSA_WITH_AES_256_GCM_SHA384;
extern const SSL_SUITE SSL_SUITE_ECDH_RSA_WITH_ARIA_128_CBC_SHA256;
extern const SSL_SUITE SSL_SUITE_ECDH_RSA_WITH_ARIA_128_GCM_SHA256;
extern const SSL_SUITE SSL_SUITE_ECDH_RSA_WITH_ARIA_256_CBC_SHA384;
extern const SSL_SUITE SSL_SUITE_ECDH_RSA_WITH_ARIA_256_GCM_SHA384;
extern const SSL_SUITE SSL_SUITE_ECDH_RSA_WITH_CAMELLIA_128_CBC_SHA256;
extern const SSL_SUITE SSL_SUITE_ECDH_RSA_WITH_CAMELLIA_128_GCM_SHA256;
extern const SSL_SUITE SSL_SUITE_ECDH_RSA_WITH_CAMELLIA_256_CBC_SHA384;
extern const SSL_SUITE SSL_SUITE_ECDH_RSA_WITH_CAMELLIA_256_GCM_SHA384;
extern const SSL_SUITE SSL_SUITE_ECDH_ECDSA_WITH_NULL_SHA;
extern const SSL_SUITE SSL_SUITE_ECDH_ECDSA_WITH_RC4_128_SHA;
extern const SSL_SUITE SSL_SUITE_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA;
extern const SSL_SUITE SSL_SUITE_ECDH_ECDSA_WITH_AES_128_CBC_SHA;
extern const SSL_SUITE SSL_SUITE_ECDH_ECDSA_WITH_AES_256_CBC_SHA;
extern const SSL_SUITE SSL_SUITE_ECDH_ECDSA_WITH_AES_128_CBC_SHA256;
extern const SSL_SUITE SSL_SUITE_ECDH_ECDSA_WITH_AES_128_GCM_SHA256;
extern const SSL_SUITE SSL_SUITE_ECDH_ECDSA_WITH_AES_256_CBC_SHA384;
extern const SSL_SUITE SSL_SUITE_ECDH_ECDSA_WITH_AES_256_GCM_SHA384;
extern const SSL_SUITE SSL_SUITE_ECDH_ECDSA_WITH_ARIA_128_CBC_SHA256;
extern const SSL_SUITE SSL_SUITE_ECDH_ECDSA_WITH_ARIA_128_GCM_SHA256;
extern const SSL_SUITE SSL_SUITE_ECDH_ECDSA_WITH_ARIA_256_CBC_SHA384;
extern const SSL_SUITE SSL_SUITE_ECDH_ECDSA_WITH_ARIA_256_GCM_SHA384;
extern const SSL_SUITE SSL_SUITE_ECDH_ECDSA_WITH_CAMELLIA_128_CBC_SHA256;
extern const SSL_SUITE SSL_SUITE_ECDH_ECDSA_WITH_CAMELLIA_128_GCM_SHA256;
extern const SSL_SUITE SSL_SUITE_ECDH_ECDSA_WITH_CAMELLIA_256_CBC_SHA384;
extern const SSL_SUITE SSL_SUITE_ECDH_ECDSA_WITH_CAMELLIA_256_GCM_SHA384;
extern const SSL_SUITE SSL_SUITE_DHE_RSA_WITH_3DES_EDE_CBC_SHA;
extern const SSL_SUITE SSL_SUITE_DHE_RSA_WITH_AES_128_CBC_SHA;
extern const SSL_SUITE SSL_SUITE_DHE_RSA_WITH_AES_256_CBC_SHA;
extern const SSL_SUITE SSL_SUITE_DHE_RSA_WITH_AES_128_CBC_SHA256;
extern const SSL_SUITE SSL_SUITE_DHE_RSA_WITH_AES_256_CBC_SHA256;
extern const SSL_SUITE SSL_SUITE_DHE_RSA_WITH_AES_256_GCM_SHA384;
extern const SSL_SUITE SSL_SUITE_DHE_RSA_WITH_AES_128_GCM_SHA256;
extern const SSL_SUITE SSL_SUITE_DHE_RSA_WITH_AES_128_CCM;
extern const SSL_SUITE SSL_SUITE_DHE_RSA_WITH_AES_256_CCM;
extern const SSL_SUITE SSL_SUITE_DHE_RSA_WITH_AES_128_CCM_8;
extern const SSL_SUITE SSL_SUITE_DHE_RSA_WITH_AES_256_CCM_8;
extern const SSL_SUITE SSL_SUITE_DHE_RSA_WITH_ARIA_128_CBC_SHA256;
extern const SSL_SUITE SSL_SUITE_DHE_RSA_WITH_ARIA_256_CBC_SHA384;
extern const SSL_SUITE SSL_SUITE_DHE_RSA_WITH_ARIA_128_GCM_SHA256;
extern const SSL_SUITE SSL_SUITE_DHE_RSA_WITH_ARIA_256_GCM_SHA384;
extern const SSL_SUITE SSL_SUITE_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA;
extern const SSL_SUITE SSL_SUITE_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA;
extern const SSL_SUITE SSL_SUITE_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256;
extern const SSL_SUITE SSL_SUITE_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA256;
extern const SSL_SUITE SSL_SUITE_RSA_WITH_RC4_128_MD5;
extern const SSL_SUITE SSL_SUITE_RSA_WITH_RC4_128_SHA;
extern const SSL_SUITE SSL_SUITE_RSA_WITH_3DES_EDE_CBC_SHA;
extern const SSL_SUITE SSL_SUITE_RSA_WITH_AES_128_CBC_SHA;
extern const SSL_SUITE SSL_SUITE_RSA_WITH_AES_256_CBC_SHA;
extern const SSL_SUITE SSL_SUITE_RSA_WITH_AES_128_CBC_SHA256;
extern const SSL_SUITE SSL_SUITE_RSA_WITH_AES_256_CBC_SHA256;
extern const SSL_SUITE SSL_SUITE_RSA_WITH_AES_256_GCM_SHA384;
extern const SSL_SUITE SSL_SUITE_RSA_WITH_AES_128_GCM_SHA256;
extern const SSL_SUITE SSL_SUITE_RSA_WITH_AES_128_CCM;
extern const SSL_SUITE SSL_SUITE_RSA_WITH_AES_256_CCM;
extern const SSL_SUITE SSL_SUITE_RSA_WITH_AES_128_CCM_8;
extern const SSL_SUITE SSL_SUITE_RSA_WITH_AES_256_CCM_8;
extern const SSL_SUITE SSL_SUITE_RSA_WITH_ARIA_128_CBC_SHA256;
extern const SSL_SUITE SSL_SUITE_RSA_WITH_ARIA_256_CBC_SHA384;
extern const SSL_SUITE SSL_SUITE_RSA_WITH_ARIA_128_GCM_SHA256;
extern const SSL_SUITE SSL_SUITE_RSA_WITH_ARIA_256_GCM_SHA384;
extern const SSL_SUITE SSL_SUITE_RSA_WITH_ARIA_128_GCM_SHA256;
extern const SSL_SUITE SSL_SUITE_RSA_WITH_ARIA_256_GCM_SHA384;
extern const SSL_SUITE SSL_SUITE_RSA_WITH_CAMELLIA_128_CBC_SHA;
extern const SSL_SUITE SSL_SUITE_RSA_WITH_CAMELLIA_256_CBC_SHA;
extern const SSL_SUITE SSL_SUITE_RSA_WITH_CAMELLIA_128_CBC_SHA256;
extern const SSL_SUITE SSL_SUITE_RSA_WITH_CAMELLIA_256_CBC_SHA256;
extern const SSL_SUITE SSL_SUITE_RSA_WITH_CAMELLIA_128_GCM_SHA256;
extern const SSL_SUITE SSL_SUITE_RSA_WITH_CAMELLIA_256_GCM_SHA384;

See also

Adding cipher suites.

Session control functions

The table below lists the functions that are used for SSL sessions.

Function Description
SSL_SESSION_Accept() Negotiate an SSL connection as a server.
SSL_SESSION_ClrFlags() Clear session-related flags.
SSL_SESSION_Connect() Connect to a server.
SSL_SESSION_Disconnect() Disconnect a client or server SSL connection.
SSL_SESSION_GetSuite() Retrieve the active suite for an SSL session.
SSL_SESSION_Prepare() Prepare SSL session before connection.
SSL_SESSION_Receive() Receive data over an established SSL/TLS connection.
SSL_SESSION_QueryFlags() Query session-related flags.
SSL_SESSION_Send() Send data over an established SSL/TLS connection.
SSL_SESSION_SendStr() Send null-terminated string to peer.
SSL_SESSION_SetAllowedSuites() Set the cipher suites to offer or accept for all connections.
SSL_SESSION_SetFlags() Set session-related flags.
SSL_SESSION_SetCertificateAPI() Set the API to use to handle PKI certificates and keys.
SSL_SESSION_SetProtocolRange() Set the protocol range supported by the SSL connection.

SSL_SESSION_Accept()

Description

Negotiate an SSL connection as a server.

Prototype

int SSL_SESSION_Accept(SSL_SESSION * pSelf);

Parameters

Parameter Description
pSelf Pointer to session context.

Return value

< 0 Processing error.
≥ 0 Success.

Additional information

This function attempts to negotiate an SSL connection with the SSL client. To negotiate a connection for a specific SSL version, restrict the range of supported TLS versions using SSL_SESSION_SetProtocolRange.

See also

SSL_SESSION_SetProtocolRange.

SSL_SESSION_ClrFlags()

Description

Clear session-related flags.

Prototype

void SSL_SESSION_ClrFlags(SSL_SESSION * pSelf,
                          unsigned      Flags);

Parameters

Parameter Description
pSelf Pointer to session context.
Flags Bitwise-or of flags to clear.

Additional information

This function clears session-related flags, for instance requesting that the client provides its certificate during negotiation.

This function must be called after initializing the session using SSL_SESSION_Prepare() and before making or accepting connections using SSL_SESSION_Connect() or SSL_SESSION_Accept().

SSL_SESSION_Connect()

Description

Connect to a server.

Prototype

int SSL_SESSION_Connect(      SSL_SESSION * pSelf,
                        const char        * sServerName);

Parameters

Parameter Description
pSelf Pointer to session context.
sServerName Name of server we wish to connect to.

Return value

≥ 0 Success.
< 0 Processing error.

Additional information

This function attempts to negotiate an SSL connection to the SSL server whose name is sServerName. The server name is used in the Server Name Indication extension of RFC 6066. If sServerName is the null pointer, the Server Name Indication extension is not included in the SSL handshake.

To negotiate a client connection for a specific SSL version, restrict the range of supported TLS versions using SSL_SESSION_SetProtocolRange.

See also

SSL_SESSION_SetProtocolRange.

SSL_SESSION_Disconnect()

Description

Disconnect a client or server SSL connection..

Prototype

void SSL_SESSION_Disconnect(SSL_SESSION * pSelf);

Parameters

Parameter Description
pSelf Pointer to session context.

Additional information

This function disconnects an existing client or server SSL connection with the SSL client. After disconnection, you must not attempt to send or receive data over the connection.

SSL_SESSION_GetSuite()

Description

Retrieve the active suite for an SSL session.

Prototype

SSL_SUITE *SSL_SESSION_GetSuite(SSL_SESSION * pSelf);

Parameters

Parameter Description
pSelf Pointer to session context.

Return value

Cipher suite in use (can be null if no suite is agreed).

Additional information

It is acceptable to use this function during a certificate callback in order to determine the type of certificate to return to emSSL.

SSL_SESSION_Prepare()

Description

Prepare SSL session before connection.

Prototype

void SSL_SESSION_Prepare(      SSL_SESSION       * pSelf,
                               int                 Socket,
                         const SSL_TRANSPORT_API * pAPI);

Parameters

Parameter Description
pSelf Session context to prepare.
Socket Socket ID used by the transport API.
pAPI Pointer to the transport API to use for the connection.

Additional information

This function initializes the SSL session and sets the communications API to use in order to transport SSL messages.

By default the session is initialized to support TLS 1.0 through 1.2. You can customize the connection protocol version for the connection using SSL_SESSION_SetProtocolRange before establishing a client or server connection.

See also

SSL_SESSION_SetProtocolRange.

SSL_SESSION_QueryFlags()

Description

Query session-related flags.

Prototype

unsigned SSL_SESSION_QueryFlags(SSL_SESSION * pSelf);

Parameters

Parameter Description
pSelf Pointer to session context.

Return value

Bitwise-or of the flags set for the session.

Additional information

This function retrieves flags set during the lifetime of a session.

The following flags are defined for an SSL server:

Flag Description
SSL_SESSION_FLAG_REQUEST_CERTIFICATE SSL server requests a certificate from the client during connection setup for mutual authentication.
SSL_SESSION_FLAG_RECEIVED_CERTIFICATE SSL server received a valid certificate from the client during connection setup.
SSL_SESSION_FLAG_REQUEST_PREVENT_FALLBACK SSL client adds the Fallback signalling sipher suite to the Client Hello message (if required) to prevent version rollback.

SSL_SESSION_Receive()

Description

Receive data over an established SSL/TLS connection.

Prototype

int SSL_SESSION_Receive(SSL_SESSION * pSelf,
                        void        * pData,
                        unsigned      DataLen);

Parameters

Parameter Description
pSelf Pointer to session context.
pData Pointer to destination that will receive TLS data.
DataLen Size of destination array in bytes.

Return value

< 0 Processing error.
≥ 0 Number of bytes received successfully.

Additional information

This function waits for data to arrive on the established TLS connection before returning. The number of bytes returned will lie between zero and DataLen. Any alerts sent by the peer are processed and converted into appropriate status codes in the return value.

SSL_SESSION_Send()

Description

Send data over an established SSL/TLS connection.

Prototype

int SSL_SESSION_Send(      SSL_SESSION * pSelf,
                     const void        * pData,
                           unsigned      DataLen);

Parameters

Parameter Description
pSelf Pointer to session context.
pData Pointer to octet string to send over SSL.
DataLen Octet length of the octet string to send.

Return value

< 0 Processing error.
≥ 0 Number of bytes send from the octet string.

Additional information

This function sends the data over the established SSL connection using the negotiated cipher suite and protocol version. Any alerts sent by the peer are processed and converted into appropriate status codes in the return value.

The data to send is immediately encrypted and sent to the peer—emSSL does not perform any buffering to opportunistically combine TLS packets.

Application data will be fragmented, as required, across multiple protocol packets according to the setting of SSL_MAX_APP_DATA_FRAGMENT_LEN.

SSL_SESSION_SendStr()

Description

Send null-terminated string to peer.

Prototype

int SSL_SESSION_SendStr(      SSL_SESSION * pSelf,
                        const char        * sText);

Parameters

Parameter Description
pSelf Pointer to session context to send over.
sText Null-terminated string to send.

Return value

< 0 Processing error.
≥ 0 Success.

Additional information

This function is a convenience that wraps a call to SSL_SESSION_Send() to send the null-terminated string over an established SSL connection.

See also

SSL_SESSION_Send.

SSL_SESSION_SetAllowedSuites()

Description

Set the cipher suites to offer or accept for all connections.

Prototype

void SSL_SESSION_SetAllowedSuites(      SSL_SESSION * pSelf,
                                  const U16         * pSuites,
                                        unsigned      SuiteCnt);

Parameters

Parameter Description
pSelf Session context to override.
pSuites Pointer to array of cipher suite IDs to allow.
SuiteCnt Count of cipher suite IDs in the array.

Additional information

This function sets the cipher suites that are to be offered by an SSL client and supported by an SSL server for a specific connection. This function enables restriction of cipher suites on a per-session basis such that client and server connections may vary the set of suites that are offered or accepted.

This function must be called after initializing the session using SSL_SESSION_Prepare() and before making or accepting connections using SSL_SESSION_Connect() or SSL_SESSION_Accept().

SSL_SESSION_SetFlags()

Description

Set session-related flags.

Prototype

void SSL_SESSION_SetFlags(SSL_SESSION * pSelf,
                          unsigned      Flags);

Parameters

Parameter Description
pSelf Pointer to session context.
Flags Bitwise-or of flags to set.

Additional information

This function sets session-related flags, for instance requesting that the client provides its certificate during negotiation.

This function must be called after initializing the session using SSL_SESSION_Prepare() and before making or accepting connections using SSL_SESSION_Connect() or SSL_SESSION_Accept().

Additional information

The following flags are defined for an SSL server:

Flag Description
SSL_SESSION_FLAG_REQUEST_CERTIFICATE SSL server requests a certificate from the client during connection setup for mutual authentication.
SSL_SESSION_FLAG_REQUEST_RESUME_CRITICAL When connecting to a server with session resumption, indicate that it is critical the session is resumed rather than a new session created. If the session is not resumed, the connection is failed.
SSL_SESSION_FLAG_DISABLE_SESSION_TICKET Disable resumption by session ticket and any advertising of session ticket capability.
SSL_SESSION_FLAG_DISABLE_RSA_PMS_VERSION_CHECK Disable TLS 1.0 premaster secret version check. See RFC 5246 section 7.4.7.1.
SSL_SESSION_FLAG_REQUIRE_STRICT_TLS_CLOSE It is an error in the TLS protocol if a socket is closed at the TCP layer without the peer preceding the closure with a close-notify alert to terminate the TLS session. By default and to provide maximum compatibility with non-compliant TLS stacks and applications, emSSL will tolerate graceful closure of TCP sockets and propagate that graceful closure to the TLS layer and also terminate the TLS session gracefully. It does this only for graceful closure of the socket: if the socket is shut down with an error, that error is propagated to the TLS layer regardless. Setting this flag requires that a close-notify be sent to close the SSL session, and socket closure at the TCP layer without the close-notify alert is considered an error.

SSL_SESSION_SetCertificateAPI()

Description

Set the API to use to handle PKI certificates and keys.

Prototype

void SSL_SESSION_SetCertificateAPI(      SSL_SESSION         * pSelf,
                                   const SSL_CERTIFICATE_API * pAPI);

Parameters

Parameter Description
pSelf Pointer to session context.
pAPI Pointer to certificate API that will be used for the session.

Additional information

This function sets the per-session API for validation of presented server certificates, for retrieving SSL server certificates and private keys (for server connections) and client certificates and keys (for client connections).

Installed certificates are required for all server connections other than those with anonymous cipher suites (which are vulnerable to man-in-the-middle attacks). It is optional for clients: if clients wish to offer certificates for mutual authentication, they must implement the API.

This function must be called after initializing the session using SSL_SESSION_Prepare() and before making or accepting connections using SSL_SESSION_Connect() or SSL_SESSION_Accept().

SSL_SESSION_SetProtocolRange()

Description

Set the protocol range supported by the SSL connection.

Prototype

void SSL_SESSION_SetProtocolRange(SSL_SESSION * pSelf,
                                  U16           MinVersion,
                                  U16           MaxVersion);

Parameters

Parameter Description
pSelf Pointer to session context.
MinVersion Minimum SSL/TLS version supported.
MaxVersion Maximum SSL/TLS version supported.

Additional information

By default, a new SSL session is initialized to offer support for all TLS versions installed during initialization. If you wish to restrict the protocols offered by a server or required by a client within the configured range, you must call this function after initialization and before any connection attempt by client or server.

It is not possible to use this function to configure emSSL for protocols prior to TLS 1.0 because SSL 2 and SSL 3 are now considered insecure and emSSL offers no support for these protocols.

Example

This example limits the protocol to TLS 1.1 through TLS 1.2, thereby excluding connections using TLS 1.0 and previous versions.

static SSL_SESSION _Session;
//
SSL_SESSION_Prepare(&Session, Socket, &_IP_Transport);
SSL_SESSION_SetProtocolRange(&_Session, SSL_PROTOCOL_TLS_1v1, SSL_PROTOCOL_TLS_1v2);

Cipher suite functions

The table below lists the functions that query cipher suite configuration.

Function Description
SSL_SUITE_CopyName() Copy IANA name of the cipher suite.
SSL_SUITE_FindByID() Find an installed cipher suite by IANA ID.
SSL_SUITE_FindByIndex() Find an installed cipher suite by preference index.
SSL_SUITE_GetCipherName() Get the cipher name for a cipher ID.
SSL_SUITE_GetIANASuiteName() Get IANA name of a SSL suite ID.
SSL_SUITE_GetID() Get the IANA cipher suite ID.
SSL_SUITE_GetKeyExchangeName() Get the name of a key exchange ID.
SSL_SUITE_GetMACAlgorithmName() Get the algorithm name for a MAC algorithm ID.
SSL_SUITE_GetPKAlgorithmName() Get the name of a public key algorithm ID.
SSL_SUITE_QueryNull() Does cipher suite have a null component?
SSL_SUITE_QueryPKAlgorithm() Query the public key algorithm associated with a key exchange.
SSL_SUITE_QueryRequiresECC() Does cipher suite require ECC support?
SSL_SUITE_QueryRequiresPSK() Does cipher suite require PSK support?
SSL_SUITE_QueryValidity() Is cipher suite supported and valid for a given TLS version?

SSL_SUITE_CopyName()

Description

Copy IANA name of the cipher suite.

Prototype

void SSL_SUITE_CopyName(      char      * pText,
                        const SSL_SUITE * pSuite);

Parameters

Parameter Description
pText Pointer to a buffer of at least 80 characters to receive the name.
pSuite The suite to return the IANA name of.

Additional information

The name has no leading “TLS” prefix, it starts with the key agreement scheme.

SSL_SUITE_FindByID()

Description

Find an installed cipher suite by IANA ID.

Prototype

SSL_SUITE *SSL_SUITE_FindByID(unsigned ID);

Parameters

Parameter Description
ID IANA cipher suite ID.

Return value

= 0 Cipher suite not found.
≠ 0 Cipher suite corresponding to the IANA ID.

Additional information

Only cipher suites installed by SSL_SUITE_Add() will be searched.

SSL_SUITE_FindByIndex()

Description

Find an installed cipher suite by preference index.

Prototype

SSL_SUITE *SSL_SUITE_FindByIndex(unsigned Index);

Parameters

Parameter Description
Index Preference index with zero indicating the first suite that was added.

Return value

= 0 Cipher suite not found.
≠ 0 Cipher suite corresponding to the preference index.

Additional information

Only cipher suites installed by SSL_SUITE_Add() will be iterated over. The suite that is added first has index 0, the second added has index 1, and so on.

SSL_SUITE_GetCipherName()

Description

Get the cipher name for a cipher ID.

Prototype

char *SSL_SUITE_GetCipherName(SSL_CIPHER_ID ID);

Parameters

Parameter Description
ID Cipher ID.

Return value

Zero-terminated string describing ID.

SSL_SUITE_GetIANASuiteName()

Description

Get IANA name of a SSL suite ID.

Prototype

char *SSL_SUITE_GetIANASuiteName(unsigned ID);

Parameters

Parameter Description
ID TLS suite ID.

Return value

The corresponding suite name or “Unknown” if the suite ID is not known.

SSL_SUITE_GetID()

Description

Get the IANA cipher suite ID.

Prototype

int SSL_SUITE_GetID(const SSL_SUITE * pSuite);

Parameters

Parameter Description
pSuite The suite under consideration.

Return value

IANA cipher suite ID.

Additional information

The list of cipher suites defined by IANA is maintained here:

http://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml

SSL_SUITE_GetKeyExchangeName()

Description

Get the name of a key exchange ID.

Prototype

char *SSL_SUITE_GetKeyExchangeName(SSL_KEY_EXCHANGE_ID ID);

Parameters

Parameter Description
ID Key exchange ID.

Return value

Zero-terminated string describing ID.

SSL_SUITE_GetMACAlgorithmName()

Description

Get the algorithm name for a MAC algorithm ID.

Prototype

char *SSL_SUITE_GetMACAlgorithmName(SSL_HASH_ALGORITHM_ID ID);

Parameters

Parameter Description
ID MAC algorithm ID.

Return value

Zero-terminated string describing ID.

SSL_SUITE_GetPKAlgorithmName()

Description

Get the name of a public key algorithm ID.

Prototype

char *SSL_SUITE_GetPKAlgorithmName(CRYPTO_X509_PK_ALGORITHM_ID ID);

Parameters

Parameter Description
ID Public key algorithm ID.

Return value

Zero-terminated string describing ID.

SSL_SUITE_QueryNull()

Description

Does cipher suite have a null component?

Prototype

int SSL_SUITE_QueryNull(const SSL_SUITE * pSuite);

Parameters

Parameter Description
pSuite Suite under consideration.

Return value

= 0 No component of the suite is NULL.
≠ 0 Some component of the suite is NULL.

SSL_SUITE_QueryPKAlgorithm()

Description

Query the public key algorithm associated with a key exchange.

Prototype

CRYPTO_X509_PK_ALGORITHM_ID SSL_SUITE_QueryPKAlgorithm(SSL_KEY_EXCHANGE_ID ID);

Parameters

Parameter Description
ID Key exchange ID.

Return value

Public key algorithm associated with the key exchange mechanism ID.

SSL_SUITE_QueryRequiresECC()

Description

Does cipher suite require ECC support?

Prototype

int SSL_SUITE_QueryRequiresECC(const SSL_SUITE * pSuite);

Parameters

Parameter Description
pSuite Suite under consideration.

Return value

= 0 Does not require ECC.
≠ 0 Requires ECC.

Additional information

Cipher suites that are ECDH or ECDHE will return true; others will returns false.

SSL_SUITE_QueryRequiresPSK()

Description

Does cipher suite require PSK support?

Prototype

int SSL_SUITE_QueryRequiresPSK(const SSL_SUITE * pSuite);

Parameters

Parameter Description
pSuite Suite under consideration.

Return value

= 0 Does not require PSK.
≠ 0 Requires PSK.

SSL_SUITE_QueryValidity()

Description

Is cipher suite supported and valid for a given TLS version?

Prototype

int SSL_SUITE_QueryValidity(const SSL_SUITE * pSuite,
                                  unsigned    Version);

Parameters

Parameter Description
pSuite Suite under consideration.
Version Protocol ID of version of SSL/TLS to test.

Return value

= 0 Cipher suite is not valid for TLS version Version.
≠ 0 Cipher suite is valid for TLS version Version.

Additional information

Only the protocol versions defined by emSSL are valid which are:

Diagnostic functions

The table below lists the diagnostic functions provided by the emSSL API.

Function Description
SSL_AddLogFilter() Add filters to the active log filter.
SSL_AddWarnFilter() Add filters to the active warning filter.
SSL_ERROR_GetText() Decode an SSL error code.
SSL_RemoveLogFilter() Remove filters from the active log filter.
SSL_RemoveWarnFilter() Remove filters from the active warning filter.
SSL_SetLogFilter() Set active log filter.
SSL_SetWarnFilter() Set the active warning filter.

SSL_AddLogFilter()

Description

Add filters to the active log filter.

Prototype

U32 SSL_AddLogFilter(U32 FilterMask);

Parameters

Parameter Description
FilterMask Filters to enable.

Return value

The log filter mask before addition.

Additional information

This function adds to the existing log filter mask using a bitwise or of the new filter mask and the given filter mask.

Example

This example temporarily enables error logging during connection setup.

SSL_SESSION Session;
U32         Previous;
//
Previous = SSL_AddLogFilter(SSL_LOG_ERROR);
Status   = SSL_SESSION_Connect(&Session, "www.segger.com");
SSL_SetLogFilter(Previous);

See also

Logging flags, SSL_RemoveLogFilter.

SSL_AddWarnFilter()

Description

Add filters to the active warning filter.

Prototype

U32 SSL_AddWarnFilter(U32 FilterMask);

Parameters

Parameter Description
FilterMask Filters to enable.

Return value

The warning filter mask before addition.

Additional information

This function adds to the existing warning filter mask using a bitwise or of the new filter mask and the given filter mask.

Example

This example temporarily enables alert warnings during connection setup.

SSL_SESSION Session;
U32         Previous;
//
Previous = SSL_AddWarnFilter(SSL_WARN_ALERT);
Status   = SSL_SESSION_Connect(&Session, "www.segger.com");
SSL_SetWarnFilter(Previous);

See also

SSL_ERROR_GetText()

Description

Decode an SSL error code.

Prototype

char *SSL_ERROR_GetText(int ErrorCode);

Parameters

Parameter Description
ErrorCode Error code returned by emSSL.

Return value

Zero-terminated string describing the emSSL error status.

SSL_RemoveLogFilter()

Description

Remove filters from the active log filter.

Prototype

U32 SSL_RemoveLogFilter(U32 FilterMask);

Parameters

Parameter Description
FilterMask Filters to disable.

Return value

The log filter mask before removal.

Additional information

This function removes the filters specified in FilterMask from the existing log filter.

Example

This example temporarily suspends error logging during connection setup. SSL_SESSION Session;

U32         Previous;
//
Previous = SSL_AddRemoveFilter(SSL_LOG_ERROR);
Status   = SSL_SESSION_Connect(&Session, "www.segger.com");
SSL_SetLogFilter(Previous);

See also

Logging flags, SSL_AddLogFilter.

SSL_RemoveWarnFilter()

Description

Remove filters from the active warning filter.

Prototype

U32 SSL_RemoveWarnFilter(U32 FilterMask);

Parameters

Parameter Description
FilterMask Filters to disable.

Return value

The warning filter mask before removal.

Additional information

This function removes the filters specified in FilterMask from the existing log filter.

SSL_SetLogFilter()

Description

Set active log filter.

Prototype

U32 SSL_SetLogFilter(U32 FilterMask);

Parameters

Parameter Description
FilterMask Filters to enable.

Return value

The log filter mask before replacement.

Additional information

This function sets the log filter mask to use, entirely replacing the previously set filter mask. The bits set in the filter mask enable appropriate messages to the log.

Example

This example sets the log filter to report only keys and cryptographic data with all others disabled.

SSL_SetLogFilter(SSL_LOG_KEYS | SSL_LOG_CRYPTO);

See also

SSL_SetWarnFilter()

Description

Set the active warning filter.

Prototype

U32 SSL_SetWarnFilter(U32 FilterMask);

Parameters

Parameter Description
FilterMask Filters to enable.

Return value

The warning filter mask before replacement.

Additional information

This function sets the warning filter mask to use, entirely replacing the previously set filter mask. The bits set in the filter mask enable appropriate warnings.

Example

This example sets the warning filter to report only alerts and cryptography warnings with all others disabled.

SSL_SetWarnFilter(SSL_WARN_ALERT | SSL_WARN_CRYPTO);

See also

Internal functions, variables and data structures

Internal functions of emSSL are not explained here as they are not required to use emSSL. The application should not rely on any of the internal elements, since they may be subject to change. Only the documented API functions are guaranteed to remain unchanged and compatible in future versions of emSSL.

API evolution

This section describes the changes made to the API for this version of emSSL.

Version 2.52

The following are the API additions in this version:

Version 2.50

The following are the API changes in this version:

The following are now documented:

Version 2.42

The following are the API changes in this version:

The following are now documented:

Version 2.40

The following are the API changes in this version:

Version 2.30

The following are the API changes in this version:

Configuring emSSL

emSSL is configurable. It is designed for both high performance and low memory usage.

This chapter describes the available compile-time and runtime configuration options.

emSSL’s functionality (i.e. its feature set) is completely configurable using runtime calls to select the way that emSSL performs as a client and a server. However, there are choices to be made between different implementations of some computationally intensive algorithms. At the source level you can trade speed of execution for a more compact implementation to reduce code space — this configuration is made using preprocessor symbols defined in a particular manner when compiling emSSL from source code.

Please refer to the chapter Best practice for details on best practices when configuring SSL and TLS systems.

Compile-time configuration

Application data fragmentation

Default

#define SSL_MAX_APP_DATA_FRAGMENT_LEN   1024

Override

To define a non-default value, define this symbol in SSL_Conf.h.

Description

Set this preprocessor symbol to define the maximum length of an application data packet. Send requests with more than this quantity of data will be transparently fragmented across multiple application data packets by emSSL.

The valid range is from 1 to 16384 inclusive. The advantage of setting this value to a small value is that less memory is required by emSSL when encapsulating the packet for transmission using the TLS protocol. The disadvantage of a small value is that there will be more transmission overhead required by the encapsulation and, therefore, transmission is less efficient in terms of bandwidth.

Server session cache size

Default

#define SSL_SESSION_CACHE_SIZE   5

Override

To define a non-default value, define this symbol in SSL_Conf.h.

Description

Set this preprocessor symbol to define the number of entries in the session cache. Setting this symbol to zero disables the session cache.

Supported ticket lengths

Default

#define SSL_MAX_SESSION_TICKET_LEN    256

Override

To define a non-default value, define this symbol in SSL_Conf.h.

Description

This preprocessor symbol defines the maximum session ticket length supported by TLS client connections. If this is set to zero, session tickets (as a client) will not be supported by emSSL.

The session ticket is sent by the server and, therefore, the client has no control over its length. You should consider the servers you will be connecting to, as a client, and determine an appropriate ticket size. Ticket sizes vary considerably in length, from a few hundred bytes up to two kilobytes.

Runtime configuration

Before a secure connection is established, emSSL must be configured with the cipher suites and supporting algorithms needed for a secure connection. SSL_X_Config.c is configured to match the requirements of most applications and can be taken as an example. You must configure:

Each cipher suite that you add and protocol version that you support will require supporting components to be configured as well.

Cipher suites explained

A TLS cipher suite is composed of three parts:

These three parts are put together in an identifier of the form:

TLS--keyexchange--WITH--bulkcipher--authentication

For instance, a TLS cipher that combines ECDHE--ECDSA key exchange with an AES--256--CBC bulk cipher and uses SHA--384 message authentication would be:

This is a lot of information packed into a single identifier. emSSL identifies each suite following that naming convention but replaces “TLS” with “SSL”, and replaces hyphens with underscores such that the resulting identifier is acceptable to a C compiler. So, the above suite becomes:

In theory you create a cipher suite by picking any combination of key exchange, cipher, and MAC, but there are good reasons that only a handful of combinations are in popular use — those good reasons include security analysis of the cryptographic strengths of each of the components and appropriate matching between the parts.

For each of the cipher suite parts, you must add an appropriate implementation of public key methods (Adding public key signature verifiers), bulk ciphers (Adding ciphers), and message authentication (Adding MACs).

Adding cipher suites

emSSL supports a number of cipher suites and each supported cipher suite must be added to emSSL.

To install cipher suites into emSSL, call SSL_SUITE_Add, specifying the suite to add, in SSL_X_Config():

void SSL_X_Config(void) {
  SSL_SUITE_Add(&SSL_SUITE_ECDHE_RSA_WITH_AES_256_GCM_SHA384);
}

The suites supported by this version of emSSL are specified using standard naming conventions described earlier:

ECDHE-ECDSA

ECDHE-RSA

ECDH-RSA

ECDH-ECDSA

DHE-RSA

RSA

Suite preference order

The order in which suites are added defines the default preference order of suites in the negotiation phase of a client connection.

Adding ciphers

You must add the required bulk cipher implementation using SSL_Cipher_Add when configuring cipher suites. The bulk cipher implementations are:

These cipher implementations are written entirely in software and do not offer any acceleration beyond configuring AES or DES during compilation (see Ciphers).

Although the implementation of ciphers in emSSL is highly efficient, emSSL is designed to be highly modular in order to take full advantage of both hardware acceleration and vendor-optimized cryptography libraries. Please refer to Configuring cryptography for further details.

Example

The cipher suite TLS-ECDHE-ECDSA-WITH-AES-256-CBC-SHA384 uses AES-256-CBC as the bulk cipher. In order to support this cipher suite correctly you must add appropriate support for AES-256-CBC with:

SSL_CIPHER_Add(&SSL_CIPHER_AES_256_CBC_API);

Adding MACs

You must add required message authentication code implementations using SSL_MAC_Add when configuring cipher suites. The MAC implementations are:

These MAC implementations are written entirely in software and do not offer any acceleration beyond configuring MD5 and SHA during compilation.

Although the implementation of MACs in emSSL is highly efficient, emSSL is designed to be highly modular in order to take full advantage of both hardware acceleration and vendor-optimized cryptography libraries. Please refer to Configuring cryptography for further details.

Example

The cipher suite TLS-ECDHE-ECDSA-WITH-AES-256-CBC-SHA384 uses SHA-384 as the MAC. In order to support this cipher suite correctly you must add appropriate support for SHA-384 with:

SSL_MAC_Add(&SSL_MAC_SHA384_API);

Adding public key signature verifiers

You must add the required public key signature verifiers (according to the cipher suites you select) using SSL_SIGNATURE_VERIFY_Add(). The public key signature verifier implementations are:

These signature verification implementations are written entirely in software but take advantage of any hardware acceleration offered by the MAC schemes.

Although the implementation of signature verifiers in emSSL is highly efficient, emSSL is designed to be highly modular in order to take full advantage of both hardware acceleration and vendor-optimized cryptography libraries. Please refer to Configuring cryptography for further details.

Example

The cipher suite TLS-ECDHE-ECDSA-WITH-AES-256-CBC-SHA384 uses the key exchange ECDHE-ECDSA where ECDSA is the signature method. In order to support this cipher suite correctly you must add appropriate support for ECDSA using:

SSL_SIGNATURE_VERIFY_Add(&SSL_SIGNATURE_VERIFY_ECDSA_API);

Adding public key message signers

You must add the required public key message signers verifiers (according to the cipher suites you select) using SSL_SIGNATURE_SIGN_Add(). The public key signature verifier implementations are:

These message signing implementations are written entirely in software but take advantage of any hardware acceleration offered by the MAC schemes.

Although the implementation of message signers in emSSL is highly efficient, emSSL is designed to be highly modular in order to take full advantage of both hardware acceleration and vendor-optimized cryptography libraries. Please refer to Configuring cryptography for further details.

Example

The cipher suite TLS-RSA-WITH-AES-256-CBC-SHA384 uses a static RSA key exchange scheme and in server mode must sign part of the exchange between client and server. In order to support this cipher suite correctly you must add appropriate support for static RSA key exchange using:

SSL_SIGNATURE_VERIFY_Add(&SSL_SIGNATURE_SIGN_RSA_API);

Adding signature algorithms

When implementing emSSL as a client, the client must advertise the signature schemes that it is willing to accept when negotiating keys and verifying certificates. You must therefore configure the signature schemes that you wish to offer and also install the signature verifiers and MACs that comprise the signature algorithms you advertise.

The signature schemes are broken down by public key:

RSA

DSA

ECDSA

These signature algorithm implementations are written entirely in software and do not offer any acceleration beyond that offered by static configuration of each SHA and MD5 component.

Although the implementation of signature algorithms in emSSL is highly efficient, emSSL is designed to be highly modular in order to take full advantage of both hardware acceleration and vendor-optimized cryptography libraries. Please refer to Configuring cryptography for further details.

Example

The cipher suite TLS-ECDHE-ECDSA-WITH-AES-256-CBC-SHA384 would use a signature based on ECDSA. You can add support for this scheme using a SHA-256 message digest and advertise it to a client with:

SSL_SIGNATURE_ALGORITHM_Add(SSL_SIGNATURE_SHA256_WITH_ECDSA);

However, you also need to add appropriate MAC algorithms and public key signature verifiers to support this scheme:

SSL_MAC_Add(&SSL_MAC_SHA256_API);
SSL_SIGNATURE_VERIFY_Add(&SSL_SIGNATURE_VERIFY_ECDSA_API);

Adding elliptic curves

If emSSL is configured to support any elliptic curve cipher suite, i.e. those starting ECDH or ECDHE, it must also be configured with at least one elliptic curve.

emSSL supports recommended NIST elliptic curves over prime fields which provide different encryption strengths.

The following NIST elliptic curves are implemented within emSSL, defined in the NIST standard FIPS 186-4:

The following NIST curves are implemented, but are significantly slower than the NIST curves above for the same security strength:

The following Brainpool curves are implemented, but are significantly slower than the NIST curves for the same security strength:

The following curve is implemented, although support for it is somewhat limited on the Internet:

Higher strength elliptic curves require more memory and more computational power to work with and many servers limit the elliptic curves they support in order to reduce the load on the server when establishing a secure connection. The client is burdened in a similar fashion, so you should carefully consider which curves to install to provide the required level of security and acceptable performance along with interoperability—see Implementation details for some advice.

Example

To install the elliptic curves into emSSL, call SSL_CURVE_Add() in SSL_X_Config():

void SSL_X_Config(void) {
  SSL_CURVE_Add(&SSL_CURVE_secp192r1);
  SSL_CURVE_Add(&SSL_CURVE_secp224r1);
  SSL_CURVE_Add(&SSL_CURVE_secp256r1);
  SSL_CURVE_Add(&SSL_CURVE_secp384r1);
  SSL_CURVE_Add(&SSL_CURVE_secp521r1);
}

Adding TLS protocols

You must configure the TLS protocol versions that you wish to support as a client or server. emSSL supports TLS protocol version 1.0, 1.1, and 1.2. You can add support for each protocol using SSL_PROTOCOL_Add(). The protocols offered by emSSL are:

Note that adding support for a particular version of the protocol has an effect on the TLS pseudorandom function that is required.

TLS version 1.0 and 1.1

These schemes require the TLS version 1.0 PRF implementation that is a combination of MD5 and SHA.

TLS version 1.2

This protocol version will always use PRF-SHA256 as the PRF for all TLS 1.0 and 1.1 cipher suites. For TLS 1.2 cipher suites, the PRF is defined by the cipher suite itself:

Example

We support a single cipher suite SSL-SUITE-RSA-WITH-AES-128-CBC-SHA and TLS protocol version 1.0 only. Putting aside configuration of the cipher suite and other items and concentrating on the PRF, this cipher suite and TLS protocol combination requires only the PRF-TLS1 pseudorandom function:

SSL_SUITE_Add(&SSL_SUITE_RSA_WITH_AES_128_CBC_SHA);
SSL_PROTOCOL_ADD(&SSL_PROTOCOL_TLS1v0_API);

Extending support for TLS versions 1.1 and 1.2 but retaining a single TLS version 1.0 cipher suite requires the addition of PRF-SHA256 — this is because the TLS version 1.0 cipher suite’s MAC is upgraded to SHA-256 when negotiating a TLS 1.2 connection:

SSL_SUITE_Add(&SSL_SUITE_RSA_WITH_AES_128_CBC_SHA);
SSL_PROTOCOL_Add(&SSL_PROTOCOL_TLS1v0_API);
SSL_PROTOCOL_Add(&SSL_PROTOCOL_TLS1v1_API);
SSL_PROTOCOL_Add(&SSL_PROTOCOL_TLS1v2_API);

Extending support for the TLS 1.2 cipher suite SSL-SUITE-RSA-WITH-AES-256-GCM-SHA384 requires the addition of PRF-SHA384 as this is mandated by the cipher suite’s SHA-384 MAC:

SSL_SUITE_Add(&SSL_SUITE_RSA_WITH_AES_128_CBC_SHA);
SSL_SUITE_Add(&SSL_SUITE_RSA_WITH_AES_256_GCM_SHA384);
SSL_PROTOCOL_Add(&SSL_PROTOCOL_TLS1v0_API);
SSL_PROTOCOL_Add(&SSL_PROTOCOL_TLS1v1_API);
SSL_PROTOCOL_Add(&SSL_PROTOCOL_TLS1v2_API);

The order that you add components to emSSL does not matter, you can add components in the order that feels most natural. When SSL_X_Config() returns, SSL_Init() will validate the configuration and warn you on anything that can be eliminated and will halt if it requires something that has not been configured.

emSSL will diagnose issues if installed TLS support requires an underlying algorithm that is not configured at the emCrypt layer.

Configuring cryptography

Overview

In addition to configuring emSSL capabilities at the protocol level, it is necessary to configure how these are implemented by the shared cryptographic library, emCrypt.

emCrypt provides cryptographic services for all SEGGER security products (emSSL, emSSH, emSecure-RSA, and emSecure-ECDSA) and must be configured before it is used stand-alone or with one of these products.

There are two parts to emCrypt configuration:

The following sections describe compile-time and runtime configuation of emCrypt.

Compile-time configuration

In order to configure how compute-intensive cryptographic algorithms are compiled to balance code size and execution performance you can change the compile-time flags in the configuration file CRYPTO_Conf.h.

The default configuration strikes a balance between code size and execution speed and runs well on the broadest range of hardware.

Note

All user configuration of the cryptographic algorithms must be made in the file CRYPTO_Conf.h and only that file. Do not make any adjustments to the file CRYPTO_ConfDefaults.h.

Multiprecision integer, bits per limb

Default

#define CRYPTO_MPI_BITS_PER_LIMB     32

Override

To define a non-default value, define this symbol in CRYPTO_Conf.h.

Description

This preprocessor symbol configures the number of bits per limb for multiprecision integer algorithms. The default of 32 matches 32-bit targets well, such as ARM and PIC32. In general, it is best to set the number of bits per limb to the number of bits in the standard int or unsigned type used by the target compiler.

Supported configurations are:

Hashes

MD5

Default

#define CRYPTO_CONFIG_MD5_OPTIMIZE     0

Override

To define a non-default value, define this symbol in CRYPTO_Conf.h.

Description

Set this preprocessor symbol to zero to optimize the MD5 hash functions for size rather than for speed. When optimized for speed, the MD5 function is open coded and faster, but is significantly larger.

Profile

The following table shows required context size, lookup table (LUT) size, and code size in kilobytes for each configuration value. All values are approximate and for a Cortex-M3 processor.

Setting Context size LUT LUT size Code size Total size
0 0.16 KB Flash 0.3 KB 0.4 KB 0.7 KB
1 0.16 KB - - 2.0 KB 2.0 KB
SHA-1

Default

#define CRYPTO_CONFIG_SHA1_OPTIMIZE     0

Override

To define a non-default value, define this symbol in CRYPTO_Conf.h.

Description

Set this preprocessor symbol to zero to optimize the SHA-1 hash functions for size rather than for speed. When optimized for speed, the SHA-1 function is open coded and faster, but is significantly larger.

Profile

The following table shows required context size, lookup table (LUT) size, and code size in kilobytes for each configuration value. All values are approximate and for a Cortex-M4 processor.

Setting Context size LUT LUT size Code size Total size
0 0.16 KB - - 0.6 KB 0.6 KB
1 0.16 KB - - 3.6 KB 3.6 KB
SHA-256

Default

#define CRYPTO_CONFIG_SHA256_OPTIMIZE     0

Override

To define a non-default value, define this symbol in CRYPTO_Conf.h.

Description

Set this preprocessor symbol to zero to optimize the SHA-256 hash functions for size rather than for speed. When optimized for speed, the SHA-256 function is open coded and faster, but is significantly larger.

Profile

The following table shows required context size, lookup table (LUT) size, and code size in kilobytes for each configuration value. All values are approximate and for a Cortex-M3 processor.

Setting Context size LUT LUT size Code size Total size
0 0.17 KB Flash 0.3 KB 0.5 KB 0.8 KB
1 0.17 KB - - 7.7 KB 7.7 KB
SHA-512

Default

#define CRYPTO_CONFIG_SHA512_OPTIMIZE     0

Override

To define a non-default value, define this symbol in CRYPTO_Conf.h.

Description

Set this preprocessor symbol to zero to optimize the SHA-512 hash functions for size rather than for speed. When optimized for speed, the SHA-512 function is open coded and faster, but is significantly larger.

Profile

The following table shows required context size, lookup table (LUT) size, and code size in kilobytes for each configuration value. All values are approximate and for a Cortex-M3 processor.

Setting Context size LUT LUT size Code size Total size
0 0.20 KB Flash 0.7 KB  1.1 KB  1.8 KB
1 0.20 KB Flash 0.7 KB 10.3 KB 11.0 KB
2 0.20 KB Flash 0.1 KB 41.5 KB 41.6 KB

Ciphers

AES

Default

#define CRYPTO_CONFIG_AES_OPTIMIZE     2

Override

To define a non-default value, define this symbol in CRYPTO_Conf.h.

Description

Set this preprocessor symbol nonzero to optimize AES to use tables for matrix multiplication. Optimization levels are 0 through 7 with larger numbers generally producing better performance.

Profile

The following table shows required context size, lookup table (LUT) size, and code size in kilobytes for each configuration value. All values are approximate and for a Cortex-M3 processor.

Setting Context size LUT LUT size Code size Total size
0 0.24 KB Flash 2.0 KB  3.2 KB  5.2 KB
1 0.24 KB Flash 2.0 KB  2.7 KB  4.7 KB
2 0.24 KB Flash 8.5 KB  2.4 KB 10.9 KB
3 0.24 KB Flash 1.9 KB 12.5 KB 14.4 KB
4 0.24 KB RAM 2.0 KB  3.2 KB  5.2 KB
5 0.24 KB RAM 2.0 KB  2.7 KB  4.7 KB
6 0.24 KB RAM 8.5 KB  2.4 KB 10.9 KB
7 0.24 KB RAM 1.9 KB 12.5 KB 14.4 KB
DES

Default

#define CRYPTO_CONFIG_DES_OPTIMIZE     0

Override

To define a non-default value, define this symbol in CRYPTO_Conf.h.

Description

Set this preprocessor symbol nonzero to optimize DES and 3DES to place tables in RAM rather than flash. Optimization levels are 0 through 5 with larger numbers generally producing better performance.

Profile

The following table shows required context size, lookup table (LUT) size, and code size in kilobytes for each configuration value. All values are approximate and for a Cortex-M3 processor.

Setting Context size LUT LUT size Code size Total size
0 0.38 KB Flash 2.1 KB 1.3 KB 3.4 KB
1 0.38 KB Flash 2.1 KB 2.1 KB 4.2 KB
2 0.38 KB Flash 2.1 KB 5.3 KB 7.4 KB
3 0.38 KB RAM 2.1 KB 1.3 KB 3.4 KB
4 0.38 KB RAM 2.1 KB 2.1 KB 4.2 KB
5 0.38 KB RAM 2.1 KB 5.3 KB 7.4 KB
SEED

Default

#define CRYPTO_CONFIG_SEED_OPTIMIZE     0

Override

To define a non-default value, define this symbol in CRYPTO_Conf.h.

Description

Set this preprocessor symbol nonzero to optimize SEED to place tables in RAM rather than flash and to optimized the table sizes. Optimization levels are 0 through 3 with larger numbers generally producing better performance.

Profile

The following table shows required context size, lookup table (LUT) size, and code size in kilobytes for each configuration value. All values are approximate and for a Cortex-M3 processor.

Setting Context size LUT LUT size Code size Total size
0 0.14 KB Flash 0.5 KB 0.5 KB 1.0 KB
1 0.14 KB Flash 4.0 KB 0.4 KB 4.4 KB
2 0.14 KB RAM 0.5 KB 0.5 KB 1.0 KB
3 0.14 KB RAM 4.0 KB 0.4 KB 4.4 KB
ARIA

Default

#define CRYPTO_CONFIG_ARIA_OPTIMIZE     0

Override

To define a non-default value, define this symbol in CRYPTO_Conf.h.

Description

Set this preprocessor symbol nonzero to optimize ARIA to place tables in RAM rather than flash.

Profile

The following table shows required context size, lookup table (LUT) size, and code size in kilobytes for each configuration value. All values are approximate and for a Cortex-M3 processor.

Setting Context size LUT LUT size Code size Total size
0 0.28 KB Flash 1.0 KB 1.9 KB 2.9 KB
1 0.28 KB RAM 1.0 KB 1.9 KB 2.9 KB
Camellia

Default

#define CRYPTO_CONFIG_CAMELLIA_OPTIMIZE     0

Override

To define a non-default value, define this symbol in CRYPTO_Conf.h.

Description

Set this preprocessor symbol nonzero to optimize Camellia to use more efficient tables. Optimization levels are 0 (smallest) to 3 (fastest).

Profile

The following table shows required context size, lookup table (LUT) size, and code size in kilobytes for each configuration value. All values are approximate and for a Cortex-M3 processor.

Setting Context size LUT LUT size Code size Total size
0 0.27 KB Flash 1.0 KB 28.8 KB 29.8 KB
1 0.27 KB Flash 4.0 KB 20.7 KB 24.7 KB
2 0.27 KB RAM 1.0 KB 28.8 KB 29.8 KB
3 0.27 KB RAM 4.0 KB 20.7 KB 24.7 KB

Runtime configuration

The ciphers and hash functions that clients require must be installed as part of emCrypt configuration. The function CRYPTO_X_Conf() is called from CRYPTO_Init() to install any required cryptographic support.

emCrypt provides software implementations of all ciphers and hashes, but also supports plug-in hardware accelerators.

Hashes

emCrypt provides the following software implementations of the following hash algorithms for emSSL:

This section summarizes how to install the software hash implementations. For details on how to plug in hardware-assisted hash algorithms for a particular device, see Plug-in hardware accelerators.

MD5

Prototype

extern const CRYPTO_HASH_API CRYPTO_HASH_MD5_SW;

Description

This API provides a software-only implementation of MD5.

Installation

void CRYPTO_X_Conf(void) {
  CRYPTO_MD5_Install(&CRYPTO_HASH_MD5_SW, NULL);
}

See also

See MD5 for details on how to configure the performance and footprint of this algorithm.

SHA-1

Prototype

extern const CRYPTO_HASH_API CRYPTO_HASH_SHA1_SW;

Description

This API provides a software-only implementation of SHA-1.

Installation

void CRYPTO_X_Conf(void) {
  CRYPTO_SHA1_Install(&CRYPTO_HASH_SHA1_SW, NULL);
}

See also

See SHA-1 for details on how to configure the performance and footprint of this algorithm.

SHA-256

Prototype

extern const CRYPTO_HASH_API CRYPTO_HASH_SHA256_SW;

Description

This API provides a software-only implementation of SHA-256 and SHA-224.

Installation

void CRYPTO_X_Conf(void) {
  CRYPTO_SHA256_Install(&CRYPTO_HASH_SHA256_SW, NULL);
}

See also

See SHA-256 for details on how to configure the performance and footprint of this algorithm.

SHA-512

Prototype

extern const CRYPTO_HASH_API CRYPTO_HASH_SHA512_SW;

Description

This API provides a software-only implementation of SHA-512 and SHA-384.

Installation

void CRYPTO_X_Conf(void) {
  CRYPTO_SHA512_Install(&CRYPTO_HASH_SHA512_SW, NULL);
}

See also

See SHA-512 for details on how to configure the performance and footprint of this algorithm.

Ciphers

emCrypt provides the following software implementations of the following cipher algorithms for emSSL:

This section summarizes how to install the software cipher implementations. For details on how to plug in hardware-assisted cipher algorithms for a particular device, see Plug-in hardware accelerators.

AES

Prototype

extern const CRYPTO_CIPHER_API CRYPTO_CIPHER_AES_SW;

Description

This API provides a software-only implementation of AES.

Installation

void CRYPTO_X_Conf(void) {
  CRYPTO_AES_Install(&CRYPTO_CIPHER_AES_SW, NULL);
}

See also

See AES for details on how to configure the performance and footprint of this algorithm.

DES

Prototype

extern const CRYPTO_CIPHER_API CRYPTO_CIPHER_TDES_SW;

Description

This API provides a software-only implementation of DES.

Installation

void CRYPTO_X_Conf(void) {
  CRYPTO_TDES_Install(&CRYPTO_CIPHER_TDES_SW, NULL);
}

See also

See DES for details on how to configure the performance and footprint of this algorithm.

SEED

Prototype

extern const CRYPTO_CIPHER_API CRYPTO_CIPHER_SEED_SW;

Description

This API provides a software-only implementation of SEED.

Installation

void CRYPTO_X_Conf(void) {
  CRYPTO_SEED_Install(&CRYPTO_CIPHER_SEED_SW, NULL);
}

See also

See SEED for details on how to configure the performance and footprint of this algorithm.

ARIA

Prototype

extern const CRYPTO_CIPHER_API CRYPTO_CIPHER_ARIA_SW;

Description

This API provides a software-only implementation of ARIA.

Installation

void CRYPTO_X_Conf(void) {
  CRYPTO_ARIA_Install(&CRYPTO_CIPHER_ARIA_SW, NULL);
}

See also

See ARIA for details on how to configure the performance and footprint of this algorithm.

Camellia

Prototype

extern const CRYPTO_CIPHER_API CRYPTO_CIPHER_CAMELLIA_SW;

Description

This API provides a software-only implementation of Camellia.

Installation

void CRYPTO_X_Conf(void) {
  CRYPTO_CAMELLIA_Install(&CRYPTO_CIPHER_CAMELLIA_SW, NULL);
}

See also

See Camellia for details on how to configure the performance and footprint of this algorithm.

Plug-in hardware accelerators

SEGGER security products are written in a way such that underlying cryptographic operations can be exchanged in order to benefit from hardware acceleration or vendor libraries optimized for a particular device.

emSSL requires no additional hardware in order to execute its underlying cryptographic operations: public key algorithms, bulk encipherment, and message authentication are completely implemented in software. However, there are many devices that offer hardware acceleration for one or more of these operations and there is nothing that prevents emSSL from utilizing any such capability.

For further information on hardware acceleration, refer to the following sections:

For background information on hardware acceleration, refer to Hardware acceleration.

LPC18S and LPC43S AES ROM (Add-on)

The LPC18Sxx and LPC43Sxx microcontrollers provide an AES-128 hardware accelerator. The capabilities of this accelerator are exposed through a ROM-based API which insulates the programmer from changes to or variants of the underlying accelerator hardware.

emSSL has specialized hardware-assisted AES ciphering for the following cryptographic algorithms:

All other AES-128 cipher modes (e.g. AES-GCM and AES-CCM) use hardware-assisted ciphering of individual blocks with software managing the cipher mode. All ciphering with AES-192 and AES-256 falls back to using a pure software AES kernel.

Installing LPC ROM hardware support

The following hardware-assisted interfaces are available:

extern const CRYPTO_CIPHER_API CRYPTO_CIPHER_AES_HW_LPC_ROM;

If all you require is AES-128, you can install hardware support using:

void CRYPTO_X_Config(void) {
  CRYPTO_AES_Install(&CRYPTO_CIPHER_AES_HW_LPC_ROM, 0);
}

However, if you require AES-192 or AES-256 in addition to AES-128, you must install a software fallback for these key sizes:

void CRYPTO_X_Config(void) {
  CRYPTO_AES_Install(&CRYPTO_CIPHER_AES_HW_LPC_ROM,
                     &CRYPTO_CIPHER_AES_SW);
}
LPC cryptographic units

The emSSL implementation of hardware assistance requires one cryptographic unit with index #0 that covers ciphering. See CRYPTO-OS integration for further details.

Sample LPS18S setup

The following is the cryptographic setup for the NXP LPCXpresso18S37 board:

/*********************************************************************
*               (c) SEGGER Microcontroller GmbH & Co. KG             *
*                        The Embedded Experts                        *
*                           www.segger.com                           *
**********************************************************************

-------------------------- END-OF-HEADER -----------------------------

File        : CRYPTO_X_Config_LPC18S37.c
Purpose     : Configure CRYPTO for LPC18S37 devices.

*/

/*********************************************************************
*
*       #include Section
*
**********************************************************************
*/

#include "CRYPTO.h"

/*********************************************************************
*
*       Public code
*
**********************************************************************
*/

/*********************************************************************
*
*       CRYPTO_X_Panic()
*
*  Function description
*    Hang when something unexpected happens.
*/
void CRYPTO_X_Panic(void) {
  for (;;) {
    /* Hang */
  }
}

/*********************************************************************
*
*       CRYPTO_X_Config()
*
*  Function description
*    Configure hardware assist for CRYPTO component.
*/
void CRYPTO_X_Config(void) {
 CRYPTO_AES_Install       (&CRYPTO_CIPHER_AES_HW_LPC_ROM, &CRYPTO_CIPHER_AES_SW);
 CRYPTO_TDES_Install      (&CRYPTO_CIPHER_TDES_SW,        0);
 CRYPTO_MD5_Install       (&CRYPTO_HASH_MD5_SW,           0);
 CRYPTO_SHA1_Install      (&CRYPTO_HASH_SHA1_SW,          0);
 CRYPTO_SHA256_Install    (&CRYPTO_HASH_SHA256_SW,        0);
 CRYPTO_SHA512_Install    (&CRYPTO_HASH_SHA512_SW,        0);
 CRYPTO_RIPEMD160_Install (&CRYPTO_HASH_RIPEMD160_SW,     0);
}

/*************************** End of file ****************************/
Kinetis CAU coprocessor (Add-on)

The Kinetis Cryptographic Acceleration Unit (CAU) is a primitive accelerator presented as a memory-mapped peripheral.

emSSL has specialized hardware-assisted ciphering and hashing support for the following cryptographic algorithms using the CAU:

All other cipher modes (e.g. AES-GCM and AES-CCM) use hardware-assisted ciphering of individual blocks with software manging the cipher mode.

Installing CAU hardware support

The following hardware-assisted interfaces are available:

extern const CRYPTO_CIPHER_API CRYPTO_CIPHER_AES_HW_Kinetis_CAU;
extern const CRYPTO_CIPHER_API CRYPTO_CIPHER_TDES_HW_Kinetis_CAU;
extern const CRYPTO_HASH_API   CRYPTO_HASH_MD5_HW_Kinetis_CAU;
extern const CRYPTO_HASH_API   CRYPTO_HASH_SHA1_HW_Kinetis_CAU;
extern const CRYPTO_HASH_API   CRYPTO_HASH_SHA224_HW_Kinetis_CAU;
extern const CRYPTO_HASH_API   CRYPTO_HASH_SHA256_HW_Kinetis_CAU;

You can install hardware support using:

void CRYPTO_X_Config(void) {
  CRYPTO_MD5_Install   (&CRYPTO_HASH_MD5_HW_Kinetis_CAU,    NULL);
  CRYPTO_SHA1_Install  (&CRYPTO_HASH_SHA1_HW_Kinetis_CAU,   NULL);
  CRYPTO_SHA224_Install(&CRYPTO_HASH_SHA224_HW_Kinetis_CAU, NULL);
  CRYPTO_SHA256_Install(&CRYPTO_HASH_SHA256_HW_Kinetis_CAU, NULL);
  CRYPTO_AES_Install   (&CRYPTO_CIPHER_AES_HW_Kinetis_CAU,  NULL);
  CRYPTO_TDES_Install  (&CRYPTO_CIPHER_TDES_HW_Kinetis_CAU, NULL);
}

Note

Whilst there is an MD5 accelerator, hardware-assisted MD5 is slower than a pure software implementation of MD5 using Thumb-2 so we recommend that you do not install the MD5 accelerator.

Kinetis cryptographic units

The emSSL implementation of hardware assistance requires one cryptographic unit with index #0 covering both ciphering and hashing. See CRYPTO-OS integration for further details.

Sample Kinetis setup

The following is the cryptographic setup for the SEGGER emPower board based on the Kinetis K66 device.

/*********************************************************************
*               (c) SEGGER Microcontroller GmbH & Co. KG             *
*                        The Embedded Experts                        *
*                           www.segger.com                           *
**********************************************************************

-------------------------- END-OF-HEADER -----------------------------
File        : CRYPTO_X_Config_K66.c
Purpose     : Configure CRYPTO for K66 devices.

*/

/*********************************************************************
*
*       #include Section
*
**********************************************************************
*/

#include "CRYPTO.h"

/*********************************************************************
*
*       Public code
*
**********************************************************************
*/

/*********************************************************************
*
*       CRYPTO_X_Panic()
*
*  Function description
*    Hang when something unexpected happens.
*/
void CRYPTO_X_Panic(void) {
  for (;;) {
    /* Hang */
  }
}

/*********************************************************************
*
*       CRYPTO_X_Config()
*
*  Function description
*    Configure hardware assist for CRYPTO component.
*/
void CRYPTO_X_Config(void) {
  volatile U32 *pReg;
  //
  // Install hardware assistance.
  //
  CRYPTO_MD5_Install      (&CRYPTO_HASH_MD5_HW_Kinetis_CAU,    NULL);
  CRYPTO_SHA1_Install     (&CRYPTO_HASH_SHA1_HW_Kinetis_CAU,   NULL);
  CRYPTO_SHA224_Install   (&CRYPTO_HASH_SHA224_HW_Kinetis_CAU, NULL);
  CRYPTO_SHA256_Install   (&CRYPTO_HASH_SHA256_HW_Kinetis_CAU, NULL);
  CRYPTO_AES_Install      (&CRYPTO_CIPHER_AES_HW_Kinetis_CAU,  NULL);
  CRYPTO_TDES_Install     (&CRYPTO_CIPHER_TDES_HW_Kinetis_CAU, NULL);
  //
  // Software ciphers.
  //
  CRYPTO_CAST_Install     (&CRYPTO_CIPHER_CAST_SW,     NULL);
  CRYPTO_SEED_Install     (&CRYPTO_CIPHER_SEED_SW,     NULL);
  CRYPTO_ARIA_Install     (&CRYPTO_CIPHER_ARIA_SW,     NULL);
  CRYPTO_CAMELLIA_Install (&CRYPTO_CIPHER_CAMELLIA_SW, NULL);
  CRYPTO_BLOWFISH_Install (&CRYPTO_CIPHER_BLOWFISH_SW, NULL);
  CRYPTO_TWOFISH_Install  (&CRYPTO_CIPHER_TWOFISH_SW,  NULL);
  //
  // Software hashing.
  //
  CRYPTO_SHA512_Install   (&CRYPTO_HASH_SHA512_SW,    NULL);
  CRYPTO_RIPEMD160_Install(&CRYPTO_HASH_RIPEMD160_SW, NULL);
  //
  // Turn on clocks to RNGA, bit 0 of SIM_SCGC3, and install RNG.
  //
  pReg = (void *)0x40048030;
  *pReg |= 1;
  //
  // Install Hash_DRBG-SHA-256 with RNGA entropy.
  //
  CRYPTO_RNG_InstallEx(&CRYPTO_RNG_DRBG_HASH_SHA256, &CRYPTO_RNG_HW_Kinetis_RNGA);
  //
  // Install small modular exponentiation functions.
  //
  CRYPTO_MPI_SetPublicModExp (CRYPTO_MPI_ModExp_Basic_Fast);
  CRYPTO_MPI_SetPrivateModExp(CRYPTO_MPI_ModExp_Basic_Fast);
}

/*************************** End of file ****************************/
iMX RT10xx data coprocessor (Add-on)

The iMX RT10xx Data Coprocessor (DCP) is a programmable crotographic accelerator presented as a memory-mapped peripheral.

emSSL has specialized hardware-assisted ciphering and hashing support for the following cryptographic algorithms using the DCP:

All other cipher modes (e.g. AES-GCM and AES-CCM) use hardware-assisted ciphering of individual blocks with software manging the cipher mode.

Installing iMX RT10xx hardware support

The following hardware-assisted interfaces are available:

extern const CRYPTO_CIPHER_API CRYPTO_CIPHER_AES_HW_RT10xx_DCP;
extern const CRYPTO_HASH_API   CRYPTO_HASH_SHA1_HW_RT10xx_DCP;
extern const CRYPTO_HASH_API   CRYPTO_HASH_SHA256_HW_RT10xx_DCP;

You can install hardware support using:

void CRYPTO_X_Config(void) {
  CRYPTO_SHA1_Install  (&CRYPTO_HASH_SHA1_HW_RT10xx_DCP,
                        &CRYPTO_HASH_SHA1_SW);
  CRYPTO_SHA256_Install(&CRYPTO_HASH_SHA256_HW_RT10xx_DCP,
                        &CRYPTO_HASH_SHA256_SW);
  CRYPTO_AES_Install   (&CRYPTO_CIPHER_AES_HW_RT10xx_DCP,
                        &CRYPTO_CIPHER_AES_SW);
  //
  // Install Hash_DRBG-SHA-256 with TRNG entropy.
  //
  CRYPTO_RNG_InstallEx(&CRYPTO_RNG_DRBG_HASH_SHA256,
                       &CRYPTO_RNG_HW_RT10xx_TRNG);
}
RT10xx cryptographic units

The emSSL implementation of hardware assistance requires one cryptographic unit with index #0 covering both ciphering and hashing. See CRYPTO-OS integration for further details.

Sample Kinetis setup

The following is the cryptographic setup for the SEGGER RT1051 Trace Reference board.

/*********************************************************************
*                   (c) SEGGER Microcontroller GmbH                  *
*                        The Embedded Experts                        *
*                           www.segger.com                           *
**********************************************************************

-------------------------- END-OF-HEADER -----------------------------

File        : CRYPTO_X_Config_RT10xx.c
Purpose     : Configure CRYPTO for iMX RT10xx devices.

*/

/*********************************************************************
*
*       #include Section
*
**********************************************************************
*/

#include "CRYPTO.h"

/*********************************************************************
*
*       Public code
*
**********************************************************************
*/

/*********************************************************************
*
*       CRYPTO_X_Panic()
*
*  Function description
*    Hang when something unexpected happens.
*/
void