Transport layer security protocol for SPWFxxx module
Contents
1. Functionality Cipher Authentication RSA DSA ECDSA Key exchange agreement RSA DH ECDH SRP PSK Symmetric ciphers for encryption RC4 IDEA DES 3DES AES or Camellia Hash MAC for SSLv3 0 or HMAC with MD2 MD4 MD5 SHA 1 SHA 256 after TLSv1 1 and 1 2 standards A complete list of SSL TLS cipher suites can be found in the registry maintained by the Internet assigned numbers authority IANA see 6 in References 6 31 DoclD027745 Rev 1 Ly AN4683 SSL TLS protocol overview 1 1 2 1 2 Change cipher spec protocol The change cipher spec protocol is used to change the keying material used for encryption between the client and server Keying material is raw data that is used to create keys for cryptographic use The change cipher spec protocol consists of a single message to tell the other party in the SSL TLS session that the sender wants to change to a new set of keys The key is computed from the information exchanged by the handshake protocol Alert protocol Alert messages are used to indicate a change in status or an error condition to the peer There are a wide variety of alerts to notify the peer of both normal and error conditions Alerts are commonly sent when the connection is closed an invalid message is received a message cannot be decrypted or the user cancels the operation Record protocol The record protocol receives and encrypts data from the higher layer and deliv2. AN4683 Demonstration package Note Note The accept parameter specifies the TCP port to listen for connections If not specified the default 4433 is used To start the client it is recommended to run AT S TLSCERT2 clean all to clean the Flash memory and then use these AT commands S SETTIME lt seconds gt TLSCERT f_ca lt size gt lt CR gt lt data gt S TLSCERT f_cert lt size gt lt CR gt lt data gt gt Pp Pp gt TLSDOMAIN f_domain lt server domain 5 5 S TLSCERT f_key lt size gt lt CR gt lt data gt S S AT S SOCKON lt hostname gt lt port gt s ind Seconds is the current time expressed in seconds since 1970 01 01 AT S SETTIME can be done only once after module reset AT S TLSCERT lt f_ca f_cert f_key gt lt size gt lt CR gt lt data gt stores certificates or key files in PEM format to Flash memory of the module The first input parameter is used to indicate when a root CA certificate f_ca a client certificate f_cert or key file f_key is passed to the module This command accepts data after the lt CR gt at the end of the command line The host is expected to supply lt size gt of data as last parameter of the command line The size values must be expressed in bytes AT S TLSDOMAIN f_domain lt server domain gt passes the server domain to the module and stores the domain information to Flash memory The server domain is
3. Example 2 TLS Client with one way authentication This second example implements a TLS connection supporting one way authentication The server and CA use RSA 2048 authentication Before running the example the SPWF01Sxxx client must be connected to the Wi Fi LAN as illustrated in Section 3 2 and OpenSSL must be installed on the PC acting as server For testing purposes OpenSSL 1 0 1i has been used as TLS Server Documentation and installation instructions are available on the OpenSSL website see 12 in Heferences The IP addresses of the client and server are automatically assigned by the network router To start the server open a command prompt into the folder Project Examples Example2 and run this line openssl s server cert server cert pem key server key pem accept port The accept parameter specifies the TCP port to listen on for connections If not specified the default 4433 is used To start the client it s recommended to run AT S TLSCERT2 clean all to clean the Flash memory and then use these AT commands AT S SETTIME lt seconds gt AT S TLSCERT f_ca lt size gt lt CR gt lt data gt AT S TLSDOMAIN f_domain lt server domain AT S SOCKON lt hostname gt lt port gt s ind Seconds is the current time expressed in seconds since 1970 Jan 01 AT S SETTIME can be done only once after module reset AT S TLSCERT lt f_ca f_cert f_key gt lt size gt lt CR gt lt data
4. Ti AN4683 JJ Application note Transport layer security protocol for SPWFxxx module Introduction The purpose of this document is to present a demonstration package for creating a secure connection over TCP IP between the Wi Fi module SPWF01Sxxx see 1 in References and a remote server exposing secured service Security is provided by the secure sockets layer SSL and transport layer security TLS protocols The SSL TLS protocols provide security for communication over networks such as the Internet and allow client and server applications to communicate in a way that is confidential and secure The document includes a brief introduction to SSL TLS principles a description of the demonstration package organization and a tutorial with client server connection examples May 2015 DoclD027745 Rev 1 1 31 www st com Contents AN4683 Contents 1 SSL TLS protocol overview 4 1 1 SSL TLS SUDprOlODOIS 5 1 1 1 Handshake protocol 5 1 1 2 Change cipher spec 7 1 1 3 Alert protocol e dies pete iy aes 7 1 1 4 Record protocol x iad ose eae hee Mets wie Rd 7 1 2 Authentication and certificates 7 2 SPWFO1Sxxx use modes 11 2 1 TES DIGIDODI soa he ERR
5. http tools ietf org html rfc5246 Transport Layer Security Wikipedia http en wikipedia org wiki Transport_Layer_Security http www symantec com connect articles apache 2 ssltls step step part 1 IANA registry http www iana org assignments tls parameters tls parameters xhtml Certificates and Authentication RedHat portal https access redhat com site documentation en US Red_Hat_Certificate_System 8 0 html Deployment_Guide Introduction_to_Public_ Key Cryptography Certificates and Authentication html A String Representation of Distinguished Names RFC 4514 http www ietf org rfc r c451 4 txt Internet X 509 Public Key Infrastructure Certificate and Certificate Revocation List Profile RFC 3280 http tools ietf org html rfc3280 Digital certificates IBM information center http publib boulder ibm com infocenter wmqv6 v6r0 index jsp topic 2Fcom ibm mq csqzas doc 2Fsy10600_ htm Server Name Indication Wikipedia http en wikipedia org wiki Server_Name_Indication OpenSSL website www openssl org CVE 2014 3566 CVE list of security vulnerabilities http cve mitre org cgi bin cvename cgi name CVE 2014 3566 14 Oct 2014 DoclD027745 Rev 1 27 31 Certificate generation with OpenSSL AN4683 Appendix A Certificate generation with OpenSSL 28 31 OpenSSL is an open source implementation for PC platforms Win Mac of the SSL TLS protocols providing both client and serv
6. lt sock id gt lt len gt Write application data Secure socket write Secure socket read AT S SOCKQ lt sock id gt Query socket for pending data AT S SOCKR lt sock id gt lt len gt Read application data Application Wi Fi module AP Remote host TLS Client Secure Server Mutual authentication In mutual authentication mode both parties client and server share their signed certificates In order to verify server certificate the client 1 verifies the digital signature 2 checks that the date of the certificate is in range 3 verifies the domain Additionally for client authentication the client also 4 sends its certificate to the server Be aware that in order to verify the client certificate the server should have access to the issuing certificate public or private To achieve this purpose the following steps must be completed DoclD027745 Rev 1 Ly AN4683 SPWF01Sxxx use modes Note 1 The issuing Root CA certificate must be loaded in advance into client see AT S TLSCERT in PEM format 2 check the date the module reference time must be initialized after each module reset see AT S SETTIME the time refers to UTC format and must be expressed as the time in seconds since 1970 Jan 01 3 The domain passed to the client see AT S TLSDOMAIN must match the name specified in the server certificate Common Name or others 4 The certificate
7. ECDSA WITH AES 128 CBC SHA 0xC0 0x09 TLS1 0 1 1 1 2 TLS ECDH ECDSA WITH AES 128 CBC SHA 0xC0 0x04 TLS1 0 1 1 1 2 TLS ECDHE ECDSA WITH RCA4 128 SHA 0xC0 0x07 TLS1 0 1 1 1 2 TLS ECDSA WITH RC4 128 SHA 0xC0 0x02 TLS1 0 1 1 1 2 TLS ECDHE ECDSA WITH 3DES EDE SHA 0xC0 0x08 TLS1 0 1 1 1 2 TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA 0xC0 0x03 TLS1 0 1 1 1 2 DoclD027745 Rev 1 11 31 SPWF01Sxxx use modes AN4683 2 3 2 4 2 4 1 12 31 Table 2 Demonstrator cipher suites continued Cipher suites Version TLS ECDH RSA WITH AES 256 CBC SHA 0xC0 0x0F TLS1 0 1 1 1 2 TLS_ECDHE_RSA_WITH_AES 128 CBC_SHA 0xC0 0x13 TLS1 0 1 1 1 2 TLS ECDH RSA WITH AES 128 CBC SHA 0xC0 0x0E TLS1 0 1 1 1 2 TLS ECDHE RSA WITH RC4 128 SHA 0xC0 0x11 TLS1 0 1 1 1 2 TLS ECDH RSA WITH RC4 128 SHA 0xC0 0x0C TLS1 0 1 1 1 2 TLS ECDHE RSA WITH 3DES EDE CBC SHA 0xC0 0x12 TLS1 0 1 1 1 2 TLS RSA WITH SDES EDE 0xC0 0x0D TLS1 0 1 1 1 2 TLS RSA WITH AES 256 CBC SHA256 0x00 0x3D TLS1 2 TLS RSA WITH AES 128 CBC SHA256 0x00 0x3C TLS1 2 TLS RSA WITH AES 256 CBC SHA 0x00 0x35 TLS1 0 1 1 1 2 TLS RSA WITH AES 128 CBC SHA 0x00 0x2F TLS1 0 1 1 1 2 SSL RSA WITH 128 SHA 0x00 0x05 SSL3 0 TLS1 0 1 1 1 2 SSL RSA WITH RC4 128 MD5 0x00 0x04 SSL3 0 TLS1 0 1 1 1 2 SSL RSA WITH 3DES EDE CBC SHA 0x00 0x0A SSL3 0 TLS1 0 1 1 1
8. RE RE Rua Ee ex eel REA eeeueetamasd 11 2 2 Supported ciphers list i isses es e RR eee ERE RR ER 11 2 3 Domain name check for server certificate 12 2 4 Authentication gee uc ee 12 2 4 1 Anonymous negotiation 12 2 4 2 One way authentication 13 2 4 3 Mutual authentication 14 2 5 Protocol version downgrade 16 2 6 Pseudo random number generator 16 3 Demonstration package 17 3 1 Package directories 17 3 2 Wi Fi module setup 18 3 3 Example 1 TLS Client with mutual authentication 18 3 4 Example 2 TLS Client with one way authentication 20 3 5 Example 3 Gmail SMTP server access with anonymous negotiation 22 3 6 Example 4 Xively example with anonymous negotiation 22 3 7 Example 5 connect to HTTPS my st com 22 4 Known limitations and revisions 25 5 GIOSSANY Rick a wo ae ee de a ol E RO Qu RR Ue ee 26 6 References trapna i ERARE wa 27 2 31 DoclD027745 Rev 1 Ly AN4683 Contents Appendix A Certificate gene
9. SSL TLS protocol overview AN4683 8 31 X 509 system the subject of the certificate is identified by a distinguished name DN A DN is a series of name value pairs that uniquely identify an entity The following attribute types are commonly found in the DN CN Common name T Title Organization name OU Organization unit name L Locality name ST or SP or S State or province name C Country The X 509 standard provides for a DN to be specified in a string format For example CN John O STM OU Test C IT The common name CN can describe an individual user or any other entity for example a web server DNs may include a variety of other name value pairs The rules governing the construction of DNs can be complex For comprehensive information about DNs see 8 in References In this model of trust relationships a certification authority CA is an independent and trusted third party that issues digital certificates to provide assurance that the public key of an entity truly belongs to that entity The roles of a CA are receiving a request for a digital certificate to verify the identity of the requester before building signing and returning the personal certificate To provide the CA s own public key in its CA certificate To publish lists of certificates that are no longer trusted in a certificate revocation List CRL An X 509 certificate issued by the CA binds a particular public key to the name of the DN the
10. client key files must be loaded Authentication ciphers ECDSA with all EC curves Maximum allowed size for files uploaded to module is approximately overall 3 1 Package directories The demonstration package is contained in the project folder and is organized as described below e Project firmware this folder contains the firmware binary 9 DoclD027745 Rev 1 17 31 Demonstration package AN4683 3 2 3 3 18 31 Project examples contained here are the certificates and configuration files for test examples The examples folder contains four test examples for creating a TLS secure connection between the SPWF01Sxxx module client and a remote server e Example 1 TLS Client with Mutual authentication The client server and CA use ECC authentication Section 3 3 e Example 2 TLS Client with one way authentication The server and CA use RSA 2048 authentication Section 3 2 e Example 3 Gmail SMTP server access with Anonymous negotiation Section 3 5 e Example 4 Xively example with Anonymous negotiation Section 3 6 Wi Fi module setup This section describes the essential steps for setting up the SPWFO01Sxxx module to enable the TLS features A complete list of AT commands including a detailed description of the use of the commands are contained in see 2 in References To couple the SPWF01Sxxx module with a Wi Fi access point SSID WPA PSK passphrase providing a connecti
11. gt stores certificates or key files to the module In case of one way authentication only the CA certificate f_ca must be loaded the data must be in PEM format This command accepts data after the CR at the end of the command line The host is expected to supply lt size gt of data as last parameter of the command line The size values must be expressed in bytes AT S TLSDOMAIN f_domain lt server domain gt passes the server domain to the module and stores the domain information to Flash memory The server domain is a string of DoclD027745 Rev 1 Ly AN4683 Demonstration package Note characters that must match the name specified in the server certificate Common Name or others When using AT S TLSCERT and AT S TLSDOMAIN with f_ca f_cert f_key and f_domain the file information is stored to Flash memory since Flash memory is non volatile any file stored in Flash memory will remain intact even when switching off or resetting the module Thus to remove file information from Flash you can use the command AT S TLSCERT2 clean lt f_calf_cert f_key f_domain gt to selectively remove a specific file or AT S TLSCERT2 clean all to remove all files information from Flash Note Loading files to Flash memory is always preferred Alternatively you can use AT S TLSCERT lt ca cert key gt lt size gt lt CR gt lt data gt and AT S TLSDOMAIN domain lt server domain to load files to RAM but note that a RAMis volatil
12. revisions 4 Known limitations and revisions Due to PODDLE vulnerability see 13 in References there are plans to drop SSL3 0 support in future releases of this firmware Ly DoclD027745 Rev 1 25 31 Glossary AN4683 5 26 31 Glossary AES Camelia DES DH DHE DSA DSS ECDH ECDSA HMAC HTTPS IANA IDEA IETF KRB5 MAC MD5 PSK RSA RC4 SHA SRP SSL TLS 3DES Advanced encryption standard Block cipher developed by Mitsubishi and NTT Data encryption standard Diffie Hellman Diffie Hellman ephemeral Digital signature algorithm Digital signature standard Elliptic curve Diffie Hellman Elliptic curve digital signature algorithm keyed hash message authentication code Hypertext transfer protocol secure Internet assigned numbers authority International data encryption algorithm Internet engineering task force Kerberos Message authentication code Message digest algorithm 5 Pre shared key Rivest Shamir Adleman Rivest cipher 4 Secure hash algorithm Secure remote password protocol Secure sockets layer Transport layer security Triple data encryption algorithm DoclD027745 Rev 1 AN4683 References 6 References 10 11 12 13 SPWFO01 Sxxx WiFi module www st com wifimodules UM1695 Command set reference guide for AT full stack for SPWF01Sx series of Wi Fi modules User Manual of SPWF01Sxxx The Transport Layer Security TLS Protocol Version 1 2 RFC 5246
13. 15 initialized at boot time and is based on the RC4 stream cipher algorithm DoclD027745 Rev 1 4 AN4683 Demonstration package 3 Demonstration package The functions of the demonstration package are summarized in Table 3 Table 3 Demonstration package functions Available versions SSLv3 0 and TLSv1 0 1 1 and 1 2 Automatic SSL TLS Client downgrade of protocol version Cipher suites Table 2 Public key algorithms RSA 1024 2048 ECDSA Key exchange agreement ECDH ECDHE Symmetric ciphers for AES 128 and 256 CBC 3DES ARC4 encryption Hash MD5 SHA 1 SHA 256 ECC support EC curves over 192 224 384 256 521 bit prime field Certificates X 509 certificate support PEM format Anonymous For module configuration see Section 2 4 1 and Figure 5 One way authentication For module configuration see Section 2 4 2 and Figure 6 In particular notice that Module reference time must be initialized Root CA certificate and domain name of the server must be loaded Authentication ciphers ECDSA with all EC curves RSA 1024 and RSA 2048 Configurations Maximum allowed size for files uploaded to module is approximately 1 3KB Mutual authentication For module configuration see Section 2 4 3 and Figure 7 In particular Module reference time must be initialized Root CA certificate and domain name of the server client certificate and
14. 2 Domain name check for server certificate When making a TLS connection the client requests a digital certificate from the server Once the server sends the certificate the client examines it and compares the domain it was trying to connect to with the name common name or others included in the certificate If a match is found the connection proceeds as normal If a match is not found the user may be warned of the discrepancy and the connection may be aborted as the mismatch may indicate an attempted man in the middle attack The demonstrator allows the user to bypass the warning to proceed with the connection with the user taking on the responsibility of trusting the certificate and the connection Authentication As mentioned in Section 1 SSL TLS requires a server certificate and optionally a client certificate to be exchanged during handshake Depending on the required level of trust we can have three authentication modes anonymous one way and mutual authentication The following three sub sections describe how to configure the SPWF01Sxxx module to enable the three different modes Anonymous negotiation In case of anonymous TLS connection the user assumes to be in a trusted environment thus party authentication is not required Even if server sends a certificate the client will skip the verification of authenticity DoclD027745 Rev 1 Ly AN4683 SPW
15. 465 AT S SOCKON smtp gmail com 465 s In this example the parameter ind is omitted if enabled this option requires to read the socket when a pending indication message is received When the TLS handshake is successful the AT S SOCKON gives back the sock id only then is it possible to use the AT S SOCKW to make the login on Gmail server by sending first EHLO command and then AUTH PLAIN with your credentials using the base64 encoded username password Example 4 Xively example with anonymous negotiation Xively is a cloud platform for developing and managing commercial services on the Internet of Things Xively ensures protected communication channels by using SSL TLS authentication and encryption In this example the CA certificate is not provided and the client is not expected to verify the server certificate The client is not providing its certificate so the negotiation is anonymous To access Xively server it is recommended to run AT S TLSCERT2 clean all to clean the Flash memory and then open a secure connection on port 8091 AT S SOCKON api xively com 8091 5 In this example the parameter ind is omitted if enabled this option requires to read the socket when a pending indication message is received Example 5 connect to HTTPS my st com This example shows how to use the Wi Fi module as a TLS client to connect to a secure HTTPS server and to send receive HTTP requests replies The HTTPS server we want to conne
16. F01Sxxx use modes Note This mode is particularly attractive for privacy preserving solutions and also for low memory consumption since it does not require certificates storage But it increases the chance for intruder in the middle attacks Figure 5 lists the AT required commands for opening a secure connection with anonymous negotiation followed by writing to and reading sockets Figure 5 AT commands for anonymous negotiation ee AT S SOCKON lt hostname gt lt port gt s TLS Handshake key agreement lt 3 CEP AT S SOCKW lt sock id len Write application data Secure socket write Secure socket read AT S SOCKQ lt sock id u Query socket for pending data AT S SOCKR lt sock id len Read application data Application Wi Fi module AP Remote host TLS Client Secure Server 2 4 2 One way authentication In one way authentication mode the server sends its signed certificate to an unauthenticated client In order to verify the server certificate the client 1 verifies the digital signature 2 checks that the date of the certificate is in range 3 verifies the domain To achieve this purpose the following steps must be completed 1 the issuing root CA certificate must be loaded in advance into client see AT S TLSCERT in PEM format 2 To check the date the module reference time must be initialized after each module reset see AT S SETTIME the time refers to UTC format and must be expressed as the time in seconds si
17. a string of characters that must match the name specified in the server certificate Common Name or others When using AT S TLSCERT and AT S TLSDOMAIN with f_ca f_cert and f_domain the file information is stored to Flash memory since Flash memory is non volatile any file stored in Flash memory will remain intact even when switching off or resetting the module Thus to remove file information from Flash you can use the command AT S TLSCERT2 clean f cert f key f domain to selectively remove a specific file or AT S TLSCERT2 clean all to remove all files information from Flash ones Note that loading files to Flash memory is always preferred Alternatively you may use AT S TLSCERT lt ca cert key gt lt size gt lt CR gt lt data gt and AT S TLSDOMAIN domain lt server domain to load files to RAM but note that a RAM is volatile and in this case the loaded file information is lost after switch off or module reset b files stored in RAM have higher priority than Flash ones c files upload to RAM is deprecated in favor of Flash AT S SOCKON lt hostname gt lt port gt s ind opens a secure socket to server hostname on port The hostname is the IP address of the server the port must correspond to the one specified in OpenSSL server options and the s parameter specifies a request for secure Socket The parameter ind is optional and provides the indication WIND 55 see below that some data has been received if e
18. and private key of the client must be loaded in advance into client see AT S TLSCERT in PEM format The server is in charge of client authentication If the client authentication fails it s up to the server to either keep or close the connection e Option 1 If client authentication succeeds the handshake is completed and the connection proceeds as normal e Option 2 if the client authentication fails but the server neglects it then the handshake is completed and the connection proceeds as normal e Option 3 if the client authentication fails and this blocks the server then the handshake is interrupted the connection is reset by the server and the client generates a warning message ERROR SSL TLS unable to connect the connection is closed As such to solve connection errors users either need to change authentication mode i e switch to anonymous mode Section 2 4 1 or one way mode Section 2 4 2 or load the correct certificates and key The mutual mode is clearly more resource demanding than previous ones Due to memory limitations the adoption of mutual authentication is limited to specific authentication ciphers it is recommended to use ECC ciphers up to 521 key length while RSA 1024 and RSA 2048 should be avoided as it could exceed memory resources The maximum allowed size for files uploaded to the module CA certificate domain name client certificate and client key is approximately 3 KB overall After the cl
19. certificate identifies Only the public key certified by the certificate will work with the corresponding private key possessed by the DN identified by the certificate DoclD027745 Rev 1 Ly AN4683 SSL TLS protocol overview The contents of a certificate according to the X 509 version 3 specifications may include version number of the X 509 standard supported by the certificate Thecertificate s serial number Every certificate issued by a CA has a serial number that is unique among the certificates issued by that CA Information about the user s public key including the algorithm used and a representation of the key itself DN of the CA that issued the certificate The period during which the certificate is valid The DN of the certificate subject which is also called the subject name For example in an SSL client certificate this is the user s DN Optional certificate extensions which may provide additional data used by the client or server cryptographic algorithm or cipher used by the issuing CA to create its own digital signature CA s digital signature obtained by hashing all of the data in the certificate together and encrypting it with the CA s private key The certificate text format begins with the following line followed by certificate data which should be base 64 encoded as described by RFC 1113 The certificate information must end with
20. ct to is https my st com In this example we are not verifying the server s certificate anonymous negotiation so we are not uploading any certificate to the module In case you need to authenticate the server you have to configure the module as in example 2 properly set the appropriate CA certificate domain name and time DoclD027745 Rev 1 Ly AN4683 Demonstration package 4 The first step is to open the secure connection to the HTTPS server it is recommended to run AT S TLSCERT2 clean all to clean the Flash memory and then open a secure connection to hostname my st com on port 443 as below Note that the parameter ind is enabled to activate asynchronous indications of pending data from the server AT S SOCKON my st com 443 5 ind lt CR gt lt CR gt lt LF gt ID 00 lt CR gt lt LF gt lt CR gt lt LF gt OK When the TLS Handshake is successful the AT S SOCKON gives back the sock id and all the data exchanged from now on are encrypted with the newly established session key The second step is to send an HTTPS message to the server the following code shows how to use the AT S SOCKW to send a basic HTTP GET request AT S SOCKW 00 18 lt CR gt GET HTTP 1 1 lt CR gt lt LF gt lt CR gt lt LF gt OK The server response to the above GET request is signaled by a couple of asynchronous indications see the WIND 55 in the box below In order to get and decrypt the received data we have to
21. e and in this case the loaded file information is lost after switch off or module reset b files stored in RAM have higher priority than those in Flash c file upload to RAM is deprecated in favor of Flash AT S SOCKON lt hostname gt lt port gt s ind opens a secure socket to server hostname on port The hostname is the IP address of the server the port must correspond to the one specified in OpenSSL server options and the s parameter specifies a request for secure Socket The parameter ind is optional and provides the indication WIND 55 see below that some data has been received if enabled it is strongly suggested to immediately empty the buffer when pending data is received see SOCKQ and SOCKR commands below When the TLS handshake is successful the AT S SOCKON gives back the sock id only then is it possible to write data to and read from the secure socket using AT S SOCKW AT S SOCKQ and AT S SOCKR If the parameter ind was enabled in SOCKON asynchronous indications of pending data from the secure socket may arrive at any time and have the format lt CR gt lt LF gt WIND 55 Pending Data lt sock id gt ENC lt CR gt lt LF gt When WIND 55 indications occur the pending data is still encrypted thus the length of decrypted data is not known in advance The SOCKQ can be used to get the actual length of the data decrypted by TLS library and already waiting for reading Up to 4 consecutive WIND 55 messages w o SOCKR are
22. er functionalities The core library written in the C programming language implements the basic cryptographic functions and provides various utility functions For testing purposes OpenSSL 1 0 1i has been used as TLS Server For documentation and installation instructions please refer to OpenSSL website see 12 in References Just for example purposes included below are the OpenSSL commands to generate RSA and EC compatible certificates and associated private keys Example for generating RSA signed certificates Generate key pair and a self signed certificate for the CA trusted certificate 1 openssl genpkey out ca key pem outform PEM algorithm rsa pkeyopt rsa keygen bits 1024 2 openssl req new key ca key pem days 6500 set serial 1111 subj C IT ST Lombardia L Milan O STM OU R amp D CN CA domain out ca cert pem x509 Generate server certificate key pair 3 openssl genpkey out server key pem outform PEM algorithm rsa pkeyopt rsa keygen bits 1024 4 openssl req new key server key pem days 6500 set serial 2222 subj C IT ST Lombardia L Milan O STM OU R amp D CN server domain out server cert 5 openssl ca in server cert req pem out server cert pem days 6500 keyfile ca key pem cert ca cert pem notext batch Generate client certificate key pair 6 openssl genpkey out client key pem outform PEM algorithm rsa pkeyopt rsa_keygen_bits 1024 7 openssl req new key client_ke
23. ers it to the transport layer As shown in Figure 3 the record protocol takes the data fragments it into TLSPlaintext blocks with a size appropriate to the cryptographic algorithm Then it optionally compresses or for data received decompresses the TLSPlaintext applies a MAC or HMAC HMAC is supported only by TLS to get the hash tag Finally the TLSCompressed data and hash tag and some padding eventually are concatenated and encrypted or decrypted using the information negotiated during the handshake protocol Encryption and hash ensure respectively the confidentiality and the integrity of the plaintext Figure 3 Record protocol operations Data from higher layer Fragment lt 274 Bytes 16384 Bytes TLSPlaintext EN Compresso RIS OPONA TLSCiphertext Payload of TCP segment Authentication and certificates SSL TLS requires a server certificate and optionally a client certificate The digital certificate certifies the ownership of a public key by the named subject of the certificate also known as public key certificates This allows others parties to rely upon signatures or assertions made by the private key that corresponds to the public key that is certified Digital certificates used in SSL TLS comply with the X 509 standard see 8 in References which specifies the information required and the formats for public key certificates In an DoclD027745 Rev 1 7 31
24. erverHelloDone message indicating the end of this phase of negotiation 7 If the server has sent a CertificateRequest message the client must send the Certificate message For example the client uses an X 509 digital certificate 8 Theclient sends a ClientKeyExchange message This message contains the premaster secret used in the generation of the symmetric encryption keys and the message authentication code MAC keys The client encrypts the pre master secret with the public key of the server Note The public key is sent by the server in the digital certificate or in ServerKeyExchange message 9 Ifthe client sent a digital certificate to the server the client sends a CertificateVerify message signed with the client s private key By verifying the signature of this message the server can explicitly verify the ownership of the client digital certificate 10 The client sends a ChangeCipherSpec message announcing that the new parameters cipher method keys have been loaded 11 The client sends a finished message It is the first message encrypted with the new cipher method and keys 12 The server responds with a ChangeCipherSpec and a finished message from its end 13 The SSL handshake protocol ends and the encrypted exchange of application data can be started During the initial handshaking phase the client and server negotiate cipher suites which specify a cipher for each of the following functionalities Table 1 Ciphers
25. guaranteed To prevent data loss it is suggested to empty the buffer by using the AT S SOCKR command and to avoid exceeding 4 indications AT S SOCKW lt sock id gt lt len gt AT S SOCKQ lt sock id gt AT S SOCKR lt sock id gt lt len gt when using a secure socket the module can handle data packets up to 3 KB This means that the len parameter in AT S SOCKW AT S SOCKR can be up to 3072 bytes Detailed description of AT commands is contained in see 2 in References DoclD027745 Rev 1 21 31 Demonstration package AN4683 3 5 3 6 3 7 22 31 Example 3 Gmail SMTP server access with anonymous negotiation To protect SMTP communications server can use SSL TLS encryption to provide authentication and information encryption To enable the SMTP client to verify the SMTP server certificate the issuing CA certificates should be made available to the client In this case the certificate is not provided and the client is not expected to verify server certificate Even the SMTP client is not providing its certificate so the negotiation is anonymous For the purpose of the example the Gmail SMTP server is used Since it requires SMTP authorization a Gmail account is needed for username the full Gmail address e g example gmail com and password options To access SMTP server it is recommended to run AT S TLSCERT2 clean all to clean the Flash memory and then open a secure connection on port
26. ient is configured as in Figure 7 the host can open a secure socket DoclD027745 Rev 1 15 31 SPWF01Sxxx use modes AN4683 2 5 2 6 16 31 Figure 7 AT commands for mutual authentication Initialize module RTC only after reset AT S SETTIME lt seconds gt CA root Certificate for Server authentication AT S TLSCERT f_ca lt size gt AT S TLSCERT f_cert lt size gt Client certificate AT S TLSCERT f_key lt size gt Client private key AT S TLSDOMAIN f_domain lt domain gt Server domain TLS Handshake authentication and key agreement AT S SOCKON lt hostname gt lt port gt s Opens secure socket Secure socket write r Secure socket read AT S SOCKW lt sock id gt lt len gt Write application data AT S SOCKQ lt sock id gt Query socket forpending data TT AT S SOCKR kid l Read application data Application Wi Fi module AP Remote host TLS Client Secure Server Protocol version downgrade The client is able to connect to a server running SSLv3 0 to TLSv1 2 protocol version Thanks to the version downgrade capability the client can use the highest protocol version supported by the server and eventually downgrade to SSLv3 0 if needed Pseudo random number generator The SPWF01Sxxx module provides a software based pseudo random number generator PRNG The
27. iteratively call AT S SOCKQ and AT S SOCKR to process all the received pending data as follows TWIND 55 Pending Data 0 ENC lt CR gt lt LF gt lt CR gt lt LF gt WIND 55 Pending Data 0 ENC lt CR gt lt LF gt AT S SOCKQ 00 lt CR gt lt CR gt lt LF gt DATALEN 483 lt CR gt lt LF gt lt CR gt lt LF gt OK AT S SOCKR 00 483 lt CR gt 1 1 302 Found lt CR gt lt LF gt Date Tue 31 Mar 2015 08 48 16 GMT lt CR gt lt LF gt Location https my st com cas login service https my st com CR LF Content Length 238 lt CR gt lt LF gt Content Type text html charset iso 8859 1 CR LF Proxy Connection Keep Alive lt CR gt lt LF gt Connection Keep Alive lt CR gt lt LF gt lt CR gt lt LF gt lt DOCTYPE HTML PUBLIC IETF DTD HTML 2 0 EN gt lt LF gt lt html gt lt head gt lt LF gt DoclD027745 Rev 1 23 31 Demonstration package AN4683 lt title gt 302 Found lt title gt lt LF gt lt head gt lt body gt lt LF gt lt hl gt Found lt h1 gt lt LF gt lt p gt The document has moved lt a href https my st com cas login service https my st com gt here lt a gt lt p gt lt LF gt lt body gt lt htm1 gt lt LF gt lt CR gt lt LF gt OK AT S SOCKQ 00 lt CR gt lt CR gt lt LF gt DATALEN O lt CR gt lt LF gt lt CR gt lt LF gt OK 9 24 31 DoclD027745 Rev 1 AN4683 Known limitations and
28. nabled it is strongly suggested to immediately empty the buffer when a pending data is received see SOCKQ and SOCKR commands below When the TLS handshake is successful the AT S SOCKON gives back the sock id only then is it possible to write data to and read from the secure socket using AT S SOCKW AT S SOCKQ and AT S SOCKR If the parameter ind was enabled in SOCKON asynchronous indications of pending data from the secure socket may arrive at any time and have the format lt CR gt lt LF gt WIND 55 Pending Data lt sock id gt ENC lt CR gt lt LF gt DoclD027745 Rev 1 19 31 Demonstration package AN4683 Note 3 4 Note Note 20 31 When WIND 55 indications occur the pending data is still encrypted thus the length of decrypted data is not known in advance The SOCKQ can be used to get the actual length of the data decrypted by TLS library and already waiting for reading Up to 4 consecutive WIND 55 messages w o SOCKR are guaranteed To prevent data loss it is suggested to empty the buffer by using the AT S SOCKR command and to avoid exceeding 4 indications AT S SOCKW lt sock id gt lt len gt AT S SOCKQ lt sock id gt AT S SOCKR lt sock id gt lt len gt When using a secure socket the module can handle data packets up to 3 KB This means that the len parameter in AT S SOCKW and AT S SOCKR can be up to 3072 bytes Detailed description of AT commands is contained in see 2 in References
29. nce 1970 Jan 01 3 The domain passed to the client see AT S TLSDOMAIN must match the name specified in the server certificate Common Name or others If the verification of the server certificate succeeds the connection proceeds as normal DoclD027745 Rev 1 13 81 SPWF01Sxxx use modes AN4683 Note Note 2 4 3 14 31 If verification fails either for signature verification error time or domain mismatch then the client throws a warning message ERROR SSL TLS unable to connect and the connection is closed As such to solve this connection error users either need to turn off verification of the server i e switch to anonymous mode see Section 2 4 1 or load the correct CA certificate The one way authentication works with any cipher reported in Table 2 including all ECC ciphers up to 521 key length RSA 1024 and RSA 2048 The maximum allowed size for files uploaded to module is approximately 1 3 KB After the client is configured as in Figure 6 the host can open a secure socket Figure 6 AT commands for one way authentication AT S SETTIME lt seconds gt Initialize module RTC only after reset CA root Certificate for Server authentication AT S TLSCERT f_ca lt size gt AT S TLSDOMAIN f_domain lt domain gt Server domain TLS Handshake AT S SOCKON lt hostname gt lt port gt s authentication and key agreement Opens secure socket AT S SOCKW
30. on to the Local Area Network LAN and to the Internet these are the necessary AT commands AT S SCFG wifi_mode 0 FS SCFG wifi priv mode 2 S SSIDTXT SSID S SCFG wifi text WPA PSK passphrase gt FS SCFG wifi mode 1 T CFUN 1 pp DD Db gt Once the module is connected to the access point it is ready to open a secure socket Notice that due to memory limitations the SPWFO01Sxxx module allows the opening of one single secure socket at a time i e if you want to open a new secure socket you must first close any open one Example 1 TLS Client with mutual authentication This first example implements a TLS connection supporting mutual authentication The client server and CA use EC cipher Before running this example the SPWF01 Sxxx client must be connected to the Wi Fi LAN as illustrated in Section 3 2 and OpenSSL must be installed on the PC acting as server For testing purposes OpenSSL 1 0 1i has been used as TLS Server Documentation and installation instructions are available on the OpenSSL website see 12 in Heferences The IP addresses of the client and server are automatically assigned by the network router To start the server open a command prompt in the folder Project Examples Example1 and run this line 551 s server cert server cert pem key server key pem CAfil root ca of client pem Verify 2 verify return error accept port DoclD027745 Rev 1 Ly
31. phic library targeted for embedded applications The following sections illustrate the main security features supported TLS protocol The SPWF01Sxxx module integrates a lightweight SSL TLS stack and a cryptographic library To meet device memory constraints the demonstrator enables just a subset of cryptographic algorithms with respect to Table 1 The SPWF01Sxxx implements a SSL TLS client with the features listed below S SLv3 0 and TLSv1 0 1 1 and 1 2 with automatic downgrade of protocol version Server and client authentication Multiple hashing functions MD5 SHA 1 SHA 256 Block stream and authenticated ciphers AES 128 and 256 CBC 3DES ARCA Public key algorithms RSA 1024 2048 ECDSA Key exchange ECDH ECDHE support EC curves over 192 224 384 256 521 bit prime field 509 certificate support PEM format Supported ciphers list Table 2 Demonstrator cipher suites Cipher suites Version TLS ECDHE RSA WITH AES 128 CBC SHA256 0xC0 0x27 TLS1 2 TLS ECDHE ECDSA WITH AES 128 CBC SHA256 0xC0 0x23 TLS1 2 TLS ECDH RSA WITH AES 128 CBC SHA256 0xC0 0x29 TLS1 2 TLS ECDH ECDSA WITH AES 128 CBC SHA256 0xC0 0x25 TLS1 2 TLS ECDHE ECDSA WITH AES 256 SHA 0xC0 0x0A TLS1 0 1 1 1 2 TLS ECDH ECDSA WITH AES 256 CBC SHA 0xC0 0x05 TLS1 0 1 1 1 2 TLS ECDHE
32. ration with OpenSSL 28 7 REVISION history asser skew REA RR Rd Ra Rae at 30 Ly DoclD027745 Rev 1 3 31 SSL TLS protocol overview AN4683 4 31 SSL TLS protocol overview Originally developed by Netscape in the mid 1990s the secure sockets layer SSL is a cryptographic protocol designed to provide communication security over the Internet see 3 in References Version 1 0 never publicly released while version 2 0 was released in February of 1995 but contained a number of security flaws which ultimately led to the design of SSL version 3 0 see 4 in References SSLv3 0 was a complete redesign of the protocol and is still widely supported since 1996 The IETF standards body adopted SSLv3 0 with minor tweaks and published it as TLS version 1 0 RFC 2246 1999 The two versions are very similar but interoperability is precluded TLSv1 2 RFC 5246 2008 is the latest and recommended version which is superior because it offers flexibility and key features that were unavailable in earlier protocol versions All TLS versions were further refined RFC 6176 2011 removing their backward compatibility with SSL such that TLS sessions will never negotiate the use of SSLv2 0 As shown in Figure 1 SSL TLS is typically applied in TCP IP protocol stacks and provides security services on top of the transport layer The protocol is composed of two layers the TLS record layer and
33. rposes or when the parties know and trust each other A self signed certificate is a certificate that is signed by the same entity whose identity it certifies There is no central CA TLS supports three authentication modes Mutual authentication both parties client and server share their signed certificates and authenticate each other Mutual authentication provides stronger security by assuring that the identity on both sides of the communication are known One way authentication only the server sends its signed certificate and is authenticated by the client The client is not required to send the server a digital certificate and remains unauthenticated no certificate Anonymous neither entity authenticates the identity of the other party Each party is responsible for verifying that the other s certificate is valid and has not expired or been revoked In case of one way or mutual authentication because certificate validation requires that root CA keys be distributed independently it is assumed the remote end must already possess a root CA certificate to accomplish validation DoclD027745 Rev 1 Ly AN4683 SPWF01Sxxx use modes 2 2 1 2 2 SPWF01Sxxx use modes The demonstrator allows secure TCP IP connection to be created between the Wi Fi module SPWF01Sxxx see 1 in References and a remote server exposing secured service The SPWF01Sxxx module includes a lightweight SSL TLS stack and a cryptogra
34. session ID peer certificate s the cipher suite the compression algorithm and a shared secret that is used to generate the session key Figure 2 depicts the message flow for a full handshake process see 5 in References The optional value indicates optional or situation dependent messages i e in the case of mutual authentication a TLS server must send its certificate and request a certificate from the client while in the case of anonymous negotiation the optional messages may be skipped The certificate based authentication is examined more in detail in Section 1 2 Figure 2 SSL TLS full handshake procedure SSL Client SSL Server Client Hollo want to establish secure connection support this version of SSL and these ciphers Server Hello 4 1 initially accept request have chosen lt this gt version of SSL and this cipher suite Server Key Exchange optional Here is my public key if don t have certificate Client Certificate Request optional 1 want to authenticate you Send me your certificate signed by this CA Server Hello Done EOD Client Key Exchange sending you more parameters 1 will encrypt them by your public key Certificate Verify optional will sign some information by using private key y that corresponds to my certificate Thus you can sure that am the owner of the certificate Change Cipher Spec The ne
35. t batch Ly DoclD027745 Rev 1 29 31 Revision history AN4683 7 30 31 Revision history Table 4 Document revision history Date 07 May 2015 Revision 1 Initial release Changes DoclD027745 Rev 1 AN4683 IMPORTANT NOTICE PLEASE READ CAREFULLY STMicroelectronics NV and its subsidiaries ST reserve the right to make changes corrections enhancements modifications and improvements to ST products and or to this document at any time without notice Purchasers should obtain the latest relevant information on ST products before placing orders ST products are sold pursuant to ST s terms and conditions of sale in place at the time of order acknowledgement Purchasers are solely responsible for the choice selection and use of ST products and ST assumes no liability for application assistance or the design of Purchasers products No license express or implied to any intellectual property right is granted by ST herein Resale of ST products with provisions different from the information set forth herein shall void any warranty granted by ST for such product ST and the ST logo are trademarks of ST All other product or service names are the property of their respective owners Information in this document supersedes and replaces information previously supplied in any prior versions of this document 2015 STMicroelectronics All rights reserved 4 DoclD027745 Re
36. the TLS handshake layer At the lowest level layered on top of a reliable transport protocol is the TLS record protocol The record protocol is used for encapsulation of various higher level protocols and provides two basic properties e Confidentiality e Integrity Figure 1 SSL TLS protocol architecture TCP The TLS Handshake layer consists of three sub protocols Handshake Change cipher spec and Alert The Handshake protocol is the most complex part of TLS and provides a number of very important security functions It allows the server and client to authenticate each other and to negotiate an encryption algorithm and cryptographic keys before the application protocol transmits or receives its first byte of data The TLS handshake protocol provides connection security that has three basic properties e Cipher suite negotiation e Authentication of the server and optionally of the client e Session key information exchange An outline of the sub protocols is provided in the next section DoclD027745 Rev 1 Ly AN4683 SSL TLS protocol overview 1 1 Note SSL TLS sub protocols The TLS record layer and TLS handshake layer consists of four sub protocols overall handshake protocol change cipher spec protocol alert protocol and record protocol Handshake protocol This sub protocol is used to negotiate session information between the client and the server The session information consists of a
37. this last line When you receive the certificate from another entity you may need to use a certificate chain also known as the certification path which is a list of certificates used to authenticate an entity The chain or path begins with the certificate of that entity and each certificate in the chain is signed by the entity identified by the next certificate in the chain The chain terminates with a root CA certificate The root CA certificate is always signed by the CA itself it must be considered as a trusted CA and must be available in the application e g SSL TLS client web browser The signatures of all certificates in the chain must be verified until the root CA certificate is reached Figure 4 illustrates a certification path from the certificate owner to the root CA where the chain of trust begins Notice that different chains can have multiple or even none intermediate CAs Ly DoclD027745 Rev 1 9 31 SSL TLS protocol overview AN4683 10 31 Figure 4 Certificate chain or chain of trust Owner s public key Get certificate Issuer s CA DN Issuer s CA signature Owner s CA DN Owner s CA public key Issuer s Root CA DN Issuer s Root CA signature Root CA s DN Root CA s public key Root CA s signature Verify signature Get certificate Verify signature In some cases it would be easier and less expensive to use self signed certificates for example for testing pu
38. v 1 31 31
39. xt message from me will be encrypted Client Finished encrypted gt Change Cipher Spec The next message from me will be encrypted Application s data encrypted Application s data encrypted 1 Theclient sends a ClientHello message specifying the highest SSL TLS protocol version SSLv3 0 TLSv1 0 1 1 or 1 2 it supports a random number a list of suggested cipher suites and compression methods 2 The server responds with a ServerHello message containing the chosen protocol version another random number cipher suite and compression method from the choices offered by the client and the session ID The chosen protocol version should be the highest that both client and server support DoclD027745 Rev 1 5 31 SSL TLS protocol overview AN4683 Note The client and the server must support at least one common cipher suite otherwise the handshake protocol fails The server generally chooses the strongest common cipher suite they both support 3 The server sends its digital certificate in an optional certificate message For example the server uses X 509 digital certificates 4 Additionally a ServerKeyExchange message may be sent if it is required e g if the server has no certificate or if its certificate is for signing only 5 Ifthe server requires a digital certificate for client authentication an optional CertificateRequest message is appended 6 Theserver sends a S
40. y pem days 6500 set_serial 3333 subj IC IT ST Lombardia L Milan O STM OU R amp D CN client domain out client cert req pem 8 openssl ca in client cert req pem out client days 6500 keyfile ca key pem cert ca cert pem notext batch Example for generating ECC signed certificates Generate key pair and a self signed certificate for the CA trusted certificate 1 openssl ecparam out ca key pem name prime192v1 genkey 2 openssl req new key ca key pem days 6500 set serial 1111 subj C IT ST Lombardia L Milan O STM OU R amp D CN CA domain out ca cert pem x509 DoclD027745 Rev 1 Ly AN4683 Certificate generation with OpenSSL Generate server certificate key pair 3 openssl ecparam out server_key pem name prime192v1 genkey 4 openssl req new key server_key pem days 6500 set_serial 2222 subj C IT ST Lombardia L Milan O STM OU R amp D CN server domain out server cert 5 openssl in server cert req pem out server cert pem days 6500 keyfile ca key pem cert ca cert pem notext batch Generate client certificate key pair 6 openssl ecparam out client key pem name prime192v1 genkey 7 openssl req new key client key pem days 6500 set serial 3333 subj IC IT ST2 Lombardia L Milan O STM OU R amp D CN client domain out client cert req pem 8 openssl ca in client cert req pem out client cert pem days 6500 keyfile ca key pem cert ca cert pem notex
Download Pdf Manuals
Related Search