The Security Vocabulary

Unofficial Draft 27 May 2012

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 document is merely a public working draft of a potential specification. It has no official standing of any kind and does not represent the support or consensus of any standards organisation.

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.

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:

{
  "@context": "http://purl.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.

{
  "@context": "http://purl.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 GraphSignature2011

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://purl.org/jsonld#UGNA2011
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.

{
  "@context": "http://purl.org/security/v1",
  "@type": "foaf:Person",
  "foaf:name": "Manu Sporny",
  "foaf:homepage": "http://manu.sporny.org/",
  "signature":
  {
  "@context": "http://purl.org/security/v1",
    "@type": "GraphSignature2011",
    "creator": "http://manu.sporny.org/webid#key-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.

{
  "@context": "http://purl.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

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.

{
  "@context": "http://purl.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.

{
  "@context": "http://purl.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:

{
  "@context": "http://purl.org/security/v1",
  "@id": "http://purl.org/security#GraphSignature2011",
  "@type": "Signature",
  "normalizationAlgorithm": "http://purl.org/jsonld#UGNA2011",
  "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:

{
  "@context": [
    "http://purl.org/security/v1", 
    { 
      "dc": "http://purl.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 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": "http://purl.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.6 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.

{
  "@context": "http://purl.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.7 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": [
    "http://purl.org/security/v1",
    { "ex": "http://example.org/vocab#" }
  ],
  "@graph": {
    "ex:request": "DELETE /private/2840-credit-card-log"
  }
  "signature":
  {
    "@type": "GraphSignature2011",
    "creator": "http://example.com/people/john-doe#key-5",
    "nonce": "8495723045.84957",
    "signatureValue": "Q3ODIyOGQzNGVkMzVm4NTIyZ43OWM32NjITkZDYMmMzQzNmExMgoYzI="
  }
}
        

3.8 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:

{
  "@context": "http://purl.org/security/v1",
  "@id": "http://purl.org/security#GraphSignature2011",
  "@type": "Signature",
  "normalizationAlgorithm": "http://purl.org/jsonld#UGNA2011",
  "digestAlgorithm": "http://example.com/digests#sha512",
  "signingAlgorithm": "http://www.w3.org/2000/09/xmldsig#rsa-sha1",
}
        

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

{
  "@context": "http://purl.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.10 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": "http://purl.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.11 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": "http://purl.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.12 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": "http://purl.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.13 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].

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

3.14 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": "http://purl.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.15 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": [
    "http://purl.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": "GraphSignature2011",
    "creator": "http://example.com/people/john-doe#key-5",
    "signatureValue": "OGQzNGVkMzVm4NTIyZTkZDYMmMzQzNmExMgoYzI43Q3ODIyOWM32NjI="
  }
}
        

3.16 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": [
    "http://purl.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": "GraphSignature2011",
    "creator": "http://example.com/people/john-doe#key-5",
    "signatureValue": "OGQzNGVkMzVm4NTIyZTkZDYMmMzQzNmExMgoYzI43Q3ODIyOWM32NjI="
  }
}
        

3.17 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:

{
  "@context": "http://purl.org/security/v1",
  "@id": "http://purl.org/security#GraphSignature2011",
  "@type": "Signature",
  "normalizationAlgorithm": "http://purl.org/jsonld#UGNA2011",
  "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/

A.2 Informative references

No informative references.