oscms-codecs-bridge

The bridge layer of the Open SCMS stack satisfies two main purposes.

• Provides a higher level abstraction of the underlying CODECs layer, combining specific library calls into more complex operations. These operations are specifically tailored to the needs of the Rust server implementation.
• Performs the bulk of cryptographic operations, avoiding the need for Rust to interface with the OpenSSL library.

As such, it has knowledge of the implementation of both the server and the underlying CODECs API and is therefore of little use as a stand-alone repository.

Table of Contents

• Development
  • Installing Dependencies
  • Using Docker
  • Getting the Code
  • Building the code
  • Running Unit Tests
  • Running Valgrind
• Using a Different Set of CODECs
• Contributing
• License

Development

We assume a debian-based development environment, ideally Ubuntu 24.04 or newer.

Installing Dependencies

The following libraries need to be installed on your development machine.

sudo apt install -y \
    libzip-dev \
    libssl-dev \
    libcurl4-openssl-dev

You will also need a set of tools

sudo apt-get -qy install \
    build-essential \
    clang-format-18 \
    cmake \
    cppcheck \
    curl \
    git \
    gzip \
    valgrind \
    wget

Using Docker

Alternatively, you can use the docker file provided in the oscms-ci-docker repository. This is the image used for all CI jobs for the C-language repositories during the initial development.

Clone the repository and build the image as follows

git clone git@github.com:OpenSCMS/oscms-ci-docker.git
cd oscms-ci-docker
docker build -t oscms-ci-docker . -f openscms-ci.dockerfile

Now change to the directory where you cloned this repository and run the container thus

docker run -ti --rm --volume $PWD:/WORK --user $(id -u):$(id -g) \
       oscms-ci-docker

This will place you in a bash shell within the container, with your cloned source available at /WORK. Your user inside the container will have the same group and user id as on your host, so any changes you make will have the correct permissions.

It should also be possible to use this image as a VS Code development container. The development team has not used it in this way, so if it doesn't work ... contributions are welcome.

Getting the Code

The Open SCMS stack makes heavy use of submodules. Therefore, the clone command should ensure it pulls down all sub modules as follows.

git clone --recurse-submodules git@github.com:OpenSCMS/oscms-codecs-bridge.git

Obviously, replace the URL with your own if you are cloning a fork.

Due to the use of relative submodule paths, if you are going to fork one repository you will need to fork them all. The alternative is for you to modify the paths in .gitmodules, but DO NOT commit these changes. Such a pull request will not be accepted.

The list of repositories, and their relative submodule dependencies is as follows

• OpenSCMS
  • oscms-codecs-bridge
    • oscms-asn1c-codecs
      • oscms-codecs-api
      • oscms-asn1c-generated
        • etsi_ts103097-asn
        • ieee1609dot2dot1-asn

The project also makes use of the Cmake Helpers project

Building the code

All C code is built using CMake and the CMake scripts will enforce out-of-source builds.

After cloning, create a build directory. We usually use BUILD directly in the repository root (it's included in the .gitignore), but feel free to put it anywhere convenient.

Change to your build directory and configure and build as follows

cmake .. # Or the path to your repository root
make

This will compile and link a Debug build and include all unit tests.

All CMake scripts support a common set of options and command line definitions.

Option	Default	Description
BUILD_TESTS	On	Enables or disables the building of the unit tests
CMAKE_BUILD_TYPE	Debug	Defines the build type. Acceptable values are Debug or Release. This primarily affects debug symbols and optimization levels.
EXTRA_MEMCHECK_OPTIONS	empty	Allows the specification of additional arguments to valgrind
RUN_CPPCHECK	On	Enables or disables running cppcheck on all code during the build.
SKIP_INSTALL	Off	If set to On, suppresses generation of any install targets

Running Unit Tests

After building the code (with BUILD_TESTS set to On) from the build directory, simply enter

make test

Alternatively, you can run them directly with ctest

ctest <options>

Which allows you to do things like select specific tests. See the CTest documentation for details.

Running Valgrind

From the build directory, run CTest with the memcheck option

ctest -T memcheck

By default the following valgrind options will be specified (in addition to those injected by CMake itself)

--tool=memcheck --leak-check=full --num-callers=50 --show-reachable=yes

There is also a small set of suppressions defined in './.valgrind.suppressions' to deal with some false positives.

You can specify additional options when configuring using the EXTRA_MEMCHECK_OPTIONS variable. For example, to generate suppressions in the log files and track the origin of allocations

cmake .. \
      -DEXTRA_MEMCHECK_OPTIONS="--gen-suppressions=all --track-origins=yes"

The log files will appear in the Testing/Temporary directory with names of the form MemoryChecker.<#>.log where # is the test number. The complete set of results will be in a log file with # being the total number of tests.

Using a Different Set of CODECs

The Open SCMS stack is implemented using the open source ASN1C transpiler, but it is architected to support the use of other - usually proprietary (i.e. expensive) - transpilers.

To build using a different concrete implementation of the codecs API

• Implement your new library, closely following the structure of the ASN1C Codecs implementation.
• Ensure it builds with CMake and exports a target for a static library called oscms_codecs_api
• Add your repository as a new submodule under the codecs directory.
• Modify the root CMakeLists.txt file to call add_subdirectory with the new submodule, rather than codecs/asn1c

If you've got it right, it should build without errors and pass all unit tests.

Contributing

Contributions are welcome. Please see the CONTRIBUTING file for details, including the Code of Conduct and C Style Guide.

License

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