Skip to content

doc: add security documentation #24

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Oct 2, 2025
Merged

doc: add security documentation #24

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5226d95
doc: add security documentation
zhijie-yang Sep 30, 2025
32c43c2
doc: use footnotes
zhijie-yang Sep 30, 2025
44bd5b8
chore: add word to list
zhijie-yang Sep 30, 2025
1d76953
chore: fix spelling
zhijie-yang Sep 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions docs/.sphinx/.wordlist.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,19 +7,27 @@ APIs
balancer
Charmhub
CLI
crypto
cryptographic
DCO
Diátaxis
Dqlite
dropdown
EBS
EKS
Etag
enablement
favicon
Furo
Git
GitHub
github
golang
GPG
Grafana
gz
IAM
InRelease
installable
JSON
Juju
Expand All @@ -44,12 +52,14 @@ Numbat
observability
OEM
OLM
openpgp
Permalink
PR
pre
PRs
Quickstart
ReadMe
RSA
reST
reStructuredText
roadmap
Expand All @@ -64,3 +74,4 @@ UUID
VM
webhook
YAML
YAMLs
1 change: 1 addition & 0 deletions docs/reference/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,5 @@
cmd/index
chisel-releases/index
Manifest <manifest>
Security Documentation <security>
```
83 changes: 83 additions & 0 deletions docs/reference/security.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
(chisel_security_ref)=

# Chisel Cryptographic Documentation

Chisel downloads Debian packages from
[archive.ubuntu.com](https://archive.ubuntu.com/), and extracts only selected
few files from each package. The slice definition files in
[chisel-releases](https://github.com/canonical/chisel-releases) specify the
files to extract.

Chisel is written in Go.

## Detailed Process

1. Chisel downloads and parses the YAMLs from
[chisel-releases](https://github.com/canonical/chisel-releases) repo[^1]. The
Go package [net/http](https://pkg.go.dev/net/http) is used and a tarball is
downloaded over HTTPS. Checksum of the tarball is not checked after downloading.

Chisel maintains a cache of these files[^2]. When making new requests to
download a release, Chisel reads the Etag from cache and checks whether the
cache is still valid. If it is valid, the cached release YAMLs are used.

1. Chisel downloads a few *InRelease* files from the [Ubuntu Archive
but](http://archive.ubuntu.com) these files are never cached. The InRelease
files are signed by GPG, and Chisel verifies[^3] the integrity using the [Ubuntu
Archive Automatic Signing
Key](https://keyserver.ubuntu.com/pks/lookup?search=f6ecb3762474eda9d21b7022871920d1991bc93c&fingerprint=on&op=index).[^4]
The key is specified in the [chisel.yaml in
chisel-releases](https://github.com/canonical/chisel-releases/blob/a442b2e7208128df6366f859b7a858c0d3fce925/chisel.yaml#L47).
The Go package [golang.org/x/crypto/openpgp](http://golang.org/x/crypto/openpgp)
is used for these purposes.

1. After parsing the *InRelease* files, Chisel downloads *Packages.gz* and
subsequently *Packages* from the archive. Downloads are performed over HTTP and
later the digests are cross-checked[^5]. The Go package
[hash](https://pkg.go.dev/hash) is used. Chisel maintains a cache of these
downloaded files. Each file is stored in the cache with their digest as the
filename.

1. The specified files in the slice definition files are extracted from the
downloaded Debian packages.

## (Relevant) Packages used by Chisel

Following lists the relevant packages used by Chisel to support its
cryptographic needs:

* [golang.org/x/crypto/openpgp](http://golang.org/x/crypto/openpgp) (Go package)

Additionally these Go standard library packages are used:

* [net/http](https://pkg.go.dev/net/http)
* [hash](https://pkg.go.dev/hash)

## Cryptographic technology being exposed to the user

Chisel needs a GPG public key specified in the [chisel.yaml in
chisel-releases](https://github.com/canonical/chisel-releases/blob/a442b2e7208128df6366f859b7a858c0d3fce925/chisel.yaml#L47)
to verify the signed InRelease files it downloads from the Ubuntu Archive. This
file (chisel.yaml) is exposed to the user and Users can very much specify a
different key on their forks.

The default public key in the official repository is the RSA/4096-bit [Ubuntu
Archive Automatic Signing Key
(2018)](https://keyserver.ubuntu.com/pks/lookup?search=f6ecb3762474eda9d21b7022871920d1991bc93c&fingerprint=on&op=index)
with ID 871920D1991BC93C.

```
pub (4)rsa4096/f6ecb3762474eda9d21b7022871920d1991bc93c 2018-09-17T15:01:46Z
uid Ubuntu Archive Automatic Signing Key (2018) <ftpmaster@ubuntu.com>
```


[^1]: [https://github.com/canonical/chisel/blob/v1.2.0/internal/setup/fetch.go#L32](https://github.com/canonical/chisel/blob/v1.2.0/internal/setup/fetch.go#L32)

[^2]: [https://github.com/canonical/chisel/blob/v1.2.0/internal/cache/cache.go](https://github.com/canonical/chisel/blob/v1.2.0/internal/cache/cache.go)

[^3]: The chain of trust here is that we fully trust GitHub so when we download the chisel-release from it we are also "downloading" the public keys. So, because the public keys are trusted, the downloads from the Ubuntu archives can also be trusted.

[^4]: [https://github.com/canonical/chisel/blob/v1.2.0/internal/archive/archive.go#L285](https://github.com/canonical/chisel/blob/v1.2.0/internal/archive/archive.go#L285)

[^5]: [https://github.com/canonical/chisel/blob/v1.2.0/internal/cache/cache.go#L72-L78](https://github.com/canonical/chisel/blob/v1.2.0/internal/cache/cache.go#L72-L78)
Loading