Freescale Technology Forum 2015C:\Freescale\KSDK_1.2.0\middleware\tcpip\rtcs\source\ssl 3. Firmware...

Copyright © 2015 wolfSSL Inc.

Freescale Technology Forum 2015 LAB Manual for FTF-INS-F1145 Version 1.0, June 15, 2015

Hardware: Freescale FRDM-K64F Software: Freescale KDS Freescale MQX/RTCS wolfSSL Embedded SSL/TLS Estimated Completion Time: 1 Hour

Hands-On Workshop: Create Secure Network-Connected Embedded Systems with wolfSSL (formerly CyaSSL) embedded SSL/TLS and Kinetis SDK

Key Takeaways As embedded designers, developers, and engineers, FTF attendees are working to create the next generation of smart, connected devices. The goal of this lab session is to help facilitate the process of creating more secure applications through education and hands-on practice. After working through this lab manual, you will:

● Understand how the httpsrv KDS example is secured ● Be able to generate new SSL/TLS keys and certificates ● Load new keys/certificates into the KDS httpsrv example

The following labs have been designed for use with the Freescale FRDM-K64F platform.

LAB Manual for FTF-INS-F1145


Table of Contents: A. Prerequisites and Installation B. LAB 1 - Creating a (Insecure) TCP/IP Web Server C. LAB 2 - Creating a Secure TCP/IP Web Server D. LAB 3 - Creating RSA Keys and X.509 Certificates E. LAB 4 - Using custom SSL/TLS certs and keys in httpsrv example F. Reference Material



Prerequisites and Installation: The following items should already be installed on the lab computers. Their installation steps are included here for future reference. Software:

A. Kinetis Design Studio 3.0, B. Kinetis SDK 1.2 w/ MQX RTOS C. CyaSSL add-on for KSDK v1.2 D. Wireshark

1. If the Kinetis SDK is not yet installed on your workstation, download Kinetis SDK v1.2.0

mainline release: a. Browse to www.freescale.com/ksdk b. Click Download c. Choose the appropriate Kinetis SDK installer for your operating system,

download, and install it

2. Now install CyaSSL for Kinetis SDK v1.2.0 with MQX RTOS releases and patches a. On the same download page as above, choose the appropriate CyaSSL installer

for your operating system, download, and install it

CyaSSL source files will be installed within the \tcpip\rtcs\source\ssl\ folder in the Kinetis SDK directory tree. On Windows, this path is typically: C:\Freescale\KSDK_1.2.0\middleware\tcpip\rtcs\source\ssl

3. Firmware Note: The CMSIS-DAP firmware is on the FRDM-K64F by default. From experimentation by the wolfSSL team, the Segger J-Link Firmware for OpenSDAv2 seems to have better performance. For those interested, here is a helpful blog post: http://mcuoneclipse.com/2014/04/27/segger-j-link-firmware-for-opensdav2/



LAB 1: Creating an (Insecure) TCP/IP Web Server

Purpose: Create an application that acts as a web server for HTTP clients, using the existing Freescale RTCS httpsrv example application.

Procedure: This lab will be using the httpsrv_frdmk64f example to demonstrate how to create an HTTP server. The httpsrv_frdmk64f project includes a HTTP web server that is unsecured and sends all data in the clear over the TCP/IP connection. As data is being sent in plaintext, this lab demonstrates through the use of Wireshark how a third party might inspect and see that plaintext data as it transfers across the wire. The httpsrv_ssl_frdmk64f project, which will be used in LAB 2, converts the same HTTP web server to HTTPS using SSL/TLS.

1. First, import the httpsrv_frdmk64f project into your KDS workspace. This includes all the libraries that need to be compiled.

a. File -> Import -> Project of Projects -> Existing Project Sets



b. Browse to: \middleware\tcpip\rtcs\examples\httpsrv\build\kds\httpsrv_frdmk64f

After finishing the import, the KDS workspace should now have all the libraries and projects imported that will be needed to compile the httpsrv_frdmk64f project.

2. Take a look over the _readme.txt file for the httpsrv_frdmk64f project. This file includes

details and configuration information for the project.



a. \middleware\tcpip\rtcs\source\_readme.txt

From the _readme.txt, the description of the httpsrv_frdmk64f project is: “This is the RTCS example that is used to demonstrate different features of the RTCS HTTP server. The example allows to start one or more HTTP servers on IPv4 and/or IPv6 addresses, demonstrating use of both static and dynamic web pages with CGI and server WebSocket plugin.”

3. Build all the libraries and example project

a. Select Project -> Build All

Note: The httpsrv_frdmk64f project might fail to compile due to the incorrect order of the builds. If this happens just wait until all the libraries complete their builds, then try to build httpsrv_frdmk64f again.

4. Make sure the target board is plugged into the USB for the debug connection. (Marked

“SDA USB” on FRDM-K64F board). Connect an Ethernet cable between the board and your computer. Reference photo on page 1 if needed.

5. Select the arrow next to the Debug button in the toolbar, and select “Debug

Configurations”

6. Choose the debug connection programmed into your board. In the case of the FRDM-K64F, it is “cmsis-dap” by default.



7. Wait while the download fully completes.

8. When the download is finished, the IDE will switch to the debug view and stop at the MQX main function. Click the “Resume” button to proceed. The httpsrv_frdmk64f application should now be running on the FRDM-K64F.

9. Open a terminal application of your choice (Hyperterminal, TeraTerm, etc). Select the COM port that your board has connected to, and select the 115200 baud rate.

10. Hit the enter key a few times while in the terminal application to see the MQX Shell command line:

shell>

11. Type “ipconfig”, which will in turn show the static IP address that the demo has assigned itself by default.

shell> ipconfig Eth# : 0 Link : on MTU : 1500 MAC : 00:00:5e:a0:01:67 IP4 : 192.168.1.103 Type: MANUAL IP4 Mask : 255.255.255.0 IP4 Gate : 0.0.0.0 IP4 DNS : 0.0.0.0 IP6 : DISABLED Link status task stopped

12. Configure your computer’s network adapter to be on the same IP subnet as the board.

For example, set your PC to use a static IP address of 192.168.1.110.



13. Since the FRDM-K64F is now running a web server, we should be able to connect to it over HTTP with a web browser on the PC. Open a web browser of choice, such as Chrome.

14. In your web browser, type in the IP address of the board, ie:

http://192.168.1.103

15. You should have access to the RTCS web server demo pages through your browser

16. Keep in mind that the above web page is being served over HTTP (not HTTPS), and thus is not a secure connection. This means an attacker could theoretically inject themselves between our client/server and listen or modify the data we are sending and receiving to and from the web server. To verify this, we can use the Wireshark tool to view and analyze traffic going between the FRDM-K64F board and the PC. Wireshark should be installed on your PC. If not, install it from https://www.wireshark.org/.

17. Open Wireshark, Select your network adapter interface that is connected to the FRDM-

K64F board, and click “Start Capture”. Wireshark is now capturing traffic on the interface selected and should pick up any communication between the PC browser and the web server on the board.

18. Go back to your browser and refresh the RTCS Web Server page from step #15 above.

19. Switch to Wireshark, and apply the following filter, by typing it in the “Filter” field and

clicking “Apply”, where ip.addr matches the IP address of your board. ip.addr == 192.168.1.103 && http



Browse through the packets shown. You should see HTTP plaintext, including the browser’s HTTP GET request for welcome.html as well as the returned web page from the board.



LAB 2: Creating a Secure TCP/IP Web Server

Purpose: Create an application that acts as a SECURE web server for HTTPS clients, using the existing Freescale RTCS httpsrv_ssl example application.

Procedure: This lab will be using the httpsrv_ssl_frdmk64f example to demonstrate how to use SSL/TLS in an HTTP server. The httpsrv_frdmk64f project includes a HTTP web server that is unsecured and sends all data in the clear over the TCP/IP connection. The httpsrv_ssl_frdmk64f project converts that HTTP web server to HTTPS using SSL/TLS.

1. First, import the httpsrv_ssl_frdmk64f project into your KDS workspace. This includes all the libraries that need to be compiled.

a. File -> Import -> Project of Projects -> Existing Project Sets

b. Browse to:



\middleware\tcpip\rtcs\examples\httpsrv\build\ kds\httpsrv_ssl_frdmk64f

After finishing the import, the KDS workspace should now have all the libraries and projects imported that will be needed to compile the httpsrv_frdmk64f project.

2. Take a look over the _readme.txt file for using CyaSSL with RTCS in general at the following location. This file includes details and configuration information for the project.

/middleware/tcpip/rtcs/source/ssl/_readme.txt



3. Configure RTCS to use CyaSSL. Open the rtcs_frdmk64f project, expand the

RTCS_Include group, and open the rtcs_user_config.h header file.

4. Add the following to the rtcs_user_config.h header. This define enables SSL/TLS support within the RTCS library.

#define RTCSCFG_ENABLE_SSL 1

5. For this lab, we will also be enabling CyaSSL support for hardware crypto acceleration using the Freescale mmCAU. Download the mmCAU library from the following URL:

http://www.freescale.com/webapp/sps/site/prod_summary.jsp?code=CAUAP

6. Unzip mmcau_lib_release.zip and pull out the mmcau folder, which is one level under

mmcau_lib_release. Move the folder to

\middleware\tcpip\rtcs\source\ssl



7. Add the \middleware\tcpip\rtcs\source\ssl\mmcau\asm-cm4 path to the include directory path list of the CyaSSL library project.

a. Right click on CyaSSL_frdmk64f project and choose Properties b. Open C/C++ Build and choose Settings. Under Cross ARM C Compiler ->

Includes, add the path:

${ProjDirPath}/../../../../tcpip/rtcs/source/ssl/mmcau/asm-cm4

c. Click Ok to save the settings.

8. Now, we need to tell the CyaSSL library to use the mmCAU for supported cryptography operations (AES, DES, 3DES, MD5, SHA1, SHA256).

a. Expand the Ctaocrypt_include folder b. Open the settings.h file c. Add #define FREESCALE_MMCAU 1



The settings.h file edited above controls how the CyaSSL (wolfSSL) library is compiled. This is where users can enable/disable features and customize operation of the library. These defines could also be added to the list of Preprocessor includes in the project properties.

9. Next, add the path to the mmCAU library in the application project linker settings. a. Right click on the httpsrv_ssl_frdmk64f project and choose Properties b. Open C/C++ Build and choose Settings. Under Cross ARM C Linker ->

Miscellaneous -> Other objects, add: ${ProjDirPath}/../../../../../../../tcpip/rtcs/source/ssl/mmcau/

asm-cm4/lib_mmcau.a

10. Build all the libraries and example project a. Select Project -> Build All



Note: The httpsrv_ssl_frdmk64f project might fail to compile due to the incorrect order of the builds. If this happens just wait until all the libraries complete their builds, then try to build httpsrv_ssl_frdmk64f again.

11. Make sure the target board is plugged into the USB for the debug connection. (Marked

“SDA USB” on FRDM-K64F board). Connect an Ethernet cable between the board and your computer. Reference photo on page 1 if needed.

12. Select the arrow next to the Debug button in the toolbar, and select “Debug

Configurations”

13. Choose the debug connection programmed into your board. In the case of the FRDM-K64F, it is “cmsis-dap” by default.

14. Wait while the download fully completes.

15. When the download is finished, the IDE will switch to the debug view and stop at the MQX main function. Click the “Resume” button to proceed. The httpsrv_ssl_frdmk64f application should now be running on the FRDM-K64F.

16. Open a terminal application of your choice (Hyperterminal, TeraTerm, etc). Select the COM port that your board has connected to, and select the 115200 baud rate.



17. Hit the enter key a few times while in the terminal application to see the MQX Shell command line:

shell>

18. Type “ipconfig”, which will in turn show the static IP address that the demo has assigned itself by default.

shell> ipconfig Eth# : 0 Link : on MTU : 1500 MAC : 00:00:5e:a0:01:67 IP4 : 192.168.1.103 Type: MANUAL IP4 Mask : 255.255.255.0 IP4 Gate : 0.0.0.0 IP4 DNS : 0.0.0.0 IP6 : DISABLED Link status task stopped

19. Configure your computer’s network adapter to be on the same IP subnet as the board.

For example, set your PC to use a static IP address of 192.168.1.100.

20. Since the FRDM-K64F is now running a web server, we should be able to connect to it over HTTP with a web browser on the PC. Open a web browser of choice, such as Chrome.

21. In your web browser, type in the IP address of the board, using HTTPS, ie:

https://192.168.1.103

22. Your browser will report that there is a problem with the certificate. Don’t worry, this is expected! This happens because the server’s certificate is self-signed, and generated with a CA certificate that we created and is not trusted by the browser as a respected and known Certificate Authority. Thus, the browser is suspicious of the authenticity of the certificate, as it should be!



a. The server certificate and key in this example are pre-compiled into C array format and loaded into the Flash memory along with the program code. These can be used in development, but if you take a project into production you will need to obtain your own certificate that has been signed by a trusted Certificate Authority (CA).

23. To continue using the self signed certificate during development, in your browser you

will need to add a security exception, telling the browser to proceed regardless. In Chrome, click Advanced

24. Then click Proceed to XXX.XXX.XXX.XXX (unsafe).



25. You should now have authenticated and encrypted access to the RTCS web server demo pages through your browser!

Note: The WebSocket example currently is not functional with SSL. All other examples are working.



26. We can now verify that the traffic is being encrypted. Open Wireshark, Select your network adapter interface that is connected to the FRDM-K64F board, and click “Start Capture”. Wireshark is now capturing traffic on the interface selected and should pick up any communication between the PC browser and the web server on the board.

27. Go back to your browser and refresh the RTCS Web Server page from step #25 above.

28. Switch to Wireshark. By default, Wireshark doesn’t know how to “decode” traffic

unless we tell it to do so. To see SSL/TLS specific packets, right click on one of the packets, go to “Analyze” -> “Decode As”, select “Both” from the dropdown box, then select “SSL” from the list of protocols. Once you click “Apply” the SSL/TLS packets should be recognized by Wireshark.

29. In Wireshark, apply the following filter, by typing it in the “Filter” field and clicking

“Apply”, where ip.addr matches the IP address of your board. ip.addr == 192.168.1.103 && ssl Browse through the packets shown. You should see SSL packets, but instead of seeing browser’s HTTP GET request for welcome.html as well as the returned web page from the board, we now see TLS 1.2 handshake messages (Client Hello, Server Hello, etc.) and encrypted data (Application Data).

30. To determine the SSL/TLS protocol being used, you can look at the “Protocol” column. Here, you should see “TLS 1.2”. To determine what cipher suite the client and server have negotiated:



a. Click on the “Server Hello” message b. Expand the “Secure Sockets Layer” detail section, expand “TLSv1.2 Record

Layer”, expand “Handshake Protocol”, and you will see the cipher suite listed.

One example might be: TLS_RSA_WITH_AES_256_CBC_SHA



LAB 3: Creating RSA Keys and X.509 Certificates

Purpose: Create a new RSA public/private key pair and self signed X.509 certificate.

Procedure: This lab will walk through the creation of a new RSA key pair as well as the creation of a new self-signed X.509 certificate. We will be using cygwin and openssl to generate the keys and certificates.

1. Open the cygwin64 terminal application from the Windows Start menu or by searching for it in the program menu.

2. Change directories to a temporary directory of your choice. For example:

cd /certgen

3. Create an RSA 2048-bit key: openssl genrsa 2048 > ca-key.pem

4. Generate a CA certificate: openssl req -new -x509 -nodes -sha1 -days 1000 \

-key ca-key.pem > ca-cert.pem

5. Answer the questions prompted by the openssl application. You may fill these details out as you like. In a real-world scenario, you would want to make sure these fields are accurate.

Country Name (2 letter code) [AU]:US State or Province Name (full name) [Some-State]:Texas Locality Name (eg, city) []:Austin Organization Name (eg, company) [Internet Widgits Pty Ltd]:wolfSSL Organizational Unit Name (eg, section) []:Training Test Root Cert Common Name (e.g. server FQDN or YOUR name) []:www.example.com Email Address []:[email protected]

6. Generate the server certificate:

openssl req -newkey rsa:2048 -sha1 -days 1000 -nodes \

-keyout server-key-k64.pem > server-req-k64.pem



7. Now answer the questions again, but for the server certificate:

Country Name (2 letter code) [AU]:US State or Province Name (full name) [Some-State]:Texas Locality Name (eg, city) []:Austin Organization Name (eg, company) [Internet Widgits Pty Ltd]:wolfSSL Organizational Unit Name (eg, section) []:Test Server Cert Common Name (e.g. server FQDN or YOUR name) []:www.example.com Email Address []:[email protected]

8. Sign the server certificate with the CA cert and key generated in step #5:

openssl x509 -req -in server-req-k64.pem -days 1000 -sha1 \

-CA ca-cert.pem -CAkey ca-key.pem \ -set_serial 01 > server-cert-k64.pem

9. The wolfSSL package (available from wolfssl.com), includes a perl script which converts

key and certificate files into C arrays. To use this, we need to download the latest stable release of wolfSSL:

a. Browse to the wolfSSL download page:

https://wolfssl.com/wolfSSL/download/downloadForm.php b. Download wolfSSL to your local lab computer c. Unzip the wolfSSL-x.x.x.zip package

10. Copy the PEM files from step #9 to the wolfSSL “/certs” directory:

cp server-key-k64.pem /wolfssl-x.x.x/certs

cp server-cert-k64.pem /wolfssl-x.x.x/certs

11. Edit the gencertbuf.pl file inside of the wolfSSL package root directory

a. Change the 2048 file list by appending the newly-created PEM files to it. The additions are the last two lines below. Note that a comma is needed on the line above the two added lines.

my @fileList_2048 = ( [ "./certs/client-key.der", "client_key_der_2048" ], [ "./certs/client-cert.der", "client_cert_der_2048" ], [ "./certs/dh2048.der", "dh_key_der_2048" ], [ "./certs/dsa2048.der", "dsa_key_der_2048" ], [ "./certs/rsa2048.der", "rsa_key_der_2048" ], [ "./certs/ca-cert.der", "ca_cert_der_2048" ], [ "./certs/server-key.der", "server_key_der_2048" ], [ "./certs/server-cert.der", "server_cert_der_2048" ],



[ "./certs/server-key-k64.pem", "server_key_pem_k64" ], [ "./certs/server-cert-k64.pem", "iot6 _server_cert_pem_k64" ] );

12. Generate the new certificate and key buffers by running the script from the root

wolfSSL directory: cd /wolfssl-x.x.x ./gencertbuf.pl

13. After the script finishes running, the two newly-created C arrays will have been placed in the following header file:

/wolfssl/certs_test.h

These two new buffers will be used in LAB 4, where they will be used by the httpsrv_ssl_frdmk64f example application.



LAB 4: Using custom SSL/TLS certs and keys in httpsrv example

Purpose: Learn how to use the certificate and key from Lab 3 in the httpsrv_ssl_frdmk64f example application.

Procedure: The httpsrv_ssl_frdmk64f project defines the SSL library configuration parameters in a struct called “ssl_params” in Source/config.h:

1. The default server key and certificate for the httpsrv_ssl_frdmk64f project are pre-compiled into a TFS (trivial file system) as C arrays and Flashed as part of the program code. To replace these with our own (the ones created in LAB 3), we will need to replace the default ones with the new arrays.

2. In the httpsrv_ssl_frdmk64 project, open:

Source/nio_tfs_data.c

3. In this file, you will see the following arrays:

nio_tfs_filesystem_ssl_server_cert_pem[] = server certificate in PEM format. nio_tfs_filesystem_ssl_server_key_pem[] = server private key in PEM format.

These arrays are mapped to the “file system path” at the end of nio_tfs_data.c in the nio_tfs_data[] array.

4. Replace the contents of nio_tfs_filesystem_ssl_server_cert_pem[] with server_cert_pem_k64[] from /wolfssl/certs_test.h (reference Lab 3).

5. Replace the contents of nio_tfs_filesystem_ssl_server_key_pem[] with

server_key_pem_k64[] from /wolfssl/certs_test.h (reference Lab 3).



6. Recompile and re-run the HTTPS server example.

7. Connect to the HTTPS IP address of your server board. You will need to re-add a new

security exception into your browser (you’ll get the warning as you did in Lab 2).

8. Open the certificate details in your browser, note that they are different! You successfully changed the server’s certificate and key file.

Note that the httpsrv_ssl_frdmk64f example is using the RTCS_ssl_*() API calls internally to establish and maintain the SSL/TLS connection. If you wanted to use the RTCS SSL functionality outside of the RTCS HTTP server, you would need to include the “rtcs_ssl.h” header as noted in the presentation, then use the RTCS_ssl_*() functions. Those functions are implemented in the “rtcs_ssl.c” source file. For reference (copied again here from presentation): typedef enum rtcs_ssl_init_type { RTCS_SSL_SERVER, RTCS_SSL_CLIENT }RTCS_SSL_INIT_TYPE; typedef struct rtcs_ssl_params_struct { char* cert_file; /* Client or Server Certificate file.*/ char* priv_key_file; /* Client or Server private key file.*/ char* ca_file; /* CA (Certificate Authority) certificate file.*/ RTCS_SSL_INIT_TYPE init_type; }RTCS_SSL_PARAMS_STRUCT; void* RTCS_ssl_init(RTCS_SSL_PARAMS_STRUCT *params); void RTCS_ssl_release(void *ctx); uint32_t RTCS_ssl_socket(void* ctx, uint32_t sock); uint32_t RTCS_ssl_shutdown(uint32_t ssl_sock); int32_t RTCS_ssl_recv(uint32_t ssl_sock, void *buf, uint32_t len, uint32_t flags); int32_t RTCS_ssl_send(uint32_t ssl_sock, void *buf, uint32_t len, uint32_t flags); Directly Using wolfSSL Keep in mind that in addition to using CyaSSL (wolfSSL) through the RTCS_ssl_*() API, you can also download it from www.wolfssl.com under the GPLv2 license and use it directly in your code through the wolfSSL_*() API.



Reference Material wolfSSL Manual: http://wolfssl.com/wolfSSL/Docs-wolfssl-manual-toc.html

Date post:	31-Jan-2021
Category:	Documents
Upload:	others
View:	2 times
Download:	0 times

Freescale Technology Forum 2015C:\Freescale\KSDK_1.2.0\middleware\tcpip\rtcs\source\ssl 3. Firmware...

Documents