From cfdfe3bbae7a06cd1cc6f1aee5bdf918b86b58d8 Mon Sep 17 00:00:00 2001 From: moxie0 Date: Wed, 17 Oct 2012 20:37:52 -0700 Subject: [PATCH] switch to markdown --- Protocol.creole => Protocol.md | 36 +++++++++++++++++----------------- 1 file changed, 18 insertions(+), 18 deletions(-) rename Protocol.creole => Protocol.md (96%) diff --git a/Protocol.creole b/Protocol.md similarity index 96% rename from Protocol.creole rename to Protocol.md index 11b93bd..b06cf27 100644 --- a/Protocol.creole +++ b/Protocol.md @@ -1,8 +1,8 @@ The TextSecure encrypted messaging protocol is derivative of "OTR Messaging." The major difference being the use of ECC keys instead of standard DSA, as well as the compression of some data structure formats. -== Common Structures +## Common Structures -{{{ +``` struct { opaque version[1]; } TextSecure_Version; @@ -11,24 +11,24 @@ struct { opaque key_id[3]; opaque key[33]; } TextSecure_Key; -}}} +``` * "version" is a 8 bit value that represents both the currently speaking as well as maximum supported version of the protocol a client supports. The top 4 bits represent the version of the current message to follow, and the bottom 4 bits represent the maximum supported protocol version the sending client speaks. * "key_id" is the key ID number. * "key" is an ECC key from the P-256 curve, encoded down to 33 bytes using point compression. -== Key Exchange Messsage Format +## Key Exchange Messsage Format -{{{ +``` struct { TextSecure_Version version; TextSecure_Key key; } TextSecure_KeyExchange; -}}} +``` -== Data Message Format +## Data Message Format -{{{ +``` struct { TextSecure_Version version; opaque sender_key_id[3]; @@ -38,7 +38,7 @@ struct { opaque encrypted_message[...]; opaque mac[10]; } TextSecure_Message; -}}} +``` * "sender_key_id" The ID of the sender's asymmetric key being used for this message. * "recipient_key_id" The ID of the recipient's asymmetric key being used for this message. @@ -47,11 +47,11 @@ struct { * "encrypted_message" The contents of the message, encrypted using AES-128 in CTR mode. The plaintext is always padded out with 0x00 bytes such that the total packet is an exact multiple of the maximum SMS size. * "mac" HMAC-SHA1 of all the previous fields, truncated to 10 bytes. Note that this is the encrypt-then-authenticate. -== Transport Format +## Transport Format It is not possible to rely on the multipart message facility provided by the SMS UDH in order to send long messages. It does not work on CDMA networks, so we have to provide for message chaining ourselves. Messages are fragmented using the following format: -{{{ +``` struct { opaque identifier[3]; TextSecure_Version version; @@ -59,7 +59,7 @@ struct { opaque multipart_message_id[1]; (optional) TextSecure_Message message; } TextSecure_Fragment; -}}} +``` * "identifier" Everything following this field is appended to an identifier (the string "?TSK" for a key exchange message or the string "?TSM" for a data message) and hashed iteratively with SHA1 for 1000 iterations. The result is then truncated to 3 bytes. * "fragment_count" The top 4 bits represent the index of this fragment (0-based) and the bottom 4 bits represent the total number of fragments. @@ -68,7 +68,7 @@ struct { The entire TextSecure_Fragment is Base64 encoded, without trailing padding. -== Sending A Message +## Sending A Message When composing a message, the total headerfied, encrypted, and mac'd data message is handed to the transport layer, which then splits the data message into fragments small enough to fit into individual SMS messages. Once the receiving end has received all the fragments, it reassembles them into one message again before verifying the MAC and decrypting. @@ -76,7 +76,7 @@ Some knowledge of the transport layer sizing requirements is needed by the appli In the end, there are 60 characters available in the first fragment, and 115 in each subsequent fragment. -== Verifying And Decrypting A Message +## Verifying And Decrypting A Message A shared secret is generated by doing ECDH using the keys corresponding to the key ids in the message. All of the ECC parameters are chosen from the NSA Suite B specification. @@ -88,13 +88,13 @@ The two AES keys are computed by taking bytes from SHA256(S0 + 0x00) and SHA256( Mac key M1 = SHA1(C1), M2 = SHA1(C2). -== Starting And Verifying A Session +## Starting And Verifying A Session Either client can begin a sesison by sending a key exchange message. When keys have been exchanged in both directions, a SHA1 fingerprint of each entire key exchange message is displayed which users can verify over the phone. A session rolls forward just like an OTR session, where only two keys for the sender and recipient are maintained at any time. Keys previous to that are forgotten. -== Local Encryption +## Local Encryption Should clients choose to have "non-ephemeral" conversations, which is to say that the messages they send and receive are stored to disk, they need to be re-encrypted since the original keys used to encrypt them may vanish as the protocol rolls forward. @@ -102,13 +102,13 @@ Clients generate a 128bit AES key and 160bit MAC key at install time, which are Locally encrypted messages are then encrypted using AES-CBC$ with HMAC-SHA1 in the encrypt-then-authenticate paradigm. So the format is: -{{{ +``` struct { opaque random_iv[16]; opaque encrypted_message[...]; opaque mac[20]; } TextSecure_LocalMessage; -}}} +``` * "random_iv" is a random IV. * "encrypted_message" is the ciphertext of AES-CBC$(plaintext)