;;;; Copyright (C) 2020 Julien Lepiller ;;;; ;;;; This library is free software; you can redistribute it and/or ;;;; modify it under the terms of the GNU Lesser General Public ;;;; License as published by the Free Software Foundation; either ;;;; version 3 of the License, or (at your option) any later version. ;;;; ;;;; This library is distributed in the hope that it will be useful, ;;;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU ;;;; Lesser General Public License for more details. ;;;; ;;;; You should have received a copy of the GNU Lesser General Public ;;;; License along with this library; if not, write to the Free Software ;;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ;;;; (define-module (http-signature vocabulary) #:use-module (activitystreams ontology) #:use-module (activitystreams predicates) #:use-module (ice-9 match) #:use-module (jsonld json) #:use-module (web uri) #:export (security-ontology)) (define-public vocab "https://w3id.org/security#") (define* (make-sec-type label #:key (uri (string-append vocab label)) (comment "") (subclass-of '())) (build-as-type label #:uri uri #:comment comment #:subclass-of subclass-of)) (define* (make-sec-property label domain range #:key (uri (string-append vocab label)) (functional? #f) (subproperty-of '()) (comment "")) (build-as-property label domain range #:uri uri #:functional? functional? #:subproperty-of subproperty-of #:comment comment)) ;; Classes (define-public Digest (make-sec-type "Digest" #:comment "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.")) (define-public EncryptedMessage (make-sec-type "EncryptedMessage" #:comment "A class of messages that are obfuscated in some cryptographic manner. These messages are incredibly difficult to decrypt without the proper decryption key.")) (define-public Signature (make-sec-type "Signature" #:comment "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.")) (define-public GraphSignature2012 (make-sec-type "GraphSignature2012" #:subclass-of (list Signature) #:comment "A graph signature is used for digital signatures on RDF graphs. The default canonicalization mechanism is specified in the RDF Graph normalization specification, which effectively deterministically names all unnamed nodes. The default signature mechanism uses a SHA-256 digest and RSA to perform the digital signature.")) (define-public LinkedDataSignature2015 (make-sec-type "LinkedDataSignature2015" #:subclass-of (list Signature) #:comment "A Linked Data signature is used for digital signatures on RDF Datasets. The default canonicalization mechanism is specified in the RDF Dataset Normalization specification, which effectively deterministically names all unnamed nodes. The default signature mechanism uses a SHA-256 digest and RSA to perform the digital signature. This signature uses a algorithm for producing the data that it signs and verifies that is different from other Linked Data signatures.")) (define-public LinkedDataSignature2016 (make-sec-type "LinkedDataSignature2016" #:subclass-of (list Signature) #:comment "A Linked Data signature is used for digital signatures on RDF Datasets. The default canonicalization mechanism is specified in the RDF Dataset Normalization specification, which effectively deterministically names all unnamed nodes. The default signature mechanism uses a SHA-256 digest and RSA to perform the digital signature.")) (define-public Key (make-sec-type "Key" #:comment "This class represents a cryptographic key that may be used for encryption, decryption, or digitally signing data.")) (define-public sec-types (list Digest EncryptedMessage Signature GraphSignature2012 LinkedDataSignature2015 LinkedDataSignature2016 Key)) (define-public authenticationTag (make-sec-property "authenticationTag" "EncryptedMessage" string? #:comment "Not specified")) (define-public creator (make-sec-property "creator" "Signature" uri? #:comment "Not specified")) (define-public cipherAlgorithm (make-sec-property "cipherAlgorithm" "EncryptedMessage" string? #:comment "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.")) (define-public cipherData (make-sec-property "cipherData" "EncryptedMessage" string? #:comment "Cipher data an opaque blob of information that is used to specify an encrypted message.")) (define-public digestAlgorithm (make-sec-property "digestAlgorithm" "Digest" string? #:comment "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) 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 is typically used to specify information for a signature algorithm.")) (define-public digestValue (make-sec-property "digestValue" "Digest" string? #:comment "The digest value is used to express the output of the digest algorithm expressed in Base-16 (hexadecimal) format.")) (define-public cipherKey (make-sec-property "cipherKey" "EncryptedMessage" string? #:comment "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.")) (define-public expires (make-sec-property "expires" "" string? #:comment "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.")) (define-public initializationVector (make-sec-property "initializationVector" "EncryptedMessage" string? #:comment "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.")) (define-public nonce (make-sec-property "nonce" "" string? #:comment "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.")) (define-public canonicalizationAlgorithm (make-sec-property "canonicalizationAlgorithm" "" (list uri? string?) #:comment "The canonicalization 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. Canonicalization 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.")) (define-public owner (make-sec-property "owner" "Key" uri? #:comment "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.")) (define-public password (make-sec-property "password" "" string? #:comment "A secret that is used to generate a key that can be used to encrypt or decrypt message. It is typically a string value.")) (define-public privateKeyPem (make-sec-property "privateKeyPem" "Key" string? #:comment "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.")) (define-public publicKey (make-sec-property "publicKey" "EncryptedMessage" uri? #:comment "A public key property is used to specify a URL that contains information about a public key.")) (define-public publicKeyPem (make-sec-property "publicKeyPem" "Key" string? #:comment "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.")) (define-public publicKeyService (make-sec-property "publicKeyService" "" string? #:comment "The publicKeyService property is used to express the REST URL that provides public key management services as defined by the Web Key specification.")) (define-public revoked (make-sec-property "revoked" "" date? #:comment "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.")) (define-public signature (make-sec-property ;; XXX: not correct, there is no defined domain "signature" "Object" "Signature" #:comment "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.")) (define-public signatureValue (make-sec-property "signatureValue" "Signature" string? #:comment "The signature value is used to express the output of the signature algorithm expressed in base-64 format.")) (define-public signatureAlgorithm (make-sec-property "signatureAlgorithm" "Signature" string? #:comment "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) 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 signature algorithm, so this property rarely needs to be used in practice when specifying digital signatures.")) (define sec-properties (list cipherAlgorithm cipherData digestAlgorithm digestValue cipherKey expires initializationVector nonce canonicalizationAlgorithm owner password privateKeyPem publicKey publicKeyPem publicKeyService revoked signature signatureValue signatureAlgorithm)) (define security-ontology (make-ontology '("https://w3id.org/security/v1") sec-types sec-properties))