Initial commit

.gitignore

@@ -0,0 +1 @@
+*.html

README.md

@@ -0,0 +1,5 @@
+# TLS/SSL
+
+[Mbed TLS notes](mbedtls/)
+
+[OpenSSL notes](openssl/)

scripts/build.sh

@@ -0,0 +1,9 @@
+#!/bin/sh
+set -eu
+cd "$(dirname "$0")"/..
+set -x
+pandoc -o www/index.html README.md
+mkdir -p www/openssl
+pandoc -o www/openssl/index.html source/openssl.md
+mkdir -p www/mbedtls
+pandoc -o www/mbedtls/index.html source/mbedtls.md

scripts/upload.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+set -eu
+cd "$(dirname "$0")"/..
+set -x
+scripts/build.sh
+rsync -vcr --delete www/ alpha.servers.scheme.org:/production/groups/www/tls/

source/mbedtls.md

@@ -0,0 +1,17 @@
+# Mbed TLS notes
+
+Mbed TLS (previously PolarSSL) is an implementation of the TLS and SSL
+protocols.
+
+## MacOS
+
+Homebrew formula:
+
+```
+depends_on "ca-certificates"
+depends_on "mbedtls"
+```
+
+Bundle installed by the `ca-certificates` formula:
+
+`#{HOMEBREW_PREFIX}/share/ca-certificates/cacert.pem`

source/openssl.md

@@ -0,0 +1,64 @@
+# OpenSSL notes
+
+## Installation
+
+### OpenBSD (6.3)
+
+- The `pkg-config` command comes with the OS.
+- The OS comes with LibreSSL 2.7.2.
+- The `pkg-config --cflags --libs openssl` command works out of the
+  box and finds the system library.
+
+### NetBSD (7.1)
+
+- The `pkg-config` command needs to be installed separately with `sudo
+  pkg_add pkgconf` (or `sudo pkg_add pkg-config`).
+- The OS comes with OpenSSL 1.0.1u.
+- Even though the OS does not come with a pkg-config command, it does
+  ship with an openssl.pc file, so once you install pkg-config the
+  `pkg-config --cflags --libs openssl` finds the system library.
+- However, the native OpenSSL 1.0.1 is older than the version 1.0.2
+  required by the Chicken egg. Users need to `sudo pkg_add libressl`
+  or `sudo pkg_add openssl` from the OS package manager.
+- After doing that, `pkg-config --cflags --libs openssl` points to the
+  OpenSSL or LibreSSL version from the package manager, which
+  automatically overrides the native version for this purpose.
+
+### FreeBSD (12.0) and DragonFlyBSD (5.6)
+
+- The `pkg-config` command needs to be installed separately with `sudo
+  pkg install pkgconf`.
+- The OS comes with OpenSSL 1.1.1a-freebsd (FreeBSD) or LibreSSL 2.9.1
+  (DragonFly) but neither FreeBSD nor DragonFly ships with a
+  complementary openssl.pc file for pkg-config.
+- Therefore `pkg-config --cflags --libs openssl` still does not work.
+- Easiest fix: tell people to `sudo pkg install libressl` or `sudo pkg
+  install openssl`.
+- Then `pkg-config --cflags --libs openssl` finds that copy of
+  libressl or openssl.
+
+### MacOS (10.14 "Mojave")
+
+- The `pkg-config` command needs to be installed separately (Homebrew:
+  `brew install pkg-config`).
+- The OS comes with LibreSSL 2.6.5 but does not ship with an
+  openssl.pc file. Also, the <openssl/ssl.h> and other necessary C
+  header files may not be installed even though the shared library is.
+- Easiest fix: tell people to use Homebrew to install an
+  OpenSSL-compatible library: `brew install openssl` or `brew install
+  libressl`.
+- `pkg-config --cflags --libs openssl` does not work even when you
+  have installed the separate package from Homebrew, because Homebrew
+  packages don't put their `.pc` files where pkg-config can find them.
+- That can be remedied with:
+
+      export PKG_CONFIG_PATH="$(brew --prefix openssl)/lib/pkgconfig"
+      export PKG_CONFIG_PATH="$(brew --prefix libressl)/lib/pkgconfig"
+
+- Then `pkg-config --cflags --libs openssl` finds that copy of
+  libressl or openssl.
+
+IMPORTANT: In many of the above cases, the `openssl` shell command can
+represent a different version of OpenSSL/LibreSSL than the library and
+headers found by pkg-config. So `openssl` should not be invoked to
+gather any version information in build scripts.