Hide last authors
SandrineAvakian 1.1 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc /}}
3 {{/box}}
Johan Pascal 3.1 4
SandrineAvakian 1.1 5 = Linphone Instant Messaging Encryption (LIME) =
Johan Pascal 3.1 6
SandrineAvakian 1.1 7 == Message encryption/decryption ==
Johan Pascal 3.1 8
SandrineAvakian 1.1 9 === Random material used ===
Johan Pascal 3.1 10
SandrineAvakian 1.1 11 Sending and receiving messages are treated separately. There is key material for sending messages to a peer and separated one for message reception from the same peer.
12 On each side, stored in ZRTP cache.
Johan Pascal 3.1 14 Secret :
SandrineAvakian 1.1 15
Johan Pascal 3.1 16 * sender/receiver key(256 bits, actually 192 bits for key, 64 bits for Initial Vector)
17 * sender/receiver Session Id(256 bits)
SandrineAvakian 1.1 18
Johan Pascal 3.1 19 Public :
21 * sender/receiver Session Index (32 bits)
22 * end of key validity (64 bits UTC time)
23 * ZID (ZRTP unique ID) (96 bits)
SandrineAvakian 1.1 25 ZRTP cache is an XML file with the following structure (only LIME relevant component are listed here)
Sylvain Berfini 3.6 27 {{code language="xml"}}
Johan Pascal 3.1 28 <selfZID/>
SandrineAvakian 1.1 29 <peer>
Johan Pascal 3.1 30 <peerZID/> (unique)
31 <sip Uri/> (can be more than one)
32 <sender Key, Session Id, Session Index/> (unique)
33 <receiver Key, Session Id, Session Index/> (unique)
34 <key validity limit (UTC time)/> (unique)
35 </peer>
36 {{/code}}
SandrineAvakian 1.1 37
38 === Encryption ===
Johan Pascal 3.1 39
40 Message is encrypted using AES-192 in GCM mode(SCIMP use CCM mode which is very similar, GCM is supposed to be lighter on CPU) with authentication tag(sender/receiver ZID and sender Session Index are authenticated). Result message is an XML doc :
Sylvain Berfini 4.1 41
Sylvain Berfini 3.6 42 {{code language="xml"}}
Sylvain Berfini 4.1 43 <sender ZID/>
SandrineAvakian 1.1 44 <msg>
Johan Pascal 3.1 45 <receiverZID/>
46 <session Index/>
47 <auth tag(16 bytes) and cipher text in b64 coding/>
Sylvain Berfini 4.1 48 </msg>{{/code}}
Johan Pascal 3.1 49
SandrineAvakian 1.1 50 === Decryption ===
Johan Pascal 3.1 51
SandrineAvakian 1.1 52 Message is decrypted, sender/receiver ZID and Session Index are authenticated (see AES GCM for details).
Johan Pascal 3.1 53
SandrineAvakian 1.1 54 === Key derivation ===
Johan Pascal 3.1 55
SandrineAvakian 1.1 56 After any encryption or decryption, the key used is derived using a one way hash function so any attacker able to reach a key can't decrypt past messages.
Johan Pascal 3.1 58 Key derivation function(identical to the one defined in SCIMP paper) :
SandrineAvakian 1.1 59 {{code}}HMAC_SHA256(Key, 0x0000001||"MessageKey"||0x00||SessionId||SessionIndex||0x00000100){{/code}}
61 Session Index of derived key is incremented by one.
Johan Pascal 3.1 62
SandrineAvakian 1.1 63 === Lost messages/Key derivations sync ===
Johan Pascal 3.1 64
SandrineAvakian 1.1 66 On message reception and before decryption, the receiver checks, using the session Id in the message and the local one, that the key derivation are still in sync with peer. If session index received is ahead the one locally stored, local image of key is derived until correct session index is reached(a limit is set at build time to not go into key derivation process if the session index is too far).
68 === Shared secret expiration date ===
Johan Pascal 3.1 70 In order to prevent messages being encrypted forever with a key associated to an old or lost device, each peer(ZID) sending key have an expiration date. This expiration date is reset each time a ZRTP exchange occurs(voice/video call) and each time this peer(ZID hence device) send us a valid encrypted chat message. When a key has expired, any valid incoming message from peer will make it valid again for the preset time period: expiration applies to sending key only, not reception's one.
SandrineAvakian 1.1 71
Johan Pascal 3.1 72 Validity period extent can be set in the linphone config file using, in the **[sip]** section, the **lime_key_validity** setting.
74 The config setting accept either:
76 * an integer interpreted as a number of seconds
77 * a list of integer values with suffix from Y,M,W,d,h,m,s respectively year, month, week, day, hour, minute and second (matching {[0-9]+[Y,M,W,d,h,m,s]?}* ). Month is set to always be a 30 days period and year a 365 days period.
79 The default value of this setting is 0 which implies no expiration date for the sending key.
81 Any change in the extension of the validity period setting will be executive after the next ZRTP call to the matching device or message received from it.
SandrineAvakian 1.1 83 == ZID/sip URI matching ==
85 ZID is attached to a device and created randomly at first run of a ZRTP session on that device.
86 Sip Uri defines a sip account.
88 One ZID can be associated to several sip URI (multiple SIP accounts on the same device)
89 One sip URI can be associated to multiple ZID (account being used on several devices)
91 === Message sending ===
Johan Pascal 3.1 93 Parse the ZRTP cache to find any <peer> element having the correct <sip Uri>. We may found :
95 * None :Message encryption is not possible
96 * One : Encrypt using the sender key material(if not expired) and send the messages
97 * Several : Create a message with multiple <msg> elements, one for each possible peer ZID encrypted with the relevant sender key material.
SandrineAvakian 1.1 99 === Message reception ===
101 Retrieve sender ZID from message and parse our cache to find a peer with matching ZID. If no matching ZID is found, unable to decrypt messages.
Johan Pascal 3.1 103 Retrieve from message a <msg> element having a <receiver ZID> matching our. If not found, unable to decrypt message, otherwise decrypt it and update the reception key and sender key expiration date.
SandrineAvakian 1.1 104
105 == Key material generation/re-sync ==
107 At each ZRTP enabled call, some new key material is created and stored in the cache along other ZRTP related secrets.
109 The extra secret shared material generation is defined in section 4.5.2 of ZRTP's RFC as exported key. Key, Session Id and Session Index are generated for sender and receiver using this mechanism at each call.