[Example Service Home]  [Simple]  [Sync Detailed]  [Async Detailed]  [Signature Tools]  [Client Side]

Signatures

Signatures are sometimes needed with the synchronous protocol. This is necessary if your template has variables that could be replaced by malicious values by a bad actor in a phising attack, or if you are using redirects without a syncRedirectDomain in the template DNS Providers.

If your template is mostly static and you aren't doing redirects, or if your template is mostly static and you are doing redirects but you specify a syncRedirectDomain in your template then you don't need to sign your requests.

The signature is generated from the properly URL Encoded query string. The Service Provider would generate a signature using a private key, appending the signature as sig= onto the query string when calling the DNS Provider.

The DNS Provider will verify the signature by fetching the public key from DNS. This is fetched as a series of TXT records from the dmain specified in syncPubKeyDomain in the template. The host name for these records is added onto the query string as key=.

The format of the public key in DNS can be found in the spec at: https://github.com/Domain-Connect/spec/blob/master/Domain%20Connect%20Spec%20Draft.adoc#digitally-sign-requests

Generating they Key Pair

To generate a key pair run the following commands:

openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048

openssl rsa -pubout -in private_key.pem -out public_key.pem

You use the private key to generate your signature, and you publish the public key in DNS for the DNS Provider to verify your signature.

Generating the Signature

This form will generate a signature. It allows a Service Provider to verify their code is generating the signature correctly.

Warning: This form does take the private key as a parameter. Normally your private key would be kept secret and not shared. As such it is not recommended that you use your production private key in this form.

The private key should be all the characters between the -----BEGIN/END----- block. If the private key is not provided, the private key for the example service will be used.


Query String:
Private Key:
 

Verifying the Signature from a Public Key

This form can test signature verification. You provide your query string, signature, and the public key. The public key should be all the characters between the -----BEGIN/END----- block.


Sig:
Query String:
Public Key:
 

Verifying the Signature from a Public Key in DNS

This form can test signature verification. You provide your query string and signature. Instead of providing the public key, you provide the Host (normally passed as key=<value> on the query string) and the Domain (normally the syncPubKeyDomain in the template).

Sig:
Query String:
Host (key=):
Domain (syncPubKeyDomain):
 

Verifying the Signature from the URL sent to the DNS Provider

This form isn't that different than the previous. Except here you provide the URL are sending the DNS Provider and the Domain (normally the syncPubKeyDomain in the template). The code will grab the components out of the URL and verify the signature.

URL:
Domain (syncPubKeyDomain):
 

Publishing the Public Key in DNS

This form will generate the DNS Records for publishing a public key. Paste the contents of the public key below. This is the base 64 content (not the -----BEGIN PUBLIC KEY----- or ----END PUBLIC KEY-----).

Fetching the Public Key from DNS

This form will allow you to test fetching your public key from DNS. You provide the Host (normally the key=<value> from the query string) and the Domain (normally syncPubKeyDomain from the template).

Host (key=):
Domain (syncPubKeyDomain):