From 0b5c2d366a04a0f145ec4ac8f2ce1db59585cf56 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lukas=20M=C3=A4rdian?= Date: Wed, 11 Sep 2024 14:25:18 +0200 Subject: [PATCH] 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 | 15 +++++++++++ doc/netplan-yaml.md | 3 +++ doc/security.md | 51 ++++++++++++++++++++++++++++++++++++++ tools/grep_cryptography.sh | 25 +++++++++++++++++++ 4 files changed, 94 insertions(+) create mode 100755 tools/grep_cryptography.sh diff --git a/doc/.custom_wordlist.txt b/doc/.custom_wordlist.txt index 4af1c0fcb..1ec8f3fdc 100644 --- a/doc/.custom_wordlist.txt +++ b/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 diff --git a/doc/netplan-yaml.md b/doc/netplan-yaml.md index 4f86b6e08..998b06c05 100644 --- a/doc/netplan-yaml.md +++ b/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. diff --git a/doc/security.md b/doc/security.md index 5c323a03a..54aa4d300 100644 --- a/doc/security.md +++ b/doc/security.md @@ -36,6 +36,57 @@ will become world-readable. * `/run/systemd/system/netplan-wpa-*.service` * `/run/systemd/system/systemd-networkd-wait-online.service.d/10-netplan*.conf` +## 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` for wired and wireless authentication and authorization, +[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. +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, diff --git a/tools/grep_cryptography.sh b/tools/grep_cryptography.sh new file mode 100755 index 000000000..cb99a7a3b --- /dev/null +++ b/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