Issuer hosting requirements

Examples
1

Updated 12/7/2017 to use v2 Blockcerts schema

The quick start guide makes some content and service hosting simplifications that should be considered before issuing certificates. (More options will be possible in the future; read about Blockcerts longevity and availability)

An issuer should provide permanent URLs for certain content referenced in blockchain certificates. This enables:

  • Certificate verification: the hosted issuer identity information is needed during verification
  • Convenience for recipient: the recipient can share a URL pointing to their certificate

Failing to make content available at the expected URLs reduces the value of (and confidence in) an issuer’s certificates. The issuer is not required to host this data, but is responsible for ensuring its availability at the expected URL.

The default deployment in cert-viewer exposes these endpoints, but the issuer may decide to host these outside of the cert-viewer, depending on the issuer’s deployment requirements.

Hosting Issuer Identity

The issuer uses this endpoint to state their identity, including issuing public key used in verification. Open Badges requires that the certificate contain an issuer identification URL. The schema and content of the hosted information is specified by here.

Example certificate value

badge.issuer.id = "https://example.org/organization.json"

Example hosted content

{
  "id": "http://example.org/issuer/the-issuer.json",
  "url": "http://example.org/certificates/",
  "introductionURL": "http://example.org/intro/",
  "name": "Example issuer",
  "email": "issuer@example.org",
  "image": ""data:image/png;base64,..."
  "issuerKeys": [
    {
      "date": "2016-08-28",
      "key": "1Q3P94rdNyftFBEKiN1fxmt2HnQgSCB619"
    }
  ],
  "revocationKeys": [
    {
      "date": "2016-08-28",
      "key": "1PrmJ6pGbfe4ucNCVbe4tbXRRHMsDDSxvY"
    }
  ]
}

Hosting Issued Certificates

Privacy considerations

If the issuer and recipient agree that the certificate content is safe to share (it doesn’t contain confidential information), issuers should host the certificates they’ve issued as a convenience to their recipients. Issuers should also provide the recipient with their complete JSON-formatted Blockchain Certificate (or recommend they download it) so that recipients have access to their certificates even if the issuer’s site is down. Issuers are encouraged to protect the recipient’s email by hashing it.

The cert-viewer project provides an endpoint to display the certificate in preview form, and the raw JSON format.

The certificate itself contains a URL pointing to the hosting location for the certificate. If hosting the certificates, the issuer set this value to a permanent URL where they will host the certificate.

Example certificate value

badge.issuer.id = https://example.org/609c2989-275f-4f4c-ab02-b245cfb09017.json

Example hosted content

At the URL, there will be a preview form of the recipient’s certificate, with an option to download the raw JSON certificate. You can use cert-viewer as a starting point.

Introductions

This is the recommended convention for allowing a recipient wallet-holder to submit an introduction to the issuer. The wallet manages the recipient’s bitcoin addresses, which is a secure and convenient way for recipients to track their keys.

The cert-viewer project demonstrates an endpoint that a wallet-holder can use to submit introductions to the issuer.

1 Like
2

Hi Kim,

Quick question on the above.

In which file do you add:

document.certificate.issuer.id = https://example.org/organization.json

If you have any other documents on steps for hosting, that would be greatly appreciated.

Thanks.

3

Hi Jake,
I’m sorry for the delay. This article is out of date. That is supposed to go in the certificate (created by cert-tools), but that’s probably not clear because this article is using the v1 schema. I’ll update it to use the v2 Blockcerts schema.

Thanks,
Kim

4

Hi Jake,
So for example, this would be the context of badge.issuer.id

{
  "badge": {
    "id": "urn:uuid:82a4c9f2-3588-457b-80ea-da695571b8fc",
    "type": "BadgeClass",
    "name": "Certificate of Accomplishment",
...
    "issuer": {
      "id": "https://example.org/organization.json",
      "type": "Profile",
      "name": "University of Learning",
...
    }
  }
}

Thanks,
Kim

5

Great, thanks Kim. That would be helpful.

6

Hi Kim,

Thanks for the hosting schema updates.

I am struggling with some of the basic steps of hosting cert viewer on a web server. I.e. I would like to be able to view a json certificate using ‘award.html’ online (as per the way cert-viewer does via the file cert_viewer\templates\award.html).

I have successfully tested cert viewer on a local host, but I am still struggling to figure the steps to set up cert viewer on a web server. Do you have any information you can share on steps to set up cert viewer on a web server?

Cheers.

Jake

7

Kim,

Question for Certificate verification:
The example you gave for issuer identity, there are two IssuerKeys (public keys), one is valid since 08/28/2016 and another is the revoked key since 08/28/2016.
So if a certificate was issued before 08/28/2016, I assume the IssuerKey should be used to verify the certificate should be the revoked one since 08/28/2016. Is this a valid solution?

Thank you very much for your advice

Ye