Skip to content

Commit fab2571

Browse files
Added meta.security object and Security documentation (#137)
As per issue #129. This commit adds support for using the Strong Distribution Model for ensuring the integrity of events and authenticity of event authors. This is achieved via an optional meta.security.sdm object, with two required properties: authorIdentity and encryptedDigest. Schemas have been updated accordingly, and one example (ArtP) provided.
1 parent d9de812 commit fab2571

File tree

24 files changed

+489
-2
lines changed

24 files changed

+489
-2
lines changed

README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ __IMPORTANT NOTICE:__ The contents of this repository currectly reflect a __DRAF
1818
1. [The Links Object](./eiffel-syntax-and-usage/the-links-object.md)
1919
1. [Versioning](./eiffel-syntax-and-usage/versioning.md)
2020
1. [Compositions and Validity Checking](./eiffel-syntax-and-usage/compositions-and-validity-checking.md)
21+
1. [Security](./eiffel-syntax-and-usage/security.md)
2122
1. The Eiffel Vocabulary
2223
1. [EiffelActivityTriggeredEvent (ActT)](./eiffel-vocabulary/EiffelActivityTriggeredEvent.md)
2324
1. [EiffelActivityCanceledEvent (ActC)](./eiffel-vocabulary/EiffelActivityCanceledEvent.md)
Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Security
2+
Let us begin by establishing that the Eiffel protocol by itself can be considered neither _secure_ nor _insecure_, any more than English is secure or French is insecure. Security is not a property of the language or the protocol as such, but of how it is communicated and managed. That being said, security is a highly relevant concern, and where feasible Eiffel supports it. It is important to understand that security is a broad concept, however, and that feasibility varies depending on the type of security in question. In literature, the three key concepts of security (sometimes referred to as the CIA triad) are confidentiality, integrity and availability. We will discuss each of these in turn.
3+
4+
## Confidentiality
5+
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.
6+
7+
## Integrity
8+
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).
9+
10+
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.
11+
12+
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.
13+
14+
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).
15+
16+
## Availability
17+
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-syntax-and-usage/the-meta-object.md

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -86,11 +86,34 @@ __Format:__ URI
8686
__Required:__ No
8787
__Description:__ The URI of, related to or describing the event sender.
8888

89+
### meta.security
90+
__Type:__ Object
91+
__Format:__
92+
__Required:__ No
93+
__Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information.
94+
95+
#### meta.security.sdm
96+
__Type:__ Object
97+
__Format:__
98+
__Required:__ No
99+
__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_.
100+
101+
##### meta.security.sdm.authorIdentity
102+
__Type:__ String
103+
__Format:__
104+
__Required:__ Yes
105+
__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.
106+
107+
##### meta.security.sdm.encryptedDigest
108+
__Type:__ String
109+
__Format:__
110+
__Required:__ Yes
111+
__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.
89112

90113
 
91114
 
92115

93116
------------------
94117
 
95118

96-
<a name="footnote1">1</a>: Event types are versioned independently from one another. There are three important consequences of this. First, any change to __meta__ requires all events to be updated. Second, any schema of a specific version of an event must also include the __meta__ object – specifically as it is defined for that version of the event. Third, consumers should be prepared to receive events of varying __meta__ contents. The exception to this are the __meta.type__ and __meta.version__ fields, which are always assumed to be present change.
119+
<a name="footnote1">1</a>: Event types are versioned independently from one another. There are three important consequences of this. First, any change to __meta__ requires all events to be updated. Second, any schema of a specific version of an event must also include the __meta__ object – specifically as it is defined for that version of the event. Third, consumers should be prepared to receive events of varying __meta__ contents. The exception to this are the __meta.type__ and __meta.version__ fields, which are always assumed to be present change.

examples/events/EiffelArtifactPublishedEvent/simple.json

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,13 @@
33
"type": "EiffelArtifactPublishedEvent",
44
"version": "1.0.0",
55
"time": 1234567890,
6-
"id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee0"
6+
"id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee0",
7+
"security": {
8+
"sdm": {
9+
"authorIdentity": "MyCompany/JohnDoe",
10+
"encryptedDigest": "a7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a"
11+
}
12+
}
713
},
814
"data": {
915
"locations": [

schemas/EiffelActivityCanceledEvent/1.0.0.json

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,28 @@
6363
}
6464
},
6565
"additionalProperties": false
66+
},
67+
"security": {
68+
"type": "object",
69+
"properties": {
70+
"sdm": {
71+
"type": "object",
72+
"properties": {
73+
"authorIdentity": {
74+
"type": "string"
75+
},
76+
"encryptedDigest": {
77+
"type": "string"
78+
}
79+
},
80+
"required": [
81+
"authorIdentity",
82+
"encryptedDigest"
83+
],
84+
"additionalProperties": false
85+
}
86+
},
87+
"additionalProperties": false
6688
}
6789
},
6890
"required": [

schemas/EiffelActivityFinishedEvent/1.0.0.json

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,28 @@
6363
}
6464
},
6565
"additionalProperties": false
66+
},
67+
"security": {
68+
"type": "object",
69+
"properties": {
70+
"sdm": {
71+
"type": "object",
72+
"properties": {
73+
"authorIdentity": {
74+
"type": "string"
75+
},
76+
"encryptedDigest": {
77+
"type": "string"
78+
}
79+
},
80+
"required": [
81+
"authorIdentity",
82+
"encryptedDigest"
83+
],
84+
"additionalProperties": false
85+
}
86+
},
87+
"additionalProperties": false
6688
}
6789
},
6890
"required": [

schemas/EiffelActivityStartedEvent/1.0.0.json

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,28 @@
6363
}
6464
},
6565
"additionalProperties": false
66+
},
67+
"security": {
68+
"type": "object",
69+
"properties": {
70+
"sdm": {
71+
"type": "object",
72+
"properties": {
73+
"authorIdentity": {
74+
"type": "string"
75+
},
76+
"encryptedDigest": {
77+
"type": "string"
78+
}
79+
},
80+
"required": [
81+
"authorIdentity",
82+
"encryptedDigest"
83+
],
84+
"additionalProperties": false
85+
}
86+
},
87+
"additionalProperties": false
6688
}
6789
},
6890
"required": [

schemas/EiffelActivityTriggeredEvent/1.0.0.json

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,28 @@
6363
}
6464
},
6565
"additionalProperties": false
66+
},
67+
"security": {
68+
"type": "object",
69+
"properties": {
70+
"sdm": {
71+
"type": "object",
72+
"properties": {
73+
"authorIdentity": {
74+
"type": "string"
75+
},
76+
"encryptedDigest": {
77+
"type": "string"
78+
}
79+
},
80+
"required": [
81+
"authorIdentity",
82+
"encryptedDigest"
83+
],
84+
"additionalProperties": false
85+
}
86+
},
87+
"additionalProperties": false
6688
}
6789
},
6890
"required": [

schemas/EiffelAnnouncementPublishedEvent/1.0.0.json

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,28 @@
6363
}
6464
},
6565
"additionalProperties": false
66+
},
67+
"security": {
68+
"type": "object",
69+
"properties": {
70+
"sdm": {
71+
"type": "object",
72+
"properties": {
73+
"authorIdentity": {
74+
"type": "string"
75+
},
76+
"encryptedDigest": {
77+
"type": "string"
78+
}
79+
},
80+
"required": [
81+
"authorIdentity",
82+
"encryptedDigest"
83+
],
84+
"additionalProperties": false
85+
}
86+
},
87+
"additionalProperties": false
6688
}
6789
},
6890
"required": [

schemas/EiffelArtifactCreatedEvent/1.0.0.json

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,28 @@
6363
}
6464
},
6565
"additionalProperties": false
66+
},
67+
"security": {
68+
"type": "object",
69+
"properties": {
70+
"sdm": {
71+
"type": "object",
72+
"properties": {
73+
"authorIdentity": {
74+
"type": "string"
75+
},
76+
"encryptedDigest": {
77+
"type": "string"
78+
}
79+
},
80+
"required": [
81+
"authorIdentity",
82+
"encryptedDigest"
83+
],
84+
"additionalProperties": false
85+
}
86+
},
87+
"additionalProperties": false
6688
}
6789
},
6890
"required": [

0 commit comments

Comments
 (0)