From 04a44cdedcfca06e35042c0a75c67871834ec0f2 Mon Sep 17 00:00:00 2001
From: Simon Fels <simon.fels@canonical.com>
Date: Wed, 28 Aug 2024 16:57:15 +0200
Subject: [PATCH] feat: add cryptographic explanation for the Anbox runtime

---
 .custom_wordlist.txt                          |  3 ++
 .../cryptography/crypto_anbox_runtime.md      | 32 +++++++++++++++++++
 explanation/cryptography/landing.md           |  1 +
 3 files changed, 36 insertions(+)
 create mode 100644 explanation/cryptography/crypto_anbox_runtime.md

diff --git a/.custom_wordlist.txt b/.custom_wordlist.txt
index 7e84edd2..c9c1be32 100644
--- a/.custom_wordlist.txt
+++ b/.custom_wordlist.txt
@@ -28,6 +28,7 @@ APKs
 AppArmor
 Appium
 ARMv
+ASN
 async
 AttributeError
 AudioTrack
@@ -44,6 +45,7 @@ Bluetooth
 BombSquad
 bool
 boolean
+BoringSSL
 BPF
 bzip
 CDN
@@ -85,6 +87,7 @@ Dev
 devmode
 DNS
 dnsmasq
+DER
 Dqlite
 DrArm
 drawio
diff --git a/explanation/cryptography/crypto_anbox_runtime.md b/explanation/cryptography/crypto_anbox_runtime.md
new file mode 100644
index 00000000..925f0cfc
--- /dev/null
+++ b/explanation/cryptography/crypto_anbox_runtime.md
@@ -0,0 +1,32 @@
+(exp-security-crypto-anbox-runtime)=
+# Anbox runtime
+
+The Anbox runtime (see {ref}`howto-anbox-runtime`) is using cryptographic technology for:
+
+* TLS transport encryption
+* Token based authentication
+* WebRTC
+
+## TLS transport encryption
+
+All HTTP communication Anbox performs over IP connections to external services is using TLS for transport encryption.
+
+When communicating with the HTTPS API of the Anbox Stream Agent, Anbox will either rely on [system CA certificates](https://launchpad.net/ubuntu/+source/ca-certificates) or verify the certificate presented via TLS against a SHA-256 fingerprint of the certificate with which it has been configured. For the fingerprint validation, Anbox will retrieve the remote certificate and use the `X509_digest` method from [OpenSSL](https://launchpad.net/ubuntu/+source/openssl/) to calculate a SHA-256 hash. The hash is then compared against the expected hash. If they don't match, the connection to the Anbox Stream Gateway is cancelled by Anbox.
+
+## Token based authentication
+
+Anbox accesses a limited set of API endpoints of the Anbox Management Service (AMS) to submit status information during runtime. Access is authenticated by a scope-limited [JWT](https://jwt.io/) based token. See {ref}`exp-security-crypto-ams` for more details.
+
+As part of the WebRTC connection process, Anbox communicates with the HTTP API endpoints provided by the Anbox Stream Agent. Anbox authenticates itself to the agent by presenting a token (see {ref}`exp-security-crypto-stream-agent`) and validates the TLS certificate of the agent by checking its fingerprint. The fingerprint Anbox uses for the validation check is the SHA-256 hash of the complete ASN.1 DER content (certificate, signature algorithm and signature) of the TLS certificate that the agent uses.
+
+## WebRTC
+
+For streaming of audio, video and other data, the Anbox runtime uses WebRTC as provided by the upstream [WebRTC](https://webrtc.org) project from Google. Unlike the upstream default, the WebRTC build for the Anbox runtime utilises [OpenSSL](https://launchpad.net/ubuntu/+source/openssl/) instead of Google's [BoringSSL](https://boringssl.googlesource.com/boringssl) for any cryptographic use.
+
+The security model and cryptographic use of WebRTC is described in [RFC8827](https://www.rfc-editor.org/rfc/rfc8827) and use of WebRTC in the Anbox runtime does not deviate from this.
+
+## Packages used
+
+* [Go standard library](https://pkg.go.dev/std)
+* [OpenSSL](https://launchpad.net/ubuntu/+source/openssl/)
+* [`ca-certificates`](https://launchpad.net/ubuntu/+source/ca-certificates)
\ No newline at end of file
diff --git a/explanation/cryptography/landing.md b/explanation/cryptography/landing.md
index f77f1a6a..e2d43e9d 100644
--- a/explanation/cryptography/landing.md
+++ b/explanation/cryptography/landing.md
@@ -10,6 +10,7 @@ This information is currently available for the following components:
   :maxdepth: 1
 
 crypto_ams
+crypto_anbox_runtime
 crypto_stream_agent
 crypto_dashboard
 ```
\ No newline at end of file