Module patchify::server

source ·
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§

  • Axum
    Endpoint handlers for use with the Axum web framework.
  • Config
    The configuration options for the server.
  • Core
    The core functionality of the server.

Enums§