SecApi Rust Bindings

This repository contains Rust bindings for SecAPI. There are two different crates in this repo:

1. secapi-sys: The raw C-bindings uses as a FFI (Foreign Function Interface). Must be binary compatible with the version of SecApi that the user is linking to. Since Rust can not read header files (like how C and C++ can share the same header files) we need to let Rust know what data types and function interfaces it can expect when we link it to the C/C++ compiled library. The use of the #[repr(C)] macro ensures that all data types have the same memory layout as their C/C++ counterparts. No additional functionality should be implemented in this crate.
2. secapi: Provides an anti-corruption layer. Calls into secapi-sys but exposes a Rust API that uses idiomatic data structures. This is necessary to ensure callers of this library program in Rust and not some Rust/C/C++ hybrid. Since the FFI calls must match their C/C++ counterparts, there will be a lot of wrapper code to take Rust data structures and convert them in C pointers or other primitive data structures. In addition all FFI calls are unsafe and must be wrapped in the unsafe { } block. Since the borrow checker can not resolve pointers, we must manually call Box::into_raw() to provide the FFI with the raw pointer and then call Box::from_raw() to bring the pointer back under Rust's borrow checker.

Building

The recommend way of build is using Docker with the included Dockerfile and docker-compose.yml file. Using Docker ensures that the build behavior is repeatable on every system regardless of the host system.

First we need to create volume where we will house our work area. We want this volume to be persistent and not destroyed if our container is stopped or removed. To create a persistent container run the following command:

$ docker volume create rust_work_area

Next we need to build our Docker image. This Docker image will be used as the build and run environment for Rust development. To build the image using the Dockerfile execute the following commands.

$ cd docker
$ docker compose build

Now that the image is built we need to start a container. A container is just an instance of an image, much like a process is an instance of a program. Once the container is running we can launch a shell that will allow us to interact with the container.

$ docker compose up
$ docker exec -it rust /bin/bash

Once we are in the container we now need to clone this repo again (I know its like inception). Once the repo is cloned, cd into the newly created repo and you should be able to build. On the first build it will take a bit longer since we will be building the reference implementation of SecAPI. Please be patient.

(Docker Container) $ git clone https://github.com/rdkcentral/secapi-rust.git
(Docker Container) $ cd secapi-rust
(Docker Container) $ git submodule init
(Docker Container) $ git submodule update
(Docker Container) $ cargo build

Once that is done you can now do a quick sanity check test. You will have to set the ROOT_KEYSTORE environment variable so that the reference implementation knows what to use as the root keystore.

(Docker Container) $ ROOT_KEYSTORE=~/secapi-rust/root_keystore.p12 cargo test

Process

The process on how everything is built is a bit complex. Here is a high level overview so that you can understand the build process in case something goes wrong or you are just interested:

1. tasecureapi is built. The tasecureapi project exists in this repo as a submodule. Since the version of secapi-sys and the outputted libsaclient.so must be binary compatible, we ensure that any changes that get pushed only get incorporated in this library once we have had a change to update the Rust bindings. Once the library is build we copy it in to Rust's OUT_DIR.
2. secapi-sys is built and linked to both libc.so and libsaclient.so.
3. secapi is built and linked to secapi-sys.

Features

This library has a couple of different feature flags that will effect how the library is built. They are listed below:

1. system-sa-client (Disabled by default): Default will build the reference SecAPI and link against its shared library output. If this flag is enabled, then the build process will look for a libsaclient.so in the system library folders (/lib, /usr/lib, etc.) and link against that library.

Dependencies

• secapi-sys:

  1. libc
  2. copy_dir: Is required to build but is not a runtime dependency

• secapi

  1. libc
  2. chrono
  3. bitflags
  4. uuid

If doing a default build (which has the system-sa-client feature disabled) then Cargo will build the default reference library tasecureapi and dynamically link it to the output of this project. You will then need the following dependencies inorder to build tasecureapi.

• tasecureapi

  1. cmake: Required to build the library
  2. gtest and gmock: Required to build unit tests (but not linked to in the output shared library saclient.so)
  3. libyajl: Required to build and link against
  4. openssl: Required to build and link against

License

This project is licensed under the Apache-2.0 License - see the LICENSE file for details

Examples

Generate random bytes and use it as a symmetrical Key

use secapi::{DigestAlgorithm, ErrorStatus, Rights};
use secapi::key::{Key, KeyFormat};
use secapi::crypto::random_bytes;

// The size of a 128 bit key in bytes
const SYM_128_KEY_SIZE: usize = (128 / 8);

// The rust counterpart of the following:
// std::vector<uint8_t> random_bytes(SYM_128_KEY_SIZE);
// if (RAND_bytes(random_bytes.data(), static_cast<int>(random_bytes.size())) != 1) {
//    ERROR("RAND_bytes failed");
//    std::exit(-1);
// }
let mut random_bytes = random_bytes(SYM_128_KEY_SIZE)?;

// The Rust counterpart of the following:
// sa_rights rights;
// sa_rights_set_allow_all(&rights);
let rights = Rights::allow_all();

// The Rust counterpart of the following:
// auto key = create_uninitialized_sa_key();
// sa_import_parameters_symmetric params = {rights};
// sa_status const status = sa_key_import(
//    key.get(),
//    SA_KEY_FORMAT_SYMMETRIC_BYTES,
//    random_bytes.data(),
//    random_bytes.size(),
//    &params
// );
//
// if (status != SA_STATUS_OK) {
//    ERROR("sa_key_import failed");
//    std::exit(-1);
// }
let key = Key::import(KeyFormat::SymmetricBytes { rights }, &mut clone_key)?;

// The Rust counterpart of the following:
// size_t out_length = 0;
// sa_status status = sa_key_digest(nullptr, &out_length, *key, SA_DIGEST_ALGORITHM_SHA1);
// if (status != SA_STATUS_OK) {
//    ERROR("sa_key_digest failed");
//    std::exit(-1);
// }
//
// auto digest = std::vector<uint8_t>(out_length);
// status = sa_key_digest(digest.data(), &out_length, *key, SA_DIGEST_ALGORITHM_SHA1);
// if (status != SA_STATUS_OK) {
//    ERROR("sa_key_digest failed");
//    std::exit(-1);
// }
let sha1_digest = key.digest(DigestAlgorithm::SHA1)?;

Import a RSA Key

use secapi::{ErrorStatus, Rights};
use secapi::key::{Key, KeyFormat};

// The Rust counterpart of the following:
// sa_rights rights;
// sa_rights_set_allow_all(&rights);
let rights = Rights::allow_all();

// The Rust counterpart of the following:
// auto key = create_uninitialized_sa_key();
// sa_import_parameters_rsa_private_key_info params = {rights};
// sa_status const status = sa_key_import(
//    key.get(),
//    SA_KEY_FORMAT_RSA_PRIVATE_KEY_INFO,
//    clear_key.data(),
//    clear_key.size(),
//    &params
// );
//
// if (status != SA_STATUS_OK) {
//    ERROR("sa_key_import failed");
//    std::exit(-1);
// }
let mut clone_key = RSA_1024;
let key = Key::import(KeyFormat::RsaPrivateKeyInfo { rights }, &mut clone_key)?;

// The Rust counterpart of the following:
// sa_header header;
// sa_status const status = sa_key_header(&header, *key);
// if (status != SA_STATUS_OK) {
//    ERROR("sa_key_header failed");
//    std::exit(-1);
// }
// ASSERT_EQ(header.type, 2);
// ASSERT_EQ(header.size, 128);
let header = key.header()?;
assert_eq!(header.key_type, KeyType::Rsa);
assert_eq!(header.size, 128);

Current Implementation Status

sa.h

sa_crypto.h

sa_key.h

sa_svp.h