Libelium Waspmote v15 and Plug & Sense Operating instructions

Waspmote Encryption Libraries
Programming guide

-2- v7.0
Document version: v7.0 - 02/2017
© Libelium Comunicaciones Distribuidas S.L.
Index
INDEX
1. Introduction......................................................................................................................................... 3
2. Integrity................................................................................................................................................ 6
2.1. Waspmote Libraries ....................................................................................................................................................................6
2.1.1. Waspmote Hash Files .................................................................................................................................................6
2.1.2. Constructor ....................................................................................................................................................................6
2.1.3. Pre-Dened Constants ...............................................................................................................................................6
2.2. Calculating Message Digest.....................................................................................................................................................7
2.2.1. Calculating MD5 hash.................................................................................................................................................7
2.2.2. Calculating SHA hash .................................................................................................................................................7
2.3. Printing Message..........................................................................................................................................................................8
3. Authenticity ......................................................................................................................................... 9
3.1. Waspmote Libraries .................................................................................................................................................................10
3.1.1. Waspmote RSA Files .................................................................................................................................................10
3.1.2. Constructor ..................................................................................................................................................................10
3.1.3. Pre-Dened Constants .............................................................................................................................................10
3.2. Encrypting Message.................................................................................................................................................................10
4. Condentiality (privacy) ................................................................................................................... 11
4.1. Waspmote Libraries .................................................................................................................................................................13
4.1.1. Waspmote AES Files .................................................................................................................................................13
4.1.2. Constructor ..................................................................................................................................................................13
4.1.3. Pre-Dened Constants .............................................................................................................................................13
4.2. Calculating the encrypted message length...................................................................................................................13
4.3. AES Encryption .........................................................................................................................................................................13
4.4. Printing Message.......................................................................................................................................................................14
5. Secure Communication Scheme....................................................................................................... 15
6. Key Management on Meshlium........................................................................................................ 16
6.1. Link layer key Management (only XBee) ..........................................................................................................................16
6.2. Application Layer Key Management (AES libraries) .....................................................................................................18
7. Code examples and extended information .................................................................................... 20
8. API changelog.................................................................................................................................... 22
9. Certications...................................................................................................................................... 23

-3- v7.0
Introduction
1. Introduction
This guide explains the Encryption library features and functions. There are no great variations in this library for our new product
lines Waspmote v15 and Plug & Sense! v15, released on October 2016.
Anyway, if you are using previous versions of our products, please use the corresponding guides, available on our Development
website.
You can get more information about the generation change on the document“New generation of Libelium product lines”.
The new Encryption Libraries are designed to add to the Waspmote sensor platform the capabilities necessary to protect the
information gathered by the sensors. To do so three cryptography layers are dened:
•Link Layer: In the rst one all the nodes of the network share a common preshared key which is used to encrypt the
information using AES 128. This process is carried out by specic hardware integrated in the same 802.15.4/ZigBee radio,
allowing the maximum eciency of the sensor nodes energy consumption. This rst security layer ensures no third party
devices will be able to even connect to the network (access control).
•Application Layer: In the second security layer each node uses a point to point encryption scheme with Meshlium -the
Gateway of the network-. This way, even the intermediate nodes of the network (the ones which forward the information
to the destination) will not be able to see the sensor data transmitted. Messages are sent using AES, (implemented by the
software library) ensuring complete condentiality and privacy while maintaining the minimum resources of the node in
term of computing cycles and energy consumption.
•Secure Web Server Connection: The third security technique is carried out in Meshlium -the Gateway- where HTTPS and
SSH connections are used to send the information to the Cloud server located on the Internet.
A fourth optional encryption layer allows each node to encrypt the information using the Public key of the Cloud server. Thus,
the information will be kept condentially all the way from the sensor device to the web or data base server on the Internet.
Note: The Encryption Libraries are part of the Waspmote API and have been designed to work solely on top of the Waspmote and
Waspmote Plug & Sense sensor platforms. More info at:
http://www.libelium.com/waspmote
http://www.libelium.com/plug_&_sense
- Transmission of sensor data:
Information is encrypted in the application layer via software with AES using the key shared exclusively between the origin and
the destination. Then the packet is encrypted again in the link layer via hardware with AES 128 so that only trusted packets be
forwarded, ensuring access control and improving the usage of resources of the network.
Figure : Communication diagram

-4- v7.0
Introduction
Figure : Waspmote frame on OSI stack for communication (via 802.15.4)
Figure : Waspmote frame structure for communication (via 802.15.4)

-5- v7.0
Introduction
Common security issues which are solved include:
- Access control: by using AES 128 in the link layer we ensure that only nodes with the shared key can access to the routing
capabilities of the sensor network. If a strange node sends a message to the network the message will be discharged in the rst
hop so no extra communication resources will be used. The AES 128 algorithm is implemented in the same radio using specic
hardware, for this reason the information will be automatically discarded and not even sent to the microcontroller.This provides
an extra layer of security as the main control unit of the node will not be interrupted from performing basic tasks or event not
awaken from the sleep mode (what ensures optimum energy usage).
- Authentication: the library implements also RSA with asymmetric key scheme. Each node has a pair of Public/Private keys
(1024b) which uses to sign the messages in order to ensure the authenticity of origin and destination.
- Data Condentiality (Privacy): by doubling encryption of the messages we ensure that rst that only the nodes which form
part of the network can see the general routing packets (AES 128 in the link layer) and after that we establish an encryption
tunnel by direct P2P encryption between origin and destination (using AES).
- Data Integrity: the new library uses hash algorithms such as MD5 and SHA to create the checksum of the message and to
ensure that the nal information received correspond with the original sent.
- Non-repudiation: by signing the messages with RSA keys we have also the legal proof that the information sent really was
sent by a specic sensor node and not by other. Important in the future when all the sensitive sensor information has to be
legally approved.
Each node may store thousands of dierent Public Keys of the nodes of the network in its SD card. So we can establish a real P2P
encryption among any sensor and the Gateway and even between any sensor and any web or data base server directly.
The new Libraries are specically designed to be used in the Waspmote hardware sensor platform and are distributed along
with the Waspmote IDE which is distributed under an open source license.
Note: The Encryption Libraries are part of the Waspmote API and have been designed to work solely on top of the Waspmote and
Waspmote Plug & Sense sensor platforms. More info at:
http://www.libelium.com/waspmote
http://www.libelium.com/plug_&_sense

-6- v7.0
Integrity
2. Integrity
The data integrity security ensures the correctness or accuracy of data.The data is protected against unauthorized modication,
deletion, creation, and replication and provides an indication of these unauthorized. Integrity implies that the data is an exact
copy of some original version.
Data integrity is provided by hash functions like Message Digest Algorithm (MD5) or Secure Hash Algorithm (SHA).The following
methods are provided by the Encryption libraries:
• MD5 algorithm takes as input a message of arbitrary length and produces as output a 128-bit“ngerprint” or “message
digest” of the input message. MD5 is currently a standard, Internet Engineering Task Force (IETF) Request for Comments
(RFC) 1321. In comparison, MD5 is not quite as fast as the MD4 algorithm, but oers much more assurance of data secu-
rity.
• SHA is considered to be the successor to MD5. The Federal Information Processing Standard (FIPS 180-2) species four
secure hash algorithms: SHA-1, SHA-256, SHA-384, and SHA-512. All algorithms are iterative, one-way hash functions
that can process a message with a maximum length of 264 bits to 2128 bits to produce a 160 to 512-bit condensed repre-
sentation called a message digest. The input message is processed in 512-bit to 1024-bit blocks. The four algorithms
dier most signicantly in the number of bits for the message digest length. Each SHA algorithm processes a message
in two stages: preprocessing and hash computation. Preprocessing involves padding a message, parsing the padded
message into 512-bit or 1024-bit blocks, and setting initialization values to be used in the hash computation. The hash
computation generates a message schedule from the padded message and uses that schedule, along with functions,
constants, and word operations to iteratively generate a series of hash values. The nal hash value generated by the hash
computation is used to determine the message digest.
2.1. Waspmote Libraries
2.1.1. Waspmote Hash Files
WaspHash.h is the header le of the class, and WaspHash.cpp is the class where the functions and variables are implemented.
It is mandatory to include the Hash library when using it. The following line must be introduced at the beginning of the code:
#include <WaspHash.h>
2.1.2. Constructor
To start using Waspmote Hash library, an object from class ‘WaspHash’ must be created. This object, called ‘HASH’, is created
inside the Waspmote Hash library and it is public to all libraries. It is used through the guide to show how the Waspmote Hash
library works.
When creating this constructor, no variables are initialized by default.
2.1.3. Pre-Dened Constants
There are some constants dened in ‘WaspHash.h’ related with the dierent encryption and padding modes that can be used
to encrypt and decrypt messages.

-7- v7.0
Integrity
2.2. Calculating Message Digest
This section will describe how calculate a message digest depends on the selected algorithm. The dierent algorithms provide
dierent messages digest size.
For example, the Message Digest (MD5) hash is a mathematical algorithm which produces a unique 128 bit number (a hash)
created from the data input. If even one bit of data changes, the hash value will change.
2.2.1. Calculating MD5 hash
Previously, a variable to store the message digest must be declared. This variable must be correctly dimensioned to contain the
calculated hash message.
{
uint8_t hash_message[16];
}
The features that must be met in order to calculate the MD5 algorithm are:
Algorithms Output size
(bits)
Internal state
size (bits)
Block size
(bits)
Max message
size (bits)
Word size
(bits)
MD5 128 128 512 2⁶⁴− 1 32
The next code shows how to calculate the message digest with HASH.md5(). The inputs expected are: the pointer to the buer
where the output is stored, the input message pointer and the length of the input message.
{
char message[] = “Libelium”;
HASH.md5(hash_message_md5, (uint8_t*)message, strlen(message)*8);
}
2.2.2. Calculating SHA hash
The features that must be met in order to calculate the SHA algorithm are:
Algorithms Output size
(bits)
Internal state
size (bits)
Block size
(bits)
Max message
size (bits)
Word size
(bits) Rounds
SHA-1 160 160 512 2⁶⁴− 1 32 80
SHA-224 224 256 512 2⁶⁴− 1 32 64
SHA-256 256 256 512 2⁶⁴− 1 32 64
SHA-384 384 512 512 2¹²⁸− 1 64 80
SHA-512 512 512 1024 2¹²⁸− 1 64 80
Previously, a variable to store the message digest must be declared. This variable must be correctly dimensioned to contain the
calculated hash message.
If SHA-1 is used, the variable that stores the hash message is dened:
{
uint8_t hash_message[20];
}
If SHA-384 is used, the variable that stores the hash message is dened:
{
uint8_t hash_message[48];
}

-8- v7.0
Integrity
Next code shows how to calculate the message digest with HASH.sha(). The inputs expected are: the SHA algorithm, the
pointer to the buer where the output is stored, the input message pointer and the length of the input message.
{
char message[] = “Libelium”;
HASH.sha(SHA1, hash_message, (uint8_t*)message, strlen(message)*8);
}
{
char message[] = “Libelium”;
HASH.sha(SHA384, hash_message, (uint8_t*)message, strlen(message)*8);
}
2.3. Printing Message
Using the hash function HASH.printMessageDigest() the message digest is written via USB port.
{
// Write message digest by USB port
HASH.printMessageDigest(“SHA-1:”, hash_message, 20);
HASH.printMessageDigest(“MD5:”, hash_message, 16);
}
Example of use may be found in:
http://www.libelium.com/development/waspmote/examples/hash-01-md5
http://www.libelium.com/development/waspmote/examples/hash-02-sha1

-9- v7.0
Authenticity
3. Authenticity
Authenticity is the assurance that a message, transaction, or other exchange of information is from the source it claims to be
from. Authenticity involves proof of identity.
Forensuring messageauthenticity,RSA algorithm isused.TheRSA cryptosystemisthemostwidely-usedpublic keycryptography
algorithm in the world. It can be used to encrypt a message without the need to exchange a secret key separately. Its security is
based on the diculty of factoring large integers.
The RSA algorithm can be used for both public key encryption and digital signatures:
•Public-key encryption: Party A can send an encrypted message to party B without any prior exchange of secret keys. A
just uses B’s public key to encrypt the message and B decrypts it using the private key, which is only known by the receiver.
•Digital signatures: RSA can also be used to sign a message, so A can sign a message using their private key and B can verify
it using A’s public key.
Key generation
• 1. Choose two dierent prime numbers pand q. For security purposes, the integers pand qshould be chosen at random,
and should be of similar bit-length.
• 2. Compute n = p·q. The resulting nis used as the modulus for both public and private keys. Its length, usually expressed in
bits, is the key length.
• 3. Compute φ(n) = (p-1)(q-1).
• 4. Choose a public exponent ’e’ such that 1 < e < φ(n), which is coprime to φ(n). The number eis released as the public key
exponent.
• 5. Compute a private exponent ’d’ that satises the congruence ed ≡1 (mod φ(n)). The number dis kept as the private key
exponent.
• 6. The public key consists of the modulus nand the public exponent e. The private key consists of the modulus nand
the private exponent d, which must be kept secret. p, q, and φ(n) must also be kept secret because they can be used to
calculate d.
The best size for a modulus depends on one’s security needs.The larger the modulus, the greater the security, but also the slower
the RSA algorithm operations. One should choose a modulus length upon consideration, rst, of the value of the protected data
and how long it needs to be protected, and, second, of how powerful one’s potential threats might be. Typical bit lengths are
1024, 2048, 3072, 4096, etc.
This is the process of transforming a plaintext message into ciphertext, or vice-versa. The RSA function, for message ‘m’ and key
‘k’ is evaluated as follows:
F(m,k) = mkmod n
There are obviously two cases:
•RSA Encryption scheme: Encrypting with the public key, and then decrypting with the private key
- Encryption rule: F (m,e) = memod n = c
- Decryption rule: F (c,d) = cdmod n = m
- Where‘m’ is the message,‘e’ is the public exponent,‘d’is the private exponent and‘c’ is the ciphertext.

-10- v7.0
Authenticity
•RSA Signature scheme: Encrypting with the private key, and then decrypting with the public key.
- Encryption rule: F (m,d) = mdmod n = s
- Decryption rule: F (s,e) = semod n = m
- Where‘m’ is the message,‘e’ is the public exponent,‘d’is the private exponent and‘c’ is the ciphertext.
RSA is slower than certain other symmetric cryptosystems. RSA is, in fact, commonly used to securely transmit the keys for
another less secure, but faster algorithm.
3.1. Waspmote Libraries
3.1.1. Waspmote RSA Files
WaspRSA.h is the header le of the class, and WaspRSA.cpp is the class where the functions and variables are implemented.
It is mandatory to include the RSA library when using it. The following line must be introduced at the beginning of the code:
#include <WaspRSA.h>
3.1.2. Constructor
To start using Waspmote RSA library, an object from class ‘WaspRSA’ must be created. This object, called ‘RSA’, is created inside
the Waspmote RSA library and it is public to all libraries. It is used through the guide to show how the Waspmote RSA library
works.
When creating this constructor, no variables are initialized by default.
3.1.3. Pre-Dened Constants
There are some constants dened in‘WaspRSA .h’ related with the dierent encryption and padding modes that can be used to
encrypt messages.
3.2. Encrypting Message
The function RSA.encrypt() encrypts an original message to an encrypted message using the public exponent ‘e’ and the
modulus‘n’. Receiver can decrypt the message using the private key.
{
RSA.encrypt( original_message,
public_exponent,
modulus,
encrypted_message,
sizeof(encrypted_message));
}
Note: The maximum input size message must be smaller than the modulus.
Example of use:
http://www.libelium.com/development/waspmote/examples/rsa-01-encryption