Digital Signature Vocabulary

Unofficial Draft 08 March 2011

Editor:
Manu Sporny, Digital Bazaar, Inc.

Abstract

Status of This Document

This document is merely a draft PaySwarm Exploratory Group document. It has no official standing of any kind and does not represent consensus of the Web community.

Table of Contents

1. Introduction

This document describes a number of classes and properties that can be used to express digital signatures on the Semantic Web.

This entire document is a work in progress and is thus incredibly unstable. It must not be used for any production use. It may harm children and animals. It will probably set your house on fire. You have been warned.

2. Classes

2.1 Key

This class represents a cryptographic key that may be used for digital signatures or cryptography.

Status
unstable
Parent Class
owl:Thing
Properties
sig:publicKey, sig:privateKeyPem, sig:publicKeyPem

The example below describes a cryptographic key that contains both the public and private key as well as the owner of the key.

{
   "@": "<https://payswarm.example.com/i/bob/keys/1>",
   "a": "<sig:Key>",
   "ps:owner": "<https://payswarm.example.com/i/bob>",
   "sig:privateKeyPem": "-----BEGIN PUBLIC KEY-----\nMII8YbF3s8q3c...j8Fk88FsRa3K\n-----END PUBLIC KEY-----\n"
   "sig:publicKeyPem": "-----BEGIN PRIVATE KEY-----\nMIIBG0BA...OClDQAB\n-----END PRIVATE KEY-----\n"
}

2.2 Signature

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

Status
unstable
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. For a signature sub-class to be of use, it should express at least three signature algorithm properties: sig:canonicalizationMethod, sig:digestMethod, and sig:signingAlgorithm.

2.3 JsonldSignature

A JSON-LD signature is used for digital signatures on RDF graphs expressed in JSON-LD format. The default canonicalization mechanism is specified in the JSON-LD specification, which effectively resolves all CURIEs and eliminates all whitespace in the markup. The default digest method uses the SHA-1 algorithm. The default signature mechanism uses a SHA-1 digest and RSA to perform the digital signature.

Status
unstable
Parent Class
sig:Signature
Properties
sig:signer, sig:signatureValue
Signing Properties
Default Canonicalization Method
http://purl.org/jsonld#standard-canonicalization
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 canonicalization algorithm for JSON-LD.

{
    "a": "<foaf:Person>",
    "foaf:name": "Manu Sporny",
    "foaf:homepage": "<http://manu.sporny.org/>",
    "sig:signature: 
    {
        "a": "<sig:JsonldSignature>",
        "sig:signer": "<http://manu.sporny.org/webid#key-5>",
        "sig:signatureValue": "OGQzNGVkMzVmMmQ3ODIyOWM32MzQzNmExMgoYzI4ZDY3NjI4NTIyZTk="
    }
}

2.4 XmlSignature

An XML signature is used for digital signatures in RDF graphs where the data is expressed in an XML format. The default canonicalization mechanism is specifiedspecified in the XML Canonicalization specification. The default digest method uses the SHA-1 algorithm. The default signature mechanism uses a SHA-1 digest and RSA to perform the digital signature.

Status
unstable
Parent Class
sig:Signature
Properties
sig:signer, sig:signatureValue
Signing Properties
Default Canonicalization Method
http://www.w3.org/2006/12/xml-c14n11
Default Digest Method
http://www.w3.org/2000/09/xmldsig#sha1
Default Signing Algorithm
http://www.w3.org/2000/09/xmldsig#rsa-sha1

The signature example below demonstrates how XML data can be expressed and digitally signed in an RDF graph.

@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix sig: <http://purl.org/signature#> .
_:bnode1 rdf:type sig:XmlSignature ;
         sig:data "<mydata>Some data</mydata>" ;
         sig:signer <http://example.com/people/john-doe#key-5> ;
         sig:signatureValue "OGQzNGVkMzVmMmQ3ODIyOWM32MzQzNmExMgoYzI4ZDY3NjI4NTIyZTk=" .
}

Signature defaults can be overridden by specifying the non-default values like so:

@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix sig: <http://purl.org/signature#> .
_:bnode1 rdf:type sig:XmlSignature ;
         sig:data "<mydata>Some data</mydata>" ;
         sig:canonicalizationMethod <http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments>;
         sig:digestMethod <http://example.org/digestMethods#sha1024>;
         sig:signingAlgorithm <http://example.org/signatureMethods#superSecretSignatureAlgorithm>;
         sig:signer <http://example.com/people/john-doe#key-5> ;
         sig:signatureValue "3ODIyOWOGQzNGVkMzVmMmQM32MzQzNmExMgNjI4NTIyZTkoYzI4ZDY3=" .
}

3. Properties

3.1 canonicalizationMethod

The canonicalization method is used to transform the target graph, or the sig:data property into a form that can be passed to a cryptographic digest method. The digest is then digitally signed using a digital signature algorithm. Canonicalization ensures that a piece of software that is generating a digital signature is able to simplify the input graph or data to a form that is the same across all programs regardless of how much whitespace and unnecessary formatting information is included in the input data.

Status
unstable
Domain
sig:Signature
Range
xsd:anyURI, xsd:string

While the canonicalization method is usually associated with the digital signature class defaults, it can also be specified in a signature to override the defaults:

{
    "a": "<foaf:Person>",
    "foaf:name": "Joe Bob",
    "foaf:homepage": "<http://example.org/joebob>",
    "sig:signature: 
    {
        "a": "<sig:JsonldSignature>",
        "sig:canonicazationMethod": "<http://example.com/vocab#fancy-canonicalization-method>",
        "sig:signer": "<http://example.com/people/john-doe#key-5>",
        "sig:signatureValue": "Q3ODIyOWM32OGQzNGVkMzVmMmMzQzNmExMgoYzI43NjI4NTIyZTkZDY="
    }
}

3.2 data

Used to specify the data associated with a signature if the information should not be gleaned from the containing graph.

Status
unstable
Domain
sig:Signature
Range
xsd:string, rdf:XMLLiteral

The following example demonstrates how the data property can be specified explicitly. This example is a bit strange as a JSON-LD signature would typically be found in the same graph as the data that was signed, but the example below shows that signatures can be specified in a number of flexible ways:

{
    "a": "<sig:JsonldSignature>",
    "sig:data": "{ \"#\" : { \"foaf\" : \"http://xmlns.com/foaf/0.1\" }, \"a\": \"<foaf:Person>\", \"foaf:name\": \"Joe Bob\" }",
    "sig:signer": "<http://example.com/people/john-doe#key-5>",
    "sig:signatureValue": "kMzVmMmQ3OgoYzIOGQzNGV4ZDY3NjI4NTIyZTkDIyOWM32MzQzNmExM="
}

3.3 digestMethod

The digest method is used to specify the cryptographic function to use when generating the data to be digitally signed. Typically, text to be signed goes through three steps: 1) canonicalization, 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 rarely needs to be used in practice.

Status
unstable
Domain
sig:Signature
Range
xsd:anyURI, xsd:string

The following example shows how the digest method can override the default digest method specified by the signature class:

{
    "a": "<foaf:Person>",
    "foaf:name": "Jane Doe",
    "foaf:homepage": "<http://example.org/jane>",
    "sig:signature: 
    {
        "a": "<sig:JsonldSignature>",
        "sig:digestMethod": "<http://example.com/digests#sha512>",
        "sig:signer": "<http://example.com/people/john-doe#key-5>",
        "sig:signatureValue": "OGQzNGVkMzVm4NTIyZTkZDYMmMzQzNmExMgoYzI43Q3ODIyOWM32NjI="
    }
}

3.4 publicKey

A public key property refers to a URL that contains information about a public key.

Status
unstable
Domain
sig:Key, owl:Thing
Range
xsd:anyURI

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

{
   "@": "<https://payswarm.example.com/i/bob/keys/1>",
   "a": "<sig:Key>",
   "ps:owner": "<https://payswarm.example.com/i/bob>",
   "sig:publicKeyPem": "-----BEGIN PRIVATE KEY-----\nMIIBG0BA...OClDQAB\n-----END PRIVATE KEY-----\n"
}

3.5 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
unstable
Domain
sig:Key, owl:Thing
Range
xsd:string

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

{
   "@": "<https://payswarm.example.com/i/bob/keys/1>",
   "a": "<sig:Key>",
   "ps:owner": "<https://payswarm.example.com/i/bob>",
   "sig:privateKeyPem": "-----BEGIN PUBLIC KEY-----\nMII8YbF3s8q3c...j8Fk88FsRa3K\n-----END PUBLIC KEY-----\n"
   "sig:publicKeyPem": "-----BEGIN PRIVATE KEY-----\nMIIBG0BA...OClDQAB\n-----END PRIVATE KEY-----\n"
}

3.6 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
unstable
Domain
sig:Key, owl:Thing
Range
xsd:string

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

{
   "@": "<https://payswarm.example.com/i/bob/keys/1>",
   "ps:owner": "<https://payswarm.example.com/i/bob>",
   "ps:publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMIIBG0BA...OClDQAB\n-----END PUBLIC KEY-----\n"
}

3.7 signature

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

Status
unstable
Domain
owl:Thing
Range
sig: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:

{
    "@": "<http://example.com/people#jane",
    "a": "<foaf:Person>",
    "foaf:name": "Jane Doe",
    "foaf:homepage": "<http://example.org/jane>",
    "sig:signature: 
    {
        "a": "<sig:JsonldSignature>",
        "sig:signer": "<http://example.com/people/john-doe#key-5>",
        "sig:signatureValue": "OGQzNGVkMzVm4NTIyZTkZDYMmMzQzNmExMgoYzI43Q3ODIyOWM32NjI="
    }
}

3.8 signatureFor

A signatureFor property can be used to express a digital signature of a graph that is external to the local environment, or a sub-graph of the local environment.

Is this really that much different from sig:data? Can we collapse the two properties into one?

Status
unstable
Domain
sig:Signature
Range
xsd:anyURI, owl:Thing

{
    "@": "<http://example.com/people#jane",
    "a": "<foaf:Person>",
    "foaf:name": "Jane Doe",
    "foaf:homepage": "<http://example.org/jane>",
    "foaf:knows":
    {
        "@": "<http://example.com/people#john",
        "a": "<foaf:Person>",
        "foaf:name": "John Smith",
        "foaf:homepage": "<http://example.org/john>",
    },
    "sig:signature: 
    {
        "a": "<sig:JsonldSignature>",
        "sig:signatureFor" : "<http://example.org/people#john>",
        "sig:signer": "<http://example.com/people/john-doe#key-5>",
        "sig:signatureValue": "IyQ3ODOGQzN4NTIyZTkZDYMmMzQzNmExMgoYzI43OWM32NjIGVkMzVm="
    }
}

3.9 signer

The signer property specifies a location where you may retrieve information about the public key that created the digital signature in order to verify the authenticity of the signature, as well as any owner information related to the public key.

Status
unstable
Domain
TBD
Range
TBD

The following example expresses the location of the semantic information about the public key that can be used to verify the digital signature:

{
    "@": "<http://example.com/people#jane",
    "a": "<foaf:Person>",
    "foaf:name": "Jane Doe",
    "foaf:homepage": "<http://example.org/jane>",
    "sig:signature: 
    {
        "a": "<sig:JsonldSignature>",
        "sig:signer": "<http://example.com/people/john-doe#key-5>",
        "sig:signatureValue": "OGQzNGVkMzVm4NTIyZTkZDYMmMzQzNmExMgoYzI43Q3ODIyOWM32NjI="
    }
}

3.10 signatureValue

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

Status
unstable
Domain
sig:Signature
Range
xsd:string

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

{
    "@": "<http://example.com/people#jane",
    "a": "<foaf:Person>",
    "foaf:name": "Jane Doe",
    "foaf:homepage": "<http://example.org/jane>",
    "sig:signature: 
    {
        "a": "<sig:JsonldSignature>",
        "sig:signer": "<http://example.com/people/john-doe#key-5>",
        "sig:signatureValue": "OGQzNGVkMzVm4NTIyZTkZDYMmMzQzNmExMgoYzI43Q3ODIyOWM32NjI="
    }
}

3.11 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) canonicalization, 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.

Status
unstable
Domain
sig:Signature
Range
xsd:anyURI, xsd:string

{
    "a": "<foaf:Person>",
    "foaf:name": "Joe Bob",
    "foaf:homepage": "<http://example.org/joebob>",
    "sig:signature: 
    {
        "a": "<sig:JsonldSignature>",
        "sig:signingAlgorithm": "<http://example.com/vocab#special-signing-algorithm>",
        "sig:signer": "<http://example.com/people/john-doe#key-5>",
        "sig:signatureValue": "P9fDIyOWM32OGQzNGVkMzVmMmMzQzNmExMgoYzI43NjI4k3FJKs98f="
    }
}

A. References

A.1 Normative references

No normative references.

A.2 Informative references

No informative references.