AVR32753: AVR32 UC3 How To Connect To An SSL-server: Features
AVR32753: AVR32 UC3 How To Connect To An SSL-server: Features
SSL-server
Features
• Basic HTTPS connection to a web server running on a PC
- POLARSSL Library with support of: 32-bit
• Block and stream ciphers: AES, ARC4 DES/3DES
• Public-key cryptography: RSA, MPI, Diffie-Hellman
Microcontrollers
• Cryptographic protocols: SSL/TLS client and server
• Hash functions: MD2, MD4, MD5, SHA-1, SHA-256, SHA-512
• Random Number Generators: HAVEGE Application Note
- lwIP TCP/IP Stack 1.3.0
- Free RTOS
1 Introduction
This application note demonstrates the ability of the UC3 device to exchange
messages with a server over TCP/IP connectivity through a secure socket layer
connection.
Rev. 32111C-AVR-11/09
2 Requirements
The software provided with this application note requires several components:
• A computer running Microsoft® Windows® 2000/XP/Vista.
• AVR32Studio and the GNU toolchain (GCC) or IAR Embedded Workbench® for
AVR32 compiler.
• A JTAGICE mkII or AVROne! Debugger.
• FLIP Version 3.2.1. (Available on www.atmel.com )
• An AVR UC3 evaluation kit: EVK1100.
3 Acronyms
AES: Advanced Encryption Standard, also known as Rijndael, is a block cipher
adopted as an encryption standard.
ARC4: Alleged Rivest Cipher 4, a stream cipher developed by Ron Rivest.
DES: Data Encryption Standard, a deprecated cryptographic block cipher.
DHCP: Dynamic Host Configuration Protocol.
DNS: Domain Name System (DNS) associates various information with domain
names.
EBI: External Bus Interface.
GPIO: General Purpose Input Output.
HAVEGE: Hardware Volatile Entropy Gathering and Expansion, is a user-level
software unpredictable random number generator.
LwIP: Lightweight IP is a widely used open source TCP/IP stack designed for
embedded systems.
MACB: Media Access Control version B.
MD2: Message Digest Algorithm 2, is a cryptographic hash function developed by
Ronald Rivest in 1989. The algorithm is optimized for 8-bit computers.
MD4: Message Digest Algorithm 4, is a cryptographic hash function developed by
Ronald Rivest in 1990.
MD5: Message Digest Algorithm 5, is a cryptographic hash function developed by
Ronald Rivest in 1991.
RSA: Rivest, Shamir, & Adleman, public key encryption technology.
SDRAM: Synchronous Dynamic Random Access Memory.
SRAM: Static Random Access Memory.
SHA-1: Secure Hashing Algorithm 1.
SHA-256: one of the four Secure Hashing Algorithm 2.
SHA-512: one of the four Secure Hashing Algorithm 5.
SSL: Secure Sockets Layer, a communications protocol, predecessor to Transport
Layer Security.
TC: Timer Counter, 16-bit Timer Counter channels available on the UC3.
TLS: Transport Layer Security, successor to Secure Sockets Layer.
TCP/IP: Transmission Control Protocol/Internet Protocol.
URL: Uniform Resource Locator is a compact string of characters used to represent a
resource available on the Internet.
USART: Universal Synchronous & Asynchronous Receiver Transmitter.
POLARSSL: an open source embedded SSL/TLS library with standalone cipher and
cryptic algorithm.
2 AVR32753
32111C-AVR-11/09
AVR32753
4 SSL Operations
The aim of this application is to demonstrate how to secure a message exchange
between the client running on the EVK1100 board and a server. This is done by using
the SSL/TLS standard. To realize this objective several major software components
are needed.
4.1.1 POLARSSL
This is a small footprint SSL library which contains all needed functions to implement
an SSL/TLS server or client.
Each cipher in POLARSSL (AES, MD5, SHA-1, etc.) is self-contained and can be
reused as a standalone module.
For example, the file “aes.c” contains all functions to operate an AES ciphering.
This demo uses a SSL/TLS client module which contains a set of functions that allow
to easily create a client without a strong knowledge in SSL/TLS technologies.
4.1.2 FreeRtos
This is a portable, open source, mini Real Time Kernel.
Thanks to this OS, this demo will create different tasks such as network tasks and the
basic SLL task.
4.1.3 lwIP
This is a Lightweight TCP/IP stack designed for embedded systems. This stack has
been ported on UC3 to use the MACB controller of the UC3A.
The lwIP stack is executed as a FreeRtos task. This demo uses version 1.3.0, which
includes supports for DHCP.
3
32111C-AVR-11/09
4.2 Client Operation
The Client software runs on the EVK1100. When the board is switched on, the
necessary UC3 resources are initialized:
o CPU frequency
o USART
o SDRAM
o GPIO for LED blinking
At this point the program will tell the user through the USART that the initialization is
correctly done.
The software will then start FreeRtos tasks:
1. LED blinking tasks: this is a set of three tasks used to visually check if the
application is alive. During the demo, each task controls a LED (LED 1, 2 and 3).
These LEDs will continuously blink at a different frequency.
2. Ethernet tasks: These two tasks (lwIP and Ethernet) take care of handling the
TCP/IP stack, and also manage ping requests and DHCP functionality. The MACB
must be initialized before these two tasks are launched.
3. Basic web server: This optional task (see Make file) is a web server which can be
used for task monitoring.
4. Basic SSL client: This task handles the secure message exchange. It creates a
client task that uses SSL/TLS network layers and performs the following:
o Initializes SSL/TLS required structure.
o Connects to a server.
o Prepares SSL/TLS structure for a secure transaction.
o Secures the transaction using Simple SSL/TLS handshake. (See
next chapter)
o Writes a message to the server through SSL/TLS layer.
o Reads a message from the server through SSL/TLS layer.
o Dumps this message through USART.
o Closes the connection to the server.
o Cleans all SSL/TLS requires the structures.
4 AVR32753
32111C-AVR-11/09
AVR32753
5
32111C-AVR-11/09
4.4 Client Software Architecture
4.4.1.1 Main()
The main() function of the program is located in the file:
src/SERVICES/POLARSSL/EXAMPLES/SSL_EXAMPLE/main.c
• Initialize the clock, SDRAM and UART.
• Start LED blinking tasks.
• Start the Ethernet Task which includes LwIP and MACB setup, web server
task and Client SSL task.
src/NETWORK/BasicSSL/Basicssl.c
This file contains the task called: vBasicSSLClient, that does the following:
2. Starts to connect to the SSL server using the network connection function. This
operation is done every second until the connection request is accepted by the
server.
3. Once connected to the server, created structures are initialized with the following
code; this operation is required before writing a message.
The ssl structure contains much information:
o Supported cipher algorithm.
o SSL/TLS version.
o State of the transaction.
o Expiration time
o Random number table
6 AVR32753
32111C-AVR-11/09
AVR32753
/* set client mode in ssl structure */
ssl_set_endpoint( ssl, SSL_IS_CLIENT );
4. Now, the client is able to write a message to the server using the function
“write_ssl”. All SSL handshakes are done automatically in this function.
/* While there are data to be written over the security layer */
while( ( ret = ssl_write( ssl, buf, len ) ) <= 0 ) {
/* if Error during written, this is dumped on the UIART */
if( ret != POLARSSL_ERR_NET_TRY_AGAIN ){
PRINTF_DBG( " failed\n");
PRINTF_DBG( "SSL : ! ssl_write returned %x(%x)\n\n",
ret,-ret );
goto exit;
}
}
len = ret;
PRINTF_DBG( " %d bytes read\n\n%s\n", len, (char *) buf );
}
while( 0 );
7
32111C-AVR-11/09
6. Once all data have been read, the connection is closed and the allocated data
structures are freed.
net_close( server_fd );
7. A red LED starts blinking to let user know that the secure transaction is done.
for(;; ) {
gpio_clr_gpio_pin(LED6_GPIO);
vTaskDelay(200);
}
4.4.1.3 Drivers
The AT32UC3A drivers’ sources are located in the src/DRIVERS directory.
This application requires:
• CPU/CYCLE_COUNTER: needed to compute time or delay
• EBI/SDRAMC: This driver is needed to control the SDRAM.
• FLASHC: Flash controller driver needed during clock setting to sets internal flash
wait state.
• GPIO: controls the LEDs.
• INTC: interrupt handling.
• MACB: Ethernet controller for network functions.
• PM: power management, sets clock cycle.
• TC: Timer Counter, needed by freeRTOS
• USART: needed to dump the secure message received from the server to UART1.
4.4.1.4 Components
The hardware components sources are located in the src/COMPONENTS directory.
There is only one component needed for this application:
The SDRAM component used for dynamic memory allocation.
All dynamic memory allocated for this application will be done in the memory range
from:
0xD0000000 to 0xD2000000
8 AVR32753
32111C-AVR-11/09
AVR32753
Table 4-1. Major SSL structures and tasks stacks are stored in this SDRAM:
Structure ssl_conetxte 2168 Bytes
4.4.1.5 SERVICES
This application requires the following services:
POLARSSL 0.12.1: for documentation see [1].
Lwip 1.3.0: for documentation see [2].
FreeRTOS: for documentation see [3].
4.4.3.1 src/SERVICES/POLARSSL/EXAMPLES/SSL_EXAMPLE/conf_eth.h
This header file sets all external configurations of the Ethernet module such as the
Mac address, server and client IP address.
Table 4-2. Mac address: this address must be unique, given values are in
hexadecimal.
#define ETHERNET_CONF_ETHADDR0 0x00
9
32111C-AVR-11/09
Table 4-3. Board IP address, required if DHCP is not enabled (see lwipopts.h).
#define ETHERNET_CONF_IPADDR0 192
#define ETHERNET_CONF_IPADDR1 168
#define ETHERNET_CONF_IPADDR2 0
#define ETHERNET_CONF_IPADDR4 2
This configuration will set client IP address to: 192.168.0.2
4.4.3.2 src/SERVICES/POLARSSL/EXAMPLES/SSL_EXAMPLE/conf_lwip_threads.h
Table 4-5. SSL task setting.
4.4.3.3 src/SERVICES/FREERTOS/Source/include/FreeRTOSConfig.h
This file contains configuration defines for FreeRtos. There are no SSL client related
defines in this file.
4.4.3.4 src/SERVICES/POLARSSL/EXAMPLES/SSL_EXAMPLE/lwipopts.h
Table 4-6. LwIP 1.3.0 configuration.
1 :(enable), this is used to enable or disable
#define LWIP_DHCP DHCP;
0 :(disable, default value) the client file uses
the fixed IP address set in conf_eth.h
4.4.3.5 src/SERVICES/POLARSSL/include/polarssl/config.h
Disable or enable some POLARSSL functionalities. Handle with care because the
SSL/TLS client functions need most of the modules.
It has been built with debug option on, so during transactions, all handshakes
information from a server point of view will be dumped on the console.
To run this server, execute ‘ssl_server.exe’ in a console and the server does the
following:
• It waits for a connection requests on port 4433.
• When it accepts a connection from a client
o Executes a full handshake with the client to secure the transaction.
o safely exchanges messages with the client
11
32111C-AVR-11/09
The following menu will appear:
12 AVR32753
32111C-AVR-11/09
AVR32753
5.2.2 DHCP enable
If DHCP mode has been setup in the client application (#define LWIP_DHCP 1),
there is nothing to setup. DHCP will give an address to the client application.
Plug one side of the Ethernet cable to EVK1100 connector named “eth” and the other
side on an Ethernet switch, hub or router.
Remove the line with the ‘#error’ message, save the file and recompile the project.
5.3.1 GCC
The GCC project is located here:
src/SERVICES/POLARSSL/ EXAMPLE/SSL_CLIENT/AT32UC3A0512/GCC/
To build the project under GCC, run the following command in a console:
‘make clean’ to clean up the project
‘make all’ to build up the full application
5.3.2 IAR
The IAR project is located in:
src/SERVICES/POLARSSL/ EXAMPLE/SSL_CLIENT/AT32UC3A0512/IAR/
To build the project under IAR :
Double click on ‘ssl_example.eww’ or menu ‘FileÎopenÎworkspace…’
13
32111C-AVR-11/09
5.3.3 AVR32STUDIO
Run avr32studio.
Import Existing Project into Workspace (File->import…), press the “next” button.
Select the archive file with the browse button. Select the project AVR32753 and press
the “finish” button.
14 AVR32753
32111C-AVR-11/09
AVR32753
Note: This is a server application, if you using a firewall, you must be sure that port
4433 accepts connection requests. Otherwise, client connection requests will be
refused by the firewall.
15
32111C-AVR-11/09
• PC SSL/TLS Server:
Server will display status of connection request.
5.6 Troubleshooting
The client is not able to connect to the server:
• If the PC that hosts the server is protected by a firewall, disable it or open
port 4433.
• If using DHCP, check on HyperTerminal if the local interface gets an address
from the DHCP
• Check if the server address is the same as the one set in conf_eth.h.
You can check if the client application is running using the ping command:
e.g.: ping 192.168.0.2
If this demo application has been built with HTTP_USED=1, you can run a web
browser and use the following URL: http://192.168.0.2
This will let you see the index.html page with some FreeRtos task information:
16 AVR32753
32111C-AVR-11/09
AVR32753
6 Reference
[1] POLARSSL
http://www.polarssl.org
[2] LWIP
http://savannah.nongnu.org/projects/lwip/
[3] FreeRTOS
http://www.freertos.org/
[4] Practical TCP/IP and Ethernet Networking for Industry.
By Deon Reynders, Edwin Wright.
ISBN-13: 978-0750658065
[5] SSL and TLS essentials: SSL & TLS Essentials: Securing the Web.
By Stephen A. Thomas
ISBN-13: 978-0471383543
[6] AVR32015: AVR32 Studio getting started
http://www.atmel.com/dyn/resources/prod_documents/doc32086.pdf
17
32111C-AVR-11/09
7 Appnotes Revision History
Please note that the page numbers referred to in this section are referrring to this
document. The referring revision in this section is referring to the document revision.
1 Initial version
18 AVR32753
32111C-AVR-11/09
Disclaimer
Headquarters International
Atmel Corporation Atmel Asia Atmel Europe Atmel Japan
2325 Orchard Parkway Unit 1-5 & 16, 19/F Le Krebs 9F, Tonetsu Shinkawa Bldg.
San Jose, CA 95131 BEA Tower, Millennium City 5 8, Rue Jean-Pierre Timbaud 1-24-8 Shinkawa
USA 418 Kwun Tong Road BP 309 Chuo-ku, Tokyo 104-0033
Tel: 1(408) 441-0311 Kwun Tong, Kowloon 78054 Saint-Quentin-en- Japan
Fax: 1(408) 487-2600 Hong Kong Yvelines Cedex Tel: (81) 3-3523-3551
Tel: (852) 2245-6100 France Fax: (81) 3-3523-7581
Fax: (852) 2722-1369 Tel: (33) 1-30-60-70-00
Fax: (33) 1-30-60-71-11
Product Contact
Literature Request
www.atmel.com/literature
Disclaimer: The information in this document is provided in connection with Atmel products. No license, express or implied, by estoppel or otherwise, to any
intellectual property right is granted by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN ATMEL’S TERMS AND
CONDITIONS OF SALE LOCATED ON ATMEL’S WEB SITE, ATMEL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED
OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,
CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS,
BUSINESS INTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS
BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no representations or warranties with respect to the accuracy or completeness of the
contents of this document and reserves the right to make changes to specifications and product descriptions at any time without notice. Atmel does not make any
commitment to update the information contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and shall not be used in,
automotive applications. Atmel’s products are not intended, authorized, or warranted for use as components in applications intended to support or sustain life.
© 2009 Atmel Corporation. All rights reserved. Atmel®, Atmel logo and combinations thereof, AVR®, AVR® logo and others, are the
registered trademarks or trademarks of Atmel Corporation or its subsidiaries. Windows® and others are registered trademarks or trademarks of
Microsoft Corporation in the US and/or other countries. Other terms and product names may be trademarks of others.
32111C-AVR-11/09