Transcript v2.1​

We added support for skills in the latest version of OpenCerts transcripts schema. The skills will enrich your OpenCerts using the definition provided by WSG skills framework. A skill looks like:

{
  "frameworkUri": "https://www.skillsfuture.sg/skills-framework",
  "frameworkVersion": "1.0",
  "frameworkName": "SFw",
  "sector": "Air Transport",
  "category": "Aircraft Operations",
  "competencyCode": "ATP-ACO-4001-1.1",
  "competencyDescription": "Monitor aircraft systems, performance and external environments as well as comply with Air Traffic Control (ATC) instructions and en route navigation requirements to ensure safe and optimal flight conditions",
  "competencyLevel": "Level 4",
  "competencyLevelDescription": "Analyse aircraft performance through close monitoring of flight decks to ensure optimal flight conditions during cruise"
}

You can add as many skills as needed. You can find a full example here

Migration legacy to new renderer​

In order to help more institution to adopt the decentralized architecture of OpenCerts v2, we have created a guide to help early adopter to migrate from the legacy render to the decentralized renderer.

A good part of software engineering is to handle errors that arise from your application. At GovTech, we understand the importance of having good error handling practices too.

In this post, we detail some of our recent upgrades to the opencerts-verify library that improves the error handling coverage when attempting to verify OpenCerts or OpenAttestation documents.

Introduction​

In the past, opencerts-verify could only handle just a few types of errors. With the increasing usage of OpenCerts in recent months due to the Covid-19 pandemic, we've seen a wide variety of interesting and funky errors.

For example,

• Infura and Cloudflare would rate-limit you if you try to spam them through our verifier, and thus returns a HTTP 429 Too Many Requests error
• Cloudflare's Ethereum Gateway would randomly return a HTTP 502 Bad Gateway error
• Users will try to tamper with their certificate, just for the fun of it or to test our OpenCerts verifier 😉

For the first two scenarios, our OpenCerts verifier would previously show that the certificate is invalid. That's because we didn't handle HTTP errors in opencerts-verify.

For the last scenario, our OpenCerts verifier didn't handle those cases properly and instead, our opencerts.io frontend verifier will say that it's (a) not issued and (b) revoked at the same time. While such a case can happen, it clearly doesn't reflect the actual error — that is, the user probably tampered with the certificate's merkleRoot. I'll describe more later in the Invalid Argument section.

New errors​

From opencerts-verify version 2.2.0, we introduced the handling of these few errors and they are:

• SERVER_ERROR
• INVALID_ARGUMENT

SERVER_ERROR​

This error encompasses Ethers's { "bad response", "failed response", "missing response" }.

To recap,

A 4xx code indicates an error caused by the user, whereas 5xx codes tell the client that they did everything correctly and it's the server itself who caused the problem.

Generally, Ethers classify both 4xx and 5xx errors as bad response.

(For those who're interested in how Ethers handle HTTP-related errors internally, you might want to take a look at this.)

Instead of checking for Ethers error messages (e.g. bad response, missing response, etc.), we now group them using Ethers error codes (e.g. SERVER_ERROR) wherever possible — because there are just too many different error messages to handle.

Do note that error messages are NOT the same as error codes, you can think of error codes as an umbrella term for many error messages.

As for our decision to group both (a) user errors and (b) server errors together, that's because we don't need to have a finer level of granularity at this moment (i.e. we don't need to know that it's 4xx vs 5xx).

INVALID_ARGUMENT​

As the name suggests, the INVALID_ARGUMENT error means the input argument is invalid. In this case, we're referring to the merkle root.

Because our verifier uses the document's merkleRoot to check against what's stored on the Ethereum blockchain, there were cases where users have tried to mess with their certificate.

Below are three examples of invalid merkleRoots:

• 61dc9186345e05cc2ae53dc72af880a3b66e2fa7983feaa6254d1518540de5 is even length, but is not 64 characters (or 32 bytes) as required of merkle roots - Ethers returns error message incorrect data length

• 61dc9186345e05cc2ae53dc72af880a3b66e2fa7983feaa6254d1518540de50 is not of a valid length - Ethers returns error message hex is of odd-length

• 61dc9186345e05cc2ae53dc72af880a3b66e2fa7983feaa6254d1518540de50Z is of valid length, BUT contains an invalid character (the Z) - Ethers returns error message invalid hex string

All three examples above are classified as INVALID_ARGUMENT from opencerts-verify version 2.2.0.

For good measure, 61dc9186345e05cc2ae53dc72af880a3b66e2fa7983feaa6254d1518540de50a is OK, leaving this here for an example of a valid merkleRoot to provide context for the three errors above.

Further discussion​

That's all for now!

For any feedback, feel free to reach us out on GitHub.

As part of our efforts to ease the adoption of OpenCerts, we have worked on several items for the past weeks.

Multi issuers​

While having multiple issuers has always been available in OpenCerts, there has been no documentation on this feature, as well how it differs from single issuer documents. The use cases might be rare (for instance when there is a collaboration between multiple institutions), but now we got you covered.

Deploy verify API​

We have been providing an API to verify OpenCerts document for quite awhile, however we don't provide support or SLA for it. This resulted in people copying and pasting the code and then deploying it into their own infrastructure.

The repository already contained scripts to automatically deploy to different infrastructure, but there was another complication. The repository contains multiple functions and while you might be interested by the API to verify documents, you might not be interested in the other APIs.

We have worked on that and improved it:

• every API is independently deployable (including verify API)
• the process is documented

Migration from v1 to v2​

When revamping the documentation, we missed the article that covered the migration from v1 to v2. We fixed that problem, and the documentation is available again

For any feedback, feel free to reach us out on Github.

🎉 Welcome to the brand new OpenCerts documentation 🎉

Documentation organisation​

We have worked on revamping the documentation to make a clear distinction between OpenAttestation documentation and OpenCerts documentation.

One might be confuse to understand the difference between OpenAttestation and OpenCerts:

• OpenAttestation is a standard that helps to create Verifiable Document.
• OpenCerts is a specific implementation, using OpenAttestation, whose purpose is to provide institutions a way to create Verifiable Certificates.

In OpenCerts documentation we will then focus only on what's specific to OpenCerts:

• How to create valid OpenCerts transcripts?
• OpenCerts verifiers.
• OpenCerts verify API.
• Suggestion to perform live transcripts.

Other useful links:

• OpenAttestation documentation
• OpenCerts Legacy documentation

What happened in OpenCerts recently?​

While we were working on the documentation, we also created many components that might be useful for OpenCerts integrators:

OpenAttestation CLI​

We worked on OpenAttestation CLI to add a new option when wrapping documents. This option allow you to specify a URL to a custom schema to ensure the validity of the document you wrap. Read more in the documentation.

There are 2 differences between OpenCerts CLI and OpenAttestation CLI:

• OpenAttestation CLI force you to use documentStore instead of certificateStore (don't worry they are strictly equivalent).
• OpenAttestation CLI force you to provide identityProof using DNS-TXT record.

We strongly recommend and encourage to use OpenAttestation CLI in the future. OpenCerts CLI will be deprecated.

OpenCerts verifier​

OpenCerts identity verification is based on a registry maintained by SSG. Because of this, OpenCerts identity verification is not compatible with OpenAttestation identity verification.

To overcome this problem, we built a javascript library @govtechsg/opencerts-verify that check the identity over OpenCerts registry and over DNS-TXT record. Read more in the documentation.

OpenCerts verify API​

Sometimes during development you might need to make sure a certificate that you generated is valid. While you could use dev.opencerts.io to assert the validity of the certificate, the process is hard to automate and tedious.

To help you on this, we published an API that you might use to validate certificate using HTTP call. Read more in the documentation

This API does not provide any guarantee for production purposes. We might work on providing a terraform module that you could use to deploy the API on your own infrastructure.

Live transcripts​

For institutions that might want to provide live transcripts to their students, we wrote documentation on how they can make use of OpenAttestation Status API. The documentation is just an implementation suggestion and does not mean you MUST follow it. Read more in the documentation