Improved security support (#197)

Updated meta.security according to Issue #185. Documentation and schema of all event types has been updated, resulting in a major version step of all event types. Where applicable, examples have been updated, while some examples have been preserved to demonstrate previous behavior in older versions.

Description of information integrity protection has been updated in security.md.

Author: d-stahl-ericsson

eiffel-syntax-and-usage/security.md

@@ -1,5 +1,5 @@
 <!---
-   Copyright 2017 Ericsson AB.
+   Copyright 2017-2018 Ericsson AB.
    For a full list of individual contributors, please see the commit history.
 
    Licensed under the Apache License, Version 2.0 (the "License");
@@ -22,13 +22,13 @@ Let us begin by establishing that the Eiffel protocol by itself can be considere
 In the words of ISO27000, confidentiality means that "information is not made available or disclosed to unauthorized individuals, entities, or processes". This can be achieved through multiple (and often complementary) means, such as encryption and access control. The Eiffel protocol itself cannot support confidentiality; instead it is a property of the systems used to transport, process and store the Eiffel events. In other words, if the confidentiality of information communicated as Eiffel events is a concern for you, then you are recommended to take appropriate action to ensure the confidentiality of your data, both at rest and in transit, e.g. through encryption.
 
 ## Integrity
-In information security, integrity refers to the accuracy and completeness of data. In other words, safeguarding integrity requires protection against both malicious and unintentional tampering with or corruption of data in an unauthorized or undetected manner. This cannot be _solved_ by a communication protocol, as it relies on adequate infrastructure and processes for managing the data, but it can be _supported_. Eiffel supports data integrity through digital signing, according to the [Strong Distribution Model](http://www.cryptnet.net/fdp/crypto/strong_distro.html).
+In information security, integrity refers to the accuracy and completeness of data. In other words, safeguarding integrity requires protection against both malicious and unintentional tampering with or corruption of data in an unauthorized or undetected manner. This cannot be _solved_ by a communication protocol, as it relies on adequate infrastructure and processes for managing the data, but it can be _supported_. Eiffel supports data integrity through digital signatures.
 
 A digital signature is a combination of hashing technology and encryption. Hash functions are commonly used to ensure data integrity and are familiar to most software professionals. By using checksums or hash values (particularly hash values, or _digests_, produced by cryptographic hash functions such as the SHA series), any piece of data of arbitrary length is computed into a fixed length digest, with any alteration of the input data resulting in a different digest. Consequently, as long as the digest of the received data matches the digest of the data sent, its integrity can be verified. Unfortunately, the digest must be securely communicated: any malicious attacker able to not only manipulate the data but also the digest can make a corrupted message appear authentic. This is why digital signing also employs encryption.
 
-In the Strong Distribution Model, the author of the data encrypts the digest using a _private key_. A private key is one half of an asymmetric _key pair_, with a matching _public key_ making up the other half. As the names suggest, the private key is kept secret, while the public key is distributed. The two keys in a pair are matches in the sense that one key can decrypt data encrypted by the other, and vice versa. In other words, if the recipient of a message can identify the correct public key and use it to decrypt the digest, and that digest turns out to be correct, both the identity of the author and the integrity of the data can be verified.
+The Eiffel protocol's support is influenced by [JSON Web Signatures (JWS)](https://tools.ietf.org/html/rfc7515), with slight modifications to allow inclusion of the signature within the event message itself, rather than as part of a header. This serves to keep every Eiffel event self-contained, with information integrity protection optional for the producer to include and optional for the consumer to consider. Note that this optionality does not in any way lessen the strength of the security provided: it is always up to the recipient of an unprotected Eiffel event to decide whether to trust it or not. In this sense, Eiffel support of data integrity is very similar to that employed by other document formats, such as the [Portable Document Format](http://www.adobe.com/devnet/pdf/pdf_reference.html).
 
-In support of this model, Eiffel events optionally include properties for communicating author identity and the encrypted digest as part of the __meta.security__ object. In combination, these two properties enable enforcement of the Strong Distribution Model. They are kept optional, however, as the Eiffel protocol itself leaves the decision to the user whether to make use of this security feature. Note that this optionality does not in any way lessen the strength of the security model: it is always up to the recipient of an unprotected Eiffel event to decide whether to trust it or not. In this sense, Eiffel support of data integrity is very similar to that employed by other document formats, such as the [Portable Document Format](http://www.adobe.com/devnet/pdf/pdf_reference.html).
+Apart from digital signing, the Eiffel protocol also supports author identification using [Distinguished Names](https://tools.ietf.org/html/rfc2253) and event sequence integrity protection. Please see the documentation of each event type for further information and detailed instructions on correct usage.
 
 ## Availability
-Availability of information communicated over the Eiffel protocol is a property of the communication channels and storage solutions used. In other words, similarly to confidentiality, it is an infrastructural concern and external to the protocol itself.
+Availability of information communicated over the Eiffel protocol is a property of the communication channels and storage solutions used. In other words, similarly to confidentiality, it is an infrastructural concern and external to the protocol itself.

eiffel-vocabulary/EiffelActivityCanceledEvent.md

@@ -123,28 +123,64 @@ __Format:__
 __Required:__ No  
 __Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information.
 
-#### meta.security.sdm
+#### meta.security.authorIdentity
+__Type:__ String  
+__Format:__ [Distinguished Name](https://tools.ietf.org/html/rfc2253)  
+__Required:__ Yes  
+__Description:__ The identity of the author of the event. This property is intended to enable the recipient to identify the author of the event contents and/or look up the appropriate public key for decrypting the __meta.security.integrityProtection.signature__ value and thereby verifying author identity and data integrity.
+
+#### meta.security.integrityProtection
 __Type:__ Object  
 __Format:__  
 __Required:__ No  
-__Description:__ An optional object for properties supporting the [Strong Distribution Model](http://www.cryptnet.net/fdp/crypto/strong_distro.html). Note that this only addressed the _integrity_ of the Eiffel event, not its _confidentiality_ or _availability_.
+__Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object:
+1. Generate the entire event, but with the __meta.security.integrityProtection.signature__ value set to an empty string.
+1. Serialize the event on [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00).
+1. Generate the signature using the __meta.security.integrityProtection.alg__ algorithm.
+1. Set the __meta.security.integrityProtection.signature__ value to the resulting signature while maintaining Canonical JSON Form.
+To verify the integrity of the event, the consumer then resets __meta.security.integrityProtection.signature__ to an empty string and ensures Canonical JSON Form before verifying the signature.
+
+##### meta.security.integrityProtection.alg
+__Type:__ String  
+__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none"  
+__Required:__ Yes  
+__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none".
 
-##### meta.security.sdm.authorIdentity
+##### meta.security.integrityProtection.signature
 __Type:__ String  
 __Format:__  
 __Required:__ Yes  
-__Description:__ The identity of the author of the event. This property is intended to enable the recipient to look up the appropriate public key for decrypting the digest and thereby verifying author identity and data integrity. The format of the author identity varies depending on the key infrastructure solution used. Note that this requires the presence of a Trusted Authority (TA) which the recipient can query for the correct public key. The identity and location of the TA must never be included in the event itself, as this would compromise the security of the solution.
+__Description:__ The signature produced by the signing algorithm.
+
+##### meta.security.integrityProtection.publicKey
+__Type:__ String  
+__Format:__  
+__Required:__ No  
+__Description:__ The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via __meta.security.integrityProtection__.
+
+#### meta.security.sequenceProtection
+__Type:__ Object[]  
+__Format:__  
+__Required:__ No  
+__Description:__ An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment __meta.security.sequenceProtection.position__ by 1. The first event produced in a given named sequence SHALL numbered 1.
 
-##### meta.security.sdm.encryptedDigest
+##### meta.security.sequenceProtection.sequenceName
 __Type:__ String  
 __Format:__  
 __Required:__ Yes  
-__Description:__ The encrypted digest. The cryptographic hash function and the decryption algorithm to use, similarly to the Trusted Authority (TA), must be known to the recipient. Note that the digest of the entire event is affected by the value of this property. For this reason the input to the hash function SHALL be the entire event unaltered in all parts except for this property, which SHALL be replaced by an empty string.
+__Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event.
+
+##### meta.security.sequenceProtection.position
+__Type:__ Integer  
+__Format:__  
+__Required:__ Yes  
+__Description:__ The number of the event within the named sequence.
 
 ## Version History
 | Version   | Introduced in                                          | Changes                                 |
 | --------- | ------------------------------------------------------ | --------------------------------------- |
-| 2.0.0     | Current version                                        | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |
+| 3.0.0     | Current version                                        | Improved information integrity protection | (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)) |
+| 2.0.0     | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityCanceledEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |
 | 1.1.0     | [edition-toulouse](../../../tree/edition-toulouse)     | Multiple links of type FLOW_CONTEXT allowed. |
 | 1.0.0     | [edition-bordeaux](../../../tree/edition-bordeaux)     | Initial version.                        |
 

eiffel-vocabulary/EiffelActivityFinishedEvent.md

@@ -155,28 +155,64 @@ __Format:__
 __Required:__ No  
 __Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information.
 
-#### meta.security.sdm
+#### meta.security.authorIdentity
+__Type:__ String  
+__Format:__ [Distinguished Name](https://tools.ietf.org/html/rfc2253)  
+__Required:__ Yes  
+__Description:__ The identity of the author of the event. This property is intended to enable the recipient to identify the author of the event contents and/or look up the appropriate public key for decrypting the __meta.security.integrityProtection.signature__ value and thereby verifying author identity and data integrity.
+
+#### meta.security.integrityProtection
 __Type:__ Object  
 __Format:__  
 __Required:__ No  
-__Description:__ An optional object for properties supporting the [Strong Distribution Model](http://www.cryptnet.net/fdp/crypto/strong_distro.html). Note that this only addressed the _integrity_ of the Eiffel event, not its _confidentiality_ or _availability_.
+__Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object:
+1. Generate the entire event, but with the __meta.security.integrityProtection.signature__ value set to an empty string.
+1. Serialize the event on [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00).
+1. Generate the signature using the __meta.security.integrityProtection.alg__ algorithm.
+1. Set the __meta.security.integrityProtection.signature__ value to the resulting signature while maintaining Canonical JSON Form.
+To verify the integrity of the event, the consumer then resets __meta.security.integrityProtection.signature__ to an empty string and ensures Canonical JSON Form before verifying the signature.
+
+##### meta.security.integrityProtection.alg
+__Type:__ String  
+__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none"  
+__Required:__ Yes  
+__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none".
 
-##### meta.security.sdm.authorIdentity
+##### meta.security.integrityProtection.signature
 __Type:__ String  
 __Format:__  
 __Required:__ Yes  
-__Description:__ The identity of the author of the event. This property is intended to enable the recipient to look up the appropriate public key for decrypting the digest and thereby verifying author identity and data integrity. The format of the author identity varies depending on the key infrastructure solution used. Note that this requires the presence of a Trusted Authority (TA) which the recipient can query for the correct public key. The identity and location of the TA must never be included in the event itself, as this would compromise the security of the solution.
+__Description:__ The signature produced by the signing algorithm.
 
-##### meta.security.sdm.encryptedDigest
+##### meta.security.integrityProtection.publicKey
 __Type:__ String  
 __Format:__  
+__Required:__ No  
+__Description:__ The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via __meta.security.integrityProtection__.
+
+#### meta.security.sequenceProtection
+__Type:__ Object[]  
+__Format:__  
+__Required:__ No  
+__Description:__ An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment __meta.security.sequenceProtection.position__ by 1. The first event produced in a given named sequence SHALL numbered 1.
+
+##### meta.security.sequenceProtection.sequenceName
+__Type:__ String  
+__Format:__  
+__Required:__ Yes  
+__Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event.
+
+##### meta.security.sequenceProtection.position
+__Type:__ Integer  
+__Format:__  
 __Required:__ Yes  
-__Description:__ The encrypted digest. The cryptographic hash function and the decryption algorithm to use, similarly to the Trusted Authority (TA), must be known to the recipient. Note that the digest of the entire event is affected by the value of this property. For this reason the input to the hash function SHALL be the entire event unaltered in all parts except for this property, which SHALL be replaced by an empty string.
+__Description:__ The number of the event within the named sequence.
 
 ## Version History
 | Version   | Introduced in                                          | Changes                                 |
 | --------- | ------------------------------------------------------ | --------------------------------------- |
-| 2.0.0     | Current version                                        | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |
+| 3.0.0     | Current version                                        | Improved information integrity protection | (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)) |
+| 2.0.0     | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityFinishedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |
 | 1.1.0     | [edition-toulouse](../../../tree/edition-toulouse)     | Multiple links of type FLOW_CONTEXT allowed. |
 | 1.0.0     | [edition-bordeaux](../../../tree/edition-bordeaux)     | Initial version.                        |