Domain Key Identified Federation (DKIF)

[Cajga]

Simple Summary

We are working on a project (to submit it to SBC) which extends the current stellar federation standard/workflow in order to improve security and enable hosted federation without the need to trust the federation provider.
The extension is based on a simplified version of the well known and used standard DKIM (DomainKeys Identified Mail). It introduces signing of federation records and signature validation by the client. The solution is backwards compatible with the current workflow. Older clients can simply ignore the signature and newer clients which implement the new validation workflow can show a sign to the sender to verify that DKIF was used to resolve the federation address.

On Lumenbox site we have a simple explanation page about the extension here
In this issue you will find the detailed explanation.

Abstract/Motivation/Specification

Current federation workflow

Currently, in order to resolve a federation address, the client needs to do the following:

1. fetch the stellar.toml file from https://<domain>/.well-known/stellar.toml and read the FEDERATION_SERVER entry from it
2. fetch the response from the federation server using secure HTTP GET and required parameters
3. proceed with the payment

Although it is mandatory to use HTTPS for both requests, both the web server and the federation server are possible targets for hackers. These servers are directly exposed to the internet and if a hacker manages to compromise either of them they could redirect the payments.
In case an attacker compromised the web server hosting the example.com site, they could rewrite the stellar.toml file pointing the FREDERATION_SERVER entry to their own host, serving wrong records and receiving all the payments. Compromising the federation server would allow the attacker to replace the public keys in each response, receiving all the payments.
Also, the current solution forces people to run federation servers unless they totally trust a federation provider. These providers could change the records they return in te respone, receiving the payments instead of the original destination.

Proposal: signing and validating the federation records

We would like to introduce the signing of the federation records using the workflow below. These signatures can be inspected and validated by the clients (“wallets” who are sending money to a destination address) before sending payments.

Preparation

We generate a domain signing key pair using Ed25519 (same algorithm that is used for other components ) for each domain. We keep the public key in a TXT record (same method as DKIM) in the DNS of the domain which looks like the following: federation._stellardomainkey IN TXT “<publickey>”.
The format of the public key matches exactly the format of a Stellar address, and the existing tools for creating a signing pair can be used.
We pre-sign the federation records (offline) and include the signatures into the DB together with the other entries. We will have one signature per federation entry which contains all the federation records (stellar_address, account_id, memo_type, memo).
We configure the federation server to include a signature entry into the JSON response which looks like the following: “signature”:<base64 encoded federation response XDR signature>”

Workflow with the new clients

New clients that support DKIF would take the following steps to resolve a federation address and validate it’s signature:

1. fetch the stellar.toml file from https://<domain>/.well-known/stellar.toml and read the FEDERATION_SERVER entry from it
2. fetch the response from the federation server using HTTP GET and required parameters
3. try to fetch the public key from the federation._stellardomainkey.<domain> TXT record of the domain
4. If both of the public key and the signature from the federation response were missing then client proceeds with the payment without DKIF validation as it currently does
5. If only one of them was missing (public key or the signature in the federation response), it blocks the payment and warns the sender
6. If both public key and signature were found, but federation entries cannot be validated using the signature and the public key, it blocks the payment and warns the sender
7. If federation entries could be validated using the signature and the public key it proceeds with payment (and notes the sender that the resolution was using DKIF)

Benefits

When a federation service is using DKIF, taking over the web server which hosts the stellar.toml file and/or the federation server itself would not allow the attackers to redirect the payment. In order to do that, they would need to alter in addition the DNS response on the client side as well.
This allows (and requires) that the open federation providers sign the records offline and upload it to the federation database together with the records.
It also allows the introduction of federation hosting for people or organisations who have their own domains but do not want or cannot run their own federation server. These people can include their public key into their own DNS, sign the records with their private key, upload them together with the signatures to a federation hosting provider and point the FEDERATION_SERVER entry to the provider. With this solution there is no need to trust the federation provider as it would not be able to temper with the presigned records or signature.

Backwards Compatibility

This workflow is compatible with existing clients and federation servers which do not implement signing/validation. Older federation servers would not return a signature field and older clients would just ignore the signatures (we assume that clients ignore additional fields in the JSON response from federation servers).

Implementation

Sadly, till now, we overlooked this possibility to create a SEP/discussion about a SEP. We've announced our porject about an open and hosted federation site for the SBC about a month ago waiting for feedback (https://galactictalk.org/d/789-domainkeys-identified-federation-dkif) but now we know that was not the right place.
We've created the PR for the official federation server with tests and a PR for the official stellar JS Base.

The workflow has been implemented in our Open & Hosted federation service Lumenbox

[zulucrypto]

@Cajga - One thing I'm confused about:

We configure the federation server to include a signature entry into the JSON response which looks like the following (see DKIM for more info about fields): “signature”:”h=stellar_address:account_id:memo_type:memo;b=”

Can you clarify what exactly is being signed? Is it the value of the FEDERATION_SERVER in the toml file?

I'm also wondering if this technique could be used to sign the sha256 of the entire stellar.toml file since that would also allow you to detect malicious changes to the other fields in the file.

[Cajga]

Hi @zulucrypto,

The federation records in the responses are the ones which get signed and the signature is attached to the response itself.
Signing the "FEDERATION_SERVER entry in the toml file" or the toml file itself would not increase the security from the federation point of view. Signing and validating the federation records in the response is demonstrating the authenticity of those records. So, even if attackers can alter the federation server response (tempering with the FEDERATION_SERVER entry and/or taking over the federation server itself), they will not be able have a valid signature in their altered response and as such, the client would reject the payment.

Using the examples from the federation developer site let us show how a signed federation response looks like which is using DKIF:
For the following federation request: https://YOUR_FEDERATION_SERVER/federation?q=jed*stellar.org&type=name we would have the following JSON in the response body:

{
  "stellar_address": "jed*stellar.org",
  "account_id": "GD6WU64OEP5C4LRBH6NK3MHYIA2ADN6K6II6EXPNVUR3ERBXT4AN4ACD",
  "memo_type": "text",
  "memo": "this is the memo for Jed",
  "signature": "base64(sign(xdr(values of the fields)))"
}

The client then would behave the way how we explain in the Workflow with the new clients section.

Please let us know in case something is still foggy.

[zulucrypto]

Thanks @Cajga , that was helpful!

I'm not very familiar with the Go codebase, but I looked through your PR and didn't see where the signature is calculated. I was wondering if implementing this would require storing the signing key on the federation server since you need to sign fields that may change frequently (specifically a memo)?

[Cajga]

@zulucrypto,

The signing should not be done on the federation server. Otherwise, if that got compromised they would be able to sign the altered federation records with the secret key.
The signing is done offline (could still be automated but on a server which is not directly exposed to the internet).
As such, the federation server does not do anything more than just provide the signatures from the database together with the normal records.

[zulucrypto]

@Cajga - That sounds good. If I was implementing a "privacy" federation service that automatically rotated the account and/or memo I could still generate the signatures on a secure machine and send them to the federation server's database.

Thanks for the explanations!

[Cajga]

@zulucrypto,

You're welcome. We've received many positive comments (on galactictalk) for the solution from non stellar developers. Unfortunately, we did not receive any feedback from SDF yet. Let see if they will like it or not. :)

[Cajga]

After we got more familiar with the Stellar XDR definitions, we realized that listing the fields which will be signed is unnecessary.
So, we updated the signature JSON field in the issue and the comments.

[Cajga]

We went live with our service which is using DKIF: https://lumenbox.org

[johansten]

How is this not an approved SEP yet?

[Cajga]

Hi Dzham (@johansten) ,

Well, it looks it got attention thanks to the build challenge as it was one of the "finalist" project. We have Pull Requests as well to the official federation server and to the JS library (that may require some cleanup as we didn't want to spend too much time on the project without any official feedback) but no answer on those either. Well let see.

In case you decide to implement the verification into Stargazer we would be more than happy to advertise that on the site.

[johansten]

I'm just trying to point out how flawed the SEP process is.

I'd be happy to integrate.

[fnando]

This is a nice proposal to increase federation security. It's a bummer that no one from Stellar have gave any feedback at all. :/

[theaeolianmachine]

Hi @Cajga,

My sincerest apologies for the lack of a response on this front — it's taken some time for us to determine a process that actually creates better accountability towards moving SEPs and CAPs forward.

I'm happy to merge this in a draft if you could take a look at the redefined process that's been outlined in ecosystem/README.md and submit a PR with this as a draft. In the future, we will not be using issues as a means of where drafts are stored. When you're doing that, can you please reshape this file to be in the format of sep-template.md?

Best,

Johnny

[leighmcculloch]

Hi @Cajga, I'm particularly interested in ideas that would make the data that federation services expose verifiable. As @theaeolianmachine mentioned here #80 (comment) if you could move the proposal into the format in a PR we could merge it as a draft proposal.

In terms of the proposal itself, I'm particularly interested in this statement:

We pre-sign the federation records (offline) and include the signatures into the DB together with the other entries.

How does the pre-signing offline process work? A wallet that is providing federation needs a users account to be instantly available via federation so they can start receiving payments immediately after signup. The federation server will need to have a record for the user and be signed automatically. If the key is online and available to the federation server to get that signature then if the server is compromised the key is compromised and impersonating signatures could be created which I assume is why you propose the key be offline.

If the key is offline how do new users of a wallet or federation service have their records available automatically/immediately?

Thanks!

[leighmcculloch]

As there hasn't been a draft submitted and 1 year has passed since the last comment I am closing the issue. Please reopen the issue if anyone wishes to pursue this.