MySensors Library & Examples  2.2.0-61-g15351cd
Files | Macros | Functions
+ Collaboration diagram for MySigning:

Detailed Description

API declaration for MySigning signing backend.

See also
Message signing

Files

file  MySigning.h
 API declaration for MySigning signing backend.
 
file  SecureActuator.ino
 Example sketch showing how to securely control locks.
 
file  SecurityPersonalizer.ino
 Security personalization sketch.
 

Macros

#define NUM_OF(x)   (sizeof(x)/sizeof(x[0]))
 Helper macro to determine the number of elements in a array.
 

Functions

void signerInit (void)
 Initializes signing infrastructure and associated backend. More...
 
void signerPresentation (MyMessage &msg, uint8_t destination)
 Does signing specific presentation for a node. More...
 
bool signerProcessInternal (MyMessage &msg)
 Manages internal signing message handshaking. More...
 
bool signerCheckTimer (void)
 Check timeout of verification session. More...
 
bool signerPutNonce (MyMessage &msg)
 Get nonce from provided message and store for signing operations. More...
 
bool signerSignMsg (MyMessage &msg)
 Signs provided message. All remaining space in message payload buffer is used for signing identifier and signature. More...
 
bool signerVerifyMsg (MyMessage &msg)
 Verifies signature in provided message. More...
 
void signerSha256Init (void)
 Initialize a hash calculation session. More...
 
void signerSha256Update (const uint8_t *data, size_t sz)
 Add data to an ongoing hash calculation session. More...
 
uint8_t * signerSha256Final (void)
 Finalize an ongoing hash calculation session and return the hash. More...
 
int signerMemcmp (const void *a, const void *b, size_t sz)
 Do a timing neutral memory comparison. More...
 

Function Documentation

bool signerCheckTimer ( void  )

Check timeout of verification session.

Nonce will be purged if it takes too long for a signed message to be sent to the receiver.
Usage: This function should be called on regular intervals, typically within some process loop.

Returns
true if session is still valid.
void signerInit ( void  )

Initializes signing infrastructure and associated backend.

This function makes sure that the internal states of the signing infrastructure is set to a known initial state.
Usage: This function should be called before any signing related operations take place.

int signerMemcmp ( const void *  a,
const void *  b,
size_t  sz 
)

Do a timing neutral memory comparison.

The function behaves similar to memcmp with the difference that it will always use the same number of instructions for a given number of bytes, no matter how the two buffers differ and the response is either 0 or -1.

Parameters
aFirst buffer for comparison.
bSecond buffer for comparison.
szThe number of bytes to compare.
Returns
0 if buffers match, -1 if they do not.
void signerPresentation ( MyMessage msg,
uint8_t  destination 
)

Does signing specific presentation for a node.

This function makes sure any signing related presentation info is shared with the other part. The presentation of the gateways signing preferences is done in signerProcessInternal().
Usage: This function should be called by the presentation routine of the MySensors library. You only need to call this directly from a sketch to set up a node to node signed message exchange. If you do call this directly from a sketch, and you at some point change your sketch to go from requiring signing to not requiring signatures, you need to present this change to the node at least once, so it can update its requirements tables accordingly. Or it will keep believing that this node require signatures and attempt to send signed messages to it.

Parameters
msgMessage buffer to use.
destinationNode ID of the destination.
bool signerProcessInternal ( MyMessage msg)

Manages internal signing message handshaking.

This function takes care of signing related message handshaking such as nonce exchange.
Usage: This function should be called by the incoming message handler before any further message processing is performed on internal messages. This function should only be called for C_INTERNAL class messages.

Parameters
msgMessage buffer to process.
Returns
true if caller should stop further message processing.
bool signerPutNonce ( MyMessage msg)

Get nonce from provided message and store for signing operations.

Returns false if subsystem is busy processing an ongoing signing operation.
Returns false if signing identifier found in message is not supported by the used backend.
If successful, this marks the start of a signing operation at the sending side so implementation is expected to do any necessary initializations within this call.
Usage: This function is typically called as action when receiving a I_NONCE_RESPONSE message.

Parameters
msgThe message to get the nonce from.
Returns
true if successful, else false.
uint8_t* signerSha256Final ( void  )

Finalize an ongoing hash calculation session and return the hash.

The returned hash size is always 32 bytes. Buffer can be assumed to be valid until signerSha256Init() is called again.

Returns
Buffer with 32-byte hash.
Examples:
SecurityPersonalizer.ino.
void signerSha256Init ( void  )

Initialize a hash calculation session.

Any ongoing calculation session will be terminated/reset.

Examples:
SecurityPersonalizer.ino.
void signerSha256Update ( const uint8_t *  data,
size_t  sz 
)

Add data to an ongoing hash calculation session.

More data can be added by repeated calls to this function.

Parameters
dataBuffer with data to add.
szSize of data buffer.
Examples:
SecurityPersonalizer.ino.
bool signerSignMsg ( MyMessage msg)

Signs provided message. All remaining space in message payload buffer is used for signing identifier and signature.

Nonce used for signature calculation is the one generated previously within signerProcessInternal().
Nonce will be cleared when this function is called to prevent re-use of nonce.
Returns false if subsystem is busy processing an ongoing signing operation.
Returns false if not two bytes or more of free payload space is left in provided message.
This ends a signing operation at the sending side so implementation is expected to do any deinitializations and enter a power saving state within this call.
Usage: This function is typically called as action when receiving a I_NONCE_RESPONSE message and after signerPutNonce() has successfully been executed.

Parameters
msgThe message to sign.
Returns
true if successful, else false.
bool signerVerifyMsg ( MyMessage msg)

Verifies signature in provided message.

Nonce used for verification is the one previously set using signerPutNonce().
Nonce will be cleared when this function is called to prevent re-use of nonce.
Returns false if subsystem is busy processing an ongoing signing operation.
Returns false if signing identifier found in message is not supported by the used backend.
This ends a signing operation at the receiving side so implementation is expected to do any deinitializations and enter a power saving state within this call.
Usage: This function is typically called when receiving a message that is flagged as signed and MY_SIGNING_REQUEST_SIGNATURES is activated.

Parameters
msgThe message to verify.
Returns
true if successful, else false.