From 2fe9e9c77d56332d6431e7d465aae7bc337e6c93 Mon Sep 17 00:00:00 2001 From: Angie Jones Date: Tue, 15 Aug 2023 20:16:26 -0500 Subject: [PATCH] SSI Service Info (#14) * added info on authentication and updated info on creating DIDs * shortened subject * add more info on SSI Service --- content/ssi_did_ion.txt | 13 ++++++ content/ssi_did_key.txt | 13 ++++++ content/ssi_signed_unsigned_schema.txt | 61 ++++++++++++++++++++++++++ content/ssi_vc_schema.txt | 51 +++++++++++++++++++++ content/ssi_verify_credential.txt | 31 +++++++++++++ content/ssi_verify_presentation.txt | 21 +++++++++ 6 files changed, 190 insertions(+) create mode 100644 content/ssi_did_ion.txt create mode 100644 content/ssi_did_key.txt create mode 100644 content/ssi_signed_unsigned_schema.txt create mode 100644 content/ssi_vc_schema.txt create mode 100644 content/ssi_verify_credential.txt create mode 100644 content/ssi_verify_presentation.txt diff --git a/content/ssi_did_ion.txt b/content/ssi_did_ion.txt new file mode 100644 index 0000000..d96b052 --- /dev/null +++ b/content/ssi_did_ion.txt @@ -0,0 +1,13 @@ +How to use SSI Service to create a DID with did:ion method + +----- + +To create a did:ion DID, run the following request: + +```bash +curl -X PUT localhost:8080/v1/dids/ion -d '{"keyType":"Ed25519"}' +``` + +'Ed25519' is used as the key type in this example as it is sufficient for generating digital signatures and is known for its high level of security and efficiency, however you can use other applicable key types. + +More info on supported DID methods: https://developer.tbd.website/docs/glossary#did-method \ No newline at end of file diff --git a/content/ssi_did_key.txt b/content/ssi_did_key.txt new file mode 100644 index 0000000..8371e12 --- /dev/null +++ b/content/ssi_did_key.txt @@ -0,0 +1,13 @@ +How to use SSI Service to create a DID with did:key method + +----- + +To create a did:key DID, run the following request: + +```bash +curl -X PUT localhost:8080/v1/dids/key -d '{"keyType":"Ed25519"}' +``` + +'Ed25519' is used as the key type in this example as it is sufficient for generating digital signatures and is known for its high level of security and efficiency, however you can use other applicable key types. + +More info on supported DID methods: https://developer.tbd.website/docs/glossary#did-method \ No newline at end of file diff --git a/content/ssi_signed_unsigned_schema.txt b/content/ssi_signed_unsigned_schema.txt new file mode 100644 index 0000000..e8d17e3 --- /dev/null +++ b/content/ssi_signed_unsigned_schema.txt @@ -0,0 +1,61 @@ +Explains the difference between a signed and unsigned credential schema + +----- + +The SSI Service exposes a set of APIs for managing schemas. To create a schema you have two options: signed or unsigned. + +The signed version of a schema is packaged as a VC. In some cases, it's useful to package a JSON Schema as a VC to retain information about authorship (who created the schema), when it was created, and enable other features the VC Data Model offers, such as the ability to suspend the usage of a schema. + +An unsigned schema consists of the JSON schema without the VC fields. + +Example of an unsigned schema: + +```json +curl -X PUT localhost:8080/v1/schemas -d '{ + "name": "Email Credential", + "schema": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "credentialSubject": { + "type": "object", + "properties": { + "emailAddress": { + "type": "string", + "format": "email" + } + }, + "required": ["emailAddress"] + } + } + } +}' +``` + +Example of signed schema: + +```json +curl -X PUT localhost:8080/v1/schemas -d '{ + "name": "Email Credential", + "issuer": "did:key:z6MkjePG6UBCLbrgUQgURoTSuXAbRpDbCdTLEPUXDqUC4EFw", + "verificationMethodId": "did:key:z6MkjePG6UBCLbrgUQgURoTSuXAbRpDbCdTLEPUXDqUC4EFw#z6MkjePG6UBCLbrgUQgURoTSuXAbRpDbCdTLEPUXDqUC4EFw", + "schema": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "credentialSubject": { + "type": "object", + "properties": { + "emailAddress": { + "type": "string", + "format": "email" + } + }, + "required": ["emailAddress"] + } + } + } +}' +``` + +Notice the signed VC contains `issuer` and `verificationMethodId` properties. \ No newline at end of file diff --git a/content/ssi_vc_schema.txt b/content/ssi_vc_schema.txt new file mode 100644 index 0000000..a2f86b9 --- /dev/null +++ b/content/ssi_vc_schema.txt @@ -0,0 +1,51 @@ +How to create a credential schema with SSI Service + +----- + +A Credential Schema is a document that defines the structure of a Verifiable Credential (VC). It's based on JSON Schema and specifies which properties the issuer will use to create the VC. + +1. Construct the JSON Schema and specify if any of the properties are required. Here's an example of a VC Schema for an email address + +```json +{ + "$id": "https://example.com/schemas/email.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "name": "Email Address", + "type": "object", + "properties": { + "emailAddress": { + "type": "string", + "format": "email" + } + }, + "required": ["emailAddress"] +} +``` + +The $id keyword identifies a schema resource with its canonical URI. Note that this URI is an identifier and not necessarily a network locator. In the case of a network-addressable URL, a schema does not need to be downloadable from its canonical URI. + +2. Create Credential Schema + +To apply a JSON Schema to a Verifiable Credential, add your data properties in the `credentialSubject` section of the JSON: + +```json +curl -X PUT localhost:8080/v1/schemas -d '{ + "name": "Email Credential", + "schema": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "credentialSubject": { + "type": "object", + "properties": { + "emailAddress": { + "type": "string", + "format": "email" + } + }, + "required": ["emailAddress"] + } + } + } +}' +``` \ No newline at end of file diff --git a/content/ssi_verify_credential.txt b/content/ssi_verify_credential.txt new file mode 100644 index 0000000..3bf3730 --- /dev/null +++ b/content/ssi_verify_credential.txt @@ -0,0 +1,31 @@ +How to verify a credential from an issuer with SSI Service + +----- + +As a part of SSI Service, `/v1/credentials/verification` is used as a stateless utility to verify any credential. + +To verify the VC, run the follow command after replacing the credentialJWT value with the one from your credential: + +```bash +curl -X PUT localhost:8080/v1/credentials/verification -d '{ + "credentialJwt": "eyJhbGciOiJFZERTQSIsImtpZCI6ImRpZDprZXk6..." +}' +``` + +This performs the following verification process: + +✅ Make sure the credential is complaint with the VC Data Model + +✅ Make sure the credential is not expired + +✅ Make sure the signature of the credential is valid (currently supports both JWT and some Linked Data credentials) + +✅ Make sure its data complies with the credential schema if one exists (note: the schema must be hosted within the service) + +Upon success the following response should be returned: + +```json +{ + "verified": true +} +``` \ No newline at end of file diff --git a/content/ssi_verify_presentation.txt b/content/ssi_verify_presentation.txt new file mode 100644 index 0000000..19f3e9b --- /dev/null +++ b/content/ssi_verify_presentation.txt @@ -0,0 +1,21 @@ +How to verify a presentation with SSI Service + +----- + +A VC holder may provide a Verifiable Presentation for verification, which is an object that serves as an authenticated wrapper around a set of credentials they wish to have verified. + +You can use the SSI Service to verify a VC Presentation by making a `PUT` request to `/v1/presentations/verification`. A sample request is as follows: + +```bash +curl -X PUT localhost:3000/v1/presentations/verification -d '{ + "presentationJwt": "eyJhbGciOixlQ3JlZGVudGlhbCI6WyJ..." +}' +``` + +Upon success we see a response such as: + +```json +{ + "verified": true +} +``` \ No newline at end of file