diff --git a/explanation/cryptography/index.md b/explanation/cryptography/index.md new file mode 100644 index 0000000..8072d37 --- /dev/null +++ b/explanation/cryptography/index.md @@ -0,0 +1,16 @@ +(cryptography)= +# Cryptography + +This section describes the cryptographic algorithms used by the Charmed HPC project. + +- {ref}`munge` +- {ref}`jwt` + +```{toctree} +:titlesonly: +:maxdepth: 1 +:hidden: + +MUNGE +JSON Web Tokens +``` \ No newline at end of file diff --git a/explanation/cryptography/jwt.md b/explanation/cryptography/jwt.md new file mode 100644 index 0000000..e7012de --- /dev/null +++ b/explanation/cryptography/jwt.md @@ -0,0 +1,17 @@ +(jwt)= +# JSON Web Tokens (JWT) + +Some Slurm charms support [JSON Web Tokens](https://jwt.io/) as an alternative authentication method for a Slurm cluster. + +This service is used by the Slurm charms: + +- [`slurmctld`](https://charmhub.io/slurmctld) +- [`slurmrestd`](https://charmhub.io/slurmrestd) + +A shared private encryption key is required to verify the signature of client tokens. The current method uses RSA with a length of 2048 bits, which is generated using the [`cryptography`](https://pypi.org/project/cryptography/) package for Python. + +The [Slurm documentation](https://slurm.schedmd.com/jwt.html) contains more information about the topic. + +## Libraries used + +- [`cryptography`](https://pypi.org/project/cryptography/), from PyPi. \ No newline at end of file diff --git a/explanation/cryptography/munge.md b/explanation/cryptography/munge.md new file mode 100644 index 0000000..9911501 --- /dev/null +++ b/explanation/cryptography/munge.md @@ -0,0 +1,20 @@ +(munge)= +# MUNGE + +[MUNGE (MUNGE Uid 'N' Gid Emporium)](https://dun.github.io/munge/) is an authentication service for creating and validating credentials. + +This service is used by all our Slurm charms, including: + +- [`slurmctld`](https://charmhub.io/slurmctld) +- [`slurmd`](https://charmhub.io/slurmd) +- [`slurmdbd`](https://charmhub.io/slurmdbd) +- [`slurmrestd`](https://charmhub.io/slurmrestd) + +MUNGE requires sharing a cryptographically secure key between all the Slurm nodes in a cluster. To generate this key, the charms +use the [mungectl](https://github.com/charmed-hpc/mungectl) utility, which uses Go's [`crypto/rand`](https://pkg.go.dev/crypto/rand) library to generate a cryptographically secure key of 1024 bytes of length, using either [`getrandom(2)`](https://man7.org/linux/man-pages/man2/getrandom.2.html) if available, and [`/dev/urandom`](https://en.wikipedia.org/wiki//dev/random) otherwise. + +You can find more information about MUNGE on its [official wiki](https://github.com/dun/munge/wiki). + +## Packages used + +- [`crypto/rand`](https://pkg.go.dev/crypto/rand), from the [Go standard library](https://pkg.go.dev/std). \ No newline at end of file diff --git a/explanation/index.md b/explanation/index.md index 2d69eee..f8c3910 100644 --- a/explanation/index.md +++ b/explanation/index.md @@ -1,4 +1,14 @@ (explanation)= # Explanation +- {ref}`cryptography` + 🚧 Under construction 🚧 + +```{toctree} +:titlesonly: +:maxdepth: 1 +:hidden: + +cryptography/index +``` \ No newline at end of file