Add support for Estimated Issuance Time - unsigned

[bedinotti]

API for Issuance Estimates

Issuer Support

If an issuer supports Estimates, they will have 2 additional properties on their identity json:

"issuingEstimateURL": "http://example.com/api/estimate",
"issuingEstimateAuth": "signed"

Issuing Estimate URL Protocol - signed

If the value of issuingEstimateAuth is signed, then it will follow a similar pattern to the one below, except the request will be signed with the private key associated with public key you want the estimate about.

We won't be implementing this for this milestone, but we're reserving it and making it the default since it truly limits request estimates to those who have the private key they want the estimate about.

Issuing Estimate URL Protocol - unsigned

If the value of issueingEstiamteAuth is unsigned, then things are a bit simpler:

To get an estimate with this URL, simply send a GET request with the public key of the recipient to the issuingEstimateURL specified by the issuer.

GET http://example.com/api/estimate?key=1LnDcFKAKnypCeFD1CEtMn8UPawLJb6qcd 

If the recipient identified by that public key doesn't have any scheduled issuances associated with them, or if the issuer doesn't know who this key refers to, they should respond with an empty array.

200 OK
[]

It's important that this be returned for users that the issuer doesn't recognize to avoid information disclosure about who may be associated with this issuer. More on that in the privacy section below.

However, if they are scheduled to recieve one or more certificates, then those are returned as JSON objects in the array:

200 OK
[
    {
    	"title": "Diploma",
    	"willIssueOn": "2017-03-10T18:17:48.102+00:00"
    }
]

Mobile Wallet Messaging

After a successful introduction, the mobile wallet apps will automatically ask for an estimate from the issuer, if the issuer supports this functionality. It will also ask for an estimate when the previous estimate passes.

If there is no estimate provided by the API, the app will say

{Issuer Name} will send you your Blockcert soon.

If it does provide an estimate with a willIssueOn datetime, the app will say

You should see your {title} certificate from {Issuer Name} around {March 10th, 2017}.

Note that while the API may be more specific with its estimate, the apps will only give the specificity of the day.

Security & Privacy concerns

There's no login or auth mechanism behind this API, so anybody could query it to learn if a specific person is scheduled to recieve a certificate. This would also reveal the title of the certificate, which could be damaging if the title is for an embarrassing achievement. Like graduating from Clown College.

However, using the public key exchanged with the issuer rather than some other piece of public information (like email) makes this harder to accomplish. Since a unique address is shared with each issuer, an attacker would have to snoop on that initial introduction or hack the issuer directly to obtain it. And if that later case happens, then they can already do more damage than learn about your attendance Clown College.

The signed auth method, which is the default, limits it further. If a public key is used with multiple issuers, then it may be reasonable to assume someone knows your public key. However, forcing these requests to come in signed with the associated private key means only the holder of the private key can request estimates for themselves.

Also, making sure the response for a recipient that doesn't exist looks identical to a recipient that exists but has no scheduled issuances is critical. It prevents an attacker from brute forcing the public keys of all recipients. It prevents them from using a list of known public keys to figure out which recipients are associated with this issuer.

Extensibility to Other Chains

The focus right now is on the bitcoin blockchain, along with all the other tools in our arsenal. Fortunately, this API can be extended in a number of ways when we come across this problem:

• The keys are just strings, so they can be whatever is needed to identify a specific user on any chain
• Additional parameters can be added if we need to clarify which chain the key is intended on, you know, if we get to multi-chain issuers.