-
Adrien van den Bossche authoredAdrien van den Bossche authored
RHEncryptedDriver.h 12.91 KiB
// RHEncryptedDriver.h
// Generic encryption layer that could use any driver
// But will encrypt all data.
// Requires the Arduinolibs/Crypto library:
// https://github.com/rweather/arduinolibs
//
// Author: Philippe.Rochat'at'gmail.com
// Contributed to the RadioHead project by the author
// $Id: RHEncryptedDriver.h,v 1.3 2018/09/23 23:54:01 mikem Exp $
#ifndef RHEncryptedDriver_h
#define RHEncryptedDriver_h
#include <RHGenericDriver.h>
#ifdef RH_ENABLE_ENCRYPTION_MODULE
#include <BlockCipher.h>
// Undef this if trailing 0 on each enrypted message is ok.
// This defined means a first byte of the payload is used to encode content length
// And the received message content is trimmed to this length
#define STRICT_CONTENT_LEN
// Define this to allow encrypted content to span over 2 messages
// STRICT_CONTENT_LEN and ALLOW_MULTIPLE_MSG aren't compatible !!!
// With STRICT_CONTENT_LEN, receiver will try to extract length from every message !!!!
//#define ALLOW_MULTIPLE_MSG
/////////////////////////////////////////////////////////////////////
/// \class RHEncryptedDriver RHEncryptedDriver <RHEncryptedDriver.h>
/// \brief Virtual Driver to encrypt/decrypt data. Can be used with any other RadioHead driver.
///
/// This driver acts as a wrapper for any other RadioHead driver, adding encryption and decryption of
/// messages that are passed to and from the actual radio driver. Only the message payload is encrypted,
/// and not the to/from address or flags. Any of the encryption ciphers supported by
/// ArduinoLibs Cryptographic Library http://rweather.github.io/arduinolibs/crypto.html may be used.
///
/// For successful communications, both sender and receiver must use the same cipher and the same key.
///
/// In order to enable this module you must uncomment #define RH_ENABLE_ENCRYPTION_MODULE at the bottom of RadioHead.h
/// But ensure you have installed the Crypto directory from arduinolibs first:
/// http://rweather.github.io/arduinolibs/index.html
class RHEncryptedDriver : public RHGenericDriver
{
public:
/// Constructor.
/// Adds a ciphering layer to messages sent and received by the actual transport driver.
/// \param[in] driver The RadioHead driver to use to transport messages.
/// \param[in] blockcipher The blockcipher (from arduinolibs) that crypt/decrypt data. Ensure that
/// the blockcipher has had its key set before sending or receiving messages.
RHEncryptedDriver(RHGenericDriver& driver, BlockCipher& blockcipher);
/// Calls the real driver's init()
/// \return The value returned from the driver init() method;
virtual bool init() { return _driver.init();};
/// Tests whether a new message is available
/// from the Driver.
/// On most drivers, this will also put the Driver into RHModeRx mode until
/// a message is actually received by the transport, when it wil be returned to RHModeIdle.
/// This can be called multiple times in a timeout loop
/// \return true if a new, complete, error-free uncollected message is available to be retreived by recv()
virtual bool available() { return _driver.available();};
/// Turns the receiver on if it not already on.
/// If there is a valid message available, copy it to buf and return true
/// else return false.
/// If a message is copied, *len is set to the length (Caution, 0 length messages are permitted).
/// You should be sure to call this function frequently enough to not miss any messages /// It is recommended that you call it in your main loop.
/// \param[in] buf Location to copy the received message
/// \param[in,out] len Pointer to available space in buf. Set to the actual number of octets copied.
/// \return true if a valid message was copied to buf
virtual bool recv(uint8_t* buf, uint8_t* len);
/// Waits until any previous transmit packet is finished being transmitted with waitPacketSent().
/// Then optionally waits for Channel Activity Detection (CAD)
/// to show the channnel is clear (if the radio supports CAD) by calling waitCAD().
/// Then loads a message into the transmitter and starts the transmitter. Note that a message length
/// of 0 is permitted.
/// \param[in] data Array of data to be sent
/// \param[in] len Number of bytes of data to send
/// specify the maximum time in ms to wait. If 0 (the default) do not wait for CAD before transmitting.
/// \return true if the message length was valid and it was correctly queued for transmit. Return false
/// if CAD was requested and the CAD timeout timed out before clear channel was detected.
virtual bool send(const uint8_t* data, uint8_t len);
/// Returns the maximum message length
/// available in this Driver, which depends on the maximum length supported by the underlying transport driver.
/// \return The maximum legal message length
virtual uint8_t maxMessageLength();
/// Blocks until the transmitter
/// is no longer transmitting.
virtual bool waitPacketSent() { return _driver.waitPacketSent();} ;
/// Blocks until the transmitter is no longer transmitting.
/// or until the timeout occuers, whichever happens first
/// \param[in] timeout Maximum time to wait in milliseconds.
/// \return true if the radio completed transmission within the timeout period. False if it timed out.
virtual bool waitPacketSent(uint16_t timeout) {return _driver.waitPacketSent(timeout);} ;
/// Starts the receiver and blocks until a received message is available or a timeout
/// \param[in] timeout Maximum time to wait in milliseconds.
/// \return true if a message is available
virtual bool waitAvailableTimeout(uint16_t timeout) {return _driver.waitAvailableTimeout(timeout);};
/// Calls the waitCAD method in the driver
/// \return The return value from teh drivers waitCAD() method
virtual bool waitCAD() { return _driver.waitCAD();};
/// Sets the Channel Activity Detection timeout in milliseconds to be used by waitCAD().
/// The default is 0, which means do not wait for CAD detection.
/// CAD detection depends on support for isChannelActive() by your particular radio.
void setCADTimeout(unsigned long cad_timeout) {_driver.setCADTimeout(cad_timeout);};
/// Determine if the currently selected radio channel is active.
/// This is expected to be subclassed by specific radios to implement their Channel Activity Detection
/// if supported. If the radio does not support CAD, returns true immediately. If a RadioHead radio
/// supports isChannelActive() it will be documented in the radio specific documentation.
/// This is called automatically by waitCAD().
/// \return true if the radio-specific CAD (as returned by override of isChannelActive()) shows the
/// current radio channel as active, else false. If there is no radio-specific CAD, returns false.
virtual bool isChannelActive() { return _driver.isChannelActive();};
/// Sets the address of this node. Defaults to 0xFF. Subclasses or the user may want to change this.
/// This will be used to test the adddress in incoming messages. In non-promiscuous mode,
/// only messages with a TO header the same as thisAddress or the broadcast addess (0xFF) will be accepted.
/// In promiscuous mode, all messages will be accepted regardless of the TO header.
/// In a conventional multinode system, all nodes will have a unique address
/// (which you could store in EEPROM).
/// You would normally set the header FROM address to be the same as thisAddress (though you dont have to,
/// allowing the possibilty of address spoofing).
/// \param[in] thisAddress The address of this node.
virtual void setThisAddress(uint8_t thisAddress) { _driver.setThisAddress(thisAddress);};
/// Sets the TO header to be sent in all subsequent messages
/// \param[in] to The new TO header value
virtual void setHeaderTo(uint8_t to){ _driver.setHeaderTo(to);};
/// Sets the FROM header to be sent in all subsequent messages
/// \param[in] from The new FROM header value
virtual void setHeaderFrom(uint8_t from){ _driver.setHeaderFrom(from);};
/// Sets the ID header to be sent in all subsequent messages
/// \param[in] id The new ID header value
virtual void setHeaderId(uint8_t id){ _driver.setHeaderId(id);};
/// Sets and clears bits in the FLAGS header to be sent in all subsequent messages
/// First it clears he FLAGS according to the clear argument, then sets the flags according to the
/// set argument. The default for clear always clears the application specific flags.
/// \param[in] set bitmask of bits to be set. Flags are cleared with the clear mask before being set.
/// \param[in] clear bitmask of flags to clear. Defaults to RH_FLAGS_APPLICATION_SPECIFIC
/// which clears the application specific flags, resulting in new application specific flags
/// identical to the set.
virtual void setHeaderFlags(uint8_t set, uint8_t clear = RH_FLAGS_APPLICATION_SPECIFIC) { _driver.setHeaderFlags(set, clear);};
/// Tells the receiver to accept messages with any TO address, not just messages
/// addressed to thisAddress or the broadcast address
/// \param[in] promiscuous true if you wish to receive messages with any TO address
virtual void setPromiscuous(bool promiscuous){ _driver.setPromiscuous(promiscuous);};
/// Returns the TO header of the last received message
/// \return The TO header
virtual uint8_t headerTo() { return _driver.headerTo();};
/// Returns the FROM header of the last received message
/// \return The FROM header
virtual uint8_t headerFrom() { return _driver.headerFrom();};
/// Returns the ID header of the last received message
/// \return The ID header
virtual uint8_t headerId() { return _driver.headerId();};
/// Returns the FLAGS header of the last received message
/// \return The FLAGS header
virtual uint8_t headerFlags() { return _driver.headerFlags();};
/// Returns the most recent RSSI (Receiver Signal Strength Indicator).
/// Usually it is the RSSI of the last received message, which is measured when the preamble is received.
/// If you called readRssi() more recently, it will return that more recent value.
/// \return The most recent RSSI measurement in dBm.
int16_t lastRssi() { return _driver.lastRssi();};
/// Returns the operating mode of the library.
/// \return the current mode, one of RF69_MODE_*
RHMode mode() { return _driver.mode();};
/// Sets the operating mode of the transport.
void setMode(RHMode mode) { _driver.setMode(mode);};
/// Sets the transport hardware into low-power sleep mode
/// (if supported). May be overridden by specific drivers to initialte sleep mode.
/// If successful, the transport will stay in sleep mode until woken by
/// changing mode it idle, transmit or receive (eg by calling send(), recv(), available() etc)
/// \return true if sleep mode is supported by transport hardware and the RadioHead driver, and if sleep mode
/// was successfully entered. If sleep mode is not suported, return false.
virtual bool sleep() { return _driver.sleep();};
/// Returns the count of the number of bad received packets (ie packets with bad lengths, checksum etc)
/// which were rejected and not delivered to the application.
/// Caution: not all drivers can correctly report this count. Some underlying hardware only report
/// good packets.
/// \return The number of bad packets received.
virtual uint16_t rxBad() { return _driver.rxBad();};
/// Returns the count of the number of
/// good received packets
/// \return The number of good packets received. virtual uint16_t rxGood() { return _driver.rxGood();};
/// Returns the count of the number of
/// packets successfully transmitted (though not necessarily received by the destination)
/// \return The number of packets successfully transmitted
virtual uint16_t txGood() { return _driver.txGood();};
private:
/// The underlying transport river we are to use
RHGenericDriver& _driver;
/// The CipherBlock we are to use for encrypting/decrypting
BlockCipher& _blockcipher;
/// Struct for with buffers for ciphering
typedef struct
{
size_t blockSize = 0;
uint8_t *inputBlock = NULL;
//uint8_t *outputBlock = NULL;
} CipherBlocks;
CipherBlocks _cipheringBlocks;
/// Buffer to store encrypted/decrypted message
uint8_t* _buffer;
};
/// @example nrf24_encrypted_client.pde
/// @example nrf24_encrypted_server.pde
/// @example rf95_encrypted_client.pde
/// @example rf95_encrypted_server.pde
/// @example serial_encrypted_reliable_datagram_client.pde
/// @example serial_encrypted_reliable_datagram_server.pde
#endif
#endif