DomainConnect.Signing (DomainConnect v0.5.0)

Copy Markdown View Source

RSA request signing for Domain Connect signed templates.

A signed template requires the apply request to carry a sig (RSA-SHA256 signature, PKCS#1 v1.5, Base64) over the query string, plus a key naming the TXT record where the matching public key is published. The DNS provider verifies the signature before applying records.

The signature is computed over the canonical query: each name and value RFC3986-encoded, parameters sorted by encoded name, joined with &. That canonical string is what gets sent (with sig/key appended), so it verifies whether the provider checks the bytes as-received or re-canonicalizes them.

Pass :private_key (an unencrypted RSA private-key PEM) and :key_id (a single DNS label) to DomainConnect.apply_url/2 or DomainConnect.async_apply/3 to sign.

Summary

Functions

build_query(query_kw, opts)

Builds the final apply query string from query_kw, signing it when opts carries both :private_key and :key_id.

sign(message, private_key_pem, key_id)

Signs message with the RSA private key in private_key_pem (RSA-SHA256) and returns the sig/key params. message should already be the canonical query string. Returns a tagged error for a bad key_id, a non-RSA/encrypted/unusable key, or a signing failure.

Functions

build_query(query_kw, opts)

@spec build_query(keyword(), keyword()) :: {:ok, String.t()} | {:error, term()}

Builds the final apply query string from query_kw, signing it when opts carries both :private_key and :key_id.

Unsigned: a normal URI.encode_query/1. Signed: the canonical query plus &sig=…&key=…. Returns {:error, {:invalid, :signing}} for half configuration, or a key/signing error.

sign(message, private_key_pem, key_id)

@spec sign(String.t(), String.t(), String.t()) ::
  {:ok, %{sig: String.t(), key: String.t()}} | {:error, term()}

Signs message with the RSA private key in private_key_pem (RSA-SHA256) and returns the sig/key params. message should already be the canonical query string. Returns a tagged error for a bad key_id, a non-RSA/encrypted/unusable key, or a signing failure.