Network Component  Version 7.11.0
MDK Middleware for IPv4 and IPv6 Networking
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Using Secure Services

The Network Component offers secure software components that are using Mbed TLS. The user of the Network Component does not see the Mbed TLS API as it is hidden by the standard API of the secure component.

Currently, the following component is available in a secure variant:

To be able to communicate securely, you will need to generate appropriate certificates for the server. The section Creating your own certificates and keys explains how to achieve this for the secure components by using additional tools that are part of the Network Component.

HTTPS Server

The web server and the compact web server have secure variants available. In the Manage Run-Time Environment window simply select the appropriate variant:

select_https.png

Converting the HTTP server to HTTPS

It is also possible to convert an already existing (compact) web server to a secure HTTPS web server. A few simple steps are required to achieve this:

  1. Download and install the ARM:mbedTLS Software Pack (see Add the mbed TLS library to a µVision project).
  2. Change the following software components in the Manage Run-Time Environment:
    • Set Network:Service:Web Server (Compact) variant to HTTPS. This adds the file Net_Security.c to the project which contains test keys/certificates. To change them, follow the steps provided in Creating your own certificates and keys.
    • Enable Security:mbed TLS or resolve this dependency automatically.
  3. Update the mbedTLS_Config.h configuration file with the following (a copy named mbedTLS_config_HTTPS.h is available in the Template folder):
    /*
    * Configuration template for HTTPS
    * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
    * SPDX-License-Identifier: Apache-2.0
    * Licensed under the Apache License, Version 2.0 (the "License"); you may
    * not use this file except in compliance with the License.
    * You may obtain a copy of the License at
    * http://www.apache.org/licenses/LICENSE-2.0
    * Unless required by applicable law or agreed to in writing, software
    * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
    * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    * See the License for the specific language governing permissions and
    * limitations under the License.
    * This file is part of mbed TLS (https://tls.mbed.org)
    */
    /*
    * This set of compile-time options may be used to enable
    * or disable features selectively, and reduce the global
    * memory footprint.
    */
    #ifndef MBEDTLS_CONFIG_H
    #define MBEDTLS_CONFIG_H
    /* System support */
    #define MBEDTLS_ENTROPY_HARDWARE_ALT
    /* mbed TLS feature support */
    #define MBEDTLS_AES_ROM_TABLES
    #define MBEDTLS_CIPHER_MODE_CBC
    #define MBEDTLS_CIPHER_MODE_CFB
    #define MBEDTLS_CIPHER_MODE_CTR
    #define MBEDTLS_CIPHER_PADDING_PKCS7
    #define MBEDTLS_CIPHER_PADDING_ONE_AND_ZEROS
    #define MBEDTLS_CIPHER_PADDING_ZEROS_AND_LEN
    #define MBEDTLS_CIPHER_PADDING_ZEROS
    #define MBEDTLS_REMOVE_ARC4_CIPHERSUITES
    #define MBEDTLS_KEY_EXCHANGE_PSK_ENABLED
    #define MBEDTLS_KEY_EXCHANGE_DHE_PSK_ENABLED
    #define MBEDTLS_KEY_EXCHANGE_RSA_PSK_ENABLED
    #define MBEDTLS_KEY_EXCHANGE_RSA_ENABLED
    #define MBEDTLS_KEY_EXCHANGE_DHE_RSA_ENABLED
    #define MBEDTLS_GENPRIME
    #define MBEDTLS_NO_PLATFORM_ENTROPY
    #define MBEDTLS_PK_RSA_ALT_SUPPORT
    #define MBEDTLS_PKCS1_V15
    #define MBEDTLS_PKCS1_V21
    #define MBEDTLS_SSL_ALL_ALERT_MESSAGES
    #define MBEDTLS_SSL_ENCRYPT_THEN_MAC
    #define MBEDTLS_SSL_EXTENDED_MASTER_SECRET
    #define MBEDTLS_SSL_FALLBACK_SCSV
    #define MBEDTLS_SSL_CBC_RECORD_SPLITTING
    #define MBEDTLS_SSL_RENEGOTIATION
    #define MBEDTLS_SSL_MAX_FRAGMENT_LENGTH
    #define MBEDTLS_SSL_PROTO_SSL3
    #define MBEDTLS_SSL_PROTO_TLS1
    #define MBEDTLS_SSL_PROTO_TLS1_1
    #define MBEDTLS_SSL_PROTO_TLS1_2
    #define MBEDTLS_SSL_ALPN
    #define MBEDTLS_SSL_SESSION_TICKETS
    #define MBEDTLS_SSL_SERVER_NAME_INDICATION
    #define MBEDTLS_SSL_TRUNCATED_HMAC
    #define MBEDTLS_X509_CHECK_KEY_USAGE
    #define MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE
    #define MBEDTLS_X509_RSASSA_PSS_SUPPORT
    /* mbed TLS modules */
    #define MBEDTLS_AES_C
    #define MBEDTLS_ARC4_C
    #define MBEDTLS_ASN1_PARSE_C
    #define MBEDTLS_BASE64_C
    #define MBEDTLS_BIGNUM_C
    #define MBEDTLS_BLOWFISH_C
    #define MBEDTLS_CAMELLIA_C
    #define MBEDTLS_CCM_C
    #define MBEDTLS_CIPHER_C
    #define MBEDTLS_CTR_DRBG_C
    //#define MBEDTLS_DEBUG_C
    #define MBEDTLS_DES_C
    #define MBEDTLS_DHM_C
    #define MBEDTLS_ENTROPY_C
    #define MBEDTLS_GCM_C
    #define MBEDTLS_HMAC_DRBG_C
    #define MBEDTLS_MD_C
    #define MBEDTLS_MD5_C
    #define MBEDTLS_OID_C
    #define MBEDTLS_PEM_PARSE_C
    #define MBEDTLS_PK_C
    #define MBEDTLS_PK_PARSE_C
    #define MBEDTLS_PKCS5_C
    #define MBEDTLS_PKCS12_C
    #define MBEDTLS_PLATFORM_C
    #define MBEDTLS_RIPEMD160_C
    #define MBEDTLS_RSA_C
    #define MBEDTLS_SHA1_C
    #define MBEDTLS_SHA256_C
    #define MBEDTLS_SHA512_C
    #define MBEDTLS_SSL_CACHE_C
    #define MBEDTLS_SSL_COOKIE_C
    #define MBEDTLS_SSL_TICKET_C
    #define MBEDTLS_SSL_SRV_C
    #define MBEDTLS_SSL_TLS_C
    #define MBEDTLS_X509_USE_C
    #define MBEDTLS_X509_CRT_PARSE_C
    #define MBEDTLS_X509_CSR_PARSE_C
    // ======== Optimizations =========
    /*
    * Save RAM at the expense of interoperability: do this only if you control
    * both ends of the connection! (See coments in "mbedtls/ssl.h".)
    * The minimum size here depends on the certificate chain used as well as the
    * typical size of records.
    */
    #define MBEDTLS_SSL_MAX_CONTENT_LEN 4096
    #include "check_config.h"
    #endif /* MBEDTLS_CONFIG_H */
  4. Set your device's heap to 90KB or more (or increase existing). In the Project window, under Device, open the file startup_xxx.s and set
    Heap_Size = 0x16000
    or more, depending on your application.
  5. Configure the RTX threads
    • If you use RTX v5, you do not need to change the RTX settings, because all resources are statically allocated.
    • If you use RTX v4, you must change the following settings in the file:
      • Increase the Number of concurrent running user threads by 1
      • Increase the Number of threads with user-provided stack size by 1
      • Increase Total stack size [bytes] for threads with user-provided stack size by the value set for the macro TLS_THREAD_STACK_SIZE in TLS_mbed.c (default is 4096)
  6. Update the HTTP Server configuration file (Net_Config_HTTP_Server.h):
    • Change the Port Number to 443 or to 0 (auto-selects 443 for HTTPS or 80 for HTTP)
  7. Build the example and download to Flash. If it fails, please check your "Read/Write Memory Areas" in your target options.
  8. You can test the example from a browser by connecting to "https://board_name" or "https://ip_address" (depending on your settings in Net_Config.c file.
Note
  • The first connection might take a while (a few seconds up to 10s) and depends on the browser and how many sockets/sessions it initially opens (differs in Edge, Chrome, Firefox, etc.). This delay is normal and due to the time required for asymmetric cryptography calculations on the target. After the initial delay, the HTTPS server works almost as fast the HTTP server.
  • Your browser will complain during the connection that the certificate has a problem or is not trusted. You will need to add the certificate to your browser's trusted certificate storage manually.
  • Do not use the test certificate in productive environments as it is not secret. Before shipping your product, make sure that you have added your own certificates and keys.

Creating your own certificates and keys

The Network Component's HTTPS service adds the file Net_Security.c to the project. This file contains generic test keys/certificates which enable the application to run out of the box. If you want to adapt the keys/certificates to your needs, you can do this by modifying this file or by executing the batch file Net_Security.bat that is part of the Network Component.

Net_Security.bat can be registered in µVision under Tools for general usage:

  • Go to Tools –> Customize Tools Menu
  • Click the New (Insert) button and enter a meaningful name, for example "Net_Security Keys"
  • In the Command box enter $PRTE\Network\Net_Security.bat
  • In the Initial Folder box enter $PRTE\Network
  • In the Arguments box enter @K
  • Enable Run Independent
Net_Security_Keys.PNG
Settings required for the Net_Security.bat file

This setting is needed only once in µVision and will work for any project since it uses project related folders.

The file Net_Security.bat is copied to the project (.\RTE\Network) folder together with Net_Security.c. As it is project specific, the batch file can be customized to reflect your specific values for the certificates:

  • CA and Server Private Keys: type (default: RSA) and key_size (default: 2048)
  • CA certificate: issuer_name (default:CN="Test CA",O="Unknown",C=US), serial (default: 0), not_before (default: 20150101000000), not_after (20201231235959)
  • Server certificate: subject_name (default: CN="localhost",O="MyOrganization",C=US), serial (default: 1), not_before (default: 20150101000000), not_after (20201231235959)

The beginning of the file contains some environment settings that can also be changed:

  • RTEPATH: specifies the path to Software Packs. This is required if the batch file is executed directly from Windows. When it is executed from µVision, it is set automatically.
  • Pack Versions (MDK-MW and mbedTLS): only required if you want to select a specific Pack version. By default, the latest available Pack is used.

As soon as you run the batch file from the Tools menu, it will create the keys/certificates and change the Net_Security.c automatically to reflect the changes. You can then continue building the project.

Note
  • The Net_Security.bat file calls the pem2mw.exe utility. This utility does not support all kinds of certificates.
  • If you are using an unsupported certificate, you can bypass pem2mw easily by manually creating the output Net_Security.c file:
    • Adapt Net_Security.bat to skip calling pem2mw (optional)
    • Copy the contents of ca.crt into NetSecurity_ServerCA structure in Net_Security.c and add leading " and trailing \n" to each line
    • Copy the contents of server.crt into NetSecurity_ServerCert structure in Net_Security.c and add leading " and trailing \n" to each line
    • Copy the contents of server.key into NetSecurity_ServerKey structure in Net_Security.c and add leading " and trailing \n" to each line

Code example:
Server.key

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEd3Jlb4FLOZJ51eHxeB+sbwmaPFyh
sONTUYNLCLZeC1clkM2vj3aTYbzzSs/BHl4HToQmvd4Evm5lOUVElhfeRQ==
-----END PUBLIC KEY-----

Net_Security.c

const uint8_t NetSecurity_ServerKey[] =
"-----BEGIN PUBLIC KEY-----\n"
"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEd3Jlb4FLOZJ51eHxeB+sbwmaPFyh\n"
"sONTUYNLCLZeC1clkM2vj3aTYbzzSs/BHl4HToQmvd4Evm5lOUVElhfeRQ==\n"
"-----END PUBLIC KEY-----\n"
;

SMTPS Client

The e-mail client is available in a secure variant. In the Manage Run-Time Environment window, simply select the appropriate variant:

select_smtps.png

Converting the SMTP client to SMTPS

It is also possible to convert an already existing e-mail client to a secure SMTPS e-mail client. A few simple steps are required to achieve this:

  1. Download and install the ARM:mbedTLS Software Pack (see Add the mbed TLS library to a µVision project).
  2. Change the following software components in the Manage Run-Time Environment:
    • Set Network:Service:SMTP Client variant to SMTPS.
    • Enable Security:mbed TLS or resolve this dependency automatically.
  3. Update the mbedTLS_Config.h configuration file with the following (a copy named mbedTLS_config_SMTPS.h is available in the Template folder):
    /*
    * Configuration template for SMTPS
    * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
    * SPDX-License-Identifier: Apache-2.0
    * Licensed under the Apache License, Version 2.0 (the "License"); you may
    * not use this file except in compliance with the License.
    * You may obtain a copy of the License at
    * http://www.apache.org/licenses/LICENSE-2.0
    * Unless required by applicable law or agreed to in writing, software
    * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
    * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    * See the License for the specific language governing permissions and
    * limitations under the License.
    * This file is part of mbed TLS (https://tls.mbed.org)
    */
    /*
    * This set of compile-time options may be used to enable
    * or disable features selectively, and reduce the global
    * memory footprint.
    */
    #ifndef MBEDTLS_CONFIG_H
    #define MBEDTLS_CONFIG_H
    /* System support */
    #define MBEDTLS_ENTROPY_HARDWARE_ALT
    /* mbed TLS feature support */
    #define MBEDTLS_AES_ROM_TABLES
    #define MBEDTLS_CIPHER_MODE_CBC
    #define MBEDTLS_CIPHER_PADDING_PKCS7
    #define MBEDTLS_REMOVE_ARC4_CIPHERSUITES
    #define MBEDTLS_ECP_DP_SECP256R1_ENABLED
    #define MBEDTLS_ECP_DP_SECP384R1_ENABLED
    #define MBEDTLS_ECP_NIST_OPTIM
    #define MBEDTLS_ECDSA_DETERMINISTIC
    #define MBEDTLS_KEY_EXCHANGE_PSK_ENABLED
    #define MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED
    #define MBEDTLS_KEY_EXCHANGE_ECDHE_RSA_ENABLED
    #define MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED
    #define MBEDTLS_ERROR_STRERROR_DUMMY
    #define MBEDTLS_NO_PLATFORM_ENTROPY
    #define MBEDTLS_PK_RSA_ALT_SUPPORT
    #define MBEDTLS_PKCS1_V15
    #define MBEDTLS_PKCS1_V21
    #define MBEDTLS_SELF_TEST
    #define MBEDTLS_SSL_ALL_ALERT_MESSAGES
    #define MBEDTLS_SSL_ENCRYPT_THEN_MAC
    #define MBEDTLS_SSL_EXTENDED_MASTER_SECRET
    #define MBEDTLS_SSL_RENEGOTIATION
    #define MBEDTLS_SSL_MAX_FRAGMENT_LENGTH
    #define MBEDTLS_SSL_PROTO_TLS1_2
    #define MBEDTLS_SSL_ALPN
    #define MBEDTLS_SSL_SESSION_TICKETS
    #define MBEDTLS_SSL_SERVER_NAME_INDICATION
    #define MBEDTLS_VERSION_FEATURES
    #define MBEDTLS_X509_CHECK_KEY_USAGE
    #define MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE
    /* mbed TLS modules */
    #define MBEDTLS_AES_C
    #define MBEDTLS_ASN1_PARSE_C
    #define MBEDTLS_ASN1_WRITE_C
    #define MBEDTLS_BASE64_C
    #define MBEDTLS_BIGNUM_C
    #define MBEDTLS_CCM_C
    #define MBEDTLS_CERTS_C
    #define MBEDTLS_CIPHER_C
    #define MBEDTLS_CTR_DRBG_C
    //#define MBEDTLS_DEBUG_C
    #define MBEDTLS_ECDH_C
    #define MBEDTLS_ECDSA_C
    #define MBEDTLS_ECP_C
    #define MBEDTLS_ENTROPY_C
    #define MBEDTLS_ERROR_C
    #define MBEDTLS_GCM_C
    #define MBEDTLS_HMAC_DRBG_C
    #define MBEDTLS_MD_C
    #define MBEDTLS_OID_C
    #define MBEDTLS_PEM_PARSE_C
    #define MBEDTLS_PK_C
    #define MBEDTLS_PK_PARSE_C
    #define MBEDTLS_PK_WRITE_C
    #define MBEDTLS_PLATFORM_C
    #define MBEDTLS_RSA_C
    #define MBEDTLS_SHA256_C
    #define MBEDTLS_SHA512_C
    #define MBEDTLS_SSL_CACHE_C
    #define MBEDTLS_SSL_COOKIE_C
    #define MBEDTLS_SSL_TICKET_C
    #define MBEDTLS_SSL_CLI_C
    #define MBEDTLS_SSL_TLS_C
    #define MBEDTLS_VERSION_C
    #define MBEDTLS_X509_USE_C
    #define MBEDTLS_X509_CRT_PARSE_C
    #define MBEDTLS_X509_CRL_PARSE_C
    // ======== Optimizations =========
    /*
    * Save RAM at the expense of interoperability: do this only if you control
    * both ends of the connection! (See coments in "mbedtls/ssl.h".)
    * The minimum size here depends on the certificate chain used as well as the
    * typical size of records.
    */
    #define MBEDTLS_SSL_MAX_CONTENT_LEN 8192
    #include "check_config.h"
    #endif /* MBEDTLS_CONFIG_H */
  4. Set your device's heap to at least 49 KB or increase appropriately. In the Project window, under Device, open the file startup_xxx.s and set
    Heap_Size = 0xC000
    or more, depending on your application.
  5. Configure the RTX threads
    • If you use RTX v5, you do not need to change the RTX settings, because all recources are statically allocated.
    • If you use RTX v4, you must change the following settings in the file:
      • Increase the Number of concurrent running user threads by 1
      • Increase the Number of threads with user-provided stack size by 1
      • Increase Total stack size [bytes] for threads with user-provided stack size by the value set for the macro TLS_THREAD_STACK_SIZE in TLS_mbed.c (default is 4096)
  6. Build the example and download to Flash. If it fails, please check your "Read/Write Memory Areas" in your target options.
  7. You can test the example by sending an e-mail to your e-mail account, for example to Gmail or Yahoo.
Note
  • It is not required to create your own certificates or keys to send secure e-mails using SMTPS.