Commit 3e4b3ce5 authored by Peter Waher's avatar Peter Waher

End-to-End encryption

parent efc412df
......@@ -57,47 +57,98 @@ of new public keys for every single stanza. Instead, public/private keys are gen
of stanzas (a communication session), so that anyone starting a new E2E session with the entity does so using new keys. Public keys should still be short-lived,
as to not risk all historic messages to be broken, in case a public/private key pair is broken (forward secrecy).
RSA/AES
------------
AES-256 based hybrid ciphers
---------------------------------
The `rsaAes` algorithm combines RSA public/private keys with AES-256 symmetric cipher (using Cipher Block Chaining (CBC) and PKCS#7 padding) to establish
E2E between two entities. The RSA keys are used to encrypt the AES keys and initialization vectos, as well as to sign the payload by the sender (with SHA-256
and PKCS#1 v1.5 padding).
The AES-256 based hybrid ciphers presented here, use the AES-256 symmetric cipher to encrypt and decrypt content, while an asymmetric cipher provides the
AES key to use, as well as the content signature.
When E2E encrypting a `message` stanza, it is encrypted in its entirety, and then placed in an `aes` element. This is then sent in a **normal**,
unadorned `message` stanza by itself. The only attributes transferred from the original message, is the `id` and `to` attributes. The rest is protected
inside the encrypted element.
The Initiation Vector (IV) is calculated as follows, if nothing else is specified: It consists of the first 16 bytes of the
SHA-256 hash of the UTF-8 encoded concatenation of the `id`, `type`, `from` and `to` attributes of the stanza element, in that order.
The data to encrypt is prefixed by its length. The number of bytes used for the length is variable. The length is encoded as a sequence of 7-bit value bytes
(least significant part first). The 8th bit is used to inform the reader if more length bytes are following (1), or if the byte is the last length byte (0).
Following the encoded data length, follows the data to be encrypted. AES-256 has a block size of 16 bytes. Any unused bytes in the last block are filled
with random bytes before encryption. Blocks are chained together during encryption using Cipher Block Chaining (CBC).
When E2E encrypting a `message` stanza, it is encrypted in its entirety (entire XML stanza), and then placed in an `aes` element. This is then sent in a
**normal**, unadorned `message` stanza by itself. The only attributes transferred from the original message, are the `id` and `to` attributes. The rest is
protected inside the encrypted element.
When E2E encrypting an `iq` stanza, only the contents of the stanza is encrypted, and then placed in an `aes` element. This element is then sent in an
`iq` stanza with the same `type`, `id`, `to` and `from` attributes as the original stanza.
On both cases, the signatures are calculated on the unencrypted part of the payload that is to be encrypted. Encoding of XML text to bytes is always done
In both cases, the signatures are calculated on the unencrypted part of the payload that is to be encrypted. Encoding of XML text to bytes is always done
using UTF-8 encoding.
**Note**: If the initiation vector (`ivRsa`) is not provided, the Initiation Vector is the first 16 bytes of the SHA-256 hash of the UTF-8 encoded `id`
attribute value of the corresponding stanza (i.e. parent element), which must be provided, and unique for the current key, concatenated with the `type`
attribute value of the same element, concatenated with the `to` attribute of the same element.
### RSA/AES
The `rsaAes` algorithm combines RSA public/private keys with AES-256 symmetric cipher. The RSA keys are used to encrypt all AES keys used, as well as to
sign the payload by the sender (using SHA-256 and PKCS#1 v1.5 padding).
Support for RSA/AES encryption by an endpoint is shown by including the `rsaAes` element inside the `e2e` element in the `presence` stanza. To alert the
recipient that RSA/AES is used, the `keyRsa` and `signRsa` attributes are used by the `aes` element. `keyRsa` contains the Base-64 encoded RSA-encrypted
AES key to use to decrypt the payload. The `signRsa` attribute contains the signature of the decrypted payload, made by the sender.
### ECC/AES
Elliptic Curve Cryptography can be used together with the AES-256 symmetic cipher to encrypt content between endpoints. The specific Elliptic Curve is used
to derive a common key for AES (using ECDH), as well as to sign the unencrypted content (using ECDSA).
Support for EEC/AES encryption by an endpoint is shown by including the curve algorithm element inside the `e2e` element in the `presence` stanza. Each curve
element include `x` and `y` attributes containing the coordinates of the corresponding public key (most significant byte first, and then Base-64 encoded).
To alert the recipient that EEC/AES is used, the `ec`, `ecdsa1` and `ecdsa2` attributes are used by the `aes` element. `ec` contains the name of the curve
being used, while `ecdsa1` and `ecdsa2` contains the two signature integers generated by ECDSA (most significant byte first, and then Base-64 encoded).
| Curve Name | Element | Security level | RSA equivalent |
|:-----------|:----------|:--------------:|:--------------:|
| NIST P-192 | `p192Aes` | 96 | 1024 |
| NIST P-224 | `p224Aes` | 112 | 2048 |
| NIST P-256 | `p256Aes` | 128 | 3072 |
| NIST P-384 | `p384Aes` | 192 | 7680 |
| NIST P-521 | `p521Aes` | 256 | 15360 |
Examples
-----------
Example, when publishing public keys using `presence`:
```
<presence>
<show>chat</show>
<p2p extIp='93.184.216.34' extPort='49790' locIp='192.168.0.102' locPort='49790' xmlns='urn:ieee:iot:p2p:1.0'/>
<e2e xmlns='urn:ieee:iot:e2e:1.0'>
<p521Aes x='gInX2HA3BD5fCyxDoqt6FFzKU...' y='9hAm0F4/4tmAKvkweQnMsk...'/>
<p384Aes x='ccw28YXo/VWYOAFTnNKkqOToN...' y='PazgeIFpJhdjRoHd0ARQSI...'/>
<p256Aes x='Tmz/J8/k2x8wYFm3hpqwGm17W...' y='8o9a4JpBs2KOki657Rp+qd...'/>
<p224Aes x='33lAKAeM77sGOOC0pTfVmMeMl...' y='E7bNDNZ4kxzBx54Ky3xxDd...'/>
<p192Aes x='ufDM/23BvMjDKFdkCAdd03jrj...' y='FFFBPlrFv1Y8JYVd0fVhJ8...'/>
<rsaAes size='4096' mod='vyhg+bU+QqExe7QRpKWXiRG/LkOU6D/...' exp='AQAB'/>
</e2e>
<p2p extIp='93.184.216.34' extPort='49790' locIp='192.168.0.102' locPort='49790' xmlns='urn:ieee:iot:p2p:1.0'/>
<c xmlns='http://jabber.org/protocol/caps' hash='sha-256' node='...' ver='...'/>
</presence>
```
Example, sending an E2E encrypted `iq` stanza:
<presence id='08abd652278c3c49dcc462ad38f4c17f' to='peter@waher.se/9b33abdb684b237c44b9b27b70dd4da3' from='StuartLSBtest@waher.se/ca12ae917bc6e07f4eef3ade930c9fc2'>
<show>chat</show>
<x xmlns='jabber:x:avatar'><hash>8357fc0800f0b472e35157975f269aab247dddc3</hash></x>
<ls xmlns='http://lils.is/1.0'><profile hash='14fbb5e788fe35802d3f3adb8c4a48d12bc497c4d8bb2006db6f8bd2586565ee'/></ls>
<e2e xmlns='urn:ieee:iot:e2e:1.0'>
<p521Aes x='gInX2HA3BD5fCyxDoqt6FFzKUQ55BaJp+LyK4KFEZq6QRwtor1scdDNSaxUp0Lcae8urSD6IdPiQdsGQmLSbWlg=' y='9hAm0F4/4tmAKvkweQnMskOUUC0D7Dg397FSiZddfp4PhN7NbSAm50KfD9ui8dgRuVb3248GAsv40czISfg+X9A='/>
<p384Aes x='ccw28YXo/VWYOAFTnNKkqOToN8zeUeZ6AP5flhp2Wc5MjR9ttRVB0aF7Cq2vF1Ia' y='PazgeIFpJhdjRoHd0ARQSIO+Xlq7j8hENdKGEG1XqXwqT9RtqdpacIMHAidjncZF'/>
<p256Aes x='Tmz/J8/k2x8wYFm3hpqwGm17WORbX+DqqdBxu9Aqi/A=' y='8o9a4JpBs2KOki657Rp+qdLXi6ZoBkhwp1KCAx5/ETs='/>
<p224Aes x='33lAKAeM77sGOOC0pTfVmMeMl2Jb6Uirum21vw==' y='E7bNDNZ4kxzBx54Ky3xxDdNZSrbKiCyWX8fRgA=='/>
<p192Aes x='ufDM/23BvMjDKFdkCAdd03jrjRKtcLsE' y='FFFBPlrFv1Y8JYVd0fVhJ8wU9PaxrrbJ'/>
<rsaAes size='3072' mod='w3pp0mEiK30DDm1fFlkiBdPiDkmJHFwMMRR7Oie2KuPUgZhQ8BvjHvoI2EPekOYDRGi2dq3+mGF/Dlevtbea+IZX+Y1HSdOGV9AmDABQiIFdQyAgyY0i2/nvxaEBnwuHIxNwumWqwY4jjEWeW/KVDzJfdMCCoT3tGPRysbQGwFG8OEeMnMhFJTaXaWNgxbupRlMaWi7iICazGfwnxEATo0PfFDeFFvvuRx+NX+w7rPA/kPdscxTeZ+gqhAcmVh+1V8JXuSvVdSlARLDg1wZUU94YVtehOePao9/IcRUJtoAxg68N/zkFyy+KeeJAGNY13ka/c5RK6XeVkBg6bQG3zctCe1ayDozFMSP+PQH6neBKHgjNR7KIJwB/8f16SHdImwTpOEVlX/4GEIIFoWoXV8I9lYuDQ9SxHAfQqdaaVENyjP2Q81WkfiXF1ZZzM/uTqS3WLFeA0gtWQy2qeIgBIH4D9m/9MeEYDQsOLQ53JMmA8gGB0Wn4xm9kJPGz0JL9' exp='AQAB'/>
</e2e><p2p xmlns='urn:ieee:iot:p2p:1.0' extIp='31.211.245.242' extPort='49790' locIp='192.168.0.102' locPort='49790'/><c xmlns='http://jabber.org/protocol/caps' hash='sha-256' node='http://lils.is/' ver='Im9Jsy7N/qLH4KSBQMEWBF9JrbC/8t4gKgylFrY4Je8='/></presence>
Example, sending an E2E encrypted `iq` stanza using RSA/AES:
```
<iq id='28209' type='get' to='...' from='...'>
<aes xmlns='urn:ieee:iot:e2e:1.0'
keyRsa='G1NwbnHifFUhYWIrBc3K...'
ivRsa='XetOx6h6uTMbLfDf7b9Rl...'
signRsa='mX1DQF/HKzPTfQzTAWF...'>
bpg/e2lnVqiT8IE0KCH7l...
</aes>
......@@ -107,6 +158,15 @@ Example, sending an E2E encrypted `iq` stanza:
**Note**: RSA keys are large, which will cause small stanzas to become much larger when E2E encrypted. RSA and AES is available for devices that do not
support Elliptic Curve Cryptography (ECC). ECC is able to maintain the same security strength using shorter messages.
ECC p521/AES
-----------------
Example, sending an E2E encrypted `iq` stanza using EEC/AES:
```
<iq id='304' type='get' to='...' from='...'>
<aes xmlns='urn:ieee:iot:e2e:1.0'
ec='NIST P-256'
ecdsa1='KILmz4GOURVGyRxnuPpqamDSC2zhvuHaxyvjLxonGD4='
ecdsa2='+A5RuHBq2pUfk4i+D52D8MouNd36isiOcGz1rKdpHgk='>
COS0RYr53vz9C+FoKbGgeVUewBDPvP5QESsiUbBQKrUpwv8rXTUrdKbsomQgW5oH
</aes>
</iq>
```
\ No newline at end of file
......@@ -3,9 +3,10 @@
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='urn:ieee:iot:e2e:1.0'
xmlns='urn:ieee:iot:e2e:1.0'
elementFormDefault='qualified'>
elementFormDefault='qualified'
xmlns:p2="urn:ieee:iot:p2p:1.0">
<!--
<!--
Copyright 2017-2018 The Institute of Electrical and Electronics Engineers,
Incorporated (IEEE).
......@@ -59,6 +60,8 @@ IEEE standards must not be utilized for any conformance/compliance
purposes.
-->
<xs:import namespace="urn:ieee:iot:p2p:1.0"/>
<xs:element name="e2e">
<xs:annotation>
<xs:documentation>Element added to online presence stanza, to inform peers with presence subscription on how to establish end-to-end encrypted communication with the application.</xs:documentation>
......@@ -234,4 +237,17 @@ purposes.
</xs:restriction>
</xs:simpleType>
<xs:element name="synchE2e">
<xs:annotation>
<xs:documentation>Element that can be sent in an iq get stanza to synchronize End-to-End Encryption and Peer-to-Peer parameters.</xs:documentation>
<xs:documentation>Expected response element is synchE2e as well, where the recipient of the request returns its parameters, after authorizing the request.</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element ref="e2e" minOccurs="0"/>
<xs:element ref="p2:p2p" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
\ No newline at end of file
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment