Maclain Lobdell

How To: Build and run the MQX HTTPS Server example with CyaSSL

Discussion created by Maclain Lobdell Employee on Jan 12, 2015
Latest reply on Jun 24, 2015 by sudhakar p
Branched to a new discussion

Need to enable secure encrypted communications in your systems?  Don't worry, Freescale and our partners have you covered. 

For more info see Now Available: CyaSSL for MQX RTCS


Here is a detailed overview of how to build and run the MQX http webserver example with CyaSSL.

(And how to use the MMCAU libraries for Cryptographic Acceleration on select Kinetis MCUs)

 

NOTE: These instructions use Kinetis Design Studio IDE v2.0 and FRDM-K64F, however the steps are very similar with any supported toolchain and boards.

 

1. Download Kinetis SDK v1.1.0 with MQX RTOS at www.freescale.com/ksdk

 

Click Download.

image001.png

Choose the appropriate Kinetis SDK v1.1.0 installer for your operating system, then download and install it.

image002.png

 

2. Now install CyaSSL for Kinetis SDK v1.1.0 with MQX RTOS

On the left side of the same download page, click Updates and Patches

image003.png

3. Choose the appropriate CyaSSL installer for your operating system, download and install it.

image004.png

CyaSSL source files will be installed within the <Kinetis SDK>\tcpip\rtcs\source\ssl\ folder in the Kinetis SDK directory tree.

On Windows, this path is typically: C:\Freescale\KSDK_1.1.0\tcpip\rtcs\source\ssl

 

4. Now open a supported Toolchain.  See MQX release notes at <Kinetis SDK>\rtos\mqx\doc, for a list of supported tools.

          (For your reference, check out the guide for your selected toolchain at <Kinetis SDK>\rtos\mqx\doc\tools)


Example Steps for Using Kinetis Design Studio IDE v2.0 and FRDM-K64F:

 

5. First Import the httpsrv_ssl_frdmk64f working set. This includes all the libraries that need to be built.

image005.png

Browse <Kinetis SDK>\tcpip\rtcs\examples\httpsrv\build\kds\httpsrv_ssl_frdmk64f

image006.png

6. Check out the _readme.txt file at <Kinetis SDK>\tcpip\rtcs\source\ssl for detailed information about this demo and the steps listed here.

 

7. Configure RTCS to use CyaSSL.  Open the rtcs_frdmk64f project.  Expand the RTCS_Include group.

image007.png

Open rtcs_user_config.h file and add  #define RTCSCFG_ENABLE_SSL    1

image008.png

8.       Next download the Freescale MMCAU library to enable hardware acceleration of supported cryptographic functions. 

Download the MMCAU software library here.

Unzip mmcau_lib_release.zip and pull out the mmcau folder that is one level under mmcau_lib_release.  Move that folder to <Kinetis SDK>\tcpip\rtcs\source\ssl (or anywhere else if you desire).

image009.png

9.       Now add the <Kinetis SDK>\tcpip\rtcs\source\ssl\mmcau\asm-cm4 path to include directory list of the CyaSSL library project.

Right click on the CyaSSL_frdmk64f project and choose Properties

Open C/C++ Build and choose Settings.  Under Cross ARM C CompilerIncludes…add the path  ${ProjDirPath}/../../../../tcpip/rtcs/source/ssl/mmcau/asm-cm4 (or the alternative path you placed the folder).


image010.png


Click OK to save the setting.


10.   Now tell CyaSSL to use the MMCAU library.

Expand the Ctocrypt_include folder

Open the settings.h file.

Add #define FREESCALE_MMCAU   1


11.   Now add the path to the mmcau library in the application project linker settings. 

Right click on the httpsrv_ssl_frdmk64f project and choose Properties

Open C/C++ Build and choose Settings.  Under Cross ARM C LinkerMiscellaneousOther objects add ${ProjDirPath}/../../../../../../../tcpip/rtcs/source/ssl/mmcau/asm-cm4/lib_mmcau.a (or the alternative path you placed the folder).

image012.png

12. Build all the libraries and example project

Select Project…Build ALL

image013.png

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.

 

13. Now make sure the target board is plugged in to the USB for the debug connection. (Marked “SDA USB” on FRDM-K64F).

 

14. Select the httpsrv_ssl_frdmk64f project, and click on the arrow next to the image of the Bug and select Debug Configurations

 

image014.png

15. Choose the debug connection programmed in your board’s debug firmware.  (Default for FRDM-K64F is cmsis-dap)

  image015.png

16. Wait while the download fully completes.

image016.png

17. When the download is finished, the IDE will then switch to the debug view and stop at the mqx rtos main function.  Click the Resume button.


image017.png

18. Open up the terminal program of your choice.  Select the COM port provided by the board.  For the default debug firmware (cmsis-dap) it will enumerate as mbed Serial Port (COM:xx).  Select 115200 baud rate. 

 

19. Type enter a few times to see the MQX Shell command line.

shell>

 

20. Type ipconfig.  This will show the static IP address the demo software assigns itself by default. 

shell> ipconfig

Eth#     : 0

Link     : off

MTU      : 1496

MAC      : 00:00:5e:a0:01:ca

IP4      : 192.168.1.202 Type: MANUAL

IP4 Mask : 255.255.255.0

IP4 Gate : 0.0.0.0

IP4 DNS  : 0.0.0.0

Link status task stopped

shell>

 

21. Connect an Ethernet cable between your board and computer

 

22. Configure your computer network adaptor 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

 

23. Now open a web browser such as Chrome.

 

24. Type in https://<IPADDRESS_OF_BOARD>  (e.g. https://192.168.1.202

 

25. Your browser will report that there is a problem with the certificate.  Don’t worry, this is expected!  It is because the certificate used in the demo is self-signed.  Thus, the browser is suspicious of the authenticity, like it should be!

The SSL Certificate and Key are pre-compiled into a Trivial File System (C Array) format and loaded to the Flash memory along with the program code.  These can be used in development, but if you go into production and start shipping your own products, you will need to get a certificate signed by a Certificate Authority (CA) that verifies you are who you say you are.

 

26. To continue using the self-signed certificate (during development), click Advanced.

image018.png

27. Then click Proceed to <IP ADDRESS> (unsafe)

 

image019.png

28. Now you will have encrypted access to the RTCS webserver demo pages through your browser. (Note: Chrome crosses out the https because of the self-signed certificate used in this example.)

 

image020.png

 

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

 

29. You can check the traffic with WireShark or another traffic analysis tool.

 

30. See _readme.txt file at <Kinetis SDK>\tcpip\rtcs\examples\httpsrv for more details about the HTTP Server, including how to set up static DNS to avoid typing IP addresses and allow for certificates to function properly for both IPv4 and IPv6.

 

Have fun setting up secure connections!

 

Thanks,
MacL

Outcomes