w3c-ccg / security-vocab

The Linked Data Security Vocabulary

Security Vocabulary

This repository contains the Credentials Community Group Security Vocabulary and a npm package that exports related contexts and constants.

Security Vocabulary

Security Vocabulary specification: https://w3c-ccg.github.io/security-vocab/.

Context Package

The repository contains JSON-LD contexts for the Security Vocabulary. These are also packaged in a npm package for CommonJS and ES Modules. To use with NPM and Node.js, use the following:

npm install security-context

The package exposes two values:

• contexts: A Map from context URI to JSON-LD context.
• constants: An Object of shorthand keys mapped to context URIs.

const {contexts, constants} = require('security-context');

With ES Modules:

// use one of the following forms:
import * as securityvocab1 from 'security-context';
import {default as securityvocab2} from 'security-context';
import {contexts, constants} from 'security-context';

security-vocab's Issues

JWK Ont?

We are looking for an ontology for an extension of the IETF Work on "Signing HTTP Messages" for Authentication. See the Solid Authentication Panel Issue Ontology for the KeyId document.

Looking at the security vocabulary spec I see JWK info embedded in various examples, e.g. example 2. I am having difficulty parsing the json-ld as RDF though - but this could well be that I have not yet written the JSON-LD parser I intend to write this year - and so I am not that familiar with the format. Still, trying the banana-rdf library tools I don't seem to be able to find the triples associated with the jwk.
I tried adding some context to example 2

{
"@context": [
    "https://w3id.org/security/v1",
    { "ex": "http://example.org/vocab#" }
  ],
  "id": "did:example:123#WqzaOweASs78whhl_YvCEvj1nd89IycryVlmZMefcjU",
  "type": "EcdsaSecp256k1VerificationKey2019",
  "controller": "did:example:123",
  "publicKeyJwk": {
    "crv": "secp256k1",
    "x": "4xAbUxbGGFPv4qpHlPFAUJdzteUGR1lRK-CELCufU9w",
    "y": "EYcgCTsff1qtZjI9_ckZTXDSKAIuM0BknrKgo0BZ_Is",
    "kty": "EC",
    "kid": "WqzaOweASs78whhl_YvCEvj1nd89IycryVlmZMefcjU"
  }
}

But I only seem to be able to extract one triple from it, namely:

<did:example:123#WqzaOweASs78whhl_YvCEvj1nd89IycryVlmZMefcjU> a <https://test.ont/EcdsaSecp256k1VerificationKey2019> .

Is this a bug with the Jena and RDF4J JSON-LD parsers?
I would like to be able to use that jwk as an ontology in Turtle and in other documents.

Add EcdsaSecp256k1RecoverySignature2020

https://github.com/decentralized-identity/EcdsaSecp256k1RecoverySignature2020

https://w3c-ccg.github.io/ld-cryptosuite-registry/#ecdsasecp256k1recoverysignature2020

Add vocabulary used here, and then link to the registries / DIF for additional context.

Sort v3-unstable lines

#80 (comment)

Missing documentation for allowedAction

Missing Documentation

Line number of the property that is missing a definition

https://github.com/w3c-ccg/security-vocab/blob/master/contexts/security-v2.jsonld#L28

Fix Github Pages Hosting

We should enable github pages hosting for the master branch and fix the links which are now broken.

Security vocab for Sr25519 which is used in Polkadot and substrate

We want to propose supporting Sr25519 in the security context, i.e. https://w3id.org/security/v2.
We propose adding Sr25519Signature2020 and Sr25519VerificationKey2020 in the @context.

Would this be a new version like security/v3 or can the existing v2 be updated by updating @version? Would like to understand the process of getting this approved, is updating (or creating new) context and updating the index.html sufficient?

Sr25519 is Schnorr signature using the Ristretto compression of curve25519. It has a Rust implementation called Schnorrkel that compiles to WASM and thus usable in JS applications (from polkadot-js). Relevant links

1. What is sr25519 and where did it come from?
2. Details on Schnorrkel

No Support for GPG

related https://gpg.jsld.org/contexts/#publicKeyGpg

Revise examples

remove reliance on https://w3id.org/security/v1

Missing comma in example 31

I am trying to understand the security vocabulary, and so am going through examples turning them into Turtle,
Doing that, I found a missing comma in example 31.

{
  "@context": [
    "https://w3id.org/security/v1",
    { "ex": "http://example.org/vocab#" }
  ],
  "@graph": {
    "ex:request": "DELETE /private/2840-credit-card-log"
  }
  "signature": {
    "@type": "GraphSignature2012",
    "creator": "http://example.com/people/john-doe#key-5",
    "nonce": "8495723045.84957",
    "signatureValue": "Q3ODIyOGQzNGVkMzVm4NTIyZ43OWM32NjITkZDYMmMzQzNmExMgoYzI="
  }
}

It would be nice if each of the examples were placed in its own curlable file. Then you could run tests on each of the examples to make sure they correct. It would also make it easier to try these out from command line tools.

Context resolution

The security context references https://w3id.org/security#. But https://w3id.org/security redirects to https://w3id.org/security/, which redirects to https://w3c-ccg.github.io/security-vocab/, which does not return JSON-LD - even if the HTTP Accept header is set to application/ld+json or application/json (since it is served by GitHub Pages). How is the security vocab context supposed to be referenced and resolved?

These URLs do return JSON-LD and seem to be the actual context documents, but internally they reference https://w3id.org/security:

• https://w3id.org/security/v1 -> https://w3c-ccg.github.io/security-vocab/contexts/security-v1.jsonld
• https://w3id.org/security/v2 -> https://w3c-ccg.github.io/security-vocab/contexts/security-v2.jsonld
• https://w3id.org/security/v3-unstable -> https://w3c-ccg.github.io/security-vocab/contexts/security-v3-unstable.jsonld

The redirects appear to be set here: https://github.com/perma-id/w3id.org/blob/master/security/.htaccess

This is the reference I am looking at for how to load a JSON-LD document for resolving a context:
https://www.w3.org/TR/json-ld-api/#remote-document-and-context-retrieval

Should w3id.org be updated to point https://w3id.org/security to https://w3c-ccg.github.io/security-vocab/contexts/security-v2.jsonld? Or should index.html in this repo be updated to embed the JSON-LD context? Or am I misunderstanding how these things are supposed to work?

NIST Draft for Authentication Ontology

NIST Draft 8344 has been posted. Are there plans to align the security vocab with this?

Inventory of undefined properties

We should take inventory of the properties defined in this context, that don't have documentation in the index.html, and create an issue per property so its easy to get the documentation caught up to the context definition.

We should mark each of these issues as help wanted and provide a link to a PR showing how to fix undocumented properties.

Add guidance about "version"

#56 (comment)

We don't need to include it.

Missing documentation for capability

Missing Documentation

Line number of the property that is missing a definition

https://github.com/w3c-ccg/security-vocab/blob/master/contexts/security-v2.jsonld#L31

Proposal for deterministic IDs for Sha256HmacKey2019

{
"id":"urn:digest:6a8fdcd1377afccf388999796e278cfb2768cce7b8f2534b7f281d91934b3be4",
"type":"Sha256HmacKey2019",
"privateValueBase58": "..."
}

where id is sha256 of privateValueBase58....

We need this for secure data stores....

@dlongley @dmitrizagidulin

Missing documentation for invocationTarget

Missing Documentation

Line number of the property that is missing a definition

https://github.com/w3c-ccg/security-vocab/blob/master/contexts/security-v1.jsonld#L43

Less common hashing algorithm for the message in Ed25519Signature2018

In Ed25519Signature2018 it's defined that SHA256 should be used as the prehash function of the message. However, FIPS 186-5 and in OpenSSL it's defined that SHA512 should be used for this prehash function.

I propose that we define Ed25519Signature2020 to modify the algorithm and prepare to deprecate Ed25519Signature2018

RFC8032, did not specify this (it provided suggestions through example only) which is how the ambiguity occurred.

@dlongley @msporny @mikelodder7 thoughts?

Remove unnecessary versions from v3 context

Provide reusable context compatible with VC data model context

Would it be possible to cook up a context for the security vocabulary that is compatible with VC data model context? So that it would be simple to reuse terms from the security vocabulary in the verifiable claims and presentations.

Currently both contexts are conflicting on some protected terms - namely Ed25519Signature2018 and maybe others.

The following example fails with jsonld.SyntaxError: Invalid JSON-LD syntax; tried to redefine a protected term. :

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://w3id.org/security/v1"
  ],
  "@type": ["VerifiableCredential"],
  "issuer": {
    "name": "My issuer"
  }
}

open in playground

security-vocab v3 context splitting

I have created:

• https://w3id.org/pgp/v1
• https://github.com/OR13/lds-pgp2021
• https://or13.github.io/lds-pgp2021/#PgpVerificationKey2021

As an example of splitting out context definitions...

perhaps we can find a way to adjust

security/v3 to include https://w3id.org/pgp/v1 and https://w3id.org/bbs/v1 in the future.

define https://w3id.org/security#URDNA2015

security vocab should define URDNA and give it a nice permanent URL.

Allow domain to be used more generally

decentralized-identity/.well-known#26 (comment)

Define sameAs

Useful for describing that 2 subjects are the same entity (id field associated with a verification method)... as discussed at the F2F yesterday.

We should define it here, in the did spec registries and in core with normative text.

Update CI to prevent lint, test and build failures from being merged

We should have CI/CD and branch protection on for repo's that impact security.

It should not be possible to merge a PR that fails branch protection rules (approved by code owner + no lint or build errors).

Best Practices for Inline Contexts

I am starting to feel like although they increase the size, they are a best practice over remote / by reference contexts....

A couple notes:

1. prefixing is safer in inline contexts, you don't have to worry about collisions for popular prefixes like sec.
2. only define the terms you are using... this is the biggest point. Its hard to tell what parts of a massive context, like schema.org, you are using... which its easy to fix this by only pulling the terms you need into say citizenship or traceability... IMO, thats still not as good as only defining the terms you are actually using in the vc.
3. avoids dead terminology... folks are afraid to delete terms from popular contexts.... so they tend to fill with lots of deprecated terms... thats not an issue with inline contexts.
4. not even a hint of networks requests, inlining makes it even clearer that no network requests are required to verify a VC.

Are there any additional benefits we should document?

Are there any serious reasons not to inline IF size is not a concern?.... CBOR-LD is the only thing I can think of and it does not really exist yet...

cc @dlongley @tplooker @msporny

Add Lint Config

The lint configuration used for this module should be checked into source, optional githook should be added to block any commit that breaks the linter.

Missing documentation for delegator

Missing Documentation

Line number of the property that is missing a definition

https://github.com/w3c-ccg/security-vocab/blob/master/contexts/security-v1.jsonld#L40

Missing documentation for parentCapability

Missing Documentation

Line number of the property that is missing a definition:

security-vocab/contexts/security-v2.jsonld

Line 48 in e176ae3

"parentCapability": {"@id": "sec:parentCapability", "@type": "@id"},

Which properties should we drop from V3 context that are unused now?

Related to point 3 raised by Manu in PR #70

Security vocabulary, wrong description for capabilityInvocation

In section 3.18 capabilityInvocation it is stated

An capabilityInvocation property is used to specify a URL that contains information about a verificationMethod used for capability delegation.

I guess delegation should be replaced with invocation

Specification needs editors from independent organizations

@kimdhamilton @wyc

There is no CODEOWNERs file and there is only one editor of this spec.

Ensure microdata is applied correctly to all entries

definitions for private information

https://github.com/w3c-ccg/universal-wallet-interop-spec/pull/25/files#diff-9c6d9b71546e84d84bee622bc124592cR43

@msporny if these terms are not going to be defined in this vocabulary, then we (universal wallet work item authors) will need to defined them in another vocabulary.

I'd prefer we use security vocab html to define them, but I would live with them not being in the same context....

For example:

https://w3id.org/security/v3 -> https://w3id.org/security#publicKeyJwk
https://w3id.org/security/v3-private -> https://w3id.org/security#privateKeyJwk
or
https://w3id.org/wallet/v1-> https://w3id.org/wallet#privateKeyJwk

Missing documentation for invoker

Missing Documentation

Line number of the property that is missing a definition

https://github.com/w3c-ccg/security-vocab/blob/master/contexts/security-v1.jsonld#L44

Add MerkleProof2019 to security-vocab

Hi,

Blockcerts v3 implements Verifiable Credentials standard, and uses MerkleProof2019 as the signature mechanism. At this moment we cannot verify a Blockcerts V3 in vc.js for instance as MerkleProof2019 does not exist in the security vocab. For dev mode I edited my local npm package, but that will not be sustainable in the outer world.

I had had conversations with @msporny back in March on the subject, and while I imagine it's too late to bring that into the v2 definition, I think it could be brought in to the v3 one. But I wanted confirmation it was still ok to do so before opening a PR out of the blue.

cc @kimdhamilton and Dmitry Semenovskiy for visibility

Missing documentation for caveat

Missing Documentation

Line number of the property that is missing a definition

https://github.com/w3c-ccg/security-vocab/blob/master/contexts/security-v2.jsonld#L36

sec:authenticationMethod != sec:authentication

w3c/did-spec-registries#235

Missing documentation for capabilityAction

Missing Documentation

Line number of the property that is missing a definition

https://github.com/w3c-ccg/security-vocab/blob/master/contexts/security-v1.jsonld#L32

Missing documentation for Ed25519Signature2018

Missing Documentation

Line number of the property that is missing a definition

https://github.com/w3c-ccg/security-vocab/blob/master/contexts/security-v1.jsonld#L11

Add guidance for not using "prefix" in JSON-LD

@dlongley I heard you prefer not to register prefixes, and instead use full URLs...

That should be documented in this repo somewhere... I am attempting to follow that guidance, and I will reject PRs that fail to do so from now on.

Missing documentation for capabilityChain

Missing Documentation

Line number of the property that is missing a definition

https://github.com/w3c-ccg/security-vocab/blob/master/contexts/security-v2.jsonld#L33

Is there a "digest" property?

The documentation under the digestValue property has this example:

{
  "@context": [
    "https://w3id.org/security/v1",
    {
      "dc": "https://w3id.org/dc/terms/",
      "foaf": "http://xmlns.com/foaf/0.1/"
    }
  ],
  "@id": "http://example.com/logo.jpg",
  "@type": "foaf:Image",
  "dc:title": "Example Logo",
  "digest":
  {
    "@type": "Digest",
    "digestAlgorithm": "http://www.w3.org/2000/09/xmldsig#sha1",
    "digestValue": "981ec496092bf6ea18d6251d36068b52b633268b"
  }
}

There is a digest property mentioned, but I cannot find it in any of the contexts. Is sec:digest safe to use, or should I use another vocabulary? I was looking for a suitable ontology that would allow me to link digests to entities, but so far I was unable to find any concrete property for that which wouldn't assert other unwanted facts about the subject. What is the expected way to link a digest to an entity in this ontology?

Write test suite for v3 context

Follow up issue related to #70 to write a test suite to address point 1 and 2 from Manu.

Usable JSON-LD Security Documentation

w3c-ccg/ld-cryptosuite-registry#21

I'd like to unify github pages hosting, npm module, and w3id.org security definitions and context hosting. I'm in favor of converting this repo to a registry to reduce the number of repos needed to comprehend JSON-LD security, and increase ease of contribution, reduce attack surface, etc...

See the linked issue.

Update JsonWebSignature2020 to be like Ed25519Signature2020

use scoped terms, etc...

Mark as deprecated or change ownership

This repo should be moved to a new home or marked as archived or deprecated.

See: w3c-ccg/community#97

change controller to keycontroller

In https://github.com/w3c-dvcg/security-vocab/blob/master/contexts/security-v2.jsonld#L39

This field continues to confuse people when it is used in a key block of a DID Document, as people keep assuming that it controls to the DID. No, it is used by json-ld signatures to say who controls the key.

"publicKey": [
       {
            "id": "did:btcr:xyv2-xzpq-q9wa-p7t#keys-1",
            "controller": "did:btcr:xyv2-xzpq-q9wa-p7t",
            "type": "EcdsaSecp256k1VerificationKey2019",
            "publicKeyHex": "02b97c30de767f084ce3080168ee293053ba33b235d7116a3263d29f1450936b71"
        }
    ],

I suggest that this, and possibly some other items in the security-vocab be more specific, such as keycontroller.

-- Christopher Allen

Establish best practices for using protected term

Figured out the issue and playing around with a few ways to fix it at the moment.

What I've discovered is that the new terms (except the one's defined in the VC context) are encountering issues where the terms are being redefined within the V3 context itself.

For example, when using the "@protected": true at the top of the context document it's effectively adding the term to each property. So for nonce it's going from "nonce": "https://w3id.org/security#nonce"

to now being defined like so:

"nonce": { 
  "@id": "https://w3id.org/security#nonce", 
  "@protected": true  
},

So the problem is that the way that we originally defined terms like BbsBlsSignatureProof2020 means that we're defining terms in the property contexts and then redefining them at the top level context in a way that conflicts.

Related to issues discovered during this PR: #70

Add Documentation for SchnorrSecp256k1Signature2019

https://w3c-ccg.github.io/ld-cryptosuite-registry/#secp256k1
https://github.com/decentralized-identity/SchnorrSecp256k1Signature2019

Ed25519Signature2018 appears twice

Since PR #20, Ed25519Signature2018 is now defined twice. Also see issue #21.