Repository files navigation

This firmware comes as anArduino esp8266 sketch.

This file refers to version 0.5.0 of the firmware.

The AT firmware provided by Espressif comes with basic TLS ciphersuites only. Especially, the lack of GCM-based ciphersuites makes the SSL part of the Espressif's firmware unusable on more and more web sites. This firmware addresses this issue.

The goal was to enable all modern ciphersuites implemented in BearSSL library included in esp8266/Arduino project including with some server authentication (server certificate checking).

The firmware fits into 1024 KB flash and can be run even on ESP-01 module with 8 Mbit flash.

The firmware does not (and likely will not) implement the whole set of AT commands defined in Espressif's documentation.

The major differences are:

1. Only TCP mode (with or without TLS) is supported, no UDP.

2. In multiplex mode (AT+CIPMUX=1), 5 simultaneous connections are available. Due to memory constraints, there can be only one TLS (SSL) connection at a time with standard buffer size, more concurrent TLS connections can be made with a reduced buffer size (AT+CIPSSLSIZE). When the buffer size is 512 bytes, all 5 concurrent connections can be TLS.

New features:

1. Implemented TLS security with state-of-the-art ciphersuites: certificate fingerprint checking or certificate chain verification.

2. Implemented TLS MFLN check (RFC 3546), setting TLS receive buffer size, checking MFLN status of a connection.

The firmware is still in work-in-progress state. It has been tested and is running on my devices but there might be deviations from the expected behaviour.

My testing environment uses theWifiEsp library and also the newerWiFiEspAT library.

Next development will be focused on

1. More complete AT command implementation.

There are two options for compiling and flashing this library.

First you have to installArduino IDE and thecore for the ESP8266 chip. Next get all source files from this repository, place them in a folder namedESP_ATMod and compile and upload to your ESP module.

After flashing, the module will open serial connection on RX and TX pins with 115200 Bd, 8 bits, no parity. You can talk with the module using a serial terminal of your choice.

IMPORTANT NOTE: From the firmware version 0.4.0 on, you need to use the Arduino Core for 8266 version 3.0+.

An alternative to using the Arduino IDE is to use PlatformIO.

1. InstallPlatformIO
2. Make sure that your device is in flashing mode
3. In your favourite terminal and from the root of this repository, runthe following command to build and upload the sketch to the device:

   platformio run --target upload

This has been configured and tested for the ESP-01 Black.

Certificates are stored in the ESP's filesystem with LittleFS. To add a certificate follow the following steps.

IMPORTANT: the certifcate must be in .pem format.

1. Copy the certificate you want to the data directory in ESP_ATMod
2. Install theLittleFS Filesystem Uploader
3. Select Tools > ESP8266 LittleFS Data Upload menu item. This should start uploading the files into ESP8266 flash file system. When done, IDE status bar will display LittleFS Image Uploaded message. Might take a few minutes for large file system sizes.
4. Now upload the ESP_ATMod sketch to the ESP.
5. The certificate(s) you uploaded are now loaded and ready to use (you can check them withAT+CIPSSLCERT).
6. (Optional) You may delete the .gitkeep file in the data directory. It is only there to push and pull the data directory in git. Not deleting the .gitkeep file won't do any harm.

In the following table, the list of supported AT commands is given. In the comment, only a difference between this implementation and the original Espressif's AT command firmware is given. The commands are implemented according to the Espressif's documentation, including the command order. Please refer to theEspressif's documentation for further information.

AT commands with _DEF and _CUR have (as in the standard AT firmware) an undocumented version without _DEF/CUR for backward compatibility (and forward too since AT 2 doesn't use _DEF/CUR). The command without _DEF/CUR behaves as _CUR for query and as _DEF for set (stores the parameters to the flash).

Sets the TLS receiver buffer size. The size can be 512, 1024, 2048, 4096 or 16384 (default) bytes according toRFC3546. The value is used for all subsequent TLS connections, the opened connections are not affected.

Command:

AT+CIPSSLSIZE=512

Answer:

OK

Commands

• AT+CIPRECVMODE (Set TCP or SSL Receive Mode)
• AT+CIPRECVDATA (Get TCP or SSL Data in Passive Receive Mode)
• AT+CIPRECVLEN (Get TCP or SSL Data Length in Passive Receive Mode)

Works in SSL mode in the same way as in TCP mode.

The standard AT firmware supports only one server. This firmware support up to 5 server with same AT+CIPCIPSERVER command.

In standard AT firmware 1.7 executingAT+CIPSERVER=1,<port> again even if the port is different prints no change and OK. Here it starts a new server. "no change" is returned only if maximum count of servers is reached.

In standard AT firmware 1.7 executing AT+CIPSERVER=0 stops the one server. Here it stops the first one. ExecutingAT+CIPSERVER=0,<port> stops the server listening on<port>.

CIPSERVERMAXCONN and CIPSTO are global settings, They apply to all servers.

In standard AT firmware AT_CWDHCP enables/disables the DHCP client for STA (mode 0) and starts or stops the DHCP server for SoftAP (mode 1). In ESP_ATMod the SoftAP DHCP server is always enabled. The AT+CWDHCP command is not implemented for SoftAP.

For Ethernet support, the AT+CWDHCP command is enhanced. The Ethernet DHCP client is enabled/disabled with mode 3. For AT+CWDHCP?, state of the Ethernet DHCP client is returned in third bit.

Sets and queries the CPU freqency. The only valid values are 80 and 160 Mhz.

Query:

Command:

AT+SYSCPUFREQ?

Answer:

+SYSCPUFREQ=80OK

Set:

Command:

AT+SYSCPUFREQ=<freq>

Answer:

OK

The value freq may be 80 or 160.

Sets and queries the physical wifi mode.

Query:

Command:

AT+RFMODE?

Answer:

+RFMODE=1OK

Set:

Command:

AT+RFMODE=<mode>

Answer:

OK

The allowed values of <mode> are:

Set or queries the selected TLS authentication mode. The default is no authentication. Try to avoid this because it is insecure and prone to MITM attack.

Query:

Command:

AT+CIPSSLAUTH?

Answer:

+CIPSSLAUTH=0OK

Set:

Command:

AT+CIPSSLAUTH=<mode>

Answer:

OK

The allowed values of <mode> are:

Switching to mode 1 succeeds only when the certificate SHA-1 fingerprint is preloaded (see AT+CIPSSLFP).

Switching to mode 2 succeeds only when the CA certificate preloaded (see AT+CIPSSLCERT).

Load or print the saved server certificate fingerprint. The fingerprint is based on SHA-1 hash and is exactly 20 bytes long. When connecting, the TLS engine checks the fingerprint of the received certificate against the saved value. It ensures the device is connecting to the expected server. After a successful connection, the fingerprint is checked and is no longer needed for this connection.

The SHA-1 certificate fingerprint for a site can be obtained e.g. in browser while examining the server certificate.

Query:

Command:

AT+CIPSSLFP?

Answer:

+CIPSSLFP:"4F:D5:B1:C9:B2:8C:CF:D2:D5:9C:84:5D:76:F6:F7:A1:D0:A2:FA:3D"OK

Set:

Command:

AT+CIPSSLFP="4F:D5:B1:C9:B2:8C:CF:D2:D5:9C:84:5D:76:F6:F7:A1:D0:A2:FA:3D"

or

AT+CIPSSLFP="4FD5B1C9B28CCFD2D59C845D76F6F7A1D0A2FA3D"

Answer:

OK

The fingerprint consists of exactly 20 bytes. They are set as hex values and may be divided with ':'.

Currently maximum 5 certificates at a time can be loaded. With this command the amount of certificates to load with LittleFS can be adjusted.

Query amount to load:

Command:

AT+CIPSSLCERTMAX?

Answer:

+CIPSSLCERTMAX:5OK

Set amount to load:

Command:

AT+CIPSSLCERTMAX=6

Answer:

+CIPSSLCERTMAX:6OK

Load, query or delete CA certificate for TLS certificate chain verification. Currently maximum 5 certificates at a time can be loaded. The certificates must be in PEM structure. After a successful connection, the certificate is checked and is no longer needed for this connection.

Query the first certificate:

Command:

AT+CIPSSLCERT?

Answer:

+CIPSSLCERT:no certERROR

or

+CIPSSLCERT,1:DST Root CA X3+CIPSSLCERT,2:DST Root CA X3OK

Query specific certificate:

Command:

AT+CIPSSLCERT?2

Answer:

+CIPSSLCERT,2:DST Root CA X3OK

Set:

Command:

AT+CIPSSLCERT

Answer:

OK>

You can now send the certificate (PEM encoding), no echo is given. After the last line (-----END CERTIFICATE-----), the certificate is parsed and loaded. The certificate should be sent with \n notation. For exampleisrg-root-x1-cross-signed.pem:

-----BEGIN CERTIFICATE-----MIIFYDCCBEigAwIBAgIQQAF3ITfU6UK47naqPGQKtzANBgkqhkiG9w0BAQsFADA/MSQwIgYDVQQKExtEaWdpdGFsIFNpZ25hdHVyZSBUcnVzdCBDby4xFzAVBgNVBAMTDkRTVCBSb290IENBIFgzMB4XDTIxMDEyMDE5MTQwM1oXDTI0MDkzMDE4MTQwM1owTzELMAkGA1UEBhMCVVMxKTAnBgNVBAoTIEludGVybmV0IFNlY3VyaXR5IFJlc2VhcmNoIEdyb3VwMRUwEwYDVQQDEwxJU1JHIFJvb3QgWDEwggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIKAoICAQCt6CRz9BQ385ueK1coHIe+3LffOJCMbjzmV6B493XCov71am72AE8o295ohmxEk7axY/0UEmu/H9LqMZshftEzPLpI9d1537O4/xLxIZpLwYqGcWlKZmZsj348cL+tKSIG8+TA5oCu4kuPt5l+lAOf00eXfJlII1PoOK5PCm+DLtFJV4yAdLbaL9A4jXsDcCEbdfIwPPqPrt3aY6vrFk/CjhFLfs8L6P+1dy70sntK4EwSJQxwjQMpoOFTJOwT2e4ZvxCzSow/iaNhUd6shweU9GNx7C7ib1uYgeGJXDR5bHbvO5BieebbpJovJsXQEOEO3tkQjhb7t/eo98flAgeYjzYIlefiN5YNNnWe+w5ysR2bvAP5SQXYgd0FtCrWQemsAXaVCg/Y39W9Eh81LygXbNKYwagJZHduRze6zqxZXmidf3LWicUGQSk+WT7dJvUkyRGnWqNMQB9GoZm1pzpRboY7nn1ypxIFeFntPlF4FQsDj43QLwWyPntKHEtzBRL8xurgUBN8Q5N0s8p0544fAQjQMNRbcTa0B7rBMDBcSLeCO5imfWCKoqMpgsy6vYMEG6KDA0Gh1gXxG8K28Kh8hjtGqEgqiNx2mna/H2qlPRmP6zjzZN7IKw0KKP/32+IVQtQi0Cdd4Xn+GOdwiK1O5tmLOsbdJ1Fu/7xk9TNDTwIDAQABo4IBRjCCAUIwDwYDVR0TAQH/BAUwAwEB/zAOBgNVHQ8BAf8EBAMCAQYwSwYIKwYBBQUHAQEEPzA9MDsGCCsGAQUFBzAChi9odHRwOi8vYXBwcy5pZGVudHJ1c3QuY29tL3Jvb3RzL2RzdHJvb3RjYXgzLnA3YzAfBgNVHSMEGDAWgBTEp7Gkeyxx+tvhS5B1/8QVYIWJEDBUBgNVHSAETTBLMAgGBmeBDAECATA/BgsrBgEEAYLfEwEBATAwMC4GCCsGAQUFBwIBFiJodHRwOi8vY3BzLnJvb3QteDEubGV0c2VuY3J5cHQub3JnMDwGA1UdHwQ1MDMwMaAvoC2GK2h0dHA6Ly9jcmwuaWRlbnRydXN0LmNvbS9EU1RST09UQ0FYM0NSTC5jcmwwHQYDVR0OBBYEFHm0WeZ7tuXkAXOACIjIGlj26ZtuMA0GCSqGSIb3DQEBCwUAA4IBAQAKcwBslm7/DlLQrt2M51oGrS+o44+/yQoDFVDC5WxCu2+b9LRPwkSICHXM6webFGJueN7sJ7o5XPWioW5WlHAQU7G75K/QosMrAdSW9MUgNTP52GE24HGNtLi1qoJFlcDyqSMo59ahy2cI2qBDLKobkx/J3vWraV0T9VuGWCLKTVXkcGdtwlfFRjlBz4pYg1htmf5X6DYO8A4jqv2Il9DjXA6USbW1FzXSLr9Ohe8Y4IWS6wY7bCkjCWDcRQJMEhg76fsO3txE+FiYruq9RUWhiF1myv4Q6W+CyBFCDfvp7OOGAN6dEOM4+qR9sdjoSYKEBpsr6GtPAQw4dy753ec5-----END CERTIFICATE-----

Should be:

-----BEGIN CERTIFICATE-----\nMIIFYDCCBEigAwIBAgIQQAF3ITfU6UK47naqPGQKtzANBgkqhkiG9w0BAQsFADA/\nMSQwIgYDVQQKExtEaWdpdGFsIFNpZ25hdHVyZSBUcnVzdCBDby4xFzAVBgNVBAMT\nDkRTVCBSb290IENBIFgzMB4XDTIxMDEyMDE5MTQwM1oXDTI0MDkzMDE4MTQwM1ow\nTzELMAkGA1UEBhMCVVMxKTAnBgNVBAoTIEludGVybmV0IFNlY3VyaXR5IFJlc2Vh\ncmNoIEdyb3VwMRUwEwYDVQQDEwxJU1JHIFJvb3QgWDEwggIiMA0GCSqGSIb3DQEB\nAQUAA4ICDwAwggIKAoICAQCt6CRz9BQ385ueK1coHIe+3LffOJCMbjzmV6B493XC\nov71am72AE8o295ohmxEk7axY/0UEmu/H9LqMZshftEzPLpI9d1537O4/xLxIZpL\nwYqGcWlKZmZsj348cL+tKSIG8+TA5oCu4kuPt5l+lAOf00eXfJlII1PoOK5PCm+D\nLtFJV4yAdLbaL9A4jXsDcCEbdfIwPPqPrt3aY6vrFk/CjhFLfs8L6P+1dy70sntK\n4EwSJQxwjQMpoOFTJOwT2e4ZvxCzSow/iaNhUd6shweU9GNx7C7ib1uYgeGJXDR5\nbHbvO5BieebbpJovJsXQEOEO3tkQjhb7t/eo98flAgeYjzYIlefiN5YNNnWe+w5y\nsR2bvAP5SQXYgd0FtCrWQemsAXaVCg/Y39W9Eh81LygXbNKYwagJZHduRze6zqxZ\nXmidf3LWicUGQSk+WT7dJvUkyRGnWqNMQB9GoZm1pzpRboY7nn1ypxIFeFntPlF4\nFQsDj43QLwWyPntKHEtzBRL8xurgUBN8Q5N0s8p0544fAQjQMNRbcTa0B7rBMDBc\nSLeCO5imfWCKoqMpgsy6vYMEG6KDA0Gh1gXxG8K28Kh8hjtGqEgqiNx2mna/H2ql\nPRmP6zjzZN7IKw0KKP/32+IVQtQi0Cdd4Xn+GOdwiK1O5tmLOsbdJ1Fu/7xk9TND\nTwIDAQABo4IBRjCCAUIwDwYDVR0TAQH/BAUwAwEB/zAOBgNVHQ8BAf8EBAMCAQYw\nSwYIKwYBBQUHAQEEPzA9MDsGCCsGAQUFBzAChi9odHRwOi8vYXBwcy5pZGVudHJ1\nc3QuY29tL3Jvb3RzL2RzdHJvb3RjYXgzLnA3YzAfBgNVHSMEGDAWgBTEp7Gkeyxx\n+tvhS5B1/8QVYIWJEDBUBgNVHSAETTBLMAgGBmeBDAECATA/BgsrBgEEAYLfEwEB\nATAwMC4GCCsGAQUFBwIBFiJodHRwOi8vY3BzLnJvb3QteDEubGV0c2VuY3J5cHQu\nb3JnMDwGA1UdHwQ1MDMwMaAvoC2GK2h0dHA6Ly9jcmwuaWRlbnRydXN0LmNvbS9E\nU1RST09UQ0FYM0NSTC5jcmwwHQYDVR0OBBYEFHm0WeZ7tuXkAXOACIjIGlj26Ztu\nMA0GCSqGSIb3DQEBCwUAA4IBAQAKcwBslm7/DlLQrt2M51oGrS+o44+/yQoDFVDC\n5WxCu2+b9LRPwkSICHXM6webFGJueN7sJ7o5XPWioW5WlHAQU7G75K/QosMrAdSW\n9MUgNTP52GE24HGNtLi1qoJFlcDyqSMo59ahy2cI2qBDLKobkx/J3vWraV0T9VuG\nWCLKTVXkcGdtwlfFRjlBz4pYg1htmf5X6DYO8A4jqv2Il9DjXA6USbW1FzXSLr9O\nhe8Y4IWS6wY7bCkjCWDcRQJMEhg76fsO3txE+FiYruq9RUWhiF1myv4Q6W+CyBFC\nDfvp7OOGAN6dEOM4+qR9sdjoSYKEBpsr6GtPAQw4dy753ec5\n-----END CERTIFICATE-----

The application responds with

Read 1952 bytesOK

or with an error message. In case of a successful loading, the certificate is ready to use and you can turn the certificate checking on (AT+CIPSSLAUTH=2).

The limit for the PEM certificate is 4096 characters total.

Delete a certificate:

Command:

AT+CIPSSLCERT=DELETE,1

Answer:

+CIPSSLCERT,1:deletedOK

The certificate is deleted from the memory.

The Maximum Fragment Length Negotiation extension is useful for lowering the RAM usage by reducing receiver buffer size on TLS connections. Newer TLS implementations support this extension but it would be wise to check the capability before changing a TLS buffer size and making a connection. As the server won't change this feature on the fly, you should test the MFLN capability only once.

Command:

AT+CIPSSLMFLN="site",port,size

The valid sizes are 512, 1024, 2048 and 4096.

AT+CIPSSLMFLN="www.github.com",443,512

Answer:

+CIPSSLMFLN:TRUEOK

This command checks the MFLN status on an opened TLS connection.

Command:

AT+CIPSSLSTA[=linkID]

ThelinkID value is mandatory when the multiplexing is on (AT+CIPMUX=1). It should be not entered when the multiplexing is turned off.

AT+CIPSSLSTA=0

Answer:

+CIPSSLSTA:1OK

The returned value of 1 means there was a MFLN negotiation. It holds even with the default receiver buffer size set.

This command returns the current time as unix time (number of seconds since January 1st, 1970). The time zone is fixed to GMT (UTC). The time is obtained by querying NTP servers automatically, after connecting to the internet. Before connecting to the internet or in case of an error in communication with NTP servers, the time is unknown. This situation should be temporary.

Command:

AT+SYSTIME?

Answer:

+SYSTIME:1607438042OK

If the current time is unknown, an error message is returned.

These commands support use of the Ethernet interface as in standard AT firmware version 2 and newer.

These commands for the Ethernet interface are analogous to AT+CIPSTA, AT+CIPSTAMAC and AT+CWHOSTNAME commands.