A x509 DER digital certificates wrapper library and comman line application.

• Building
  • Building in a Docker Container
  • Building locally with xmake
  • Building locally with make or cmake
• Installing
  • Pre built docker container
  • xmake or make
• Running
  • In the provided container
  • Locally
• Usage example
• Tests and Benchmarks
• CI/CD
• Documentation
• Error handling
• Design Patterns, idioms and general considerations

This project have four targets:

• libcipher.a: A static library that contains all the logic. Depends on libssl3.
• ciphervault: A binary command line application that uses libcipher to manage x509 DER certs.
• ciphervault_test: Unit tests. Depends on libcipher and gtest.
• ciphervault_bench: Execution benchmarks. Depends on libcipher and benchmark.

Build of separate targets is supported if one do not want to download a specific dependency, e.g. gtest.

The supported build tools are as follows:

This is the recomended build engine, as it uses the pre-made C++ environment cppdev. First, you have to download the container:

docker pull tomcat0x42/cppdev

For installing it:

docker pull tomcat0x42/cppdev

Finally, just run the build script:

./scripts/build

After the build is complete, the resulting targets will be available in the folder ./ciphervault.

Using the excelent tool xmake, you can download all the build dependencies and build the project:

xrepo install -y fmt cxxopts gtest benchmark tabulate
xmake build -y

The resulting files will be at ./ciphervault

If you choose the old way, you must download all the dependencies listed abobe using you favorite package manager. After that you can build:

make
# or
mkdir -p build && cd build && cmake .. && make

The resulting files will be at ./ciphervault

After the build is complete, you should install the project. There are multiple ways of doing so:

A pre built container with all the targets and dependencies is available. For downloading it:

docker pull tomcat0x42/ciphervault

After the build, all targets will be at ./ciphervault and the default installation path is /usr/local/{bin,lib}. So, for installing the targets choose one method:

make install
#or
xmake install

Just run the following command. The container will be downloaded if not found. Note the assets/.../...der file, here you can pass any x509 DER cert, but before you must map the file or dir containing it as a docker volume(-v)

docker run -v ${PWD}/assets:/ciphervault/assets -it tomcat0x42/ciphervault assets/cert/dsa/1024b-dsa-example-cert.der --table

If you followed the instalation section, all the targets should be at your path. So just run it normally:

ciphervault

You can also use xmake to run a specific target:

xmake run ciphervault
xmake run ciphervault_test
xmake run ciphervault_bench

$ ciphervault --help

ciphervault --  A x509 DER digital certificates wrapper library and comman line application.
Usage:
  ciphervault [OPTION...] positional parameters

  -c, --contents   Print the contents of the certificate.
  -i, --issuer     Print the issuer of the certificate.
  -s, --subject    Print the subject of the certificate.
  -b, --notbefore  Print the not before date of the certificate.
  -a, --notafter   Print the not after date of the certificate.
  -g, --sigalg     Print the signature algorithm of the certificate.
  -t, --table      Print the certificate in a table.
  -h, --help       Print this help message.

You can print all the cert content, separated fields or a table with some field. e.g.:

$ciphervault assets/cert/dsa/1024b-dsa-example-cert.der --table

+------------+-----------------------------------------------------------------------------------------------------------------+
|   Issuer   | C=JP, ST=Tokyo, L=Chuo-ku, O=Frank4DD, OU=WebCert Support, CN=Frank4DD Web CA/[email protected] |
+------------+-----------------------------------------------------------------------------------------------------------------+
|   Subject  |                                  C=JP, ST=Tokyo, O=Frank4DD, CN=www.example.com                                 |
+------------+-----------------------------------------------------------------------------------------------------------------+
| Not Before |                                             Aug 22 07:27:02 2012 GMT                                            |
+------------+-----------------------------------------------------------------------------------------------------------------+
|  Not After |                                             Aug 21 07:27:02 2017 GMT                                            |
+------------+-----------------------------------------------------------------------------------------------------------------+

This project have a ciphervault_test and ciphervault_bench targets, for respectively unittesting and micro-benchmarking. Whilst you can run those alone, they are more useful In the CI/CD pipeline.

The file .github/workflows/cicd.yml describe a cascading CI/CD pipeline using Github Actions as follows:

• The project is built in a container.
• The targets are copied to the host.
• Unit tests are executed.
• A docker image is published
• A github release is published.

Note that if one step fails, the others are not executed.

This project uses Doxygen for documenting classes and funtions. A html and latex version is available inside ./doc/.

One can also generate the docs using the doxygen command in the project root.

I mainly use C++ exceptions to handle errors, using the rule that libraries should not handle them, just raising, threfore containing all the error handling logic in the consumer targets.

This project makes extensive use of RAII for memory management. The basic idea of RAII is to allocate all resources that one object needs in its initialization and free them when the object is not needed anymore, e.g. when it goes out of scope. In C++ we can achieve that unsing the object constructor and destructor coupled with the use of smart pointers. Also, I use some of the sane idioms of OOP.

Also, this project is divided in a shared library, containing all the main classes, functions and logics of the domain and in various consumer targets, like the command line application, unit tests and benchmarks. Using this pattern, I can make code more maintanable and extensive, e.g. if I want to add another target(like a GUI one), I just import the needed classes from the lib. I want to thanks the Rust programming language for teaching this useful pattern.