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.

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.

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.

Classes

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:

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

EncryptedMessage

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

Status
stable
Parent Class
owl:Thing
Expected properties
authenticationTag, cipherAlgorithm, cipherData, cipherKey, initializationVector, publicKey

The example below expresses a message that has been encrypted using an AES cipher in Galois/Counter Mode and a 128-bit key (AES-128-GCM). The key has been encrypted using an RSA public key. The encrypted message, cipherData, and encrypted key, cipherKey, are both base64-encoded. To decrypt the message, first the cipherKey must be decrypted using the private key associated with the publicKey. Then, the cipherData can be decrypted using the decrypted cipherKey, cipherAlgorithm, initializationVector, and authenticationTag.

{
  "@context": "https://w3id.org/security/v1",
  "@type": "EncryptedMessage",
  "cipherData": "VTJGc2RHVmtYMThOY3h2dnNVN290Zks1dmxWc3labi9sYkU0TGloRTdxY0dpblE4OHgrUXFNNi9l\n↩
a1JMWjdXOApRSGtrbzh6UG5XOFo3WWI4djJBUG1abnlRNW5CVGViWkRGdklpMEliczNWSzRQTGdB\n↩
UFhxYTR2aWFtemwrWGV3Cmw0eFF4ancvOW85dTlEckNURjMrMDBKMVFubGdtci9abkFRSmc5UjdV\n↩
Rk55ckpYalIxZUJuKytaQ0luUTF2cUwKcm5vcDU1eWk3RFVqVnMrRXZZSkx6RVF1VlBVQ0xxdXR4\n↩
L3lvTWd4bkdhSksxOG5ZakdiekJxSGxOYm9pVStUNwpwOTJ1Q0Y0Q2RiR1NqL0U3OUp4Vmh6OXQr\n↩
Mjc2a1V3RUlNY3o2Z3FadXZMU004KzRtWkZiakh6K2N5a1VVQ2xHCi9RcTk3b2o3N2UrYXlhZjhS\n↩
ZmtEZzlUeWk3Q2szREhSblprcy9WWDJWUGhUOEJ5c3RiYndnMnN4eWc5TXhkbHoKUkVESzFvR0FJ\n↩
UDZVQ09NeWJLTGpBUm0zMTRmcWtXSFdDY29mWFNzSGNPRmM2cnp1Wko0RnVWTFNQMGROUkFRRgpB\n↩
bFQ0QUpPbzRBZHpIb2hpTy8vVGhNOTl1U1ZER1NPQ3graFAvY3V4dGNGUFBSRzNrZS8vUk1MVFZO\n↩
YVBlaUp2Ckg4L1ZWUVU4L3dLZUEyeTQ1TzQ2K2lYTnZsOGErbGg0NjRUS3RabktFb009Cg==",
  "cipherKey": "uATtey0c4nvZIsDIfpFffuCyMYGPKRLIVJCsvedE013SpEJ+1uO7x6SK9hIG9zLWRlPpwmbar2bt\n↩
gTX5NBzYC5+c5ZkXtM1O8REwIJ7wmtLdumRYEbr/TghFl3pAgXhv0mVt8XZ+KLWlxMqXnrT+ByNw\n↩
z7u3IxpqNVcXHExjXQE=",
  "cipherAlgorithm": "aes-128-gcm",
  "authenticationTag": "q25H1CzsE731OmeyEle93w==",
  "initializationVector": "vcDU1eWTy8vVGhNOszREhSblFVqVnGpBUm0zMTRmcWtMrRX=="
  "publicKey": "https://example.com/people/john/keys/23"
}
        

GraphSignature2012

Add new GraphSignatureYEAR that uses RDF Dataset Normalization.

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 signature mechanism uses a SHA-256 digest and RSA to perform the digital signature.

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

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 signature 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.

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

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.

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

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

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 signatureAlgorithm.

Properties

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 mode.

Status
stable
Range
xsd:string

The example below expresses a message that has been encrypted using an AES cipher in Galois/Counter Mode and a 128-bit key (AES-128 GCM). The key has been encrypted using an RSA public key. The encrypted message, cipherData, and encrypted key, cipherKey are both base64-encoded. To decrypt the message, first the cipherKey must be decrypted using the private key associated with the publicKey. Then, the cipherData can be decrypted using the decrypted cipherKey, cipherAlgorithm, initializationVector, and authenticationTag.

{
  "@context": "https://w3id.org/security/v1",
  "@type": "EncryptedMessage",
  "cipherData": "VTJGc2RHVmtYMThOY3h2dnNVN290Zks1dmxWc3labi9sYkU0TGloRTdxY0dpblE4OHgrUXFNNi9l\n↩
a1JMWjdXOApRSGtrbzh6UG5XOFo3WWI4djJBUG1abnlRNW5CVGViWkRGdklpMEliczNWSzRQTGdB\n↩
UFhxYTR2aWFtemwrWGV3Cmw0eFF4ancvOW85dTlEckNURjMrMDBKMVFubGdtci9abkFRSmc5UjdV\n↩
Rk55ckpYalIxZUJuKytaQ0luUTF2cUwKcm5vcDU1eWk3RFVqVnMrRXZZSkx6RVF1VlBVQ0xxdXR4\n↩
L3lvTWd4bkdhSksxOG5ZakdiekJxSGxOYm9pVStUNwpwOTJ1Q0Y0Q2RiR1NqL0U3OUp4Vmh6OXQr\n↩
Mjc2a1V3RUlNY3o2Z3FadXZMU004KzRtWkZiakh6K2N5a1VVQ2xHCi9RcTk3b2o3N2UrYXlhZjhS\n↩
ZmtEZzlUeWk3Q2szREhSblprcy9WWDJWUGhUOEJ5c3RiYndnMnN4eWc5TXhkbHoKUkVESzFvR0FJ\n↩
UDZVQ09NeWJLTGpBUm0zMTRmcWtXSFdDY29mWFNzSGNPRmM2cnp1Wko0RnVWTFNQMGROUkFRRgpB\n↩
bFQ0QUpPbzRBZHpIb2hpTy8vVGhNOTl1U1ZER1NPQ3graFAvY3V4dGNGUFBSRzNrZS8vUk1MVFZO\n↩
YVBlaUp2Ckg4L1ZWUVU4L3dLZUEyeTQ1TzQ2K2lYTnZsOGErbGg0NjRUS3RabktFb009Cg==",
  "cipherKey": "uATtey0c4nvZIsDIfpFffuCyMYGPKRLIVJCsvedE013SpEJ+1uO7x6SK9hIG9zLWRlPpwmbar2bt\n↩
gTX5NBzYC5+c5ZkXtM1O8REwIJ7wmtLdumRYEbr/TghFl3pAgXhv0mVt8XZ+KLWlxMqXnrT+ByNw\n↩
z7u3IxpqNVcXHExjXQE=",
  "cipherAlgorithm": "aes-128-gcm",
  "authenticationTag": "q25H1CzsE731OmeyEle93w==",
  "initializationVector": "vcDU1eWTy8vVGhNOszREhSblFVqVnGpBUm0zMTRmcWtMrRX=="
  "publicKey": "https://example.com/people/john/keys/23"
}
        

cipherData

Cipher data an opaque blob of information that is used to specify an encrypted message.

Status
stable
Range
xsd:string
The example below expresses a message that has been encrypted using an AES cipher in Galois/Counter Mode and a 128-bit key (AES-128 GCM). The key has been encrypted using an RSA public key. The encrypted message, cipherData, and encrypted key, cipherKey are both base64-encoded. To decrypt the message, first the cipherKey must be decrypted using the private key associated with the publicKey. Then, the cipherData can be decrypted using the decrypted cipherKey, cipherAlgorithm, initializationVector, and authenticationTag.

{
  "@context": "https://w3id.org/security/v1",
  "@type": "EncryptedMessage",
  "cipherData": "VTJGc2RHVmtYMThOY3h2dnNVN290Zks1dmxWc3labi9sYkU0TGloRTdxY0dpblE4OHgrUXFNNi9l\n↩
a1JMWjdXOApRSGtrbzh6UG5XOFo3WWI4djJBUG1abnlRNW5CVGViWkRGdklpMEliczNWSzRQTGdB\n↩
UFhxYTR2aWFtemwrWGV3Cmw0eFF4ancvOW85dTlEckNURjMrMDBKMVFubGdtci9abkFRSmc5UjdV\n↩
Rk55ckpYalIxZUJuKytaQ0luUTF2cUwKcm5vcDU1eWk3RFVqVnMrRXZZSkx6RVF1VlBVQ0xxdXR4\n↩
L3lvTWd4bkdhSksxOG5ZakdiekJxSGxOYm9pVStUNwpwOTJ1Q0Y0Q2RiR1NqL0U3OUp4Vmh6OXQr\n↩
Mjc2a1V3RUlNY3o2Z3FadXZMU004KzRtWkZiakh6K2N5a1VVQ2xHCi9RcTk3b2o3N2UrYXlhZjhS\n↩
ZmtEZzlUeWk3Q2szREhSblprcy9WWDJWUGhUOEJ5c3RiYndnMnN4eWc5TXhkbHoKUkVESzFvR0FJ\n↩
UDZVQ09NeWJLTGpBUm0zMTRmcWtXSFdDY29mWFNzSGNPRmM2cnp1Wko0RnVWTFNQMGROUkFRRgpB\n↩
bFQ0QUpPbzRBZHpIb2hpTy8vVGhNOTl1U1ZER1NPQ3graFAvY3V4dGNGUFBSRzNrZS8vUk1MVFZO\n↩
YVBlaUp2Ckg4L1ZWUVU4L3dLZUEyeTQ1TzQ2K2lYTnZsOGErbGg0NjRUS3RabktFb009Cg==",
  "cipherKey": "uATtey0c4nvZIsDIfpFffuCyMYGPKRLIVJCsvedE013SpEJ+1uO7x6SK9hIG9zLWRlPpwmbar2bt\n↩
gTX5NBzYC5+c5ZkXtM1O8REwIJ7wmtLdumRYEbr/TghFl3pAgXhv0mVt8XZ+KLWlxMqXnrT+ByNw\n↩
z7u3IxpqNVcXHExjXQE=",
  "cipherAlgorithm": "aes-128-gcm",
  "authenticationTag": "q25H1CzsE731OmeyEle93w==",
  "initializationVector": "vcDU1eWTy8vVGhNOszREhSblFVqVnGpBUm0zMTRmcWtMrRX=="
  "publicKey": "https://example.com/people/john/keys/23"
}
        

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:

{
  "@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",
  "signatureAlgorithm": "http://www.w3.org/2000/09/xmldsig#rsa-sha1",
}
        

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:

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

cipherKey

A cipher key is a symmetric key that is used to encrypt or decrypt a piece of information. The key itself may be expressed in clear text or encrypted.

Status
stable
Range
xsd:string

The example below expresses a message that has been encrypted using an AES cipher in Galois/Counter Mode and a 128-bit key (AES-128 GCM). The key has been encrypted using an RSA public key. The encrypted message, cipherData, and encrypted key, cipherKey are both base64-encoded. To decrypt the message, first the cipherKey must be decrypted using the private key associated with the publicKey. Then, the cipherData can be decrypted using the decrypted cipherKey, cipherAlgorithm, initializationVector, and authenticationTag.

{
  "@context": "https://w3id.org/security/v1",
  "@type": "EncryptedMessage",
  "cipherData": "VTJGc2RHVmtYMThOY3h2dnNVN290Zks1dmxWc3labi9sYkU0TGloRTdxY0dpblE4OHgrUXFNNi9l\n↩
a1JMWjdXOApRSGtrbzh6UG5XOFo3WWI4djJBUG1abnlRNW5CVGViWkRGdklpMEliczNWSzRQTGdB\n↩
UFhxYTR2aWFtemwrWGV3Cmw0eFF4ancvOW85dTlEckNURjMrMDBKMVFubGdtci9abkFRSmc5UjdV\n↩
Rk55ckpYalIxZUJuKytaQ0luUTF2cUwKcm5vcDU1eWk3RFVqVnMrRXZZSkx6RVF1VlBVQ0xxdXR4\n↩
L3lvTWd4bkdhSksxOG5ZakdiekJxSGxOYm9pVStUNwpwOTJ1Q0Y0Q2RiR1NqL0U3OUp4Vmh6OXQr\n↩
Mjc2a1V3RUlNY3o2Z3FadXZMU004KzRtWkZiakh6K2N5a1VVQ2xHCi9RcTk3b2o3N2UrYXlhZjhS\n↩
ZmtEZzlUeWk3Q2szREhSblprcy9WWDJWUGhUOEJ5c3RiYndnMnN4eWc5TXhkbHoKUkVESzFvR0FJ\n↩
UDZVQ09NeWJLTGpBUm0zMTRmcWtXSFdDY29mWFNzSGNPRmM2cnp1Wko0RnVWTFNQMGROUkFRRgpB\n↩
bFQ0QUpPbzRBZHpIb2hpTy8vVGhNOTl1U1ZER1NPQ3graFAvY3V4dGNGUFBSRzNrZS8vUk1MVFZO\n↩
YVBlaUp2Ckg4L1ZWUVU4L3dLZUEyeTQ1TzQ2K2lYTnZsOGErbGg0NjRUS3RabktFb009Cg==",
  "cipherKey": "uATtey0c4nvZIsDIfpFffuCyMYGPKRLIVJCsvedE013SpEJ+1uO7x6SK9hIG9zLWRlPpwmbar2bt\n↩
gTX5NBzYC5+c5ZkXtM1O8REwIJ7wmtLdumRYEbr/TghFl3pAgXhv0mVt8XZ+KLWlxMqXnrT+ByNw\n↩
z7u3IxpqNVcXHExjXQE=",
  "cipherAlgorithm": "aes-128-gcm",
  "authenticationTag": "q25H1CzsE731OmeyEle93w==",
  "initializationVector": "vcDU1eWTy8vVGhNOszREhSblFVqVnGpBUm0zMTRmcWtMrRX=="
  "publicKey": "https://example.com/people/john/keys/23"
}
        

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:

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

initializationVector

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

Status
stable
Domain
EncryptedMessage
Range
xsd:string

The example below expresses a message that has been encrypted using an AES cipher in Galois/Counter Mode and a 128-bit key (AES-128 GCM). The key has been encrypted using an RSA public key. The encrypted message, cipherData, and encrypted key, cipherKey are both base64-encoded. To decrypt the message, first the cipherKey must be decrypted using the private key associated with the publicKey. Then, the cipherData can be decrypted using the decrypted cipherKey, cipherAlgorithm, initializationVector, and authenticationTag.

{
  "@context": "https://w3id.org/security/v1",
  "@type": "EncryptedMessage",
  "cipherData": "VTJGc2RHVmtYMThOY3h2dnNVN290Zks1dmxWc3labi9sYkU0TGloRTdxY0dpblE4OHgrUXFNNi9l\n↩
a1JMWjdXOApRSGtrbzh6UG5XOFo3WWI4djJBUG1abnlRNW5CVGViWkRGdklpMEliczNWSzRQTGdB\n↩
UFhxYTR2aWFtemwrWGV3Cmw0eFF4ancvOW85dTlEckNURjMrMDBKMVFubGdtci9abkFRSmc5UjdV\n↩
Rk55ckpYalIxZUJuKytaQ0luUTF2cUwKcm5vcDU1eWk3RFVqVnMrRXZZSkx6RVF1VlBVQ0xxdXR4\n↩
L3lvTWd4bkdhSksxOG5ZakdiekJxSGxOYm9pVStUNwpwOTJ1Q0Y0Q2RiR1NqL0U3OUp4Vmh6OXQr\n↩
Mjc2a1V3RUlNY3o2Z3FadXZMU004KzRtWkZiakh6K2N5a1VVQ2xHCi9RcTk3b2o3N2UrYXlhZjhS\n↩
ZmtEZzlUeWk3Q2szREhSblprcy9WWDJWUGhUOEJ5c3RiYndnMnN4eWc5TXhkbHoKUkVESzFvR0FJ\n↩
UDZVQ09NeWJLTGpBUm0zMTRmcWtXSFdDY29mWFNzSGNPRmM2cnp1Wko0RnVWTFNQMGROUkFRRgpB\n↩
bFQ0QUpPbzRBZHpIb2hpTy8vVGhNOTl1U1ZER1NPQ3graFAvY3V4dGNGUFBSRzNrZS8vUk1MVFZO\n↩
YVBlaUp2Ckg4L1ZWUVU4L3dLZUEyeTQ1TzQ2K2lYTnZsOGErbGg0NjRUS3RabktFb009Cg==",
  "cipherKey": "uATtey0c4nvZIsDIfpFffuCyMYGPKRLIVJCsvedE013SpEJ+1uO7x6SK9hIG9zLWRlPpwmbar2bt\n↩
gTX5NBzYC5+c5ZkXtM1O8REwIJ7wmtLdumRYEbr/TghFl3pAgXhv0mVt8XZ+KLWlxMqXnrT+ByNw\n↩
z7u3IxpqNVcXHExjXQE=",
  "cipherAlgorithm": "aes-128-gcm",
  "authenticationTag": "q25H1CzsE731OmeyEle93w==",
  "initializationVector": "vcDU1eWTy8vVGhNOszREhSblFVqVnGpBUm0zMTRmcWtMrRX=="
  "publicKey": "https://example.com/people/john/keys/23"
}
        

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.

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

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 signature algorithm:

{
  "@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",
  "signatureAlgorithm": "http://www.w3.org/2000/09/xmldsig#rsa-sha1",
}
        

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:

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

password

A secret that is used to generate a key that can be used to encrypt or decrypt message. It is typically a string value.

Status
stable
Range
xsd:string

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.

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

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.

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

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.

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

publicKeyService

The publicKeyService property is used to express the REST URL that provides public key management services as defined by the Web Key [[!SECURE-MESSAGING]] 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 [[!SECURE-MESSAGING]].

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

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:

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

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:

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

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:

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

signatureAlgorithm

The signature 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 signature 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 signature algorithm can be specified for a particular class of signatures:

{
  "@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",
  "signatureAlgorithm": "http://www.w3.org/2000/09/xmldsig#rsa-sha1",
}