Configuring and Using SSL

Transcription

1 ENF0000AN040 Configuring and Using SSL Application Note Version: October, 2013

2 General TERMS OF USE OF NEW MATERIALS - PLEASE READ CAREFULLY From time to time, Novatel Wireless, in its sole discretion, may make available for download on its website ( or may transmit via mail or , updates or upgrades to, or new releases of, the firmware, software or documentation for its products (collectively, 'New Materials'). Use of such New Materials is subject to the terms and conditions set forth below, and may be subject to additional terms and conditions as set forth in Novatel Wireless's Technical Support Policy (posted on its website) and/or any written agreement between the user and Novatel Wireless. All New Materials are provided AS IS. Novatel Wireless makes no warranty or representation with respect to the merchantability, suitability, functionality, accuracy or completeness of any such New Materials. The user of such New Materials assumes all risk (known or unknown) of such use. Novatel Wireless reserves all rights in such New Materials. The user shall have only a revocable and limited license to use such New Materials in connection with the products for which they are intended. Distribution or modification of any New Materials without Novatel Wireless's consent is strictly prohibited. IN NO EVENT WILL NOVATEL WIRELESS BE RESPONSIBLE FOR ANY INCIDENTAL, INDIRECT, CONSEQUENTIAL OR SPECIAL DAMAGES AS A RESULT OF THE USE OF ANY NEW MATERIALS. NOVATEL WIRELESS 'S MAXIMUM LIABILITY FOR ANY CLAIM BASED ON THE NEW MATERIALS SHALL NOT EXCEED FIFTY U.S. DOLLARS ($50). Version Verification Please ensure you have the latest version of this document by downloading it from i novatelwireless.com

3 Copyright 2013 Novatel Wireless. All rights reserved. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording or otherwise), or for any purpose, without the express written permission of Novatel Wireless. Novatel Wireless and the Novatel Wireless logo are either registered trademarks or trademarks of Novatel Wireless, Inc. in the United States. 251 Renner Pkwy Richardson, TX USA Phone: (972) Fax: (972) info@nvtl.com ii novatelwireless.com

4 Table of Contents 1 Introduction 1 Purpose 2 References 2 Features 2 Application Support 2 Protocol 3 Supported Cipher Suites 3 Certificates 3 2 Configuring And Using SSL 4 Configuring SSL 4 Software Password 5 Certificate Management 5 Installing A Certificate 5 Displaying A Certificate 6 Deleting A Certificate 6 Friend List 6 Using SSL 7 TCP API SSL Configuration 7 TCP PAD SSL Configuration 8 Troubleshooting 9 Event Engine Interface 9 CMS Interoperability 10 iii novatelwireless.com

5 1 Introduction Purpose References Features 1 novatelwireless.com

6 Purpose This document describes how to configure and use the SSL enabled applications that are a part of the HS 3001 software. In this document the term SSL will be used to encompass both the SSL and TLS protocols as defined in RFC 2246, RFC 4346, and RFC References RFC 2246 The TLS Protocol Version 1 RFC 4346 The Transport Layer Security (TLS) Protocol Version 1.1. RFC 5246 The Transport Layer Security (TLS) Protocol Version 1.2 RFC 5280 Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile ENF0000AN001 FTP Application Note CNN0301AT00 AT Command Reference Documentation Features Application Support SSL is a client-server protocol that enables applications to create a secure communications channel. SSL encrypts traffic sent over TCP between the device and the server, validates the identity of the server, and protects the payload from tampering. In the HS 3001, two user applications are SSL-enabled: TCP API - the TCP version of the UDP application UDP PAI TCP PAD - the TCP version of the UDP application UDP PAD Only the TCP versions are SSL-enabled because SSL requires the underlying connectionoriented TCP transport protocol. The HS 3001 supports SSL and requires the HS 3001 modem to initiate SSL connection requests. The remote server must have an SSL server available and must also have the corresponding SSL-enabled application. When configuring for SSL operation, ensure the application's destination port is configured to be the SSL port for the corresponding server application. 2 novatelwireless.com

7 Protocol The HS 3001 SSL software will support SSL 3.0, TLS 1.0, TLS 1.1, and TLS 1.2 versions; it selects the highest possible version when it negotiates with the SSL server. Using a robust downgrade capability, the client and server will select the highest protocol version available on both the client and the server during the protocol negotiation. Supported Cipher Suites When the SSL client in the HS 3001 initiates the SSL negotiation with the SSL server, the supported cipher suites will be transmitted to the server. The connection negotiation will proceed after the SSL client and the SSL server agree on a cipher suite to use. The HS 3001 supports the following cipher suites: TLS_RSA_WITH_AES_128_CBC_SHA (0x3D) TLS_RSA_WITH_AES_256_CBC_SHA (0x3C) TLS_RSA_WITH_AES_128_CBC_SHA256 (0x35) TLS_RSA_WITH_AES_256_CBC_SHA256 (0x2F) TLS_RSA_WITH_RC4_128_SHA (0x05) TLS_RSA_WITH_RC4_128_MD5 (0x04) TLS_RSA_WITH_3DES_EDE_CBC_SHA (0x0A) Certificates The HS 3001 SSL software supports RSA algorithm for public key exchange. Certificates installed on the HS 3001 must be PEM format (base 64 encoded) certificate files. Certificates may be self-signed or signed by a Certificate Authority (CA). The certificate filenames can be up to 64 characters in length and filename extensions can be the length you choose. 3 novatelwireless.com

8 2 Configuring SSL Configuring And Using SSL 4 novatelwireless.com

9 Software Password The SSL protocol in the HS 3001 is a software-keyed feature. If SSL is not enabled from the factory, the customer must use the AT$SSLPW command to enable SSL for use. You only need to apply the SSL key once. Contact Novatel Wireless M2M Customer Support for information on acquiring a software key for SSL. Certificate Management The HS 3001 must have an installed public certificate that corresponds to the SSL server certificate in order to validate the SSL server. The actual certificate will depend on the choice of certificates employed by the SSL server. Certificates contain an expiration date; you must ensure this date is current. When a certificate expires, the SSL will no longer connect. The HS 3001 has a set of AT commands you can use to install, display, and delete certificates. See the AT command reference document for further details. Installing A Certificate Installing a digital certificate in the HS 3001 is a two-step process. 1. Transfer the certificate into the file system 2. Install the certificate Use the HS 3001 FTP client software or the AT$FFS Command to transfer the certificate into the file system. If the certificate resides on a remote host, you can usually transfer the certificate file using FTP. To use FTP, configure the FTP client using the AT$FTPCFG command and then transfer the file with the AT$FTPGET command. The FTP Client will store the transferred certificate in a required file system location. See the FTP Client Application Note for additional information on using the FTP client. If the certificate is available on a locally attached host, use the AT$FFS command to transfer the certificate file. The AT$FFS command installs files into the file system using the USB interface. The AT$FFS=3 command can provide a list of all files from previous file transfers or other applications. See the AT command document for further information on the AT$FFS command. After you transfer a certificate file, use the AT$SSLCI Command to install the certificate. The syntax of the command is AT$SSLCI="certificate filename". The "certificate filename" parameter in the installation command is the same file name used to perform the certificate transfer. When you install a certificate using the AT$SSLCI Command, the system copies the certificate to a location accessible by the SSL software (it does not remove the certificate file from the system). 5 novatelwireless.com

10 AT$SSLCI="certificate name" installs a certificate from the file system After you install the certificate, you may delete the original transferred certificate file from the file system using the AT$FFS=2,"certificate filename" command. Displaying A Certificate To display an installed certificate, use the "AT$SSLCI?" query command. This command will provide the file names of all certificates available to the SSL software. When the SSL is activated, the system parses and loads each installed certificate into memory, which makes it available to support authentication of the server. AT Command AT$SSLCI? Displays all install certificates Deleting A Certificate When SSL starts, the system parses all of the installed certificates and then stores them in system memory. If you no longer need certificates, you should uninstall them to conserve system resources. There are two commands used to delete installed certificates: AT$SSLCD - deletes a single specified certificate AT$SSLCDA - deletes all installed certificates You should make sure that the correct certificates remain installed. Without correct certificates, the SSL negotiation will fail and the HS 3001 will not be able to communicate with the desired server. AT Command AT$SSLCD="certificate name" AT$SSLCDA Uninstall an individual certificate Uninstalls all certficates Friend List The friend list configuration is not SSL specific, but is required to enable TCP API to contact a remote server. The friends list specifies the allowable remote hosts, the port number, and the application usage. Since SSL connections usually will use an SSL designated port number on the remote server, you should verify that you have properly configured the Friend List. TCP API requires that the Friend List usage field be set to "1". See the AT command document for more information on the AT$FRIEND Command. 6 novatelwireless.com

11 Using SSL TCP API SSL Configuration By default, the TCP API operation uses a normal (non-ssl) TCP connection and transmits data unencrypted. Use the AT$TCPSSL Command to enable SSL for TCP API. You can use other methods to start TCP API, but you should use the AT$TCPSSL Command before you activate TCP API. Use the AT$TCPSSL Command to query the current state of the TCP API SSL connection. This Command will display the SSL mode, the SSL connection state, and the negotiated cipher suite. You should also verify that you have correctly configured the FRIEND list for SSL. If you have already registered the HS 3001 and have aquired an IP address, follow this example: at$friend? $FRIEND: 01, 1, "test.nvtl.com",2721,1 ßvalid TCP API friend $FRIEND: 02, 0, " ",0,2 $FRIEND: 03, 0, " ",0,2 $FRIEND: 04, 0, " ",0,2 $FRIEND: 05, 0, " ",0,2 $FRIEND: 06, 0, " ",0,2 $FRIEND: 06, 0, " ",0,2 $FRIEND: 07, 0, " ",0,2 $FRIEND: 08, 0, " ",0,2 $FRIEND: 09, 0, " ",0,2 $FRIEND: 10, 0, " ",0,2 at$tcpssl=1 ßenable SSL for TCP API 7 novatelwireless.com

12 at$tcpapi=1 ßactivate TCP API at$tcpssl? $TCPSSL: 1,3,TLS_RSA_WITH_AES_128_CBC_SHA256 ßshows active SSL connection TCP PAD SSL Configuration By default, the TCP PAD operation uses a normal (non-ssl) TCP connection and transmits data unencrypted. Use the AT$PADSSL Command to enable SSL for TCP PAD. TCP PAD may operate in two separate modes: Client mode Server mode When in client mode, the TCP PAD will initiate connections to the configured destination. In server mode, the TCP PAD will listen for inbound connections. The AT$ACTIVE Command controls mode selection. SSL for TCP PAD will only operate if TCP PAD is in client mode. Use the AT$PADSSL Command to query the current state of the TCP PAD SSL connection. This Command will display the SSL mode, the SSL connection state, and the negotiated cipher suite. The command will display "NONE" as the negotiated cipher suite if the SSL connection is not active. You can use other methods to initiate a PAD session. If you have already registered the HS 3001 and have aquired an IP address, you can follow this as one example: at$hostif=2 ßspecify TCP PAD as the modem interface at$active=1 ßensure TCP PAD is in client mode at$paddst="mysslserver.com",1735 ßconfigure the desired remote PAD server at$padsrc=0 ßallow IP to assign the source TCP port at$padssl=1 ßenable SSL for TCP PAD 8 novatelwireless.com

13 atdt ßstart the connection request Troubleshooting When you use the AT$SSLURC command, the system may display additional URC information concerning the SSL negotiation. When SSL URC display is enabled, the following SSL state information may display as the system negotiates a connection. AT$SSLURC=1 ßenable SSL URC display AT$SSLURC=0 ßdisable SSL URC display URC VALUE Meaning Cause 0 Success, Connect SSL Connection successful 1 Certificate Loaded Certificates successfully loaded 2 Shutdown SSL connection shutdown 3 Error General Error 4 Certificate Error Error parsing certificate 5 System Error System related error, such as timer error, I/O error, system time error 6 Memory Error Error allocating memory of system buffer 7 Cryptographic Error Error related to cipher negotiation 8 Math Error Error in math library 9 RSA Error Error in RSA negotiation 10 Network Error Error in socket handling 11 Protocol Error Error in SSL protocol handshaking URCs will display on the serial port of the last SSL AT command invocation, or if the system has not issued an SSL AT Command, URCs will display on the system's default serial port. Event Engine Interface The HS 3001 has an Event Engine input event to update the status of an SSL connection. When the SSL connection changes state or an error occurs, the Event Engine updates with the new SSL status. The SSL status values are the same values used in the SSL URC display. SSL status updates are sent to the Event Engine regardless of the setting of the SSL URC display. You may use Event Engine scripts to execute any set of output events based on changes in the SSL connection status. Event category Parm1 Parm2 Description SSL Connection Status 9 novatelwireless.com

14 CMS Interoperability To configure SSL communications with CMS, ensure you have deployed the version of CMS that supports SSL connections to the HS Consider the following when using TCP-based connections with CMS or other servers: 1. The normal operating mode for the HS 3001 (when configured for TCP API connection to a server) is to create and maintain the TCP connection as long as the HS 3001 is registered on the cellular network. If you enable TCP API for the HS 3001, it will create a TCP connection to the first configured TCP API host in the friends list. If you terminate the connection, the HS 3001 will attempt to reconnect the TCP connection. This behavior is independent of SSL. 2. Though the HS 3001 may only be initiating a single TCP connection to the server, the server will have to maintain multiple TCP connections simultaneously. Each TCP connection consumes server resources and there is a practical upper limit on the number of simultaneous TCP connections any server can support. SSL places an additional computational and data overhead on each SSL TCP connection. 3. CMS supports a configurable idle timer for TCP connections. If CMS determines a TCP connection has not transmitted data over the timeout period, it will close the TCP connection. However, if still registered on the cellular network, the HS 3001 will immediately attempt to re-establish the TCP connection. Careful consideration should be made as to the setting of the CMS TCP idle timeout versus the periodicity of reporting by the HS SSL connections protect the integrity of the encryption keys by periodically forcing renegotiation of the SSL connection. This time interval depends on the SSL server implementation, but is typically less than 24 hours. 5. SSL connection startup costs can be much higher than the actual data transmitted. Depending on the exact negotiation scenario (i.e. number of certificates required, cipher suites negotiation, etc.) the data cost for establishing an SSL connection may be between 2K to 6K bytes. If an SSL connection is created, the overhead costs are much higher to transmit a single packet than if the connection cost is amortized to transmit many packets over time. 6. Block ciphers pad out data that is shorter than their block size in order to encrypt the data. When used to transmit small data packets, this padding will add to the data costs. 10 novatelwireless.com