Intregate Relic (a library for cryptography) into RIOT

Introduction

This tutorial will describe how to integrate the Relic library into RIOT. The integration of Relic will be firstly explained on the native, and secondly on the stm32f4discovery board. The Relic library is available on Relic website. Please download it from the Source tab on the website via the svn command.

Prerequisites

Before we start it is assumed that:

• the OS used for development is equipped with a working and somehow current GCC toolchain (native)
• the OS used for development is equipped with the recommended or somehow current gcc-arm-none-eabi cross toolchain (stm32f4discovery)
• the RIOT GIT-repository has been cloned, (head over to the getting started guide if you're uncertain how to obtain the RIOT source)
• the Relic library has been cloned via svn checkout http://relic-toolkit.googlecode.com/svn/trunk/ relic

Please note, for this tutorial:

• we use the hello-world example
• we cloned the relic directory into the hello-world project
• we use the Linaro Toolchain Binaries GCC in version 4.8 for ARM cross compillation

A) Integration on the native

1) Configuring our project

Please take a look at the Build Instructions of Relic website before. We will basically follow theses instructions.

1. We work in RIOT/examples/hello-world/
2. We clone the library with svn: svn checkout http://relic-toolkit.googlecode.com/svn/trunk/ relic
3. We create a folder that will then welcome the executable files: mkdir relic-build
4. Run cmake inside the target directory

• cd relic-build
• instead of the original cmake command, we need to add some Build Options. Not to make it repetitive, we write a small script named cmake.sh in the relic-build directory, copy and paste in this file the following commands:

#!/bin/bash
ls |grep -v cmake.sh |xargs rm -r
COMP="-g -m32" LINK="-m32" cmake -DARCH=X86 -DSEED=ZERO -DWORD=32 -DWITH="DV;MD;BN;CP" -DCMAKE_INSTALL_PREFIX:PATH=*Your_path*/RIOT/examples/relic/bin/native/usr/local ../relic

Please complete the beginning of the DCMAKE_INSTALL_PREFIX path with your own one. And note that we use only the "DV;MD;BN;CP" options, please read the Build Options if you need some more.

• We make this script executable with * chmod +x cmake.sh
• We run it then * ./cmake.sh

1. We compile the library:

• make
• make install

1. We compile the riot project outside:

• cd ..
• Before compiling, we need to edit the Makefile, to link our project with the Relic library, we add this at the end of the Makefile:

CFLAGS += -I/home/maxime-blanloeil/Documents/2A_TELECOM_ENSIMAG/Stage_2A_Hambourg/RIOT/examples/relic/bin/native/usr/local/include
LINKFLAGS += -L/home/maxime-blanloeil/Documents/2A_TELECOM_ENSIMAG/Stage_2A_Hambourg/RIOT/examples/relic/bin/native/usr/local/lib -lrelic_s

• We can now compile our hello-world project: make

2) Testing with some Relic functions

To check if Relic is really enable on native, let's test it.

1. First open the main.c file in our project
2. Then we copy some code from relic, we open ./relic/test/test_bn.c for example :

• We go to the line number 352, we select and copy the whole code of the subtraction function:

static int subtraction(void) {
  int code = STS_ERR;
  int s;
  bn_t a, b, c, d;

  bn_null(a);
  bn_null(b);
  bn_null(c);
  bn_null(d);

  TRY {
  	bn_new(a);
  	bn_new(b);
  	bn_new(c);
  	bn_new(d);

  	TEST_BEGIN("subtraction is anti-commutative") {
  		bn_rand(a, BN_POS, BN_BITS);
  		bn_rand(b, BN_POS, BN_BITS);
  		bn_sub(c, a, b);
  		bn_sub(d, b, a);
  		TEST_ASSERT(bn_cmp_abs(c, d) == CMP_EQ, end);
  		if (!bn_is_zero(c)) {
  			s = bn_sign(d);
  			TEST_ASSERT(bn_sign(c) != s, end);
  		}
  	}
  	TEST_END;

  	TEST_BEGIN("subtraction has identity") {
  		bn_rand(a, BN_POS, BN_BITS);
  		bn_zero(c);
  		bn_sub(d, a, c);
  		TEST_ASSERT(bn_cmp(d, a) == CMP_EQ, end);
  	}
  	TEST_END;

  	TEST_BEGIN("subtraction has inverse") {
  		bn_rand(a, BN_POS, BN_BITS);
  		bn_sub(c, a, a);
  		TEST_ASSERT(bn_is_zero(c), end);
  	}
  	TEST_END;
  }
  CATCH_ANY {
  	ERROR(end);
  }
  code = STS_OK;
end:
  bn_free(a);
  bn_free(b);
  bn_free(c);
  bn_free(d);
  return code;
}

• We paste it in our main.c file, outside the void main(void) function
• We now have to modify a little this function, we need to remove everything that is written in capital letters and change TEST_ASSERT in assert and remove the third argument ("end") of this function. Finally this is the code we get:

static int subtraction(void) {
int code = STS_ERR;
int s;
bn_t a, b, c, d;

bn_null(a);
bn_null(b);
bn_null(c);
bn_null(d);


bn_new(a);
bn_new(b);
bn_new(c);
bn_new(d);

bn_rand(a, BN_POS, BN_BITS);
bn_rand(b, BN_POS, BN_BITS);
bn_sub(c, a, b);
bn_sub(d, b, a);
assert(bn_cmp_abs(c, d) == CMP_EQ);
if (!bn_is_zero(c)) {
  s = bn_sign(d);
  assert(bn_sign(c) != s);
}
bn_rand(a, BN_POS, BN_BITS);
bn_zero(c);
bn_sub(d, a, c);
assert(bn_cmp(d, a) == CMP_EQ);

bn_rand(a, BN_POS, BN_BITS);
bn_sub(c, a, a);
assert(bn_is_zero(c));

code = STS_OK;

bn_free(a);
bn_free(b);
bn_free(c);
bn_free(d);
return code;
}

Please note that I provide here the result code, but if you want to copy some other function of Relic you will have to do the modifications by your-self.

1. We include the headers in our main.c:

#include "relic/relic.h"

1. We integrate the function we copied (subtraction()) in our void main(void) function, with the "init function" (core_init()) of Relic functions:

  int main(void)
  {      
      core_init();
      subtraction();
      puts("Hello World!");
      return 0;
  }

1. We can now compile our project again with some code implemented inside:

• make

1. Finally we run our project:

• ./bin/native/hello-world.elf

We get the expected result Hello World!, our program does not complain about the use of the Relic function so that confirms Relic has been well implemented in our RIOT project.