ST AN3967 Application note

Secure socket layer (SSL) for STM32F417xx microcontrollers

1 Introduction

STM32F417xx microcontrollers feature a complete 10/100 Mbit/s Ethernet peripheral that
supports both the Media Independent Interface (MII) and Reduced Media Independent
Interface (RMII) to interface with the Physical Layer (PHY), with hardware checksums of the
IP, UDP, TCP and ICMP protocols.

One of the advanced features of the STM32F417xx is the hardware cryptographic processor
for AES/128/192/256, Triple DES, DES, SHA-1, MD5 and RNG.

Secure Sockets Layer (SSL) and Transport Layer Security (TLS) cryptographic protocols
provide security for communications over networks, such as the Internet, and allow client
and server applications to communicate in a way that is private and secure.

The purpose of this application note is to present a demonstration package built on top of a
free SSL/TLS library: the PolarSSL library.

AN3967

Application note

This application note is structured as follows:

● A short glossary is provided in Section 2.

● A general introduction to SSL/TLS is presented in Section 3.

● Section 4 introduces the PolarSSL library.

● Section 5 describes the STM32F417xx hardware cryptographic processors.

● Lastly, Section 6 describes the demonstration package for STM32F417xx.

Note: This application targets only STM32F417xx devices, since the cryptographic acceleration is

not embedded in STM32F407xx devices, and it uses the STM3241G-EVAL board as a
hardware platform.

October 2011 Doc ID 022106 Rev 1 1/41

www.st.com

Contents AN3967

Contents

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

2 Acronyms and definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3 SSL / TLS protocol overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3.1 SSL application layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3.2 History of the SSL / TLS protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

3.3 SSL / TLS sub-protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

3.3.1 SSL Handshake protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3.3.2 SSL Record protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3.3.3 SSL Alert protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3.3.4 Change Cipher Spec protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

4 PolarSSL library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

4.1 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

5 STM32F417xx hardware cryptography . . . . . . . . . . . . . . . . . . . . . . . . . 14

5.1 Cryptographic processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

5.2 Random number generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

5.3 Hash processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

6 Description of the demonstration package . . . . . . . . . . . . . . . . . . . . . 15

6.1 Package directories and firmware components . . . . . . . . . . . . . . . . . . . . 15

6.1.1 Package directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

6.1.2 Firmware components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

6.2 Demonstration settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

6.2.1 PHY interface configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

6.2.2 MAC and IP address settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

6.2.3 STM3241G-EVAL settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

6.3 How to use the demonstration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

6.3.1 SSL client demonstration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

6.3.2 SSL server demonstration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

6.4 Memory footprint of the SSL demonstrations . . . . . . . . . . . . . . . . . . . . . . 27

6.4.1 SSL client demonstration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

2/41 Doc ID 022106 Rev 1

AN3967 Contents

6.4.2 SSL server demonstration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

7 Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

8 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Appendix A Additional information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

A.1 Flowcharts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

A.2 Project configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

A.2.1 LwIP configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

A.2.2 PolarSSL configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

A.2.3 FreeRTOS configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

A.3 Running SSL server demo with Mozilla 7.0.1 . . . . . . . . . . . . . . . . . . . . . . 36

A.4 Running SSL server demo with IE8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

9 Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Doc ID 022106 Rev 1 3/41

List of tables AN3967

List of tables

Table 1. Acronyms and definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Table 2. STM3241G-EVAL jumpers configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Table 3. SSL client demonstration footprint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Table 4. SSL server demonstration footprint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Table 5. lwIP options for SSL server demonstration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Table 6. lwIP options for SSL client demonstration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Table 7. PolarSSL options: config.h file for SSL server demonstration . . . . . . . . . . . . . . . . . . . . . . 34

Table 8. PolarSSL options: config.h file for SSL client demonstration . . . . . . . . . . . . . . . . . . . . . . . 35

Table 9. FreeRTOS configuration for SSL client demonstration. . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Table 10. FreeRTOS configuration for SSL server demonstration . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Table 11. Document revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

4/41 Doc ID 022106 Rev 1

AN3967 List of figures

List of figures

Figure 1. SSL application architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Figure 2. SSL sub-protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Figure 3. SSL Handshake protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Figure 4. Handshake protocol to resume an SSL session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Figure 5. SSL Record protocol. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Figure 6. Demonstration package structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Figure 7. PolarSSL & LwIP connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Figure 8. SSL client demonstration architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Figure 9. SSL client demonstration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Figure 10. ssl_server application window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Figure 11. HyperTerminal window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Figure 12. SSL server demonstration architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Figure 13. SSL server demonstration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Figure 14. HTML page displayed on successful connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Figure 15. HyperTerminal SSL server connection status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Figure 16. SSL client task flowchart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Figure 17. SSL server task flowchart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Figure 18. Untrusted connection dialog 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Figure 19. Untrusted connection dialog 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Figure 20. Add Security Exception dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Figure 21. Task status page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Figure 22. Cannot display webpage error message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Figure 23. Certificate error message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Figure 24. Task status page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Doc ID 022106 Rev 1 5/41

Acronyms and definitions AN3967

2 Acronyms and definitions

Table 1. Acronyms and definitions

Acronym Definition

AES Advanced Encryption Standard

ANSI American National Standards Institute

API Application Programming Interface

ARC4 Alleged Rivest Cipher 4

ARP Address Resolution Protocol

CA Certification Authority

CBC Cipher Block Chaining

CTR Counter

DES Data Encryption Standard

DHCP Dynamic Host Configuration Protocol

DHM Diffie–Hellman key exchange

ECB Electronic Codebook

FIPS Federal Information Processing Standard

HAVEGE Hardware Volatile Entropy Gathering and Expansion

HMAC Hash Message Authentication Code

HTTP Hypertext Transfer Protocol

HTTPS Secure Hypertext Transfer Protocol

ICMP Internet Control Message Protocol

IETF Internet Engineering Task Force

IGMP Internet Group Management Protocol

LwIP Lightweight IP

MAC Message Authentication Code

MAC address Media Access Control address

MCO Microcontroller Clock Output

MD2 Message Digest Algorithm 2

MII M

PPP Point-to-Point Protocol

RMII Reduced Media Independent Interface

RNG Random Number Generator

RSA Rivest, Shamir, & Adleman

edia Independent Interface

SHA-1 Secure Hashing Algorithm 1

SNMP Simple Network Management Protocol

6/41 Doc ID 022106 Rev 1

AN3967 SSL / TLS protocol overview

Table 1. Acronyms and definitions (continued)

Acronym Definition

SSL Secure Sockets Layer

TCP/IP Transmission Control Protocol/Internet Protocol

TLS Transport Layer Security

UDP User Datagram Protocol

URL Uniform Resource Locator

USART Universal Synchronous & Asynchronous Receiver Transmitter

3 SSL / TLS protocol overview

The Secure Socket Layer (SSL) and Transport Layer Security (TLS) protocols provide
communications security over the Internet and allow client/server applications to
communicate in a way that is private and reliable. These protocols are layered above a
transport protocol such as TCP/IP.

SSL is the standard security technology for creating an encrypted link between server and
client. This link ensures that all communication data remains private and secure.

The major objectives of SSL/TLS are:

● Provide data integrity between two communicating applications.

● Protect information transmitted between server and client.

● Authenticate the server to the client.

● Allow the client and server to select the cryptographic algorithms that they both

support.

● Optionally authenticate the client to the server.

● Use public-key encryption techniques to generate shared secrets.

● Establish an encrypted SSL connection.

3.1 SSL application layers

The SSL/TLS application consists of five layers:

● Application layer: the Application Layer refers to the higher-level protocols used by

most applications for network communication.

● SSL/TLS layer: the SSL/TLS layer provides security communication over the Internet.

● TCP layer: the Transport Layer's responsibilities include end-to-end message transfer

capabilities independent of the underlying network, along with error control,
segmentation, flow control, congestion control, and application addressing.

● IP layer: the Internet Protocol layer is responsible for addressing hosts and routing

packets from a source host to the destination host.

● Physical layer: the Physical Layer consists of the basic hardware transmission

technologies of a network.

Doc ID 022106 Rev 1 7/41

SSL / TLS protocol overview AN3967

Application layer

SSL/TSL layer

TCP layer

IP layer

Physical layer

MS18970V1

Figure 1. SSL application architecture

3.2 History of the SSL / TLS protocols

SSL was developed by Netscape in 1994 to secure transactions over the Internet. Soon
after, the Internet Engineering Task Force (IETF) began work to develop a standard protocol
to provide the same functionality.

● SSL 1.0 (Netscape, 1993): Internal Netscape design.

● SSL 2.0 (Netscape, 1994): This version contained a number of security flaws.

● SSL 3.0 (Netscape, 1996): All Internet browsers support this version of the protocol.

● TLS 1.0 (IETF, 1999): This version was defined in RFC 2246 as an upgrade to SSL 3.0.

“The differences between this protocol and SSL 3.0 are not dramatic, but they are
significant enough that TLS 1.0 and SSL 3.0 do not interoperate”: [1]: RFC 2246: The

TLS protocol version 1.0

Note: The “SSL/TLS” protocols is referred to as “SSL” throughout this document.

3.3 SSL / TLS sub-protocols

The SSL protocol includes four sub-protocols: the SSL Record protocol, the SSL
Handshake protocol, the SSL Alert protocol and the SSL Change Cipher Spec protocol.

Figure 2. SSL sub-protocols

8/41 Doc ID 022106 Rev 1

AN3967 SSL / TLS protocol overview

3.3.1 SSL Handshake protocol

The SSL session state is controlled by the SSL Handshake protocol. This protocol involves
using the SSL record protocol to exchange a series of messages between SSL server and
SSL client when they first start communicating. This exchange of messages is designed to
facilitate the following actions:

● The protocol version SSL 3.0 or TLS 1.0

● Allow the client and server to select the cryptographic algorithms, or ciphers, that they

both support

● Authenticate the server to the client

● Optionally authenticate the client to the server

● Use public-key encryption techniques to generate shared secrets

● Establish an encrypted SSL connection

Figure 3. SSL Handshake protocol

Doc ID 022106 Rev 1 9/41

SSL / TLS protocol overview AN3967

The following is the procedure for SSL Handshake protocol:

1. The client sends a ClientHello message specifying the highest SSL protocol version
(SSL 3.0 or TLS 1.0) it supports, a random number, a list of cipher suites and
compression methods.

2. Server responds with a ServerHello message that contains the chosen protocol
version, another random number, cipher suite and compression method from the
choices offered by the client, and the session ID.

Note: The client and the server must support at least one common cipher suite, or else the

Handshake protocol fails. The server generally chooses the strongest common cipher suite
they both support.

3. The server sends its digital certificate in an optional certificate message, for example,
the server uses X.509 digital certificates.

4. If no certificate is sent, an optional ServerKeyExchange message is sent containing the
server public information.

5. If the server requires a digital certificate for client authentication, an optional
CertificateRequest message is appended.

6. The server sends a ServerHelloDone message indicating the end of this phase of
negotiation.

7. If the server has sent a CertificateRequest message, the client must send its X.509
client certificate in a Certificate message.

8. The client sends a ClientKeyExchange message. This message contains the pre­master secret number used in the generation of the symmetric encryption keys and the
message authentication code (MAC) keys. The client encrypts pre-master secret
number with the public key of the server.

Note: The public key is sent by the server in the digital certificate or in ServerKeyExchange

message.

9. If the client sent a digital certificate to the server, the client sends a CertificateVerify
message signed with the client's private key. By verifying the signature of this message,
the server can explicitly verify the ownership of the client digital certificate.

10. The client sends a ChangeCipherSpec message announcing that the new parameters
(cipher method, keys) have been loaded.

11. The client sends a Finished message; it is the first message encrypted with the new
cipher method and keys.

12. The server responds with a ChangeCipherSpec and a Finished message from its end.

13. The SSL Handshake protocol ends and the encrypted exchange of application data
can be started.

10/41 Doc ID 022106 Rev 1

AN3967 SSL / TLS protocol overview

Resuming SSL session

When the client and the server decide to resume a previous session or to duplicate an
existing session (instead of negotiating new security parameters), the message flow is as
follows:

1. The client sends a ClientHello message using the Session ID of the session to be
resumed.

2. The server checks its session cache for a match. If a match is found, and the server is
willing to re-establish the connection under the specified session state, it sends a
ServerHello message with the same Session ID value.

3. Both client and server must send ChangeCipherSpec messages and proceed directly
to the Finished messages.

4. Once the re-establishment is complete, the client and server may begin to exchange
encrypted application data.

Note: If a Session ID match is not found, the server generates a new session ID and the client and

server perform a full Handshake protocol [1]: RFC 2246: The TLS protocol version 1.0.

Figure 4. Handshake protocol to resume an SSL session

Doc ID 022106 Rev 1 11/41

SSL / TLS protocol overview AN3967

Application data

-F1- -F2- -Fn-

Compression

Fragment

Authentification

Encryption

MS18971V1

3.3.2 SSL Record protocol

The Record protocol takes messages to be transmitted, fragments the data into
manageable blocks, optionally compresses the data, applies a MAC, encrypts, and
transmits the results.

The received data is decrypted, verified, decompressed, and reassembled, then delivered to
higher level clients.

Figure 5. SSL Record protocol

3.3.3 SSL Alert protocol

The SSL Alert protocol signals problems with the SSL session ranging from simple warnings
(unknown certificate, revoked certificate, expired certificate) to fatal error messages that
immediately terminate the SSL connection.

3.3.4 Change Cipher Spec protocol

The SSL Change Cipher Spec protocol consists of a single message that indicates the end
of the SSL Handshake protocol.

Note: For more information about SSL protocols, please refer to [1]: RFC 2246: The TLS protocol

version 1.0.

12/41 Doc ID 022106 Rev 1

AN3967 PolarSSL library

4 PolarSSL library

PolarSSL is a light-weight open source cryptographic and SSL/TLS library written in C. This
library contains all needed functions to implement an SSL/TLS server or client. It contains
also a set of hashing functions and cryptographic algorithms.

Features:

● SSL 3.0 and TLS 1.0 client/server support

● X.509 digital certificate

● Symmetric encryption algorithms: AES, Triple DES, DES, ARC4, Camellia,…

● Hash functions: MD2, MD4, MD5, SHA-1, SHA-256, SHA-384, SHA-512

● Message authentication code: HMAC MD2, HMAC MD4, HMAC MD5, HMAC SHA-1

● Software random number generator: HAVEGE

● Public key cryptography: RSA and Diffie-Hellman (DHM) key exchange

The source code of the PolarSSL library can be downloaded from this link:
http://polarssl.org/download_overview

4.1 License

PolarSSL is licensed according to the dual licensing model. PolarSSL is available under the
open source GPL version 2 license, as well as under a commercial license for closed source
projects.

For detailed information about licensing, please refer to the PolarSSL licensing webpage
http://polarssl.org/licensing

Doc ID 022106 Rev 1 13/41