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.
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 17/41
SSL / TLS protocol overviewAN3967
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 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/41Doc ID 022106 Rev 1
AN3967SSL / 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 19/41
SSL / TLS protocol overviewAN3967
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 premaster 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/41Doc ID 022106 Rev 1
AN3967SSL / 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 111/41
SSL / TLS protocol overviewAN3967
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/41Doc ID 022106 Rev 1
AN3967PolarSSL 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.
●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 113/41
STM32F417xx hardware cryptographyAN3967
5 STM32F417xx hardware cryptography
As described in Section 4, the PolarSSL library contains a set of symmetric encryption
algorithms (AES 128/192/256, Triple DES), hashing functions (MD5, SHA-1) and a software
random number generator (HAVEGE). All these functions and algorithms are needed to
implement an SSL/TLS application.
To off-load the CPU from encryption/decryption, hash and RNG (random number generator)
tasks, all these functions and algorithms are implemented using the hardware acceleration
AES 128/192/256, Triple DES, MD5, SHA-1 and analog RNG embedded in STM32F417xx.
5.1 Cryptographic processor
The cryptographic processor can be used to both encipher and decipher data using the
Triple-DES or AES algorithm. It is a fully compliant implementation of the following
standards:
●The data encryption standard (DES) and Triple-DES (TDES) as defined by the Federal
Information Processing Standards Publication “FIPS PUB 46-3, 1999 October 25”. It
follows the American National Standards Institute (ANSI) X9.52 standard.
●The advanced encryption standard (AES) as defined by Federal Information
Processing Standards Publication “FIPS PUB 197, 2001 November 26”
The CRYP processor may be used for both encryption and decryption in the Electronic
codebook (ECB) mode, the Cipher block chaining (CBC) mode or the Counter (CTR) mode
(in AES only).
5.2 Random number generator
The RNG processor is a random number generator, based on a continuous analog noise,
that provides a random 32-bit value to the host when read.
5.3 Hash processor
The hash processor is a fully compliant implementation of the secure hash algorithm (SHA-
1), the MD5 (message-digest algorithm 5) hash algorithm and the HMAC (keyed-hash
message authentication code) algorithm suitable for a variety of applications. It computes a
message digest (160 bits for the SHA-1 algorithm, 128 bits for the MD5 algorithm) for
messages of up to (2
messages by means of hash functions. HMAC algorithms consist in calling the SHA-1 or
MD5 hash function twice.
Note:For more detailed information, please refer to the CRYP, HASH and RNG sections of [2]:
RM0090: STM32F405xx, STM32F407xx, STM32F415xx and STM32F417xx microcontroller
family reference manual.
64
- 1) bits, while HMAC algorithms provide a way of authenticating
14/41Doc ID 022106 Rev 1
AN3967Description of the demonstration package
6 Description of the demonstration package
The demonstration package contains two demonstrations running on top of the PolarSSL
library and LwIP stack:
●SSL Client demonstration: This demonstration proves the ability of the STM32F417xx
device to exchange messages with a server over TCP/IP connectivity through a SSL
connection. This demonstration allows you to connect the STM3241G-EVAL board to a
secure web server with SSL protocol.
●SSL server demonstration: SSL server is a combination of HTTP with SSL protocol to
provide encryption and secure identification of the server. This demonstration allows
you to connect from a web browser to a STM3241G-EVAL board using SSL protocol.
6.1 Package directories and firmware components
6.1.1 Package directories
The demonstration package consists of five main folders listed below:
●Libraries: This folder contains all the subdirectories and files that make up the core of
the STM32F4xx Standard Peripheral library.
●Project: This folder contains the demo header and source files.
●FreeRTOS: This folder contains the real-time kernel source code and all directories
associated with the scheduler source code.
–include: contains the scheduler header files.
–portable: contains the STM32 specific code, scheduler port layer for compiler and
memory management files.
●LwIP: This folder contains all the header and source files for the TCP/IP stack.
●PolarSSL: This folder contains all the header and source files for the PolarSSL-1.0.0
library.
Doc ID 022106 Rev 115/41
Description of the demonstration packageAN3967
Figure 6.Demonstration package structure
6.1.2 Firmware components
Both demonstrations are based on three software modules: LwIP-1.3.2 (a free TCP/IP
stack), PolarSSL-1.0.0 (a free SSL/TLS library) and FreeRTOS-6.1.0 (a free real-time
kernel). These modules are described below.
LwIP stack
LwIP is a free TCP/IP stack developed by Adam Dunkels at the Swedish Institute of
Computer Science (SICS) and licensed under the BSD license. The source code can be
downloaded from this link: http://download.savannah.gnu.org/releases/lwip/
The lwIP TCP/IP stack supports the following protocols: IPv4, IPv6, UDP, TCP, ICMP, IGMP,
SNMP, ARP and PPP. It does not include protocols from the application layer, like HTTP or
HTTPS.
The lwIP offers three types of API (application programming interface):
●Raw API: native API designed to be used without an operating system. This API is
used by the core stack for interaction between the various protocols.
●Netconn API: sequential API with a higher level of abstraction than the raw API. To use
the Netconn API, an operating system is needed. All packet processing (input and
output) is done inside a dedicated thread (the TCP/IP thread). The application threads
communicate with this core thread using message boxes and semaphores.
●Socket API: based on the Berkeley socket interface (BSD Socket). To use the Socket
API, an operating system is needed.
16/41Doc ID 022106 Rev 1
AN3967Description of the demonstration package
PolarSSL library
PolarSSL is a free library used to implement a secure application based on SSL/TLS
protocols.
The official release of this library does not provide any port to any microcontroller: you need
to do it by yourself. The PolarSSL library comes with a file called net.c that works as an
interface between the library and the LwIP stack. To use PolarSSL, you need to modify this
file to support the specified stack.
net.c contains functions that ensure the transfer of the frames between PolarSSL and the
lwIP stack. Its main functions are:
●net_recv which should be called when a packet is ready to be read from the stack.
●net_send which should be called when a packet is ready to be send to the stack.
The connection layer of PolarSSL uses the socket API to communicate with the TCP/IP
stack.
Note:The API used to build the demonstration is the socket API, which is shared between
PolarSSL and the LwIP stack.
FreeRTOS
FreeRTOS is an open-source mini real-time Kernel for embedded devices. The source code
can be downloaded from this link: http://www.freertos.org/
Features:
●Scheduler operation:
–Preemptive: always runs the highest priority available task.
–Cooperative: context switches only occur if a task blocks, or explicitly calls task
YIELD() (macro used to force a context switch).
●Inter-Process Communication: the communication between tasks is achieved via the
message queue and the binary semaphores.
●The number of available priorities can be changed as needed.
Figure 7.PolarSSL & LwIP connection
Doc ID 022106 Rev 117/41
Description of the demonstration packageAN3967
6.2 Demonstration settings
6.2.1 PHY interface configuration
The demonstration firmware is used to interface the PHY with the two modes: MII and RMII.
To select the PHY interface mode you wish to use, go to the main.h file and choose one of
the two defines:
#define MII_MODE
#define RMII_MODE
For the MII mode, the PHY clock can be taken from the external crystal or provided by the
STM32 via the MCO pin if both MII_MODE and PHY_CLOCK_MCO are defined in the
main.h file.
Note:For RMII mode you have to provide the 50 MHz clock by soldering a 50 MHz oscillator (ref
SM7745HEV-50.0M or equivalent) on the U3 footprint located under CN3 and also removing
jumper on JP5. This oscillator is not provided with the board. For more details, please refer
to STM3240G-EVAL evaluation board User manual UM1461.
18/41Doc ID 022106 Rev 1
AN3967Description of the demonstration package
6.2.2 MAC and IP address settings
The default MAC address is fixed to 00:00:00:00:00:01. To change this address, you can
modify the six bytes defined in the main.h file.
In the SSL client demonstration, the IP address is set as static, the default IP address is
192.168.0.8 defined in the main.h file.
In SSL server demonstration the IP address can be set either as a static address, equal to
192.168.0.8, or as a dynamic address, assigned by a DHCP server.
The selection of the IP address configuration mode is done in the main.h file:
●Uncomment #define USE_DHCP to configure the IP address by DHCP
●Comment #define USE_DHCP to use the static address (192.168.0.8)
Note:If you choose to configure the IP address by DHCP and the application does not find a
DHCP server on the network to which it is already connected, the IP address is
automatically set to the static address (192.168.0.8).
6.2.3 STM3241G-EVAL settings
Once you have set the PHY interface mode, the MAC address and the IP address, you need
to configure the STM3241G-EVAL evaluation board as shown in the following table.
JP62-3: MII interface mode is enabled1-2: RMII interface mode is enabled
JP8Open: MII interface mode is selectedClose: RMII interface mode is selected
JP221-2: RS232 is enabled
1-2: provide 25 MHz clock by external crystal
2-3: provide 25 MHz clock by MCO at PA8
Not fitted
Doc ID 022106 Rev 119/41
Description of the demonstration packageAN3967
6.3 How to use the demonstration
6.3.1 SSL client demonstration
This demonstration consists of using the STM3241G-EVAL board as a client that connects
to a secure server to provide the SSL Handshake protocol.
Demonstration architecture
The SSL client demonstration as shown in Figure 8 contains four tasks:
LED task: Blink LED4 every 200 ms.
Ethernet task: The low-level layer was set to detect the reception of frames by
interrupts. So, when the Ethernet controller receives a valid frame, it generates an
interrupt. In the handling function of this interrupt, a binary semaphore is created to
wake up the Ethernet task. This task transfers the input frames to the TCP/IP stack.
TCP/IP task: All packet processing (input and output) is done inside this thread. The
application threads communicate with this thread using message boxes and
semaphores.
SSL client task: This task handles the SSL Handshake protocol. It connects to an SSL
server and performs the following:
2If you use a firewall, you must be sure that the ssl_server application accepts connection
requests. If it does not, the firewall will reject the client requests.
Figure 9.SSL client demonstration
Doc ID 022106 Rev 121/41
Description of the demonstration packageAN3967
The ssl_server.exe application window is shown in Figure 10. The SSL server
application displays the connection request status; all exchange messages between
the server and the client are displayed.
Figure 10. ssl_server application window
22/41Doc ID 022106 Rev 1
AN3967Description of the demonstration package
HyperTerminal
Figure 11: HyperTerminal window displays the status of the SSL client application
running on the STM32F417xx device (write messages and read messages):
–Status of SSL structures (SSL context, SSL session, SSL RNG)
–Client request to the server: “GET”
–The received message contains the result of Handshake protocol: for example
This demonstration consists of setting up the STM3241G-EVAL board as an SSL server that
waits for a SSL client request to make the connection.
Demonstration architecture
The SSL server demonstration contains five tasks:
The LED, Ethernet, and TCP_IP tasks are the same as the SSL client demonstration
tasks.
SSL server task: This task creates an SSL connection and waits for the client's request
to make the secure connection. When the connection is established, the client sends
Get request to load the html page. This page contains information about the tasks
running in this demonstration. The SSL server task also sends the status of the
connection through USART.
DHCP_Client task: This task is used to configure the IP address by DHCP. To enable
the DHCP client, uncomment the define USE_DHCP in main.h file.
Doc ID 022106 Rev 123/41
Description of the demonstration packageAN3967
Figure 12. SSL server demonstration architecture
How to use the demonstration
First, connect the STM3241G-EVAL board as follows:
●Ethernet link: Connect to a remote PC (through a crossover Ethernet cable) or to your
local network (through a straight Ethernet cable).
●RS232 link (used with HyperTerminal-like application to display debug messages):
Connect a null-modem female/female RS232 cable between the DB9 connector CN16
(USART3) and the PC serial port.
To run the SSL server demonstration:
●Build and program the SSL server code in the STM32F417 Flash.
●Start the STM3241G-EVAL board.
●Open a web browser such as Internet Explorer or Firefox, and type the board's IP
address in the browser, for example https//192.168.0.8.
Note:If you use a firewall, you must be sure that the HTTPS port accepts the connection requests.
If it does not, the firewall will reject the connection.
24/41Doc ID 022106 Rev 1
AN3967Description of the demonstration package
Figure 13. SSL server demonstration
On successful connection, a page is displayed showing the running tasks and their status.
This page contains also the number of page hits and the list of cipher suites used in the
connection.
Figure 14. HTML page displayed on successful connection
Doc ID 022106 Rev 125/41
Description of the demonstration packageAN3967
You can monitor the connection status of the SSL server application running on an
STM32F417xx device, using the HyperTerminal window. This window (Figure 15) shows:
●the status of connection, SSL structures and Handshake protocol,
●the size of the client's request message,
●the size of the server's response (html page).
Figure 15. HyperTerminal SSL server connection status
Note:The first time you connect to the server, you receive a warning message from the browser
about the certificate presented. This warning occurs when the certificate has been issued by
a certification authority (CA) that is not recognized by the browser or when the certificate
was issued to a different web address.
This is due to the fact that the SSL server application uses a self-signed test certificate. It is
safe to continue past this warning (see Appendix A on page 31).
●2 buffers of 1500 bytes constitute the lwIP pool of buffers. These parameters are
defined in the lwipopts.h file by PBUF_POOL_SIZE and PBUF_POOL_BUFSIZE.
●2 Kbytes dedicated to the lwIP's heap and defined in the lwipopts.h file by MEM_SIZE.
●5 buffers of 1520 bytes dedicated to the Ethernet driver and defined in the
stm32f4x7_eth_conf.h file.
These values are provided for demonstration purposes only. So, if you want to port the
current package and use it for your application, the above parameters should be adjusted to
your needs.
Table 3.SSL client demonstration footprint
Flash memory (bytes)SRAM (bytes)
Modules
Ro code Ro data Rw data
Ethernet driver and interface234007816
lwIP memory management and IP modules18894167088
PolarSSL630042755748
FreeRTOS30506413636
Application modules: Main and system
initialization
STM32F4xx Standard Peripherals Library
Drivers
STM324xG-EVAL board1942457644
Others (stack, heap, etc.)2161010044732
Total116326751776365
273602285
2750616
Note:The software is compiled using IAR EWARM v6.21.3, with high optimization for code size.
Doc ID 022106 Rev 127/41
Description of the demonstration packageAN3967
6.4.2 SSL server demonstration
The table below provides the server demonstration footprint, calculated with the following
configuration:
●4 buffers of 1500 bytes that constitute the lwIP pool of buffers. These parameters are
defined in the lwipopts.h file by PBUF_POOL_SIZE and PBUF_POOL_BUFSIZE.
●5 Kbytes dedicated to the lwIP's heap and defined in the lwipopts.h file by MEM_SIZE.
●6 buffers of 1520 bytes dedicated to the Ethernet driver and defined in the
stm32f4x7_eth_conf.h file.
These values are provided for demonstration purposes only. So, if you want to port the
current package and use it for your application, the above parameters should be adjusted to
your needs.
Table 4.SSL server demonstration footprint
Flash memory (bytes)SRAM (bytes)
Modules
Ro code Ro data Rw data
Ethernet driver and interface234009372
lwIP memory management and IP modules217941013888
PolarSSL656747820696
FreeRTOS33101314712
Application modules: Main and system
initialization
STM32F4xx standard peripheral library
drivers
STM324xG-EVAL board1982456344
Others (stack, heap...)216405650620
Total1235261292892301
40364652953
2750116
Note:The software is compiled using IAR EWARM v6.21.3, with high optimization for code size.
28/41Doc ID 022106 Rev 1
AN3967Conclusion
7 Conclusion
This application note describes two STM32F417xx demonstration programs that implement
the PolarSSL library.
The first one demonstrates the ability of the STM32F417xx device to exchange messages
with a server through an SSL connection. This demonstration program allows you to
connect the STM3241G-EVAL board to a secure web server.
The second one is a combination of HTTP with SSL protocol to provide encryption and
secure identification of the server. This demonstration program allows you to connect to an
STM3241G-EVAL board using the SSL protocol from a web browser.
Doc ID 022106 Rev 129/41
ReferencesAN3967
8 References
[1]: RFC 2246: The TLS protocol version 1.0
[2]: RM0090: STM32F405xx, STM32F407xx, STM32F415xx and STM32F417xx
microcontroller family reference manual
30/41Doc ID 022106 Rev 1
AN3967Additional information
MS18969V1
Start
m emset ()
Allocate all Memory (buf
)
havege _ init ()
Initialize the RNG and the
session data
ret
= 0
yes
no
ret = ssl _ write ()
Send
application data
yes
ret = ssl _ read ()
Read the HTTP response
net _ close ()
Close the connection
ssl _ free ()
Cleanup all
memory
End
no
no
ret
= 0
ret > 0
ret = ssl _ init ()
Initialize an SSL context
ret = net _ connect ()
Start the connection
yes
Appendix A Additional information
A.1 Flowcharts
Figure 16. SSL client task flowchart
Doc ID 022106 Rev 131/41
Additional informationAN3967
MS18968V1
Start
Client
connects
no
ret = ssl_ read ()
Read the HTTP Request
ret = ssl_ write ()
Write the response
net_ close ()
Close the connection
ssl_ free ()
Cleanup all memory
End
no
no
ret = 0
ret > 0
Load the certificate
Bind on https port
Wait until a client connects
Initialize the RNG and the
session data
ret= ssl _ handshake ()
Handshake protocol
yes
yes
yes
Figure 17. SSL server task flowchart
32/41Doc ID 022106 Rev 1
AN3967Additional information
A.2 Project configuration
A.2.1 LwIP configuration
Ta bl e 5 lists the lwIP software component configuration. LwIP configuration can be done by
modifying lwipopts.h:
Table 5.lwIP options for SSL server demonstration
OptionValueDescription
MEM_SIZE5 * 1024The size of the heap memory
MEMP_NUM_PBUF5
MEMP_NUM_UDP_PCB 4
MEMP_NUM_TCP_PCB5
MEMP_NUM_TCP_PCB_LISTEN5
PBUF_POOL_SIZE4The number of packet buffers
PBUF_POOL_BUFSIZE1500The size of each pbuf in the pbuf pool.
LWIP_ICMP1Enable ICMP protocol
LWIP_DHCP 1Enable DCHP protocol
LWIP_UDP 1Enable UDP protocol
LWIP_TCP1Enable TCP protocol
TCP_MSS 1460TCP maximum segment size
TCP_WND 2 * TCP_MSS
TCP_SND_BUF 2 * TCP_MSSTCP sender buffer space
The number of buffers sent without
copying
The number of simultaneously active
UDP “connections”
The number of simultaneously active
TCP connections
The number of listening TCP
connections
TCP window size: receive buffer space
in bytes
Table 6.lwIP options for SSL client demonstration
OptionValueDescription
MEM_SIZE2 * 1024The size of the heap memory
MEMP_NUM_PBUF2
MEMP_NUM_UDP_PCB 2
MEMP_NUM_TCP_PCB2
MEMP_NUM_TCP_PCB_LISTEN6
PBUF_POOL_SIZE2The number of packet buffers
PBUF_POOL_BUFSIZE1500The size of each pbuf in the pbuf pool.
Doc ID 022106 Rev 133/41
The number of buffers sent without
copying
The number of simultaneously active
UDP “connections”
The number of simultaneously active
TCP connections
The number of listening TCP
connections
Additional informationAN3967
Table 6.lwIP options for SSL client demonstration (continued)
OptionValueDescription
LWIP_ICMP1Enable ICMP protocol
LWIP_DHCP 1Enable DCHP protocol
LWIP_UDP 1Enable UDP protocol
LWIP_TCP1Enable TCP protocol
TCP_MSS 1460TCP Maximum Segment Size
TCP_WND 2 * TCP_MSS
TCP window size: receive buffer space
in bytes
TCP_SND_BUF 2 * TCP_MSSTCP sender buffer space
A.2.2 PolarSSL configuration
PolarSSL configuration can be done by modifying config.h file; you can enable/disable the
software component by commenting or uncommenting the specific line.
In order to decrease the memory size, unused modules should be commented.
Table 7.PolarSSL options: config.h file for SSL server demonstration
OptionDescription
POLARSSL_DEBUG_MSGEnable all SSL/TLS debugging messages.
The following is the procedure for Running SSL server demo with Mozilla 7.0.1.
1.Open the browser and type in the URL, for example, https://192.168.0.53. The browser
displays a warning message as in Figure 18.
Figure 18. Untrusted connection dialog 1
2. Select I Understand the Risks and an another message will be displayed as in
Figure 19.
Figure 19. Untrusted connection dialog 2
3. Click Add Exception. The browser downloads the (CA) certification authority
certificate.
36/41Doc ID 022106 Rev 1
AN3967Additional information
Figure 20. Add Security Exception dialog
4. Click Confirm Security Exception to start the secure connection as shown in
Figure 20. On successful connection, Figure 21: Task status page is displayed showing
the list of running tasks and their status. This window also contains the number of page
hits.
Figure 21. Task status page
Doc ID 022106 Rev 137/41
Additional informationAN3967
A.4 Running SSL server demo with IE8
The following is the procedure for running the SSL server demo with IE8 (Windows Internet
Explorer 8).
1.Open the browser and type in the URL, for example, https://192.168.0.8. The browser
displays a warning message.
Figure 22. Cannot display webpage error message
2. Refresh the current page.
38/41Doc ID 022106 Rev 1
AN3967Additional information
Figure 23. Certificate error message
3. Select Continue to this website (not recommended): If successful, you should see
the following web page as shown in Figure 24: Task status page.
Figure 24. Task status page
Doc ID 022106 Rev 139/41
Revision historyAN3967
9 Revision history
Table 11.Document revision history
DateRevisionChanges
31-Oct-20111Initial release
40/41Doc ID 022106 Rev 1
AN3967
Please Read Carefully:
Information in this document is provided solely in connection with ST products. STMicroelectronics NV and its subsidiaries (“ST”) reserve the
right to make changes, corrections, modifications or improvements, to this document, and the products and services described herein at any
time, without notice.
All ST products are sold pursuant to ST’s terms and conditions of sale.
Purchasers are solely responsible for the choice, selection and use of the ST products and services described herein, and ST assumes no
liability whatsoever relating to the choice, selection or use of the ST products and services described herein.
No license, express or implied, by estoppel or otherwise, to any intellectual property rights is granted under this document. If any part of this
document refers to any third party products or services it shall not be deemed a license grant by ST for the use of such third party products
or services, or any intellectual property contained therein or considered as a warranty covering the use in any manner whatsoever of such
third party products or services or any intellectual property contained therein.
UNLESS OTHERWISE SET FORTH IN ST’S TERMS AND CONDITIONS OF SALE ST DISCLAIMS ANY EXPRESS OR IMPLIED
WARRANTY WITH RESPECT TO THE USE AND/OR SALE OF ST PRODUCTS INCLUDING WITHOUT LIMITATION IMPLIED
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE (AND THEIR EQUIVALENTS UNDER THE LAWS
OF ANY JURISDICTION), OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT.
UNLESS EXPRESSLY APPROVED IN WRITING BY TWO AUTHORIZED ST REPRESENTATIVES, ST PRODUCTS ARE NOT
RECOMMENDED, AUTHORIZED OR WARRANTED FOR USE IN MILITARY, AIR CRAFT, SPACE, LIFE SAVING, OR LIFE SUSTAINING
APPLICATIONS, NOR IN PRODUCTS OR SYSTEMS WHERE FAILURE OR MALFUNCTION MAY RESULT IN PERSONAL INJURY,
DEATH, OR SEVERE PROPERTY OR ENVIRONMENTAL DAMAGE. ST PRODUCTS WHICH ARE NOT SPECIFIED AS "AUTOMOTIVE
GRADE" MAY ONLY BE USED IN AUTOMOTIVE APPLICATIONS AT USER’S OWN RISK.
Resale of ST products with provisions different from the statements and/or technical features set forth in this document shall immediately void
any warranty granted by ST for the ST product or service described herein and shall not create or extend in any manner whatsoever, any
liability of ST.
ST and the ST logo are trademarks or registered trademarks of ST in various countries.
Information in this document supersedes and replaces all information previously supplied.
The ST logo is a registered trademark of STMicroelectronics. All other names are the property of their respective owners.