Expand description
This module provides server-side functionality to add to an API.
It is designed with flexibility and ease of use in mind. The primary
functionality is provided in the Core
struct, which can be used directly
from endpoint handlers or similar. In addition, an Axum
struct is also
provided, which contains ready-made handlers for use with the Axum
web framework. These handlers call the methods on the Core
struct, and
provide a convenient way to add the functionality to an existing Axum
application.
§Signing and verification
There is support for signing HTTP responses, to ensure that they have not been tampered with, and to allow connecting clients to verify authenticity. This is done using the server’s private key, and is designed to be used with responses that contain a fully-known body (i.e. not streams), as the complete body data needs to be used to generate the signature.
The key format used is Ed25519, which is a modern and secure algorithm, more
secure and performant than RSA. Technically it’s part of the family of
Edwards-curve Digital Signature Algorithm (EdDSA
), and uses Curve25519 as
its underlying elliptic curve. It is designed for high performance, offering
fast signature generation and verification, significantly quicker than
traditional RSA signatures. The keys and signatures are also small, which is
beneficial for storage and transmission. RSA keys typically need to be at
least 2048 bits (and increasingly 3072 or 4096 bits for long-term security),
whereas Ed25519 keys are only 256 bits, yet deliver higher security.
Given its advantages, Ed25519 is often recommended for new cryptographic applications where digital signatures are required. It’s particularly suited for scenarios where performance and security are critical, such as secure communications, authentication, and blockchain technologies.
The design of this library is such that the Core
functionality does not
implement signing, as it is not directly involved with creating HTTP
responses, but the Axum
handlers do. The approach chosen is to return
the signature as an X-Signature
header, rather than embedding it in the
response body payload. This is to keep the response body payload clean and
free from additional data, and to allow the signature to be verified
separately from the response body. The pattern used by this library is that
release file downloads are not signed, allowing them to be streamed if they
are large, with a SHA256 hash being available separately for verification.
The response containing the hash is signed, so the hash can be verified as
authentic.
Due to the short length of the Ed25519 keys and signatures, they are sent in hexadecimal string format, instead of using base64. This is to ensure maximum compatibility with all potential uses. Base64 would only offer a minor saving in comparison.
§Streaming
The behaviour implemented in the provided Axum
handlers is that large
release files will be streamed. For more information on how to configure the
various streaming parameters, see the Config
struct documentation.
Structs§
- Endpoint handlers for use with the Axum web framework.
- The configuration options for the server.
- The core functionality of the server.
Enums§
- Errors that can occur in relation to releases.