Document tls.cert.auth (#3010)

Author: HHHartmann

app/modules/tls.c

@@ -525,7 +525,8 @@ static const char *fill_page_with_pem(lua_State *L, const unsigned char *flash_m
   return NULL;
 }
 
-// Lua: tls.cert.auth(true / false | PEM data [, PEM data] )
+// Lua: tls.cert.auth(PEM data [, PEM data] )
+// Lua: tls.cert.auth(true / false)
 static int tls_cert_auth(lua_State *L)
 {
   int enable;
@@ -565,7 +566,8 @@ static int tls_cert_auth(lua_State *L)
   return 1;
 }
 
-// Lua: tls.cert.verify(true / false | PEM data [, PEM data] )
+// Lua: tls.cert.verify(PEM data [, PEM data] )
+// Lua: tls.cert.verify(true / false)
 static int tls_cert_verify(lua_State *L)
 {
   int enable;
@@ -579,7 +581,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

@@ -33,7 +33,7 @@ most common features supported.  Specifically, it provides:
 	the TLS specification, which requires a 16KiB recieve buffer and,
 	therefore, 32KiB of heap within mbedTLS, even in the steady-state.
 	While it is possible to slightly raise the buffer sizes with custom
-	nodeMCU builds, connecting to endpoints out of your control will remain
+	NodeMCU builds, connecting to endpoints out of your control will remain
 	a precarious position, and so we strongly suggest that TLS connections
 	be made only to endpoints under your control, whose TLS configurations
 	can ensure that their ServerHello messages are small.  A reasonable
@@ -157,7 +157,8 @@ none
 
 ## tls.socket:hold()
 
-Throttle data reception by placing a request to block the TCP receive function. This request is not effective immediately, Espressif recommends to call it while reserving 5*1460 bytes of memory.
+Throttle data reception by placing a request to block the TCP receive function.
+This request is not effective immediately, Espressif recommends to call it while reserving 5*1460 bytes of memory.
 
 #### Syntax
 `hold()`
@@ -220,7 +221,10 @@ Sends data to remote peer.
 
 #### Note
 
-Multiple consecutive `send()` calls aren't guaranteed to work (and often don't) as network requests are treated as separate tasks by the SDK. Instead, subscribe to the "sent" event on the socket and send additional data (or close) in that callback. See [#730](https://github.com/nodemcu/nodemcu-firmware/issues/730#issuecomment-154241161) for details.
+Multiple consecutive `send()` calls aren't guaranteed to work (and often don't) as
+network requests are treated as separate tasks by the SDK.
+Instead, subscribe to the "sent" event on the socket and send additional data (or close) in that callback.
+See [#730](https://github.com/nodemcu/nodemcu-firmware/issues/730#issuecomment-154241161) for details.
 
 #### See also
 [`tls.socket:on()`](#tlssocketon)
@@ -252,16 +256,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.
@@ -318,9 +322,65 @@ at `server-ca.crt` in the root of the nodemcu-firmware build tree. The build scr
 firmware image.
 
 The alternative approach is easier for development, and that is to supply the PEM data as a string value to `tls.cert.verify`. This
-will store the certificate into the flash chip and turn on verification for that certificate. Subsequent boots of the nodemcu can then
+will store the certificate into the flash chip and turn on verification for that certificate. Subsequent boots of the ESP can then
 use `tls.cert.verify(true)` and use the stored certificate.
 
+## tls.cert.auth()
+
+Controls the client key and certificate used when the ESP creates a TLS connection (for example,
+through `tls.createConnection` or `https` or `MQTT` connections with `secure = true`).
+
+#### Syntax
+`tls.cert.auth(enable)`
+
+`tls.cert.auth(pemdata[, pemdata])`
+
+#### Parameters
+- `enable` A boolean, specifying whether subsequent TLS connections will present a client certificate. The default at boot is `false`.
+- `pemdata` Two strings, the first containing the PEM-encoded client's certificate and the second containing the PEM-encoded client's private key.
+
+#### 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.
+
+```
+tls.cert.auth([[
+-----BEGIN CERTIFICATE-----
+CLIENT CERTIFICATE String (PEM file)
+-----END CERTIFICATE-----
+]]
+,
+[[
+-----BEGIN RSA PRIVATE KEY-----
+CLIENT PRIVATE KEY String (PEM file)
+-----END RSA PRIVATE KEY-----
+]])
+```
+
+#### Notes
+The certificate needed for proofing is stored in the flash chip. The `tls.cert.auth` call with `true`
+enables proofing against the value stored in the flash.
+
+The certificate can not be defined at firmware build time but it can be loaded into the flash chip at initial boot of the firmware.
+It 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 proofing with that certificate. 
+Subsequent boots of the ESP 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