emSSL - Transport Layer Security

Segger emSSL- Transport Layer Security

What is emSSL?

emLib
emSSL is a SEGGER software library that enables secure connections across the Internet. emSSL offers both client and server capability.

SSL/TLS is a must-have in nearly every application which is connected to the Internet. Products of the IoT, smart grid or home automation markets benefit from securing their communication.

emSSL offers the possibility to establish a secured connection to any server application from your product. It can be used both target independent in native computer applications, as well as in embedded targets.

Features

Highly compact implementation runs effortlessly on single-chip MCUs!
Easy-to-understand and simple-to-use API reduces getting-started time.
No complicated configuration needed - connect out of the box in seconds, not days
Fully tested embOS/IP drop-in configuration for a flying start!
Integrates with any TCP/IP stack that offers a socket interface
Secure any open channel (e.g. serial line or wireless link), not only network sockets!
Supplied with a wide range of pluggable cipher suites for interoperability with popular servers
Pluggable architecture links only what you need - guaranteed minimal code and data footprint!
Standard support for TLS 1.0, 1.1, and 1.2
Leading-edge cipher suites offer robust confidentiality, integrity and authentication
Diffie-Hellman Ephemeral cipher suites for forward secrecy
Elliptic curve cipher suites for reduced certificate and key sizes
Pluggable,"tagged" memory manager keeps confidential data in crypto memory *
Useful examples provided in source form and as Windows executables for evaluation
Send emails securely with emSSL **

* Optional feature for secure devices that support cryptographic memory. Please contact SEGGER for device support and availability.
** emSSL delivers the secure connection only. An SMTP client is required to send the email.

Why should I use emSSL?

emSSL offers all features for current TLS and includes its latest protocol versions.

emSSL is a high quality product designed to be used easily but without any cutbacks.

emSSL is not covered by an open-source or required-attribution license and can be integrated in any free, commercial, or proprietary product without the obligation to disclose the combined source.

emSSL is provided as source code and offers transparency for all included modules, allowing inspection by auditors.

emSSL is portable. The complete software is written in ANSI C and is compiler and target independent. It can be implemented in PC applications as well as in embedded software.

emSSL is configurable. It is created for high performance and a low memory footprint. The library can be configured to fit any speed or size requirements. Unused features can be excluded, additional features can easily be added.

Supported Cipher Suites

emSSL includes the most commonly used cipher suites, which allows to connect to nearly every TLS-supporting server.
With emSSL the cipher suites can be added dynamically. When the required cipher suites are known it is possible to create a minimal size configuration by not linking in unused algorithms. This is can be done by the compiler/linker automatically. With the included scan suites application it is possible to find out the required cipher suite(s) to connect to a server.
The following list shows the cipher suites which are available in emSSL.

ECDHE-ECDSA-WITH-AES-128-CBC-SHA
ECDHE-ECDSA-WITH-AES-256-CBC-SHA
ECDHE-ECDSA-WITH-AES-128-CBC-SHA-256
ECDHE-ECDSA-WITH-AES-128-GCM-SHA-256
ECDHE-ECDSA-WITH-AES-256-CBC-SHA-384
ECDHE-ECDSA-WITH-AES-256-GCM-SHA-384
ECDHE-ECDSA-WITH-3DES-EDE-CBC-SHA
ECDHE-ECDSA-WITH-RC4-128-SHA

ECDHE-RSA-WITH-AES-128-CBC-SHA
ECDHE-RSA-WITH-AES-256-CBC-SHA
ECDHE-RSA-WITH-AES-128-CBC-SHA-256
ECDHE-RSA-WITH-AES-128-GCM-SHA-256
ECDHE-RSA-WITH-AES-256-CBC-SHA-384
ECDHE-RSA-WITH-AES-256-GCM-SHA-384
ECDHE-RSA-WITH-3DES-EDE-CBC-SHA
ECDHE-RSA-WITH-RC4-128-SHA

DHE-RSA-WITH-AES-256-GCM-SHA-384
DHE-RSA-WITH-AES-128-GCM-SHA-256
DHE-RSA-WITH-AES-128-CBC-SHA-256
DHE-RSA-WITH-AES-256-CBC-SHA-256
DHE-RSA-WITH-AES-128-CBC-SHA
DHE-RSA-WITH-AES-256-CBC-SHA
DHE-RSA-WITH-3DES-EDE-CBC-SHA

ECDH-RSA-WITH-AES-128-CBC-SHA
ECDH-RSA-WITH-AES-256-CBC-SHA
ECDH-RSA-WITH-AES-128-CBC-SHA-256
ECDH-RSA-WITH-AES-128-GCM-SHA-256
ECDH-RSA-WITH-AES-256-CBC-SHA-384
ECDH-RSA-WITH-AES-256-GCM-SHA-384
ECDH-RSA-WITH-3DES-EDE-CBC-SHA
ECDH-RSA-WITH-RC4-128-SHA

ECDH-ECDSA-WITH-AES-128-CBC-SHA
ECDH-ECDSA-WITH-AES-256-CBC-SHA
ECDH-ECDSA-WITH-AES-128-CBC-SHA-256
ECDH-ECDSA-WITH-AES-128-GCM-SHA-256
ECDH-ECDSA-WITH-AES-256-CBC-SHA-384
ECDH-ECDSA-WITH-AES-256-GCM-SHA-384
ECDH-ECDSA-WITH-3DES-EDE-CBC-SHA
ECDH-ECDSA-WITH-RC4-128-SHA

Performance

emSSL is built for high performance with target independent code. It is completely written in ANSI C and can be used in any embedded application, as well as in PC applications.

Performance Test

The following results show the connection time of a Cortex-M4, running at 200MHz from internal flash memory, using internal RAM.

Cipher Suite	RSA key length [bit]	SSL time [ms]1
RSA-WITH-AES-256-CBC-SHA-256	2048	64
ECDHE-RSA-WITH-AES-256-CBC-SHA	2048	470

1: Results may vary depending on the compiler, compiler settings and memory timings of the microcontroller used.
The times are measured for the negotiation phase, connecting to www.segger.com and www.google.com with the key exchange algorithms (marked in bold).
Cipher Suite is the used cipher suite for this connection which is supported by emSSL and the server.
SSL time is the time required by emSSL to fully agree the session keys for a secure connection — it excludes transmission and reception times over the IP transport which are highly variable.

Included Applications

emSSL includes some sample utilities in source to show how to use emSSL and as precompiled executables. Applications for benchmark and validation tests are part of the package, too.

Application name	Target platform	Description
BrowseDemo	Windows	Get a webpage via HTTPS and print it to the console.
PrintCert	Windows	Read an X.509 SSL certificate and print its information to the console.
ScanSuites	Windows	Scan a server for its supported cipher suites.
TwitterDemo	Windows	Show Twitter followers of @SEGGERMicro.

Example application

This application opens a connection to the SEGGER web site and retrieves the HTML index document over a fully secured connection. As you can see, emSSL makes working with secure sockets a breeze!

int main(int argc, char * const argv[]) {
 SSL_SESSION Session;
 unsigned    Socket;
 int         Status;
 //
 // Kick off networking and start TLS.
 //
 SYS_IP_Init();
 TLS_Init();
 //
 // Open a plain socket to www.segger.com on the default
 // HTTPS port, 443.
 //
 Socket = SYS_IP_Open("www.segger.com", 443);
 if (Socket < 0) {
 printf("Cannot open www.segger.com:443!\n");
 return 100;
 }
 //
 // Upgrade the connection to secure by negotiating a
 // session using TLS.
 //
 SSL_Prepare(&Session, Socket, &TLS_IP_Transport);
 if (SSL_Connect(&Session, 0, "www.segger.com") < 0) {
 printf("Cannot negotiate a secure connection to www.segger.com:443!\n");
 return 100;
 }
 //
 // We have established a secure connection, so ask the server
 // for some data.  This sends an HTTP GET request to retrieve
 // the default index page.
 //
 SSL_SendStr(&Session, "GET /index.html HTTP/1.0\r\n");
 SSL_SendStr(&Session, "Host: www.segger.com\r\n");
 SSL_SendStr(&Session, "\r\n");
 //
 // Now read the response.  We requested HTTP 1.0 which causes
 // the underlying socket to be closed once the reply is complete,
 // so we have no need to decode the headers.
 //
 for (;;) {
 char acBuf[256];
 Status = SSL_Receive(&Session, acBuf, sizeof(acBuf)-1);
 if (Status < 0) {
 break;
 }
 acBuf[Status] = 0;
 printf("%s", acBuf);
 }
 //
 // Close the TLS connection.
 //
 SSL_Disconnect(&Session);
 SYS_IP_Close(Socket);
 //
 // Finish up.
 //
 SSL_Exit();
 SYS_IP_Exit();
 //
 return 0;
 }

FAQ

Q: Can I use emSSL with my product?
A: Yes. emSSL can be included in nearly every product, independent from the used target, as well as in native computer applications.

Q: Does emSSL support TLS?
A: Yes. emSSL supports TLS 1.0, 1.1 and 1.2.

Q: Does emSSL support older versions of SSL?
A: No. emSSL supports only TLS 1.0 and higher. SSL 3.0 and prior are considered insecure and should not be used.

Q: I want to connect to a specific server with only one cipher suite. Do I have to include the complete emSSL in my project?
A: No. emSSL allows to select which cipher suites will be included. Unused modules can be removed from the project or may not be linked into the application, reducing the size to a minimum.

Q: I want to connect to a server on the internet. Which cipher suites will I need?
A: This depends on the server you want to connect to. emSSL includes an application to scan a server for its available cipher suites. If the server configuration does not change, only one of the available cipher suites needs to be included.

Q: I want to to secure my server with emSSL. Is this possible?
A: Not yet. The server side, including certificate management, will be available in the near future. Feel free to contact info@segger.com for planned releases.

Q:
My question is not listed here. What can I do?
A: If you have any further questions about emSSL, feel free to contact us at info@segger.com

Glossary

The following table explains the abbrevations used in the cipher suite names.

3DES-EDE	Triple data encryption standard algorithm in encrypt-decrypt-encrypt mode.
AES-128/AES-256	Advanced encryption standard algorithms
CBC	Cipher block chaining mode for AES stream ciphers
DHE	Ephemeral diffie-hellman key exchange algorithm.
ECDH	Elliptic curves diffie-hellman key exchange algorithm.
ECDHE	Ephemeral elliptic curves diffie-hellman key exchange algorithm.
ECDSA	Elliptic curves digital signature algorithm.
GCM	Galois/Counter-mode for AES stream ciphers.
MD5	Message-digest algorithm 5.
RC4	RC4 stream cipher algorithm.
RSA	Rivest, Shamir, Adleman crypto system algorithm.
SHA	Secure hash algorithm V1.
SHA-256/SHA-384	Secure hash algorithms (V20