;;;; Copyright (C) 2020 Julien Lepiller <julien@lepiller.eu>
;;;; 
;;;; 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-signatures ontology)
  #:use-module (activitystreams activitystreams)
  #:use-module (ice-9 match)
  #:use-module (jsonld json)
  #:use-module (web uri)
  #:export (security-ontology))

(define sec:vocab "https://w3id.org/security#")

(define* (make-sec-type label #:key (uri (string-append sec:vocab label))
                        (comment "") (subclass-of '()))
  (make-as-type label #:uri uri #:comment comment #:subclass-of subclass-of))

(define* (make-as-property label domain range
                           #:key (uri (string-append as:vocab label))
                           (functional? #f) (subproperty-of '()) (comment ""))
  (make-as-property label domain range #:uri uri #:functional? functional?
                    #:subproperty-of subproperty-of #:comment comment))

;; Classes

(define sec: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 sec: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 sec: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 sec:GraphSignature2012
  (make-sec-type
    "GraphSignature2012"
    #:subclass-of (list sec: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 sec:LinkedDataSignature2015
  (make-sec-type
    "LinkedDataSignature2015"
    #:subclass-of (list sec: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 sec:LinkedDataSignature2016
  (make-sec-type
    "LinkedDataSignature2016"
    #:subclass-of (list sec: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 sec:Key
  (make-sec-type
    "Key"
    #:comment
    "This class represents a cryptographic key that may be used for encryption,
decryption, or digitally signing data."))

(define sec-types (list sec:Digest sec:EncryptedMessage sec:Signature
                        sec:GraphSignature2012 sec:LinkedDataSignature2015
                        sec:LinkedDataSignature2016 sec:Key))

(define sec:authenticationTag
  (make-sec-property
    "authenticationTag" "EncryptedMessage" string?
    #:coment
    "Not specified"))

(define sec:creator
  (make-sec-property
    "creator" "Signature" iri?
    #:coment
    "Not specified"))

(define sec: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 sec:cipherData
  (make-sec-property
    "cipherData" "EncryptedMessage" string?
    #:comment
    "Cipher data an opaque blob of information that is used to specify an
encrypted message."))

(define sec: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 sec: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 sec: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 sec: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 sec: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 sec: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 sec:canonicalizationAlgorithm
  (make-sec-property
    "canonicalizationAlgorithm" "" (list iri? 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 sec:owner
  (make-sec-property
    "owner" "Key" iri?
    #: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 sec: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 sec: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 sec:publicKey
  (make-sec-property
    "publicKey" "EncryptedMessage" iri?
    #:comment
    "A public key property is used to specify a URL that contains information
about a public key."))

(define sec: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 sec: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 sec: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 sec: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 sec: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 sec: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 sec:cipherAlgorithm sec:cipherData sec:digestAlgorithm sec:digestValue
        sec:cipherKey sec:expires sec:initializationVector sec:nonce
        sec:canonicalizationAlgorithm sec:owner sec:password
        sec:privateKeyPem sec:publicKey sec:publicKeyPem sec:publicKeyService
        sec:revoked sec:signature sec:signatureValue sec:signatureAlgorithm))

(define (security-ontology (append sec-types sec-properties)))