document tls.cert.auth

app/modules/tls.c

@@ -579,7 +579,6 @@ static int tls_cert_verify(lua_State *L)
   if (lua_type(L, 1) == LUA_TSTRING) {
     const char *types[2] = { "CERTIFICATE", NULL };
     const char *names[1] = { "certificate" };
-
     const char *error = fill_page_with_pem(L, &tls_server_cert_area[0], flash_offset, types, names);
     if (error) {
       return luaL_error(L, error);

docs/modules/tls.md

@@ -252,16 +252,16 @@ none
 
 ## tls.cert.verify()
 
-Controls the vertificate verification process when the Nodemcu makes a secure connection.
+Controls the certificate verification process when the Nodemcu makes a secure connection.
 
 #### Syntax
 `tls.cert.verify(enable)`
 
-`tls.cert.verify(pemdata)`
+`tls.cert.verify(pemdata[, pemdata])`
 
 #### Parameters
 - `enable` A boolean which indicates whether verification should be enabled or not. The default at boot is `false`.
-- `pemdata` A string containing the CA certificate to use for verification.
+- `pemdata` A string containing the CA certificate to use for verification. There can be several of these.
 
 #### Returns
 `true` if it worked.
@@ -321,6 +321,55 @@ The alternative approach is easier for development, and that is to supply the PE
 will store the certificate into the flash chip and turn on verification for that certificate. Subsequent boots of the nodemcu can then
 use `tls.cert.verify(true)` and use the stored certificate.
 
+## tls.cert.auth()
+
+Controls the certificate verification process when the Nodemcu authenticates against the client like when receiving a secure connection.
+
+#### Syntax
+`tls.cert.auth(enable)`
+
+`tls.cert.auth(pemdata[, pemdata])`
+
+#### Parameters
+- `enable` A boolean which indicates whether verification should be enabled or not. The default at boot is `false`.
+- `pemdata` A string containing the CA certificate to use for verification. There can be several of these.
+
+#### Returns
+`true` if it worked.
+
+Can throw a number of errors if invalid data is supplied.
+
+#### Example
+Open an mqtt client.
+```
+tls.cert.auth(true)
+tls.cert.verify(true)
+
+m = mqtt.Client('basicPubSub', 1500, "admin", "admin", 1)
+```
+For further discussion see https://github.com/nodemcu/nodemcu-firmware/issues/2576
+
+Load a certificate into the flash chip and make a request.
+
+```
+tls.cert.auth([[
+-----BEGIN CERTIFICATE-----
+CLIENT CERTIFICATE String (PEM file)
+-----END CERTIFICATE-----
+]])
+```
+
+#### Notes
+The certificate needed for verification is stored in the flash chip. The `tls.cert.auth` call with `true`
+enables verification against the value stored in the flash.
+
+The certificate can not be loaded into the flash chip at initial boot of the firmware.
+It only can be supplied by passing the PEM data as a string value to `tls.cert.auth`. This
+will store the certificate into the flash chip and turn on verification for that certificate. 
+Subsequent boots of the nodemcu can then use `tls.cert.auth(true)` and use the stored certificate.
+
+
+
 # tls.setDebug function
 
 mbedTLS can be compiled with debug support.  If so, the tls.setDebug