W3C

The Security Vocabulary

Draft Community Group Specification 03 June 2013

Latest editor's draft:
http://payswarm.com/specs/source/vocabs/security
Editor:
Manu Sporny, Digital Bazaar, Inc.

Abstract

The Security vocabulary is used to enable Internet-based applications to encrypt, decrypt, and digitally sign information expressed as Linked Data. It also provides vocabulary terms for the creation and management of a decentralized Public Key Infrastructure via the Web.

Status of This Document

This specification was published by the Web Payments Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

Table of Contents

1. Introduction

This document describes a number of classes and properties that can be used to express digital signatures and achieve cryptographic protection for Linked Data resources. This specification was designed as a modular part of the PaySwarm decentralized payment system for the Web.

Issue 1

This entire document is a work in progress and should be considered in beta until it is ratified as an official document via the World Wide Web Consortium.

2. Classes

2.1 Digest

This class represents a message digest that may be used for data integrity verification. The digest algorithm used will determine the cryptographic properties of the digest.

Status
stable
Parent Class
owl:Thing
Expected properties
digestAlgorithm, digestValue

The example below describes a cryptographic digest:

Example 1
{
  "@context": "https://w3id.org/security/v1",
  "@type": "Digest",
  "digestAlgorithm": "http://www.w3.org/2000/09/xmldsig#sha1",
  "digestValue": "981ec496092bf6ee18d6255d96069b528633268b"
}

2.2 EncryptedMessage

A class of messages that are obfuscated in some cryptographic manner. These messages are incredibly difficult to decrypt without the proper decryption key or password.

Status
stable
Parent Class
owl:Thing
Expected properties
data, encryptionKey, password, cipherAlgorithm, iv, publicKey

The example below expresses an password-encrypted message using the AES 128-bit cipher with Cyclic-Block-Chaining. The password to unlock the encrypted message has been encrypted using the public key provided by the publicKey parameter. To decrypt the message, the private key associated with the publicKey is used to decrypt the password. The password, iv (intermediate value), and the cipher algorithm are then used to extract the final clear-text message from the the base-64 encoded data property.

Example 2
{
  "@context": "https://w3id.org/security/v1",
  "@type": "EncryptedMessage",
  "data": "VTJGc2RHVmtYMThOY3h2dnNVN290Zks1dmxWc3labi9sYkU0TGloRTdxY0dpblE4OHgrUXFNNi9l\n↩
a1JMWjdXOApRSGtrbzh6UG5XOFo3WWI4djJBUG1abnlRNW5CVGViWkRGdklpMEliczNWSzRQTGdB\n↩
UFhxYTR2aWFtemwrWGV3Cmw0eFF4ancvOW85dTlEckNURjMrMDBKMVFubGdtci9abkFRSmc5UjdV\n↩
Rk55ckpYalIxZUJuKytaQ0luUTF2cUwKcm5vcDU1eWk3RFVqVnMrRXZZSkx6RVF1VlBVQ0xxdXR4\n↩
L3lvTWd4bkdhSksxOG5ZakdiekJxSGxOYm9pVStUNwpwOTJ1Q0Y0Q2RiR1NqL0U3OUp4Vmh6OXQr\n↩
Mjc2a1V3RUlNY3o2Z3FadXZMU004KzRtWkZiakh6K2N5a1VVQ2xHCi9RcTk3b2o3N2UrYXlhZjhS\n↩
ZmtEZzlUeWk3Q2szREhSblprcy9WWDJWUGhUOEJ5c3RiYndnMnN4eWc5TXhkbHoKUkVESzFvR0FJ\n↩
UDZVQ09NeWJLTGpBUm0zMTRmcWtXSFdDY29mWFNzSGNPRmM2cnp1Wko0RnVWTFNQMGROUkFRRgpB\n↩
bFQ0QUpPbzRBZHpIb2hpTy8vVGhNOTl1U1ZER1NPQ3graFAvY3V4dGNGUFBSRzNrZS8vUk1MVFZO\n↩
YVBlaUp2Ckg4L1ZWUVU4L3dLZUEyeTQ1TzQ2K2lYTnZsOGErbGg0NjRUS3RabktFb009Cg==",
  "encryptionKey": "uATtey0c4nvZIsDIfpFffuCyMYGPKRLIVJCsvedE013SpEJ+1uO7x6SK9hIG9zLWRlPpwmbar2bt\n↩
gTX5NBzYC5+c5ZkXtM1O8REwIJ7wmtLdumRYEbr/TghFl3pAgXhv0mVt8XZ+KLWlxMqXnrT+ByNw\n↩
z7u3IxpqNVcXHExjXQE=",
  "password": "5dTlEckNURjMrMDER1NPQ3graFABKMVFub=",
  "cipherAlgorithm": "aes-128-cbc",
  "iv": "vcDU1eWTy8vVGhNOszREhSblFVqVnGpBUm0zMTRmcWtMrRX==",
  "publicKey": "https://example.com/people/john/keys/23"
}        
        

2.3 GraphSignature2012

A graph signature is used for digital signatures on RDF graphs. The default normalization mechanism is specified in the RDF Graph normalization specification, which effectively resolves all CURIEs and deterministically names all unnamed nodes. The default digest method uses the SHA-1 algorithm over a series of quads statements in N-Quad format. The default signature mechanism uses a SHA-1 digest and RSA to perform the digital signature.

Status
stable
Parent Class
Signature
Expected properties
creator, signatureValue
Signing Properties
Default Normalization Method
http://w3id.org/jsonld#UGNA2012
Default Digest Method
http://www.w3.org/2000/09/xmldsig#sha1
Default Signing Algorithm
http://www.w3.org/2000/09/xmldsig#rsa-sha1

The example below shows how a basic JSON-LD signature is expressed in a JSON-LD snippet. Note that the signature property is directly embedded in the object. The signing algorithm understands that in order to check the signature that the signature property must be removed and the text canonicalized using the standard normalization algorithm for JSON-LD.

Example 3
{
  "@context": ["https://w3id.org/security/v1", "http://json-ld.org/contexts/person.jsonld"]
  "@type": "Person",
  "name": "Manu Sporny",
  "homepage": "http://manu.sporny.org/",
  "signature":
  {
  "@context": "https://w3id.org/security/v1",
    "@type": "GraphSignature2012",
    "creator": "http://manu.sporny.org/keys/5",
    "signatureValue": "OGQzNGVkMzVmMmQ3ODIyOWM32MzQzNmExMgoYzI4ZDY3NjI4NTIyZTk="
  }
}
          

2.4 Key

This class represents a cryptographic key that may be used for encryption, decryption or digitally signing data.

Status
stable
Parent Class
owl:Thing
Expected properties
owner, privateKeyPem, publicKeyPem

The example below describes a cryptographic key that contains both the public and private key as well as the owner of the key. The owner property is described in the Commerce Vocabulary.

Example 4
{
  "@context": "https://w3id.org/security/v1",
  "@id": "https://payswarm.example.com/i/bob/keys/1",
  "@type": "Key",
  "owner": "https://payswarm.example.com/i/bob",
  "privateKeyPem": "-----BEGIN PUBLIC KEY-----\nMII8YbF3s8q3c...j8Fk88FsRa3K\n-----END PUBLIC KEY-----\n",
  "publicKeyPem": "-----BEGIN PRIVATE KEY-----\nMIIBG0BA...OClDQAB\n-----END PRIVATE KEY-----\n"
}

2.5 Signature

This class represents a digital signature on serialized data. It is an abstract class and should not be used other than for Semantic Web reasoning purposes, such as by a reasoning agent.

Status
stable
Parent Class
owl:Thing
Properties
none
Note

A Signature class MUST NOT be used as an RDF type. It should instead be used as the base class for all signature classes. A signature sub-class SHOULD express at least three signature algorithm properties: normalizationAlgorithm, digestAlgorithm, and signingAlgorithm.

3. Properties

3.1 cipherAlgorithm

The cipher algorithm describes the mechanism used to encrypt a message. It is typically a string expressing the cipher suite, the strength of the cipher and a block cipher mechanism.

Status
stable
Range
xsd:string

The example below describes the cipher as that detailed in the Advanced Encryption Standard using 128 bits and cipher block chaining. The password to unlock the encrypted message has been encrypted using the public key provided by the publicKey parameter. To decrypt the message, the private key associated with the publicKey is used to decrypt the password. The password, iv (intermediate value), and the cipher algorithm are then used to extract the final clear-text message from the the base-64 encoded data property.

Example 5
{
  "@context": "https://w3id.org/security/v1",
  "@type": "EncryptedMessage",
  "data": "VTJGc2RHVmtYMThOY3h2dnNVN290Zks1dmxWc3labi9sYkU0TGloRTdxY0dpblE4OHgrUXFNNi9l\n↩
a1JMWjdXOApRSGtrbzh6UG5XOFo3WWI4djJBUG1abnlRNW5CVGViWkRGdklpMEliczNWSzRQTGdB\n↩
UFhxYTR2aWFtemwrWGV3Cmw0eFF4ancvOW85dTlEckNURjMrMDBKMVFubGdtci9abkFRSmc5UjdV\n↩
Rk55ckpYalIxZUJuKytaQ0luUTF2cUwKcm5vcDU1eWk3RFVqVnMrRXZZSkx6RVF1VlBVQ0xxdXR4\n↩
L3lvTWd4bkdhSksxOG5ZakdiekJxSGxOYm9pVStUNwpwOTJ1Q0Y0Q2RiR1NqL0U3OUp4Vmh6OXQr\n↩
Mjc2a1V3RUlNY3o2Z3FadXZMU004KzRtWkZiakh6K2N5a1VVQ2xHCi9RcTk3b2o3N2UrYXlhZjhS\n↩
ZmtEZzlUeWk3Q2szREhSblprcy9WWDJWUGhUOEJ5c3RiYndnMnN4eWc5TXhkbHoKUkVESzFvR0FJ\n↩
UDZVQ09NeWJLTGpBUm0zMTRmcWtXSFdDY29mWFNzSGNPRmM2cnp1Wko0RnVWTFNQMGROUkFRRgpB\n↩
bFQ0QUpPbzRBZHpIb2hpTy8vVGhNOTl1U1ZER1NPQ3graFAvY3V4dGNGUFBSRzNrZS8vUk1MVFZO\n↩
YVBlaUp2Ckg4L1ZWUVU4L3dLZUEyeTQ1TzQ2K2lYTnZsOGErbGg0NjRUS3RabktFb009Cg==",
  "encryptionKey": "uATtey0c4nvZIsDIfpFffuCyMYGPKRLIVJCsvedE013SpEJ+1uO7x6SK9hIG9zLWRlPpwmbar2bt\n↩
gTX5NBzYC5+c5ZkXtM1O8REwIJ7wmtLdumRYEbr/TghFl3pAgXhv0mVt8XZ+KLWlxMqXnrT+ByNw\n↩
z7u3IxpqNVcXHExjXQE=",
  "password": "5dTlEckNURjMrMDER1NPQ3graFABKMVFub=",
  "cipherAlgorithm": "aes-128-cbc",
  "iv": "vcDU1eWTy8vVGhNOszREhSblFVqVnGpBUm0zMTRmcWtMrRX==",
  "publicKey": "http://example.com/people/john/keys/23"
}        
        

3.2 data

The data property is an opaque blob of information that is typically used to specify the data associated with a particular message.

Status
stable
Range
xsd:string
The example below describes a secret message that has been encrypted and placed in the data property. The message has been encrypted using the Advanced Encryption Standard using 128 bits and cipher block chaining. The password to unlock the encrypted message has been encrypted using the public key provided by the publicKey parameter. To decrypt the message, the private key associated with the publicKey is used to decrypt the password. The password, iv (intermediate value), and the cipher algorithm are then used to extract the final clear-text message from the the base-64 encoded data property.

Example 6
{
  "@context": "https://w3id.org/security/v1",
  "@type": "EncryptedMessage",
  "data": "VTJGc2RHVmtYMThOY3h2dnNVN290Zks1dmxWc3labi9sYkU0TGloRTdxY0dpblE4OHgrUXFNNi9l\n↩
a1JMWjdXOApRSGtrbzh6UG5XOFo3WWI4djJBUG1abnlRNW5CVGViWkRGdklpMEliczNWSzRQTGdB\n↩
UFhxYTR2aWFtemwrWGV3Cmw0eFF4ancvOW85dTlEckNURjMrMDBKMVFubGdtci9abkFRSmc5UjdV\n↩
Rk55ckpYalIxZUJuKytaQ0luUTF2cUwKcm5vcDU1eWk3RFVqVnMrRXZZSkx6RVF1VlBVQ0xxdXR4\n↩
L3lvTWd4bkdhSksxOG5ZakdiekJxSGxOYm9pVStUNwpwOTJ1Q0Y0Q2RiR1NqL0U3OUp4Vmh6OXQr\n↩
Mjc2a1V3RUlNY3o2Z3FadXZMU004KzRtWkZiakh6K2N5a1VVQ2xHCi9RcTk3b2o3N2UrYXlhZjhS\n↩
ZmtEZzlUeWk3Q2szREhSblprcy9WWDJWUGhUOEJ5c3RiYndnMnN4eWc5TXhkbHoKUkVESzFvR0FJ\n↩
UDZVQ09NeWJLTGpBUm0zMTRmcWtXSFdDY29mWFNzSGNPRmM2cnp1Wko0RnVWTFNQMGROUkFRRgpB\n↩
bFQ0QUpPbzRBZHpIb2hpTy8vVGhNOTl1U1ZER1NPQ3graFAvY3V4dGNGUFBSRzNrZS8vUk1MVFZO\n↩
YVBlaUp2Ckg4L1ZWUVU4L3dLZUEyeTQ1TzQ2K2lYTnZsOGErbGg0NjRUS3RabktFb009Cg==",
  "encryptionKey": "uATtey0c4nvZIsDIfpFffuCyMYGPKRLIVJCsvedE013SpEJ+1uO7x6SK9hIG9zLWRlPpwmbar2bt\n↩
gTX5NBzYC5+c5ZkXtM1O8REwIJ7wmtLdumRYEbr/TghFl3pAgXhv0mVt8XZ+KLWlxMqXnrT+ByNw\n↩
z7u3IxpqNVcXHExjXQE=",
  "password": "5dTlEckNURjMrMDER1NPQ3graFABKMVFub=",
  "cipherAlgorithm": "aes-128-cbc",
  "iv": "vcDU1eWTy8vVGhNOszREhSblFVqVnGpBUm0zMTRmcWtMrRX==",
  "publicKey": "http://example.com/people/john/keys/23"
}        
        

3.3 digestAlgorithm

The digest algorithm is used to specify the cryptographic function to use when generating the data to be digitally signed. Typically, data that is to be signed goes through three steps: 1) normalization, 2) digest, and 3) signature. This property is used to specify the algorithm that should be used for step #2. A signature class typically specifies a default digest method, so this property is typically used to specify information for a signature algorithm.

Status
stable
Range
IRI, xsd:string

The following example shows how the digest algorithm can be specified for a particular signature type:

Example 7
{
  "@context": "https://w3id.org/security/v1",
  "@id": "https://w3id.org/security#GraphSignature2012",
  "@type": "Signature",
  "normalizationAlgorithm": "https://w3id.org/jsonld#UGNA2012",
  "digestAlgorithm": "http://example.com/digests#sha512",
  "signingAlgorithm": "http://www.w3.org/2000/09/xmldsig#rsa-sha1",
}
        

3.4 digestValue

The digest value is used to express the output of the digest algorithm expressed in Base-16 (hexadecimal) format.

Status
stable
Domain
Digest
Range
xsd:string

The following example shows how the output of the digest algorithm can be encoded in JSON-LD:

Example 8
{
  "@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"
  }
}
        

3.5 encryptionKey

An encryption key is a value that is used to encrypt a piece of information. The key itself may be expressed in clear text or encrypted.

Status
stable
Range
xsd:string

The following example shows an encrypted message that contains an encrypted key value that has been password-protected. The password itself has been encrypted against the public key of the message receiver. In order to decode the message, the receiver must use their public key to decrypt the password, and then use the password to decrypt the encryption key. The encryption key can then be used to decrypt the data held in the message.

Example 9
{
  "@context": "https://w3id.org/security/v1",
  "@type": "EncryptedMessage",
  "data": "VTJGc2RHVmtYMThOY3h2dnNVN290Zks1dmxWc3labi9sYkU0TGloRTdxY0dpblE4OHgrUXFNNi9l\n↩
a1JMWjdXOApRSGtrbzh6UG5XOFo3WWI4djJBUG1abnlRNW5CVGViWkRGdklpMEliczNWSzRQTGdB\n↩
UFhxYTR2aWFtemwrWGV3Cmw0eFF4ancvOW85dTlEckNURjMrMDBKMVFubGdtci9abkFRSmc5UjdV\n↩
Rk55ckpYalIxZUJuKytaQ0luUTF2cUwKcm5vcDU1eWk3RFVqVnMrRXZZSkx6RVF1VlBVQ0xxdXR4\n↩
L3lvTWd4bkdhSksxOG5ZakdiekJxSGxOYm9pVStUNwpwOTJ1Q0Y0Q2RiR1NqL0U3OUp4Vmh6OXQr\n↩
Mjc2a1V3RUlNY3o2Z3FadXZMU004KzRtWkZiakh6K2N5a1VVQ2xHCi9RcTk3b2o3N2UrYXlhZjhS\n↩
ZmtEZzlUeWk3Q2szREhSblprcy9WWDJWUGhUOEJ5c3RiYndnMnN4eWc5TXhkbHoKUkVESzFvR0FJ\n↩
UDZVQ09NeWJLTGpBUm0zMTRmcWtXSFdDY29mWFNzSGNPRmM2cnp1Wko0RnVWTFNQMGROUkFRRgpB\n↩
bFQ0QUpPbzRBZHpIb2hpTy8vVGhNOTl1U1ZER1NPQ3graFAvY3V4dGNGUFBSRzNrZS8vUk1MVFZO\n↩
YVBlaUp2Ckg4L1ZWUVU4L3dLZUEyeTQ1TzQ2K2lYTnZsOGErbGg0NjRUS3RabktFb009Cg==",
  "encryptionKey": "uATtey0c4nvZIsDIfpFffuCyMYGPKRLIVJCsvedE013SpEJ+1uO7x6SK9hIG9zLWRlPpwmbar2bt\n↩
gTX5NBzYC5+c5ZkXtM1O8REwIJ7wmtLdumRYEbr/TghFl3pAgXhv0mVt8XZ+KLWlxMqXnrT+ByNw\n↩
z7u3IxpqNVcXHExjXQE=",
  "password": "5dTlEckNURjMrMDER1NPQ3graFABKMVFub=",
  "cipherAlgorithm": "aes-128-cbc",
  "iv": "vcDU1eWTy8vVGhNOszREhSblFVqVnGpBUm0zMTRmcWtMrRX==",
  "publicKey": "http://example.com/people/john/keys/23"
}
        

3.6 expires

The expiration time is typically associated with a Key and specifies when the validity of the key will expire. It is considered a best practice to only create keys that have very definite expiration periods. This period is typically set to between six months and two years. An digital signature created using an expired key MUST be marked as invalid by any software attempting to verify the signature.

Status
stable
Range
xsd:dateTime

The following example shows a key that was created on January 3rd 2012 and that expires on January 3rd 2014:

Example 10
{
  "@context": "https://w3id.org/security/v1",
  "@id": "https://payswarm.example.com/i/bob/keys/1",
  "@type": "Key",
  "created": "2012-01-03T14:34:57+0000",
  "expires": "2014-01-03T14:34:57+0000",
  "owner": "https://payswarm.example.com/i/bob",
  "publicKeyPem": "-----BEGIN PRIVATE KEY-----\nMIIBG0BA...OClDQAB\n-----END PRIVATE KEY-----\n",
}
        

3.7 iv

The initialization vector (iv) is a byte stream that is typically used to initialize certain password-based encryption schemes. For a receiving application to be able to decrypt the scheme, it must know the decryption password and the initialization vector. The value is typically base-64 encoded.

Status
stable
Domain
EncryptedMessage
Range
xsd:string

The following example shows a public key based encrypted message where the decryption password is encrypted using the public key described in the message. Since the cipher algorithm is AES-128-CBC, an initialization vector along with the password and the public key is required in order to decrypt the data.

Example 11
{
  "@context": "https://w3id.org/security/v1",
  "@type": "EncryptedMessage",
  "data": "VTJGc2RHVmtYMThOY3h2dnNVN290Zks1dmxWc3labi9sYkU0TGloRTdxY0dpblE4OHgrUXFNNi9l\n↩
a1JMWjdXOApRSGtrbzh6UG5XOFo3WWI4djJBUG1abnlRNW5CVGViWkRGdklpMEliczNWSzRQTGdB\n↩
UFhxYTR2aWFtemwrWGV3Cmw0eFF4ancvOW85dTlEckNURjMrMDBKMVFubGdtci9abkFRSmc5UjdV\n↩
Rk55ckpYalIxZUJuKytaQ0luUTF2cUwKcm5vcDU1eWk3RFVqVnMrRXZZSkx6RVF1VlBVQ0xxdXR4\n↩
L3lvTWd4bkdhSksxOG5ZakdiekJxSGxOYm9pVStUNwpwOTJ1Q0Y0Q2RiR1NqL0U3OUp4Vmh6OXQr\n↩
Mjc2a1V3RUlNY3o2Z3FadXZMU004KzRtWkZiakh6K2N5a1VVQ2xHCi9RcTk3b2o3N2UrYXlhZjhS\n↩
ZmtEZzlUeWk3Q2szREhSblprcy9WWDJWUGhUOEJ5c3RiYndnMnN4eWc5TXhkbHoKUkVESzFvR0FJ\n↩
UDZVQ09NeWJLTGpBUm0zMTRmcWtXSFdDY29mWFNzSGNPRmM2cnp1Wko0RnVWTFNQMGROUkFRRgpB\n↩
bFQ0QUpPbzRBZHpIb2hpTy8vVGhNOTl1U1ZER1NPQ3graFAvY3V4dGNGUFBSRzNrZS8vUk1MVFZO\n↩
YVBlaUp2Ckg4L1ZWUVU4L3dLZUEyeTQ1TzQ2K2lYTnZsOGErbGg0NjRUS3RabktFb009Cg==",
  "encryptionKey": "uATtey0c4nvZIsDIfpFffuCyMYGPKRLIVJCsvedE013SpEJ+1uO7x6SK9hIG9zLWRlPpwmbar2bt\n↩
gTX5NBzYC5+c5ZkXtM1O8REwIJ7wmtLdumRYEbr/TghFl3pAgXhv0mVt8XZ+KLWlxMqXnrT+ByNw\n↩
z7u3IxpqNVcXHExjXQE=",
  "password": "5dTlEckNURjMrMDER1NPQ3graFABKMVFub=",
  "cipherAlgorithm": "aes-128-cbc",
  "iv": "vcDU1eWTy8vVGhNOszREhSblFVqVnGpBUm0zMTRmcWtMrRX==",
  "publicKey": "http://example.com/people/john/keys/23"
}        
        

3.8 nonce

This property is used in conjunction with the input to the signature hashing function in order to protect against replay attacks. Typically, receivers need to track all nonce values used within a certain time period in order to ensure that an attacker cannot merely re-send a compromised packet in order to execute a privileged request.

Status
stable
Range
xsd:string

The following example shows a fairly sensitive request that is digitally signed with a nonce. How the nonce is used is up to the signature algorithm, but the value is typically included as input to the signature hashing function in order to protect against replay attacks.

Example 12
{
  "@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="
  }
}
        

3.9 normalizationAlgorithm

The normalization algorithm is used to transform the input data into a form that can be passed to a cryptographic digest method. The digest is then digitally signed using a digital signature algorithm. Normalization ensures that a piece of software that is generating a digital signature is able to do so on the same set of information in a deterministic manner.

Status
stable
Range
IRI, xsd:string

The example below shows the establishment of a new signature class, using the three pieces of information that are typically required for a signature - the normalization algorithm, the digest algorithm and the signing algorithm:

Example 13
{
  "@context": "https://w3id.org/security/v1",
  "@id": "https://w3id.org/security#GraphSignature2012",
  "@type": "Signature",
  "normalizationAlgorithm": "https://w3id.org/jsonld#UGNA2012",
  "digestAlgorithm": "http://example.com/digests#sha512",
  "signingAlgorithm": "http://www.w3.org/2000/09/xmldsig#rsa-sha1",
}
        

3.10 owner

An owner is an entity that claims control over a particular resource. Note that ownership is best validated as a two-way relationship where the owner claims ownership over a particular resource, and the resource clearly identifies its owner.

Status
stable
Range
IRI

The example below shows a cryptographic key that is owned by an entity identified by a URL. Presumably, this key is under the control of the owner and can be used to infer that any digitally signed content using the key was signed by a software agent of the owner:

Example 14
{
  "@context": "https://w3id.org/security/v1",
  "@id": "https://payswarm.example.com/i/bob/keys/1",
  "@type": "Key",
  "owner": "https://payswarm.example.com/i/bob",
  "publicKeyPem": "-----BEGIN PRIVATE KEY-----\nMIIBG0BA...OClDQAB\n-----END PRIVATE KEY-----\n"
}
        

3.11 password

A secret that is used to decrypt an encrypted message. It is typically a string value. Some passwords are encrypted using a public key so that only the intended recipient may know the password. Some passwords are provided in clear-text over a secure channel. The first method is the preferred approach for specifying a password.

Status
stable
Range
xsd:string

The password example below is a public-key encrypted string that has been base-64 encoded.

Example 15
{
  "@context": "https://w3id.org/security/v1",
  "@type": "EncryptedMessage",
  "data": "VTJGc2RHVmtYMThOY3h2dnNVN290Zks1dmxWc3labi9sYkU0TGloRTdxY0dpblE4OHgrUXFNNi9l\n↩
a1JMWjdXOApRSGtrbzh6UG5XOFo3WWI4djJBUG1abnlRNW5CVGViWkRGdklpMEliczNWSzRQTGdB\n↩
UFhxYTR2aWFtemwrWGV3Cmw0eFF4ancvOW85dTlEckNURjMrMDBKMVFubGdtci9abkFRSmc5UjdV\n↩
Rk55ckpYalIxZUJuKytaQ0luUTF2cUwKcm5vcDU1eWk3RFVqVnMrRXZZSkx6RVF1VlBVQ0xxdXR4\n↩
L3lvTWd4bkdhSksxOG5ZakdiekJxSGxOYm9pVStUNwpwOTJ1Q0Y0Q2RiR1NqL0U3OUp4Vmh6OXQr\n↩
Mjc2a1V3RUlNY3o2Z3FadXZMU004KzRtWkZiakh6K2N5a1VVQ2xHCi9RcTk3b2o3N2UrYXlhZjhS\n↩
ZmtEZzlUeWk3Q2szREhSblprcy9WWDJWUGhUOEJ5c3RiYndnMnN4eWc5TXhkbHoKUkVESzFvR0FJ\n↩
UDZVQ09NeWJLTGpBUm0zMTRmcWtXSFdDY29mWFNzSGNPRmM2cnp1Wko0RnVWTFNQMGROUkFRRgpB\n↩
bFQ0QUpPbzRBZHpIb2hpTy8vVGhNOTl1U1ZER1NPQ3graFAvY3V4dGNGUFBSRzNrZS8vUk1MVFZO\n↩
YVBlaUp2Ckg4L1ZWUVU4L3dLZUEyeTQ1TzQ2K2lYTnZsOGErbGg0NjRUS3RabktFb009Cg==",
  "encryptionKey": "uATtey0c4nvZIsDIfpFffuCyMYGPKRLIVJCsvedE013SpEJ+1uO7x6SK9hIG9zLWRlPpwmbar2bt\n↩
gTX5NBzYC5+c5ZkXtM1O8REwIJ7wmtLdumRYEbr/TghFl3pAgXhv0mVt8XZ+KLWlxMqXnrT+ByNw\n↩
z7u3IxpqNVcXHExjXQE=",
  "password": "5dTlEckNURjMrMDER1NPQ3graFABKMVFub=",
  "cipherAlgorithm": "aes-128-cbc",
  "iv": "vcDU1eWTy8vVGhNOszREhSblFVqVnGpBUm0zMTRmcWtMrRX==",
  "publicKey": "http://example.com/people/john/keys/23"
}        
        

3.12 privateKeyPem

A private key PEM property is used to specify the PEM-encoded version of the private key. This encoding is compatible with almost every Secure Sockets Layer library implementation and typically plugs directly into functions intializing private keys.

Status
stable
Domain
Key
Range
xsd:string

The following example demonstrates the expression of a private key in PEM format. The elipsis ("...") in the middle of the string denotes more data that has been abbreviated for the sake of the readability of the example.

Example 16
{
  "@context": "https://w3id.org/security/v1",
  "@id": "https://payswarm.example.com/i/bob/keys/1",
  "@type": "Key",
  "owner": "https://payswarm.example.com/i/bob",
  "privateKeyPem": "-----BEGIN PUBLIC KEY-----\nMII8YbF3s8q3c...j8Fk88FsRa3K\n-----END PUBLIC KEY-----\n"
}
        

3.13 publicKey

A public key property is used to specify a URL that contains information about a public key.

Status
stable
Range
IRI

The following example demonstrates the expression of a public key belonging to the identity https://payswarm.example.com/i/bob.

Example 17
{
  "@context": "https://w3id.org/security/v1",
  "@id": "https://payswarm.example.com/i/bob/keys/1",
  "@type": "Key",
  "owner": "https://payswarm.example.com/i/bob",
  "publicKeyPem": "-----BEGIN PRIVATE KEY-----\nMIIBG0BA...OClDQAB\n-----END PRIVATE KEY-----\n"
}
        

3.14 publicKeyPem

A public key PEM property is used to specify the PEM-encoded version of the public key. This encoding is compatible with almost every Secure Sockets Layer library implementation and typically plugs directly into functions intializing public keys.

Status
stable
Domain
Key
Range
xsd:string

The following example demonstrates the expression of a public key in PEM format. The elipsis ("...") in the middle of the string denotes more data that has been abbreviated for the sake of the readability of the example.

Example 18
{
  "@context": "https://w3id.org/security/v1",
  "@id": "https://payswarm.example.com/i/bob/keys/1",
  "owner": "https://payswarm.example.com/i/bob",
  "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMIIBG0BA...OClDQAB\n-----END PUBLIC KEY-----\n"
}
        

3.15 publicKeyService

The publicKeyService property is used to express the REST URL that provides public key management services as defined by the Web Key [WEB-KEYS] specification.

Status
unstable
Range
URL

The following example shows how a website can publish the location of a public keys service via the .well-known file. The publicKeyService can be found at the https://payswarm.example.com/public-keys URL and may be operated upon using the protocol described in [WEB-KEYS].

Example 19
{
  "@context": "https://w3id.org/security/v1",
  "@id": "https://payswarm.example.com/.well-known/services",
  "publicKeyService": "https://payswarm.example.com/public-keys"
}
        

3.16 revoked

The revocation time is typically associated with a Key that has been marked as invalid as of the date and time associated with the property. Key revocations are often used when a key is compromised, such as the theft of the private key, or during the course of best-practice key rotation schedules.

Status
stable
Range
xsd:dateTime

The following example shows a key that was created on January 3rd 2012 and revoked on May 5th 2012:

Example 20
{
  "@context": "https://w3id.org/security/v1",
  "@id": "https://payswarm.example.com/i/bob/keys/1",
  "@type": "Key",
  "created": "2012-01-03T14:34:57+0000",
  "revoked": "2012-05-01T18:11:19+0000",
  "owner": "https://payswarm.example.com/i/bob",
  "publicKeyPem": "-----BEGIN PRIVATE KEY-----\nMIIBG0BA...OClDQAB\n-----END PRIVATE KEY-----\n",
}
        

3.17 signature

The signature property is used to associate a signature with a graph of information. The signature property is typically not included in the canonicalized graph that is then digested, and digitally signed.

Status
stable
Range
Signature

The following example demonstrates how a signature on the graph identified by the subject http://example.com/people#jane is expressed using a JSON-LD signature:

Example 21
{
  "@context": [
    "https://w3id.org/security/v1",
    { "foaf": "http://xmlns.com/foaf/0.1/" }
  ]
  "@graph":
  {
     "@id": "http://example.com/people#jane",
     "@type": "foaf:Person",
     "foaf:name": "Jane Doe",
     "foaf:homepage": "http://example.org/jane"
  },
  "signature":
  {
    "@type": "GraphSignature2012",
    "creator": "http://example.com/people/john-doe#key-5",
    "signatureValue": "OGQzNGVkMzVm4NTIyZTkZDYMmMzQzNmExMgoYzI43Q3ODIyOWM32NjI="
  }
}
        

3.18 signatureValue

The signature value is used to express the output of the signature algorithm expressed in base-64 format.

Status
stable
Domain
Signature
Range
xsd:string

The following example shows how the output of the signature algorithm can be encoded in JSON-LD:

Example 22
{
  "@context": [
    "https://w3id.org/security/v1",
    { "foaf": "http://xmlns.com/foaf/0.1/" }
  ]
  "@graph":
  {
     "@id": "http://example.com/people#jane",
     "@type": "foaf:Person",
     "foaf:name": "Jane Doe",
     "foaf:homepage": "http://example.org/jane"
  },
  "signature":
  {
    "@type": "GraphSignature2012",
    "creator": "http://example.com/people/john-doe#key-5",
    "signatureValue": "OGQzNGVkMzVm4NTIyZTkZDYMmMzQzNmExMgoYzI43Q3ODIyOWM32NjI="
  }
}
        

3.19 signingAlgorithm

The signing algorithm is used to specify the cryptographic signature function to use when digitally signing the digest data. Typically, text to be signed goes through three steps: 1) normalization, 2) digest, and 3) signature. This property is used to specify the algorithm that should be used for step #3. A signature class typically specifies a default signing algorithm, so this property rarely needs to be used in practice when specifying digital signatures.

Status
unstable
Domain
Signature
Range
IRI

The following example shows how the signing algorithm can be specified for a particular class of signatures:

Example 23
{
  "@context": "https://w3id.org/security/v1",
  "@id": "https://w3id.org/security#GraphSignature2012",
  "@type": "Signature",
  "normalizationAlgorithm": "https://w3id.org/jsonld#UGNA2012",
  "digestAlgorithm": "http://example.com/digests#sha512",
  "signingAlgorithm": "http://www.w3.org/2000/09/xmldsig#rsa-sha1",
}
        

A. References

A.1 Normative references

[WEB-KEYS]
Manu Sporny; et al. Web Keys. Web Payments Community Group Working Draft. URL: http://payswarm.com/specs/source/web-keys/