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

[macl]

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.

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

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

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

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.

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

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.

Open rtcs_user_config.h file and add  #define RTCSCFG_ENABLE_SSL    1

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).

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 Compiler…Includes…add the path  ${ProjDirPath}/../../../../tcpip/rtcs/source/ssl/mmcau/asm-cm4 (or the alternative path you placed the folder).

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 Linker…Miscellaneous…Other objects add ${ProjDirPath}/../../../../../../../tcpip/rtcs/source/ssl/mmcau/asm-cm4/lib_mmcau.a (or the alternative path you placed the folder).

12. Build all the libraries and example project

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.

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

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

 

16. Wait while the download fully completes.

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.

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.

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

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.)

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

[swapnilv]

Hi,

I followd above steps for sample example "httpsrv_ssl_twrk60d100m" for "twrk60d100m" tower board using IAR workbench (version 7.10.3.6932).

It shows the sample web pages in browser using HTTPS. But after some time web server crashes/hangs.Some times the web server will not even start(doesn't show the web pages) on flashing the code to tower board.

I see below Task Errors in IAR Task Summary.

Please let me know how to fix this issue.

Also, currently web pages and certificates are implemented in Trivial File System(TFS) in sample project given.

Please let me know how I should proceed further if I want use SD card to store web pages and certificates.

Thanks,

Swapnil

[swapnilv]

Hi,

Waiting for your reply.

Please let me know how I should proceed further since the sample example itself is not working properly.

Thanks,

Swapnil

[macl]

I have asked our team to investigate.  Should get a reply soon. 

About switching the location of the certificate storage from internal flash using TFS to SD card, you can use MFS which is a FAT file system library provided with MQX RTOS.  There is an SD card example in the MFS example projects.  This should show how to use the MFS API. 

Depending on the version of MQX you are using, the example will be in one of these locations:

C:\Freescale\Freescale_MQX_4_1\mfs\examples

C:\Freescale\KSDK_1.1.0\filesystem\mfs\examples

Thanks,
Mac L

[swapnilv]

Hi,

Any update regarding the issue related to other sample examples like sdcard not working?

Thanks,
Swapnil

[macl]

Hi,

If hello world is not working then I think there is a fundamental issue with your setup.  Maybe the libraries didn't build correctly or perhaps an issue with your board or jumper settings.  I think this is a separate topic than cyassl for MQX.  I think this thread should be branched and addressed separately.

Thanks,
Mac

[sudhakarp]

Hi maclain,

               finally i build successfully. but now i am getting this error. when i am trying to DEBUG am getting

following error.

Quit (expect signal SIGINT when the program is resumed)

Quit (expect signal SIGINT when the program is resumed)

Quit (expect signal SIGINT when the program is resumed)

Exception condition detected on fd 0

error detected on stdin

[sudhakarp]

hi Maclain,

I tried cyassl build what u mentioned above method in KDS2.0 ksdk1.1.0 but when i build i am getting

"fatal error: cau_api.h: No such file or directory  " i Tried both build and build all. but still i am getting that error.

and also i make sure i copied mmcau folder in correct place.

regards,

sudhakar p

[RadekS]

We know about issue in CyaSSL implementation in KSDK1.1.0.

Problem is in handling error results from SSL library. In these cases RTCS didn't deallocate resources (memory, sockets,..).

This will be fixed in KSDK1.2.0 (release should be available during end of April 2015).

About MFS at USB and SDcard)

You can even combine both systems, where main pages are stored in flash trough TFS and some of files at MFS volumes are accessible trough aliases (like 10.11.12.13/sdcard/my_file.ext).

You can look at web-hvac demo, where some of files could be located at USB stick.

I hope it helps you.

Have a great day,
RadekS

[swapnilv]

Thanks for your reply.

Please let us know once the issue is fixed.

Regards,

Swapnil

[RadekS]

This issue was already fixed and tested at development branch. Now it waits for end of testing process and final MQX 4.2 release.

I will update this thread when new MQX4.2 package will be available.

I hope it helps you.

Have a great day,
RadekS

[swapnilv]

Will it be fixed in MQX4.2 release or KSDK 1.2.0  release?

Regards,

Swapnil

[RadekS]

Sorry, for confuse with numbering.

It will be fixed in both releases KSDK 1.2.0 and MQX 4.2.

We would like to release both packages simultaneously.

I hope it helps you.

Have a great day,
RadekS

[swapnilv]

Hi,

Waiting for your reply regarding other issues that I have observed in sample SD card example and Hello world example.

Thanks,

Swapnil