From 282ebd100db55600a594c28c674a0a115c0de9aa Mon Sep 17 00:00:00 2001 From: Nathaniel Wesley Filardo Date: Mon, 30 Sep 2019 13:41:51 +0100 Subject: [PATCH] Deprecate crypto.to{Hex,Base64} (#2929) The internal implementation already preferentially forwards to the encoder module, so we should just remove these functions as they confuse people into thinking that we don't have their inverses (see the feature request https://github.com/nodemcu/nodemcu-firmware/issues/2907). Update the docs to refer to the encoder version and add deprecation warnings to the runtime implementations. --- app/modules/crypto.c | 6 ++++++ docs/modules/crypto.md | 32 ++++++++++++++++++++------------ 2 files changed, 26 insertions(+), 12 deletions(-) diff --git a/app/modules/crypto.c b/app/modules/crypto.c index 3deabdaa..81443181 100644 --- a/app/modules/crypto.c +++ b/app/modules/crypto.c @@ -61,9 +61,11 @@ static int call_encoder( lua_State* L, const char *function ) { } static int crypto_base64_encode (lua_State* L) { + platform_print_deprecation_note("crypto.toBase64", "in the next version"); return call_encoder(L, "toBase64"); } static int crypto_hex_encode (lua_State* L) { + platform_print_deprecation_note("crypto.toHex", "in the next version"); return call_encoder(L, "toHex"); } #else @@ -79,6 +81,8 @@ static int crypto_base64_encode( lua_State* L ) const char* msg = luaL_checklstring(L, 1, &len); luaL_Buffer out; + platform_print_deprecation_note("crypto.toBase64", "in the next version"); + luaL_buffinit(L, &out); for (i = 0; i < len; i += 3) { int a = msg[i]; @@ -104,6 +108,8 @@ static int crypto_hex_encode( lua_State* L) const char* msg = luaL_checklstring(L, 1, &len); luaL_Buffer out; + platform_print_deprecation_note("crypto.toHex", "in the next version"); + luaL_buffinit(L, &out); for (i = 0; i < len; i++) { luaL_addchar(&out, crypto_hexbytes[msg[i] >> 4]); diff --git a/docs/modules/crypto.md b/docs/modules/crypto.md index 97f9dec2..75bec7e3 100644 --- a/docs/modules/crypto.md +++ b/docs/modules/crypto.md @@ -33,7 +33,7 @@ The encrypted data as a binary string. For AES this is always a multiple of 16 b #### Example ```lua -print(crypto.toHex(crypto.encrypt("AES-ECB", "1234567890abcdef", "Hi, I'm secret!"))) +print(encoder.toHex(crypto.encrypt("AES-ECB", "1234567890abcdef", "Hi, I'm secret!"))) ``` #### See also @@ -62,7 +62,7 @@ Note that the decrypted string may contain extra zero-bytes of padding at the en ```lua key = "1234567890abcdef" cipher = crypto.encrypt("AES-ECB", key, "Hi, I'm secret!") -print(crypto.toHex(cipher)) +print(encoder.toHex(cipher)) print(crypto.decrypt("AES-ECB", key, cipher)) ``` @@ -82,11 +82,11 @@ Compute a cryptographic hash of a a file. - `filename` the path to the file to hash #### Returns -A binary string containing the message digest. To obtain the textual version (ASCII hex characters), please use [`crypto.toHex()`](#cryptotohex ). +A binary string containing the message digest. To obtain the textual version (ASCII hex characters), please use [`encoder.toHex()`](encoder.md#encodertohex ). #### Example ```lua -print(crypto.toHex(crypto.fhash("sha1","myfile.lua"))) +print(encoder.toHex(crypto.fhash("sha1","myfile.lua"))) ``` ## crypto.hash() @@ -101,11 +101,11 @@ Compute a cryptographic hash of a Lua string. `str` string to hash contents of #### Returns -A binary string containing the message digest. To obtain the textual version (ASCII hex characters), please use [`crypto.toHex()`](#cryptotohex ). +A binary string containing the message digest. To obtain the textual version (ASCII hex characters), please use [`encoder.toHex()`](encoder.md#encodertohex). #### Example ```lua -print(crypto.toHex(crypto.hash("sha1","abc"))) +print(encoder.toHex(crypto.hash("sha1","abc"))) ``` ## crypto.new_hash() @@ -127,7 +127,7 @@ hashobj = crypto.new_hash("SHA1") hashobj:update("FirstString") hashobj:update("SecondString") digest = hashobj:finalize() -print(crypto.toHex(digest)) +print(encoder.toHex(digest)) ``` ## crypto.hmac() @@ -143,11 +143,11 @@ Compute a [HMAC](https://en.wikipedia.org/wiki/Hash-based_message_authentication - `key` key to use for signing, may be a binary string #### Returns -A binary string containing the HMAC signature. Use [`crypto.toHex()`](#cryptotohex) to obtain the textual version. +A binary string containing the HMAC signature. Use [`encoder.toHex()`](encoder.md#encodertohex) to obtain the textual version. #### Example ```lua -print(crypto.toHex(crypto.hmac("sha1","abc","mysecret"))) +print(encoder.toHex(crypto.hmac("sha1","abc","mysecret"))) ``` ## crypto.new_hmac() @@ -170,7 +170,7 @@ hmacobj = crypto.new_hmac("SHA1", "s3kr3t") hmacobj:update("FirstString") hmacobj:update("SecondString") digest = hmacobj:finalize() -print(crypto.toHex(digest)) +print(encoder.toHex(digest)) ``` @@ -186,17 +186,21 @@ Applies an XOR mask to a Lua string. Note that this is not a proper cryptographi - `mask` the mask to apply, repeated if shorter than the message #### Returns -The masked message, as a binary string. Use [`crypto.toHex()`](#cryptotohex) to get a textual representation of it. +The masked message, as a binary string. Use [`encoder.toHex()`](encoder.md#encodertohex) to get a textual representation of it. #### Example ```lua -print(crypto.toHex(crypto.mask("some message to obscure","X0Y7"))) +print(encoder.toHex(crypto.mask("some message to obscure","X0Y7"))) ``` ## crypto.toBase64() Provides a Base64 representation of a (binary) Lua string. +!!! warning + + This function is deprecated; please use instead [`encoder.toBase64()`](encoder.md#encodertobase64) + #### Syntax `b64 = crypto.toBase64(binary)` @@ -215,6 +219,10 @@ print(crypto.toBase64(crypto.hash("sha1","abc"))) Provides an ASCII hex representation of a (binary) Lua string. Each byte in the input string is represented as two hex characters in the output. +!!! warning + + This function is deprecated; please use instead [`encoder.toHex()`](encoder.md#encodertohex) + #### Syntax `hexstr = crypto.toHex(binary)`