ST AN3967 Application note

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.

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	Media Independent Interface
		PPP	Point-to-Point Protocol
		RMII	Reduced Media Independent Interface
		RNG	Random Number Generator
		RSA	Rivest, Shamir, & Adleman
		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.1SSL 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

Figure 1. SSL application architecture

Application layer

SSL/TSL layer

TCP layer

IP layer

Physical layer

MS18970V1

3.2History 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.3SSL / 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.1SSL 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

3.3.2SSL 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

Application data

Fragment
		-F1-				-F2-		-Fn-

Compression

Authentification

Encryption

MS18971V1

3.3.3SSL 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.4Change 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.1License

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