mirror of
https://github.com/nodemcu/nodemcu-firmware.git
synced 2025-01-30 21:12:55 +08:00
863dfb59ed
* Remove stale putative MD2 support This hasn't worked in a while, presumably since one of our upstream merges. Don't bother making it work, since MD2 is generally considered insecure. * Land mbedtls 2.16.3-77-gf02988e57 * TLS: remove some dead code from espconn_mbedtls There was some... frankly kind of scary buffer and data shuffling if ESP8266_PLATFORM was defined. Since we don't, in fact, define that preprocessor symbol, just drop the code lest anyone (possibly future-me) be scared. * TLS: espconn_mbedtls: run through astyle No functional changes * TLS: espconn_mbedtls: put the file_params on the stack There's no need to malloc a structure that's used only locally. * TLS: Further minor tidying of mbedtls glue What an absolute shitshow this is. mbedtls should absolutely not be mentioned inside sys/socket.h and app/mbedtls/app/lwIPSocket.c is not so much glue as it as a complete copy of a random subset of lwIP; it should go, but we aren't there yet. Get rid of the mysterious "mbedlts_record" struct, which housed merely a length of bytes sent solely for gating the "record sent" callback. Remove spurious __attribute__((weak)) from symbols not otherwise defined and rename them to emphasize that they are not actually part of mbedtls proper. * TLS: Rampage esp mbedtls glue and delete unused code This at least makes the shitshow smaller * TLS: lwip: fix some memp definitions I presume these also need the new arguments * TLS: Remove more non-NodeMCU code from our mbedtls * TLS: drop support for 1.1 Depending on who you ask it's either EOL already or EOL soon, so we may as well get rid of it now.
238 lines
6.5 KiB
Markdown
238 lines
6.5 KiB
Markdown
# crypto Module
|
|
| Since | Origin / Contributor | Maintainer | Source |
|
|
| :----- | :-------------------- | :---------- | :------ |
|
|
| 2015-06-02 | [DiUS](https://github.com/DiUS), [Johny Mattsson](https://github.com/jmattsson) | [Johny Mattsson](https://github.com/jmattsson) | [crypto.c](../../app/modules/crypto.c)|
|
|
|
|
The crypto modules provides various functions for working with cryptographic algorithms.
|
|
|
|
The following encryption/decryption algorithms/modes are supported:
|
|
- `"AES-ECB"` for 128-bit AES in ECB mode (NOT recommended)
|
|
- `"AES-CBC"` for 128-bit AES in CBC mode
|
|
|
|
The following hash algorithms are supported:
|
|
- MD5
|
|
- SHA1
|
|
- SHA256, SHA384, SHA512 (unless disabled in `app/include/user_config.h`)
|
|
|
|
## crypto.encrypt()
|
|
|
|
Encrypts Lua strings.
|
|
|
|
#### Syntax
|
|
`crypto.encrypt(algo, key, plain [, iv])`
|
|
|
|
#### Parameters
|
|
- `algo` the name of a supported encryption algorithm to use
|
|
- `key` the encryption key as a string; for AES encryption this *MUST* be 16 bytes long
|
|
- `plain` the string to encrypt; it will be automatically zero-padded to a 16-byte boundary if necessary
|
|
- `iv` the initilization vector, if using AES-CBC; defaults to all-zero if not given
|
|
|
|
#### Returns
|
|
The encrypted data as a binary string. For AES this is always a multiple of 16 bytes in length.
|
|
|
|
#### Example
|
|
```lua
|
|
print(encoder.toHex(crypto.encrypt("AES-ECB", "1234567890abcdef", "Hi, I'm secret!")))
|
|
```
|
|
|
|
#### See also
|
|
- [`crypto.decrypt()`](#cryptodecrypt)
|
|
|
|
|
|
## crypto.decrypt()
|
|
|
|
Decrypts previously encrypted data.
|
|
|
|
#### Syntax
|
|
`crypto.decrypt(algo, key, cipher [, iv])`
|
|
|
|
#### Parameters
|
|
- `algo` the name of a supported encryption algorithm to use
|
|
- `key` the encryption key as a string; for AES encryption this *MUST* be 16 bytes long
|
|
- `cipher` the cipher text to decrypt (as obtained from `crypto.encrypt()`)
|
|
- `iv` the initialization vector, if using AES-CBC; defaults to all-zero if not given
|
|
|
|
#### Returns
|
|
The decrypted string.
|
|
|
|
Note that the decrypted string may contain extra zero-bytes of padding at the end. One way of stripping such padding is to use `:match("(.-)%z*$")` on the decrypted string. Additional care needs to be taken if working on binary data, in which case the real length likely needs to be encoded with the data, and at which point `:sub(1, n)` can be used to strip the padding.
|
|
|
|
#### Example
|
|
```lua
|
|
key = "1234567890abcdef"
|
|
cipher = crypto.encrypt("AES-ECB", key, "Hi, I'm secret!")
|
|
print(encoder.toHex(cipher))
|
|
print(crypto.decrypt("AES-ECB", key, cipher))
|
|
```
|
|
|
|
#### See also
|
|
- [`crypto.encrypt()`](#cryptoencrypt)
|
|
|
|
|
|
## crypto.fhash()
|
|
|
|
Compute a cryptographic hash of a a file.
|
|
|
|
#### Syntax
|
|
`hash = crypto.fhash(algo, filename)`
|
|
|
|
#### Parameters
|
|
- `algo` the hash algorithm to use, case insensitive string
|
|
- `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 [`encoder.toHex()`](encoder.md#encodertohex ).
|
|
|
|
#### Example
|
|
```lua
|
|
print(encoder.toHex(crypto.fhash("sha1","myfile.lua")))
|
|
```
|
|
|
|
## crypto.hash()
|
|
|
|
Compute a cryptographic hash of a Lua string.
|
|
|
|
#### Syntax
|
|
`hash = crypto.hash(algo, str)`
|
|
|
|
#### Parameters
|
|
`algo` the hash algorithm to use, case insensitive 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 [`encoder.toHex()`](encoder.md#encodertohex).
|
|
|
|
#### Example
|
|
```lua
|
|
print(encoder.toHex(crypto.hash("sha1","abc")))
|
|
```
|
|
|
|
## crypto.new_hash()
|
|
|
|
Create a digest/hash object that can have any number of strings added to it. Object has `update` and `finalize` functions.
|
|
|
|
#### Syntax
|
|
`hashobj = crypto.new_hash(algo)`
|
|
|
|
#### Parameters
|
|
`algo` the hash algorithm to use, case insensitive string
|
|
|
|
#### Returns
|
|
Userdata object with `update` and `finalize` functions available.
|
|
|
|
#### Example
|
|
```lua
|
|
hashobj = crypto.new_hash("SHA1")
|
|
hashobj:update("FirstString")
|
|
hashobj:update("SecondString")
|
|
digest = hashobj:finalize()
|
|
print(encoder.toHex(digest))
|
|
```
|
|
|
|
## crypto.hmac()
|
|
|
|
Compute a [HMAC](https://en.wikipedia.org/wiki/Hash-based_message_authentication_code) (Hashed Message Authentication Code) signature for a Lua string.
|
|
|
|
#### Syntax
|
|
`signature = crypto.hmac(algo, str, key)`
|
|
|
|
#### Parameters
|
|
- `algo` hash algorithm to use, case insensitive string
|
|
- `str` data to calculate the hash for
|
|
- `key` key to use for signing, may be a binary string
|
|
|
|
#### Returns
|
|
A binary string containing the HMAC signature. Use [`encoder.toHex()`](encoder.md#encodertohex) to obtain the textual version.
|
|
|
|
#### Example
|
|
```lua
|
|
print(encoder.toHex(crypto.hmac("sha1","abc","mysecret")))
|
|
```
|
|
|
|
## crypto.new_hmac()
|
|
|
|
Create a hmac object that can have any number of strings added to it. Object has `update` and `finalize` functions.
|
|
|
|
#### Syntax
|
|
`hmacobj = crypto.new_hmac(algo, key)`
|
|
|
|
#### Parameters
|
|
- `algo` the hash algorithm to use, case insensitive string
|
|
- `key` the key to use (may be a binary string)
|
|
|
|
#### Returns
|
|
Userdata object with `update` and `finalize` functions available.
|
|
|
|
#### Example
|
|
```lua
|
|
hmacobj = crypto.new_hmac("SHA1", "s3kr3t")
|
|
hmacobj:update("FirstString")
|
|
hmacobj:update("SecondString")
|
|
digest = hmacobj:finalize()
|
|
print(encoder.toHex(digest))
|
|
```
|
|
|
|
|
|
## crypto.mask()
|
|
|
|
Applies an XOR mask to a Lua string. Note that this is not a proper cryptographic mechanism, but some protocols may use it nevertheless.
|
|
|
|
#### Syntax
|
|
`crypto.mask(message, mask)`
|
|
|
|
#### Parameters
|
|
- `message` message to mask
|
|
- `mask` the mask to apply, repeated if shorter than the message
|
|
|
|
#### Returns
|
|
The masked message, as a binary string. Use [`encoder.toHex()`](encoder.md#encodertohex) to get a textual representation of it.
|
|
|
|
#### Example
|
|
```lua
|
|
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)`
|
|
|
|
#### Parameters
|
|
`binary` input string to Base64 encode
|
|
|
|
#### Return
|
|
A Base64 encoded string.
|
|
|
|
#### Example
|
|
```lua
|
|
print(crypto.toBase64(crypto.hash("sha1","abc")))
|
|
```
|
|
|
|
## crypto.toHex()
|
|
|
|
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)`
|
|
|
|
#### Parameters
|
|
`binary` input string to get hex representation for
|
|
|
|
#### Returns
|
|
An ASCII hex string.
|
|
|
|
#### Example
|
|
```lua
|
|
print(crypto.toHex(crypto.hash("sha1","abc")))
|
|
```
|