Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clarify proof mechanism and algorithm selection #584

Draft
wants to merge 1 commit into
base: develop
Choose a base branch
from
Draft

Clarify proof mechanism and algorithm selection #584

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
120 changes: 69 additions & 51 deletions ob_v3p0/impl/recommended-practices.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ collective experience and collaboration of implementers. Implementers are
encouraged to join the 1EdTech community to provide feedback and discuss how we
can collectively improve our implementations and guidance.

Below are a variety of recommended practices and considertions for the
Below are a variety of recommended practices and considerations for the
implementation of the Open Badges and CLR specification.

### Issuer
Expand Down Expand Up @@ -67,23 +67,35 @@ The OB and CLR specifications define some requirements around the signing or
proving of credentials (see
[Proofs](https://www.imsglobal.org/spec/ob/v3p0#data-integrity)). Two formats of
proof method are introduced, JWTs and Linked Data Proofs. Within each format,
there are still a range of options that issuers may select for cryptographically
there are a range of options that issuers may select for cryptographically
signing the credentials. Notably, signing algorithm selection and its closely
related concept of key material expression format must be considered. The best
choices within these options sometimes depend on other parts of the issuer's
tech stack and which options are supported among wallets and verifiers with whom
badge recipients want to share their badges.

The OB specification identifies some specific options, which are used by the
conformance test suite to check product implementations. These identified
algorithms will likely see the broadest early implementation within Open Badges.
The OB 3.0 and CLR 2.0 specifications identify some specific options, which are
used by the conformance test suite to check product implementations. In order to
achieve conformance certification, issuers MUST produce credentials secured with
a supported mechanism. These identified algorithms will likely see the broadest
early implementation within Open Badges.

- Linked Data Proofs using the [[[VC-DI-EDDSA]]]. Issuers produce an
`DataIntegrityProof` proof referencing a key URL of a public key expressed
in `eddsa-rdf-2022` format as its verificationMethod.
- JWTs with `RSA256` algorithm, with key material published as JSON Web Key
(JWK).

Some issuers may experiment with or implement novel proof mechanisms, such as
new Linked Data Proofs or JWT signing algorithms, in coordination with hosts and
verifiers. These may be useful for specific use cases or to explore new
capabilities. However, issuers should be aware that these may not be supported
by all hosts, wallets and verifiers, and that interoperability may be limited
until these new mechanisms are more widely adopted. The 1EdTech Digital
Credentials Workgroup may periodically consider recommending new proof methods
for inclusion in the OB and CLR specifications and the 1EdTech certification
program.

A step-by-step guide to signing an OB or CLR is provided in the OB specification
section on [Proofs](https://www.imsglobal.org/spec/ob/v3p0#data-integrity). In
order to achieve certification, implementers must be able to pass conformance
Expand Down Expand Up @@ -112,6 +124,10 @@ include:
RSA and ECDSA on the non-NIST secp256k1 curve but not Ed25519.
- JWT signing with RSA family keys may have broader support in systems
like this across all major cloud vendors offering a KMS.
- Some proof mechanisms feature additional security properties, such as a
capability for selective disclosure, or improved "unlinkability", the
resistance to correlation of credentials or verification requests from the
same holder.

#### Publishing `Achievement` definitions and selecting `Achievement` identifiers

Expand Down Expand Up @@ -580,34 +596,34 @@ to the work is infeasible.
The `id` property also can be the evidence encoded as a Data URI. However,
embedding the evidence as Data URI as the id of the evidence has some caveats:

- Due to the JSON-LD canonicalization process for signing, there's a row for
each field of the evidence with the id inside. If the id is the evidence itself
as Data URI, the size of the payload to process grows significantly, moreover
when evidence has 5 fields and is extensible.
- Some libraries fails when processing this.
- Due to the JSON-LD canonicalization process for signing, there's a row for
each field of the evidence with the id inside. If the id is the evidence
itself as Data URI, the size of the payload to process grows significantly,
moreover when evidence has 5 fields and is extensible.
- Some libraries fail when processing this.

Also attempting to embed large data in a credential JSON is not recommended.
You should expect uneven interop performance if you do that.
Also attempting to embed large data in a credential JSON is not recommended. You
should expect uneven interop performance if you do that.

Instead, the recommendation for embedding the evidence is:

1. use a `urn:` URI for the id.
2. have a separate property (data or whatever works) that contains the text-encoded
data.
2. have a separate property (data or whatever works) that contains the
text-encoded data.

#### Key provenance

Keys used in proof generation must belong to the issuer. However, there isn't
a existing way in current standards to completely assure this provenance.
Keys used in proof generation must belong to the issuer. However, there isn't an
existing way in current standards to completely assure this provenance.

The following best practices establish a verification mechanism to assure that
the issuer is the owner of the key used in a credential.

##### Linked Data proof

Linked Data Proofs defines a method to get the public key (via `verificationMethod`)
which, as defined by [[VC-DATA-INTEGRITY]], implies the dereference of a controller
document.
Linked Data Proofs defines a method to get the public key (via
`verificationMethod`) which, as defined by [[VC-DATA-INTEGRITY]], implies the
dereference of a controller document.

Section 2.6 of [[VC-DATA-INTEGRITY]] describes a way to verify the association
of the verification method with an issuer:
Expand All @@ -618,8 +634,8 @@ of the verification method with an issuer:
> association indicates that the issuer or holder, respectively, is the
> controller of the verification method used to verify the proof.

We recommend following this practice. As an issuer, then, you must set the
value of the controller as the `id` of the issuer.
We recommend following this practice. As an issuer, then, you must set the value
of the controller as the `id` of the issuer.

##### External proof

Expand All @@ -628,10 +644,9 @@ fields of the JOSE header of the JWS. `kid` is an URI that can be dereferenced
to an object of type JWK representing the public key, wether `jwt` is the
representation of the public key.

In order to assure key provenance, we recommend the use of a JWK Set
(JKWS) [[RFC7517]].
This set, following this recommmendation, should be publicly accessible
via the well-known url:
In order to assure key provenance, we recommend the use of a JWK Set (JKWS)
[[RFC7517]]. This set, following this recommendation, should be publicly
accessible via the well-known url:

`https://{domain}/.well-known/jwks.json`

Expand Down Expand Up @@ -660,38 +675,42 @@ We propose leverage this to add a new member `iss` in the JWK for the issuer's `

##### JWK Set endpoint

Following this recommendation ultimatelly means that, for an issuer to be
trusted, the endpoint for the issuer's Json Web Key Set should be publicly
available at any time a credential is verified, which can happen long after
the issuing of the credential. If don't, there's a potential issue of a
valid credential not accepted because the endpoint is no longer available.
Following this recommendation ultimately means that, for an issuer to be
trusted, the endpoint for the issuer's JSON Web Key Set should be publicly
available at any time a credential is verified, which can happen long after the
issuing of the credential. If don't, there's a potential issue of a valid
credential not accepted because the endpoint is no longer available.

Following this recommendation, thus, implies a commitment for the issuer to maintain its JWK Set and publicly expose it throught the endpoint.
Following this recommendation, thus, implies a commitment for the issuer to
maintain its JWK Set and publicly expose it through the endpoint.

### Displayer

#### Cryptosuites in Linked Data Proofs

Linked data proofs imply the use of a cryptosuite for its generation and
further verification. The Open Badges 3.0 and Comprehensive
Learner Record 2.0 specifications define the cryptosuite to use.
Linked data proofs imply the use of a cryptosuite for its generation and further
verification. The Open Badges 3.0 and Comprehensive Learner Record 2.0
specifications define cryptosuite(s) supported by 1EdTech conformance tests.
Verifiers should expect to encounter credentials secured with these
cryptosuites.

The change of the cryptosuite has impact in newly issued credentials. But
there are already issued credentials with a proof generated using a now old
cryptosuite. Verifiers should support prior cryptosuites, specially when the
credential doesn't define the refresh service. In that case, is argually that
the issuer will provide a refreshed version of the credential with a proof
computed with the current designed cryptosuite.
Cryptosuites evolve and produce new versions occasionally. The 1EdTech
conformance process may over time support updated version or additional
cryptosuite options, and there are issued credentials with a proof generated
using a cryptosuite now considered deprecated. Verifiers should consider
supporting prior cryptosuites, especially for cases when the credential doesn't
define the refresh service. Issuers that do support refresh services may be able
to update the credential to use a newer cryptosuite.

Prior designed cryptosuites in both OB 3.0 and CLR 2.0 were:
Prior (deprecated) cryptosuites identified in OB 3.0 and CLR 2.0 drafts include:

- `eddsa-2022`
- `Ed25519Signature2020`
- `eddsa-2022`
- `Ed25519Signature2020`

#### Key provenance

Keys used in proof generation must belong to the issuer. However, there isn't
a existing way in current standards to completely assure this provenance.
Keys used in proof generation must belong to the issuer. However, there isn't an
existing way in current standards to completely assure this provenance.

The following best practices establish a verification mechanism to assure that
the issuer is the owner of the key used in a credential.
Expand Down Expand Up @@ -730,9 +749,9 @@ Section 6.3.1 of [[VC-JOSE-COSE]] extends the definition of `kid` as
> `kid` MUST be present when the key of the issuer or subject is expressed as
> a DID URL

With these two premises, the recommendation for verifing key provenance is using
JWK Set. A verifier must, then, get the public JKWS of the issuer for further
check of the provided key.
With these two premises, the recommendation for verifying key provenance is
using JWK Set. A verifier must, then, get the public JKWS of the issuer for
further check of the provided key.

In order to get the issuer's JKWS, a verifier must build a well-known url with
the `authority` part of the issuer's `id` ([[RFC3986]]):
Expand All @@ -748,9 +767,8 @@ field, this `kid` must be in the set. On the other hand, if the key is
represented by the `jwk` field, this `jwk` must be in the set with
any specified `kid`.

If the found JWT in the set contains the member `iss`, this must be equal
to issuer's `id`.

If the found JWT in the set contains the member `iss`, this must be equal to
the issuer's `id`.

<div class="note">
The credential should be considered invalid and not trustworthy if the
Expand Down
14 changes: 7 additions & 7 deletions ob_v3p0/integrity.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,13 @@ var integrity = `

## Proofs (Signatures) {#data-integrity}

This section describes mechanisms for ensuring the authenticity and integrity of OpenBadgeCredentials. At least one proof mechanism, and the details necessary to evaluate that proof, MUST be expressed for a [=credential=] to be a [=verifiable credential=]; that is, to be [=verifiable=].
This section describes mechanisms for ensuring the authenticity and integrity of OpenBadgeCredentials. At least one proof mechanism, and the details necessary to evaluate that proof, MUST be expressed for a [=credential=] to be a [=verifiable credential=]; that is, to be [=verifiable=]. In order to pass 1EdTech conformance tests, issuers MUST use a proof mechanism supported by the 1EdTech conformance test suite. See more about [Selecting proof methods and crypto algorithms](impl#selecting-proof-methods-and-crypto-algorithms) in the Implementation Guide.

### Proof Formats

The proof formats included in this specification fall into two categories:

- JSON Web Token Proof - Somtimes called VC-JWT, this format has a single implementation: the credential is encoded into a [=JWT=] which is then signed and encoded as a [=JWS=]. The JSON Web Token proof is called an external proof because the proof wraps the [=credential=] object.
- JSON Web Token Proof - Sometimes called VC-JWT, this format has a single implementation: the credential is encoded into a [=JWT=] which is then signed and encoded as a [=JWS=]. The JSON Web Token proof is called an external proof because the proof wraps the [=credential=] object.
- Linked Data Proofs - The credential is signed and the signature is used to form a [Proof](#proof) object which is appended to the credential. This format supports many different proof types. These are called embedded proofs because the proof is embedded in the data.

<div class="note">
Expand All @@ -19,7 +19,7 @@ A third category of proof format called Non-Signature Proof is not covered by th

### JSON Web Token Proof Format {#jwt-proof}

This proof format relies on the well established JWT (JSON Web Token) [[RFC7519]] and JWS (JSON Web Signature) [[RFC7515]] specifications. A JSON Web Token Proof is a JWT signed and encoded as a [=Compact JWS=] string. The proof format is described in detail in [[VC-JOSE-COSE]], refered from Section 5.13 "Securing Mechanism Specifications" of [[[VC-DATA-MODEL-2.0]]]. That description allows several options which may inhibit interoperability. This specification limits the options while maintaining compatibility with [[VC-DATA-MODEL-2.0]] to help ensure interoperability.
This proof format relies on the well established JWT (JSON Web Token) [[RFC7519]] and JWS (JSON Web Signature) [[RFC7515]] specifications. A JSON Web Token Proof is a JWT signed and encoded as a [=Compact JWS=] string. The proof format is described in detail in [[VC-JOSE-COSE]], referred from Section 5.13 "Securing Mechanism Specifications" of [[[VC-DATA-MODEL-2.0]]]. That description allows several options which may inhibit interoperability. This specification limits the options while maintaining compatibility with [[VC-DATA-MODEL-2.0]] to help ensure interoperability.

<div class="note">
At the time of the completion of this specification, the JSON Web Token Proof Format of [[VC-DATA-MODEL-2.0]] was undergoing a revision process. [[VC-JOSE-COSE]] will collect and display
Expand Down Expand Up @@ -52,7 +52,7 @@ The JOSE Header, JWT Payload, and JWS Signature are combined to form a Compact J

The resulting [=JWS=] proves that the [=issuer=] signed the [=JWT Payload=] turning the [=credential=] into a [=verifiable credential=].

When using the JSON Web Token Proof Format, the \`proof\` property MAY be ommitted from the [OpenBadgeCredential](#achievementcredential). If a Linked Data Proof is also provided, it MUST be created before the JSON Web Token Proof Format is created.
When using the JSON Web Token Proof Format, the \`proof\` property MAY be omitted from the [OpenBadgeCredential](#achievementcredential). If a Linked Data Proof is also provided, it MUST be created before the JSON Web Token Proof Format is created.

#### Create the JOSE Header {#joseheader}

Expand Down Expand Up @@ -150,7 +150,7 @@ Verifiers that receive a OpenBadgeCredential in Compact JWS format MUST perform

### Linked Data Proof Format {#lds-proof}

This standard supports the Linked Data Proof format. In order to opt for this format you MUST use the [[[VC-DI-EDDSA]]] suite.
This standard supports the Linked Data Proof format. In order to pass conformance tests for this format issuers MUST use an option supported by the 1EdTech conformance test suite, which is currently limited to the [[[VC-DI-EDDSA]]] suite.

<div class="note">
Whenever possible, you should use a library or service to create and verify a Linked Data Proof.
Expand All @@ -161,12 +161,12 @@ This standard supports the Linked Data Proof format. In order to opt for this fo
Perform these steps to attach a Linked Data Proof to the credential:

1. Create an instance of [Multikey](#multikey) as shown in [Section 2.1.1 DataIntegrityProof](https://www.w3.org/TR/vc-di-eddsa/#multikey) of [[VC-DI-EDDSA]].
1. Using the key material, sign the credential object as shown in [Section 7.1 Proof Algothim](https://w3c-ccg.github.io/data-integrity-spec/#proof-algorithm) of [[DATA-INTEGRITY-SPEC]] to produce a [Proof](#proof) as shown in [Section 2.2.1 DataIntegrityProof](https://www.w3.org/TR/vc-di-eddsa/#dataintegrityproof) of [[VC-DI-EDDSA]] with a \`proofPurpose\` of "assertionMethod".
1. Using the key material, sign the credential object as shown in [Section 7.1 Proof Algorithm](https://w3c-ccg.github.io/data-integrity-spec/#proof-algorithm) of [[DATA-INTEGRITY-SPEC]] to produce a [Proof](#proof) as shown in [Section 2.2.1 DataIntegrityProof](https://www.w3.org/TR/vc-di-eddsa/#dataintegrityproof) of [[VC-DI-EDDSA]] with a \`proofPurpose\` of "assertionMethod".
1. Add the resulting proof object to the credential \`proof\` property.

#### Verify an OpenBadgeCredential Linked Data Signature {#lds-verify}

Verify the Linked Data Proof signature as shown in [Section 7.2 Proof Verification Algorthim](https://w3c-ccg.github.io/data-integrity-spec/#proof-verification-algorithm) of [[DATA-INTEGRITY-SPEC]].
Verify the Linked Data Proof signature as shown in [Section 7.2 Proof Verification Algorithm](https://w3c-ccg.github.io/data-integrity-spec/#proof-verification-algorithm) of [[DATA-INTEGRITY-SPEC]].

### Key Management

Expand Down