Document how to convert an OpenSSL-based program to use mozilla::pkix

[briansmith]

The initial work on the documentation the conversion process is here:
https://github.com/briansmith/mozillapkix-openssl-tutorial/commits/master

git remote add gtest https://github.com/briansmith/googletest.git
git remote add pkix https://github.com/briansmith/mozillapkix.git
git remote add nostdlib https://github.com/briansmith/nostdlib.git

The weird-looking commits that added the gtest/, nostdlib/, and pkix/ subdirectories were made using:

git subtree add --squash --prefix=gtest gtest master
git subtree add --squash --prefix=pkix pkix features/openssl
git subtree add --squash --prefix=nostdlib nostdlib master

The current state of things is such that I can build and run the mozilla::pkix test suite using the OpenSSL adapter with make && make check in the mozillapkix-openssl-tutorial repo. However, I haven't pushed the commits that actually modify the example "https" program to use mozilla::pkix, and the written documentation isn't ready yet.

[colmmacc]

Just on this; I presume pkix does not use OpenSSL internally? I'm looking at how feasible it would be to integrate mozilla::pkix into s2n (https://github.com/awslabs/s2n). We also link against OpenSSL and I'm just wondering if I should be prepared for namespace issues.

Also, just very a small note: looks like the .md files are marked as binary type, so they aren't readable directly in the github web view.

[briansmith]

mozilla::pkix does not include the code for any crypto library internally. So, there will be no namespace issues.

If you look at how I used git subtree above, you can extend that to work with openssl:

git remote add https://github.com/openssl/openssl
git subtree add --squash --prefix=openssl openssl master

Similarly, you can do the same with s2n:

git remote add s2n https://github.com/awslabs/s2n
git subtree add --squash --prefix=s2n s2n master

All together, this would give your project this subdirectory structure:

gtest/ (contains GTest)
nostdlib/ (contains nostdlib)
openssl/ (contains OpenSSL)
pkix/ (contains mozilla::pkix)
s2n/ (contains s2n)

This is how I organize my projects, and this seems to be similar to how s2n is intended to be used, from my reading of its documentation.

If you look at https://github.com/briansmith/mozillapkix-openssl-tutorial/commits/master, the changes are broken up into multiple commits. The first commit is the OpenSSL-based project without mozilla::pkix. A later commit imports mozilla::pkix into the repo. The one thing that may be strange with that example is that it assumes that OpenSSL is already available, e.g. you have installed the libssl-dev or similar package on Linux. Maybe that hidden dependency may make it seem like mozilla::pkix already includes a crypto library.

Anyway, I would be very interested in seeing s2n use mozilla::pkix. I had thought it wasn't a possibility, since mozilla::pkix is in C++11, and somebody from AWS had said that s2n needs to work on platforms without a C++ compiler. (Note that, while mozilla::pkix is written in C++, it doesn't use the C++ runtime library and can be linked without libstdc++/libc++. However, its test suite currently does use the C++ runtime library.)