doc: Add initial 'Cryptography' section

Also include some new tooling in tools/grep_cryptography.sh, to indentify
cryptography related terminiology in our codebase.

doc/.custom_wordlist.txt

@@ -1,19 +1,28 @@
 APN
 ARP
+artifacts
 CDMA
 CIDR
 CONFIG
 ConnectX
 Coverity
+cryptographic
 D-Bus
 DF
 DHCP
 DNS
 DUID
+DSA
+ECDH
+ECDSA
+EdDSA
 EAP
 Ethernet
 FDB
 Fi
+fuzzer
+GnuTLS
+GLib
 GRO
 GSM
 GSO
@@ -51,11 +60,16 @@ NTP
 Netplan
 NetworkManager
 OpenFlow
+OpenPGP
+OpenSSL
 OpenVPN
+OVS
+performant
 PCI
 PSK
 QEMU
 RDNSS
+RSA
 SIGINT
 SIGUSR
 SLAAC
@@ -132,5 +146,6 @@ unconfigured
 unencrypted
 untagged
 vSwitch
+wpa
 wpasupplicant
 yaml

doc/netplan-yaml.md

@@ -891,6 +891,7 @@ network:
     > Match this policy rule based on the type of service number applied to
     > the traffic.
 
+(yaml-auth)=
 ## Authentication
 
 Netplan supports advanced authentication settings for Ethernet and Wi-Fi
@@ -1058,6 +1059,7 @@ some additional properties that can be used for SR-IOV devices.
   >
   > **Requires feature: `infiniband`**
 
+(yaml-modems)=
 ## Properties for device type `modems`
 
 **Status**: Optional.
@@ -1625,6 +1627,7 @@ The specific settings for bonds are defined below.
     > `active-backup`, `balance-alb` and `balance-tlb` modes.
 
 
+(yaml-tunnels)=
 ## Properties for device type `tunnels`
 
 **Status**: Optional.

doc/security.md

@@ -19,6 +19,62 @@ Security advice: ensure all YAML files in `/etc/netplan`, `/run/netplan` and
 `/lib/netplan` are not readable by non-privileged users.
 :::
 
+## Cryptography
+
+Netplan does not directly utilise cryptography, but configures underlying tools
+to do so. Such tools include `wpa_supplicant`, `systemd-networkd`, `NetworkManager`
+or `Open vSwitch` and they can for example be configured to setup WPA2/WPA3
+[encypted WiFi](https://w1.fi/wpa_supplicant/devel/code_structure.html#crypto_func) 
+connections, `802.1x` encrypted Ethernet connections,
+[encrypted WireGuard](https://www.wireguard.com/protocol/) VPN tunnels or SSL
+secured OVS endpoints.
+
+### Cryptographic technology used by Netplan
+
+Netplan does not use cryptographic technology directly itself at runtime. It
+utilises hash based data-structures such as `GHashTable` from GLib or Python's
+built-in `hash()` method, but those are not security related, but used for
+performant data lookup.
+
+However, when testing the code base it makes use of the `node:crypto`
+[NodeJS module](https://nodejs.org/api/crypto.html) to generate random bytes for
+our YAML schema fuzzer. See `tests/config_fuzzer/index.js`.
+
+When shipping Netplan packages to the Debian/Ubuntu archive, OpenPGP keys are
+used to sign the artifacts. Those commonly utilise 4096 bit RSA cryptography,
+but [Launchpad](https://launchpad.net/people/+me/+editpgpkeys) also supports
+varying key lengths of RSA, DSA, ECDSA, ECDH and EdDSA.
+
+### Cryptographic technology exposed to the user
+
+Netplan allows to configure certain cryptographic technology that can be
+described in its {doc}`netplan-yaml`. Notable settings include the
+{ref}`yaml-auth` block, e.g. `auth.password` can be used configure `WPA-PSK` or
+`WPA-EAP` secrets, which can also be a special `hash:...` value for
+`wpa_supplicant`. The `auth.method` field controls the technology, such as
+`PSK`, `EAP`, `EAPSHA256`, `EAPSUITE_B_192`, `SAE` or `8021X`. The
+`ca-certificate`, `client-certificate`, `client-key`, `client-key-password` or
+`phase2-auth` can be used to control the CA certificates in an `EAP` context.
+
+For `openvswitch` configurations, the `ssl` setting can contain configuration
+for CA certificates and related private keys in `ssl.ca-cert`, `ssl.certificate`
+or `ssl.private-key`.
+
+{ref}`yaml-modems` include the `password` setting, which can be used to
+authenticate with the carrier network.
+
+{ref}`yaml-tunnels` can contain the `key` setting, describing `input`, `output`
+or `private` keys. The latter can be a 256 bit, base64 encoded WireGuard key.
+
+
+### Packages providing cryptographic functionality
+
+* WireGuard (Linux kernel) – `linux-image`
+* NetworkManager (GnuTLS) – `libgnutls30`
+* Open vSwitch (OpenSSL) – `libssl3`
+* systemd-networkd (OpenSSL) – `libssl3`
+* wpa_supplicant (OpenSSL) – `libssl3`
+
 ## Static analysis with Coverity
 
 To ensure that common issues do not sneak undetected in our code base,

tools/grep_cryptography.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+# Grep Netplan's codebase for cryptography related terms, in order to update
+# its "Cryptography" documentation in doc/security.md
+# BEWARE of --color=always when using "grep -v" to filter out stuff, as the
+# output will include control characters for the colors.
+
+GREP="grep \
+    --color='always' \
+    --exclude-dir=doc \
+    --exclude-dir=doc/.sphinx/venv \
+    --exclude-dir=debian \
+    --exclude-dir=abi-compat \
+    --exclude-dir=tests \
+    --exclude-dir=.git \
+    --exclude=grep_cryptography.sh \
+    -EHRin \
+    "
+
+eval "$GREP 'crypto'"
+eval "$GREP '[^_]hash[^_T]'"  # Ignore GHashTable, g_hash_table
+eval "$GREP 'pass' | grep -Evi 'through'"  # Ignore passthrough
+eval "$GREP 'private|public|secret|encr|cert' | grep -Evi 'license|netplan'"  # Ignore GPL/NETPLAN_PUBLIC
+eval "$GREP 'ssl|tls|sha[0-9]|[^a]md[0-9]'"  # Ignore amd64
+# XXX: this produces lots of noise...
+eval "$GREP '[^_]key' | grep -Evi 'mapping|value|scalar|yaml|file|char|g_free|clear_'"  # Ignore key-value/mapping-key/YAML_SCALAR_NODE/keyfile/key_file