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:
- Highly modular such that unused features are never linked into the application.
- Be completely runtime configurable, adding each modular feature as needed.
- Present a simple user-level API that is easy to use without extensive setup.
- Easy to maintain both by SEGGER and anybody with access to the sources.
- Conform to all necessary standards and current best practices.
- Be efficient both in terms of resource usage and execution speed.
- Target 8-bit to 32-bit processors with limited resources as well as workstations.
- Provide easily-substituted cryptography for customers that require it.
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:
- ISO/ANSI C source code.
- High performance.
- Small footprint.
- Runs “out-of-the-box”.
- Highly compact implementation runs effortlessly on single-chip MCUs.
- Standard support for TLS versions 1.0, 1.1, and 1.2.
- Easy-to-understand and simple-to-use API.
- Simple configuration.
- Secure any open channel (e.g. serial line or wireless link).
- Wide range of pluggable cipher suites for interoperability with popular servers.
- Modular architecture links only what you need.
- Plug-in hardware acceleration.
- Leading-edge cipher suites for confidentiality, integrity and authentication.
- Diffie-Hellman Ephemeral cipher suites for forward secrecy.
- Elliptic curve cipher suites for reduced certificate and key sizes.
- Royalty-free.
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:
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:
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:
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:
- The hexadecimal ID of the agreed cipher suite.
- The IANA name for the agreed cipher suite (without the “TLS_” prefix).
- The TLS protocol version that was agreed between emSSL and the host.
- The type of public key used for key exchange.
- How long the connection took to set up and agree.
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:
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:
emSSL will then display its configuration and indicate that it’s 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:
- Connects to the ROT13 server
- Sends the text “SEGGER - The Embedded Experts” to the server
- Receives the response “FRTTRE - Gur Rzorqqrq Rkcregf” from the server
- Sends the text “FRTTRE - Gur Rzorqqrq Rkcregf” to the server
- Receives the response “SEGGER - The Embedded Experts” from the server
- Does the same for “SEGGER - It simply works!”
- Closes the connection
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:
- Accepts a connection from a client
- Receives the text “SEGGER - The Embedded Experts” from the client
- Send the response “FRTTRE - Gur Rzorqqrq Rkcregf” to the client
- Receives the text “FRTTRE - Gur Rzorqqrq Rkcregf” from the client
- Send the response “SEGGER - The Embedded Experts” to the client
- Does the same for “SEGGER - It simply works!”
- Sees that client drops the connection
- Waits for another connection
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.
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:
- Initialize IP networking and SSL.
- Connect a plain socket to the ROT13 port on the remote server.
- Upgrade the socket to secure by negotiating a TLS session.
- Send data to be transformed to the server.
- Receive transformed data from the server.
- Close the connection and exit.
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:
- You are using emSSL as a server, or
- You are using emSSL as a client but the server requires mutual authentication.
Types of certificate
There are three types of certificate that a Internet-facing server
can provide:
- RSA certificate
- DSA certificate
- ECDSA certificate
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:
- Create a private and public key pair. It is imperative that
the private key remains private and that you secure it against theft.
- Publish the public key, together with identification information,
as an X.509 RSA certificate. The public key is, by definition, public
and does not require protection.
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:
- Generate a set of DSA parameters, called a DSA domain
- Using the DSA domain, generate a private DSA key
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:
- NIST P-224 which is known as secp224r1.
- NIST P-384 which is known as secp384r1.
- NIST P-521 which is known as secp521r1.
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_CERTIFICATE_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 26400
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_GENERAL (1uL << 16)
#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_GENERAL | Log generally useful information. |
| 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().
Data types
The table below lists the types provided by the emSSL API. Detailed
description of each type is found in the sections that follow.
SSL_SEND_FUNC
Description
Send data to network.
Type definition
typedef int SSL_SEND_FUNC( int Socket,
const char * pData,
int Len,
int Flags);
Parameters
| Parameter | Description |
|---|
| Socket | Handle for socket to send to. |
| pData | Pointer to data to send. |
| Len | Number of octets to send. |
| Flags | Transport-based flags; none defined by emSSL. |
Return value
SSL_RECV_FUNC
Description
Receive data from network.
Type definition
typedef int SSL_RECV_FUNC(int Socket,
char * pData,
int Len,
int Flags);
Parameters
| Parameter | Description |
|---|
| Socket | Handle for socket to receive from. |
| pData | Pointer to object which receives the data. |
| Len | Maximum number of octets to receive. |
| Flags | Transport-based flags; none defined by emSSL. |
Return value
| ≥ 0 | Success, number of bytes received. |
| < 0 | Error. |
SSL_GET_TIME_FUNC
Description
Get time of day.
Type definition
typedef U32 SSL_GET_TIME_FUNC(void);
Return value
Number of seconds elapsed since 01/01/70.
SSL_IS_UDP_FUNC
Description
Inquire if transport is UDP (datagram).
Type definition
typedef int SSL_IS_UDP_FUNC(void);
Return value
| = 0 | Transport is TCP for TLS. |
| ≠ 0 | Transport is UDP for DTLS. |
SSL_TRANSPORT_API
Description
Transport-level functions for TLS protocol.
Type definition
typedef struct {
SSL_SEND_FUNC * pfSend;
SSL_RECV_FUNC * pfReceive;
SSL_GET_TIME_FUNC * pfGetTime;
SSL_IS_UDP_FUNC * pfIsUDP;
} SSL_TRANSPORT_API;
Structure members
| Member | Description |
|---|
| pfSend | Send data to network |
| pfReceive | Receive data from network |
| pfGetTime | Get current time |
| pfIsUDP | Inquire if transport is UDP (datagram) |
The table below lists the functions that return emSSL information.
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.
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.
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.
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 or IP address 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 and checked
against the Common Name or Subject Alternative Name in the
presented X.509 certificate.
If sServerName is a valid dotted-decimal IPv4 address, it is
checked against the IP address presented in the Subject Alternative
Name extension in the presented X.509 certificate.
If sServerName is the null pointer, the Server Name Indication
extension is not included in the SSL handshake and no name check
is performed against the presented X.509 certificate.
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.
Note that this function sets the TLS version to use, independent
of the transport layer. For reference, DTLS 1.0 uses the TLS 1.1
protocol and DTLS 1.2 uses the TLS 1.2 protocol.
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.
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:
- SSL_PROTOCOL_ID_SSL_3v0
- SSL_PROTOCOL_ID_TLS_1v0
- SSL_PROTOCOL_ID_TLS_1v1
- SSL_PROTOCOL_ID_TLS_1v2
Diagnostic functions
The table below lists the diagnostic functions provided by the emSSL API.
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:
- Added Curve25519 elliptic curve.
- Added Chacha20-Poly1305 cipher suites and AEAD cipher.
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:
- Removed the API SSL_PRF_Add.
- Added Camellia, ARIA, and SEED cipher suites.
- Added Camellia, ARIA, and SEED ciphers.
Version 2.30
The following are the API changes in this version:
- Removed the requirement to add PRFs. The API SSL_PRF_Add
remains for now but has no effect: it is scheduled for removal in
a future release.
- Added SSL_ROOT_CERTIFICATE_Add() to install root certificates.
- Added SSL_SESSION_SetFlags() to set per-session configuration flags.
- Added capability to request and respond with client certificates.
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:
- The key exchange method, for instance RSA or ECDHE-ECDSA
- The bulk / AEAD cipher, for instance 3DES-EDE-CBC or AES-256-GCM
- The message authentication scheme, for instance MD5 or SHA384
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:
- TLS--ECDHE--ECDSA--WITH--AES--256--CBC--SHA384
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:
- SSL_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
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
- SSL_SUITE_ECDHE_ECDSA_WITH_NULL_SHA
- SSL_SUITE_ECDHE_ECDSA_WITH_RC4_128_SHA
- SSL_SUITE_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
- SSL_SUITE_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
- SSL_SUITE_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
- SSL_SUITE_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
- SSL_SUITE_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
- SSL_SUITE_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
- SSL_SUITE_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
- SSL_SUITE_ECDHE_ECDSA_WITH_AES_128_CCM
- SSL_SUITE_ECDHE_ECDSA_WITH_AES_256_CCM
- SSL_SUITE_ECDHE_ECDSA_WITH_AES_128_CCM_8
- SSL_SUITE_ECDHE_ECDSA_WITH_AES_256_CCM_8
- SSL_SUITE_ECDHE_ECDSA_WITH_ARIA_128_CBC_SHA256
- SSL_SUITE_ECDHE_ECDSA_WITH_ARIA_256_CBC_SHA384
- SSL_SUITE_ECDHE_ECDSA_WITH_ARIA_128_GCM_SHA256
- SSL_SUITE_ECDHE_ECDSA_WITH_ARIA_256_GCM_SHA384
- SSL_SUITE_ECDHE_ECDSA_WITH_CAMELLIA_128_CBC_SHA256
- SSL_SUITE_ECDHE_ECDSA_WITH_CAMELLIA_256_CBC_SHA384
- SSL_SUITE_ECDHE_ECDSA_WITH_CAMELLIA_128_GCM_SHA256
- SSL_SUITE_ECDHE_ECDSA_WITH_CAMELLIA_256_GCM_SHA384
- SSL_SUITE_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
ECDHE-RSA
- SSL_SUITE_ECDHE_RSA_WITH_NULL_SHA
- SSL_SUITE_ECDHE_RSA_WITH_RC4_128_SHA
- SSL_SUITE_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
- SSL_SUITE_ECDHE_RSA_WITH_AES_128_CBC_SHA
- SSL_SUITE_ECDHE_RSA_WITH_AES_256_CBC_SHA
- SSL_SUITE_ECDHE_RSA_WITH_AES_128_CBC_SHA256
- SSL_SUITE_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- SSL_SUITE_ECDHE_RSA_WITH_AES_256_CBC_SHA384
- SSL_SUITE_ECDHE_RSA_WITH_AES_256_GCM_SHA384
- SSL_SUITE_ECDHE_RSA_WITH_ARIA_128_CBC_SHA256
- SSL_SUITE_ECDHE_RSA_WITH_ARIA_128_GCM_SHA256
- SSL_SUITE_ECDHE_RSA_WITH_ARIA_256_CBC_SHA384
- SSL_SUITE_ECDHE_RSA_WITH_ARIA_256_GCM_SHA384
- SSL_SUITE_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256
- SSL_SUITE_ECDHE_RSA_WITH_CAMELLIA_128_GCM_SHA256
- SSL_SUITE_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384
- SSL_SUITE_ECDHE_RSA_WITH_CAMELLIA_256_GCM_SHA384
- SSL_SUITE_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
ECDH-RSA
- SSL_SUITE_ECDH_RSA_WITH_NULL_SHA
- SSL_SUITE_ECDH_RSA_WITH_RC4_128_SHA
- SSL_SUITE_ECDH_RSA_WITH_3DES_EDE_CBC_SHA
- SSL_SUITE_ECDH_RSA_WITH_AES_128_CBC_SHA
- SSL_SUITE_ECDH_RSA_WITH_AES_256_CBC_SHA
- SSL_SUITE_ECDH_RSA_WITH_AES_128_CBC_SHA256
- SSL_SUITE_ECDH_RSA_WITH_AES_128_GCM_SHA256
- SSL_SUITE_ECDH_RSA_WITH_AES_256_CBC_SHA384
- SSL_SUITE_ECDH_RSA_WITH_AES_256_GCM_SHA384
- SSL_SUITE_ECDH_RSA_WITH_ARIA_128_CBC_SHA256
- SSL_SUITE_ECDH_RSA_WITH_ARIA_128_GCM_SHA256
- SSL_SUITE_ECDH_RSA_WITH_ARIA_256_CBC_SHA384
- SSL_SUITE_ECDH_RSA_WITH_ARIA_256_GCM_SHA384
- SSL_SUITE_ECDH_RSA_WITH_CAMELLIA_128_CBC_SHA256
- SSL_SUITE_ECDH_RSA_WITH_CAMELLIA_128_GCM_SHA256
- SSL_SUITE_ECDH_RSA_WITH_CAMELLIA_256_CBC_SHA384
- SSL_SUITE_ECDH_RSA_WITH_CAMELLIA_256_GCM_SHA384
ECDH-ECDSA
- SSL_SUITE_ECDH_ECDSA_WITH_NULL_SHA
- SSL_SUITE_ECDH_ECDSA_WITH_RC4_128_SHA
- SSL_SUITE_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA
- SSL_SUITE_ECDH_ECDSA_WITH_AES_128_CBC_SHA
- SSL_SUITE_ECDH_ECDSA_WITH_AES_256_CBC_SHA
- SSL_SUITE_ECDH_ECDSA_WITH_AES_128_CBC_SHA256
- SSL_SUITE_ECDH_ECDSA_WITH_AES_128_GCM_SHA256
- SSL_SUITE_ECDH_ECDSA_WITH_AES_256_CBC_SHA384
- SSL_SUITE_ECDH_ECDSA_WITH_AES_256_GCM_SHA384
- SSL_SUITE_ECDH_ECDSA_WITH_ARIA_128_CBC_SHA256
- SSL_SUITE_ECDH_ECDSA_WITH_ARIA_128_GCM_SHA256
- SSL_SUITE_ECDH_ECDSA_WITH_ARIA_256_CBC_SHA384
- SSL_SUITE_ECDH_ECDSA_WITH_ARIA_256_GCM_SHA384
- SSL_SUITE_ECDH_ECDSA_WITH_CAMELLIA_128_CBC_SHA256
- SSL_SUITE_ECDH_ECDSA_WITH_CAMELLIA_128_GCM_SHA256
- SSL_SUITE_ECDH_ECDSA_WITH_CAMELLIA_256_CBC_SHA384
- SSL_SUITE_ECDH_ECDSA_WITH_CAMELLIA_256_GCM_SHA384
DHE-RSA
- SSL_SUITE_DHE_RSA_WITH_3DES_EDE_CBC_SHA
- SSL_SUITE_DHE_RSA_WITH_AES_128_CBC_SHA
- SSL_SUITE_DHE_RSA_WITH_AES_256_CBC_SHA
- SSL_SUITE_DHE_RSA_WITH_AES_128_CBC_SHA256
- SSL_SUITE_DHE_RSA_WITH_AES_256_CBC_SHA256
- SSL_SUITE_DHE_RSA_WITH_AES_256_GCM_SHA384
- SSL_SUITE_DHE_RSA_WITH_AES_128_GCM_SHA256
- SSL_SUITE_DHE_RSA_WITH_AES_128_CCM
- SSL_SUITE_DHE_RSA_WITH_AES_256_CCM
- SSL_SUITE_DHE_RSA_WITH_AES_128_CCM_8
- SSL_SUITE_DHE_RSA_WITH_AES_256_CCM_8
- SSL_SUITE_DHE_RSA_WITH_ARIA_128_CBC_SHA256
- SSL_SUITE_DHE_RSA_WITH_ARIA_256_CBC_SHA384
- SSL_SUITE_DHE_RSA_WITH_ARIA_128_GCM_SHA256
- SSL_SUITE_DHE_RSA_WITH_ARIA_256_GCM_SHA384
- SSL_SUITE_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA
- SSL_SUITE_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA
- SSL_SUITE_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256
- SSL_SUITE_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA256
- SSL_SUITE_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256
RSA
- SSL_SUITE_RSA_WITH_RC4_128_MD5
- SSL_SUITE_RSA_WITH_RC4_128_SHA
- SSL_SUITE_RSA_WITH_3DES_EDE_CBC_SHA
- SSL_SUITE_RSA_WITH_AES_128_CBC_SHA
- SSL_SUITE_RSA_WITH_AES_256_CBC_SHA
- SSL_SUITE_RSA_WITH_AES_128_CBC_SHA256
- SSL_SUITE_RSA_WITH_AES_256_CBC_SHA256
- SSL_SUITE_RSA_WITH_AES_256_GCM_SHA384
- SSL_SUITE_RSA_WITH_AES_128_GCM_SHA256
- SSL_SUITE_RSA_WITH_AES_128_CCM
- SSL_SUITE_RSA_WITH_AES_256_CCM
- SSL_SUITE_RSA_WITH_AES_128_CCM_8
- SSL_SUITE_RSA_WITH_AES_256_CCM_8
- SSL_SUITE_RSA_WITH_ARIA_128_CBC_SHA256
- SSL_SUITE_RSA_WITH_ARIA_256_CBC_SHA384
- SSL_SUITE_RSA_WITH_ARIA_128_GCM_SHA256
- SSL_SUITE_RSA_WITH_ARIA_256_GCM_SHA384
- SSL_SUITE_RSA_WITH_CAMELLIA_128_CBC_SHA
- SSL_SUITE_RSA_WITH_CAMELLIA_256_CBC_SHA
- SSL_SUITE_RSA_WITH_CAMELLIA_128_CBC_SHA256
- SSL_SUITE_RSA_WITH_CAMELLIA_256_CBC_SHA256
- SSL_SUITE_RSA_WITH_CAMELLIA_128_GCM_SHA256
- SSL_SUITE_RSA_WITH_CAMELLIA_256_GCM_SHA384
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:
- SSL_CIPHER_AES_128_CBC_API
- SSL_CIPHER_AES_256_CBC_API
- SSL_CIPHER_AES_128_GCM_API
- SSL_CIPHER_AES_256_GCM_API
- SSL_CIPHER_AES_128_CCM_API
- SSL_CIPHER_AES_256_CCM_API
- SSL_CIPHER_AES_128_CCM_8_API
- SSL_CIPHER_AES_256_CCM_8_API
- SSL_CIPHER_ARIA_128_CBC_API
- SSL_CIPHER_ARIA_256_CBC_API
- SSL_CIPHER_ARIA_128_GCM_API
- SSL_CIPHER_ARIA_256_GCM_API
- SSL_CIPHER_CAMELLIA_128_CBC_API
- SSL_CIPHER_CAMELLIA_256_CBC_API
- SSL_CIPHER_CAMELLIA_128_GCM_API
- SSL_CIPHER_CAMELLIA_256_GCM_API
- SSL_CIPHER_DES_CBC_API
- SSL_CIPHER_3DES_EDE_CBC_API
- SSL_CIPHER_RC4_128_API
- SSL_CIPHER_CHACHA20_POLY1305_API
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:
- SSL_MAC_MD5_API
- SSL_MAC_SHA_API
- SSL_MAC_SHA224_API
- SSL_MAC_SHA256_API
- SSL_MAC_SHA384_API
- SSL_MAC_SHA512_API
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:
- SSL_SIGNATURE_VERIFY_RSA_API
- SSL_SIGNATURE_VERIFY_DSA_API
- SSL_SIGNATURE_VERIFY_ECDSA_API
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:
- SSL_SIGNATURE_VERIFY_RSA_API
- SSL_SIGNATURE_VERIFY_ECDSA_API
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
- 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
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:
- secp192r1 or P-192
- secp224r1 or P-224
- secp256r1 or P-256
- secp384r1 or P-384
- secp521r1 or P-521
The following NIST curves are implemented, but are significantly
slower than the NIST curves above for the same security strength:
- secp192k1
- secp224k1
- secp256k1
The following Brainpool curves are implemented, but are significantly
slower than the NIST curves for the same security strength:
- brainpoolP256r1
- brainpoolP384r1
- brainpoolP512r1
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:
- SSL_PROTOCOL_TLS1v0_API
- SSL_PROTOCOL_TLS1v1_API
- SSL_PROTOCOL_TLS1v2_API
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:
- If the cipher suite ends with -SHA256, PRF-SHA256 is required
- If the cipher suite ends with -SHA384, PRF-SHA384 is required
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:
- Compile-time configuration which defines the static
configuration of the software, selecting the way each particular
algorithm is implemented. Particular configurations are selected
by setting various preprocessor symbols when compiling.
- Runtime configuration where the cryptographic algorithms
are configured for higher-level clients such as emSSL and emSSH.
Particilar configurations are selected by installing cryptographic
services when initializing the cryptographic library.
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:
- 32 — requires the target compiler to support 64-bit types
natively (i.e. unsigned long long or unsigned __int64),
- 16 — which should run on any ISO compiler whose native
integer types are 16 or 32 bit and supports 32-bit unsigned long.
- 8 — 8-bit limb sizes are supported and selecting this size
may well lead to better multiplication performance on 8-bit
architectures.
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 |