commschamp/cc.x509.commsdsl

Implement encoding / decoding of X.509 certificate with CommsChampion Ecosystem

Overview

This project is a member of the CommsChampion Ecosystem. It provides necessary CommsDSL schemas as well as extra injection code to define the structure of the X.509 public key infrastructure certificate.

How to Build

This project uses CMake as its build system. Please open main CMakeLists.txt file and review available options as well as mentioned available parameters, which can be used in addition to standard ones provided by CMake itself, to modify the default build.

This project also has external dependencies. The build process expects to find them in the provided CMAKE_PREFIX_PATH (CMAKE_PROGRAM_PATH can also be used for path to the commsdsl code generators). The required dependencies are:

• COMMS Library
• commsdsl code generators.
• cc.asn1.commsdsl for the ASN.1 definitions.

$> cd /path/to/cc.x509.commsdsl
$> mkdir build && cd build
$> cmake .. -DCMAKE_INSTALL_PREFIX=./install -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_PREFIX_PATH=/path/to/comms/install\;/path/to/commsdsl/install\;/path/to/asn1/install
$> cmake --build . --config Release

The build process generates another CMake project (hosted as cc.x509.generated) and builds it. As the result the installation directory will contain only the X.509 certificate definition headers (without the COMMS Library).

To achieve the same output the cc.x509.generated can be used directly. Its only (optional) dependency is the COMMS Library.

There is also a testing application available, which is basically generated by the commsdsl2test code generator. To add it to the build add -DCC_X509_BUILD_APPS=ON to the cmake invocation:

$> cmake .. -DCC_X509_BUILD_APPS=ON ...

The project's cmake configuration options allow building bindings to other high level programming languages using swig and emscripten, see relevant commsdsl's documentation pages for details.

How to Use

The generated code has a definition of the certificate field in include/cc_x509/field/Certificate.h. It was defined with strict adherence to its definition in section 4.1 of the RFC-5280.

The CommsDSL schema definition uses ASN.1 definitions provided by the cc.asn1.commsdsl. Please refer to it for guidance on how ASN.1 encoding is performed and how to access required values.

The certificate field definition uses infrastructure provided by the COMMS Library. Please refer to the official tutorial and tutorial2 in particular for details how to use the field definitions.

When the X.509 certificate needs to be decoded, just use inherited read() member function.

using Certificate = cc_x509::field::Certificate<>;
Certificate cert;
std::vector<std::uint8_t> buf = {...}; // contains binary encoding of the certificate;
auto readIter = &buf[0];
auto es = cert.read(readIter, buf.size());
if (es != comms::ErrorStatus::Success) {
    ... // Invalid certificate data
    return;
}

// Certificate is successfully decoded, access its fields
...

When the X.509 certificate needs to be encoded, update all the values and call refresh() to update the Length information in every field before performing write().

using Certificate = cc_x509::field::Certificate<>;
Certificate cert;

// Set all the fields' values, remember that most of them are TLV triplets and
// their `Value` field needs to be accessed first. Then use value() member function
// to get an access to the actual storage type.

...
auto& signatureValue = cert.field_value().field_signatureValue(); // Access signatureValue member.
auto& signatureValueData = signatureValue.field_value().value(); // Access the storage of the signatureValue data
signatureValueData = ...; // Assign raw bytes of the signature storage vector.

// After update is complete, update the Length values
cert.refresh();

std::vector<std::uint8_t> encodedData;
encodedData.reserve(cert.length());
auto writeIter = std::back_inserter(encodedData);

auto es = cert.write(writeIter, buf.max_size());
if (es != comms::ErrorStatus::Success) {
    ... // Serialization failed, should not really happen
    return;
}

// Successfully encoded
...

How to (Fuzz) Test

The commsdsl project provides commsdsl2test code generator. It generates a code for the test application which is suitable for AFL testing. Is is used to generate the code for the cc_x509_input_test testing application.

The testing application just expects data from the standard input and tries to decode the certificate. If the certificate is successfully decoded, then its contents are dumped to standard output. The testing application also performs the write (encoding) of the same decoded certificate to the temporary buffer to make sure the write operation is also successful.

Compiling the application with instrumentation may look like this:

$> CC=afl-gcc CXX=afl-g++ cmake .. -DCC_X509_BUILD_APPS=ON -DCMAKE_INSTALL_PREFIX=./install \
    -DCMAKE_BUILD_TYPE=Debug \
    -DCMAKE_PREFIX_PATH=/path/to/comms/install\;/path/to/commsdsl/install\;/path/to/asn1/install
$> cmake --build . --config Debug

Debug build is recommended to enable assertions.

When the instrumented cc_x509_input_test binary is compiled, use AFL testing instructions to perform the fuzz testing. Put one or more certificate files into the input directory to help with the testing.

In case fuzz testing reports any crash, it means a bug in either COMMS Library or the generated code was discovered. Please submit an issue with the crash file attached. Any hang reports can safely be ignored. It means insufficient input data was provided to the standard input to decode the certificate.

See also Testing Generated Protocol Code for more details.