Skip to main content

URL Signing

URL Signing is a method of ensuring that a request cannot be tampered with. It is highly recommended to require signed URLs if exposing Konifer publicly to prevent denial-of-service attacks.

Currently, URL signing is only used when fetching assets. URL signatures cannot be used for storing, deleting, or updating an asset.

Supported Signing Algorithms​

3 HMAC signing algorithms are supported:

  • hmac_sha256 (default)
  • hmac_sha384
  • hmac_sha512

Configuration​

To enable URL signing, configure your secret and your algorithm in konifer.conf.

url-signing {
    enabled = true
    algorithm = hmac_sha512

    # Can also use URL_SIGNING_SECRET_KEY environment variable
    secret-key = secret
}

Usage​

To sign a request, the entire path, including query selectors and query parameters, must be included in the signature payload.

warning

Query parameters must be sorted alphabetically by parameter key in the signature payload.

Encode the HMAC digest as URL-safe Base64 with padding removed, then include it as an s query parameter. The s parameter itself is excluded from the signed payload.

GET /assets/users/123/profile?blur=20&format=webp&h=300&s=BASE64URL_HMAC_SIGNATURE

If URL signing is enabled, then all requests missing a signature returns a 403 Forbidden. Invalid signatures also return a 403 Forbidden.