encryption.rst
1 Encryption 2 ========== 3 4 Bitmessage uses the Elliptic Curve Integrated Encryption Scheme 5 `(ECIES) <http://en.wikipedia.org/wiki/Integrated_Encryption_Scheme>`_ 6 to encrypt the payload of the Message and Broadcast objects. 7 8 The scheme uses Elliptic Curve Diffie-Hellman 9 `(ECDH) <http://en.wikipedia.org/wiki/ECDH>`_ to generate a shared secret used 10 to generate the encryption parameters for Advanced Encryption Standard with 11 256bit key and Cipher-Block Chaining 12 `(AES-256-CBC) <http://en.wikipedia.org/wiki/Advanced_Encryption_Standard>`_. 13 The encrypted data will be padded to a 16 byte boundary in accordance to 14 `PKCS7 <http://en.wikipedia.org/wiki/Cryptographic_Message_Syntax>`_. This 15 means that the data is padded with N bytes of value N. 16 17 The Key Derivation Function 18 `(KDF) <http://en.wikipedia.org/wiki/Key_derivation_function>`_ used to 19 generate the key material for AES is 20 `SHA512 <http://en.wikipedia.org/wiki/Sha512>`_. The Message Authentication 21 Code (MAC) scheme used is `HMACSHA256 <http://en.wikipedia.org/wiki/Hmac>`_. 22 23 Format 24 ------ 25 26 (See also: :doc:`protocol`) 27 28 .. include:: encrypted_payload.rst 29 30 In order to reconstitute a usable (65 byte) public key (starting with 0x04), 31 the X and Y components need to be expanded by prepending them with 0x00 bytes 32 until the individual component lengths are 32 bytes. 33 34 Encryption 35 ---------- 36 37 1. The destination public key is called K. 38 2. Generate 16 random bytes using a secure random number generator. 39 Call them IV. 40 3. Generate a new random EC key pair with private key called r and public key 41 called R. 42 4. Do an EC point multiply with public key K and private key r. This gives you 43 public key P. 44 5. Use the X component of public key P and calculate the SHA512 hash H. 45 6. The first 32 bytes of H are called key_e and the last 32 bytes are called 46 key_m. 47 7. Pad the input text to a multiple of 16 bytes, in accordance to PKCS7. [#f1]_ 48 8. Encrypt the data with AES-256-CBC, using IV as initialization vector, 49 key_e as encryption key and the padded input text as payload. Call the 50 output cipher text. 51 9. Calculate a 32 byte MAC with HMACSHA256, using key_m as salt and 52 IV + R [#f2]_ + cipher text as data. Call the output MAC. 53 54 The resulting data is: IV + R + cipher text + MAC 55 56 Decryption 57 ---------- 58 59 1. The private key used to decrypt is called k. 60 2. Do an EC point multiply with private key k and public key R. This gives you 61 public key P. 62 3. Use the X component of public key P and calculate the SHA512 hash H. 63 4. The first 32 bytes of H are called key_e and the last 32 bytes are called 64 key_m. 65 5. Calculate MAC' with HMACSHA256, using key_m as salt and 66 IV + R + cipher text as data. 67 6. Compare MAC with MAC'. If not equal, decryption will fail. 68 7. Decrypt the cipher text with AES-256-CBC, using IV as initialization 69 vector, key_e as decryption key and the cipher text as payload. The output 70 is the padded input text. 71 72 .. highlight:: nasm 73 74 Partial Example 75 --------------- 76 77 .. list-table:: Public key K: 78 :header-rows: 1 79 :widths: auto 80 81 * - Data 82 - Comments 83 * - 84 85 :: 86 87 04 88 09 d4 e5 c0 ab 3d 25 fe 89 04 8c 64 c9 da 1a 24 2c 90 7f 19 41 7e 95 17 cd 26 91 69 50 d7 2c 75 57 13 58 92 5c 61 78 e9 7f e0 92 fc 93 89 7c 9a 1f 17 20 d5 77 94 0a e8 ea ad 2f a8 fc bd 95 08 e9 32 4a 5d de 18 57 96 - Public key, 0x04 prefix, then 32 bytes X and 32 bytes Y. 97 98 99 .. list-table:: Initialization Vector IV: 100 :header-rows: 1 101 :widths: auto 102 103 * - Data 104 - Comments 105 * - 106 107 :: 108 109 bd db 7c 28 29 b0 80 38 110 75 30 84 a2 f3 99 16 81 111 - 16 bytes generated with a secure random number generator. 112 113 .. list-table:: Randomly generated key pair with private key r and public key R: 114 :header-rows: 1 115 :widths: auto 116 117 * - Data 118 - Comments 119 * - 120 121 :: 122 123 5b e6 fa cd 94 1b 76 e9 124 d3 ea d0 30 29 fb db 6b 125 6e 08 09 29 3f 7f b1 97 126 d0 c5 1f 84 e9 6b 8b a4 127 - Private key r 128 * - 129 130 :: 131 132 02 ca 00 20 133 02 93 21 3d cf 13 88 b6 134 1c 2a e5 cf 80 fe e6 ff 135 ff c0 49 a2 f9 fe 73 65 136 fe 38 67 81 3c a8 12 92 137 00 20 138 df 94 68 6c 6a fb 56 5a 139 c6 14 9b 15 3d 61 b3 b2 140 87 ee 2c 7f 99 7c 14 23 141 87 96 c1 2b 43 a3 86 5a 142 - Public key R 143 144 .. list-table:: Derived public key P (point multiply r with K): 145 :header-rows: 1 146 :widths: auto 147 148 * - Data 149 - Comments 150 * - 151 152 :: 153 154 04 155 0d b8 e3 ad 8c 0c d7 3f 156 a2 b3 46 71 b7 b2 47 72 157 9b 10 11 41 57 9d 19 9e 158 0d c0 bd 02 4e ae fd 89 159 ca c8 f5 28 dc 90 b6 68 160 11 ab ac 51 7d 74 97 be 161 52 92 93 12 29 be 0b 74 162 3e 05 03 f4 43 c3 d2 96 163 - Public key P 164 * - 165 166 :: 167 168 0d b8 e3 ad 8c 0c d7 3f 169 a2 b3 46 71 b7 b2 47 72 170 9b 10 11 41 57 9d 19 9e 171 0d c0 bd 02 4e ae fd 89 172 - X component of public key P 173 174 .. list-table:: SHA512 of public key P X component (H): 175 :header-rows: 1 176 :widths: auto 177 178 * - Data 179 - Comments 180 * - 181 182 :: 183 184 17 05 43 82 82 67 86 71 185 05 26 3d 48 28 ef ff 82 186 d9 d5 9c bf 08 74 3b 69 187 6b cc 5d 69 fa 18 97 b4 188 - First 32 bytes of H called key_e 189 * - 190 191 :: 192 193 f8 3f 1e 9c c5 d6 b8 44 194 8d 39 dc 6a 9d 5f 5b 7f 195 46 0e 4a 78 e9 28 6e e8 196 d9 1c e1 66 0a 53 ea cd 197 - Last 32 bytes of H called key_m 198 199 .. list-table:: Padded input: 200 :header-rows: 1 201 :widths: auto 202 203 * - Data 204 - Comments 205 * - 206 207 :: 208 209 54 68 65 20 71 75 69 63 210 6b 20 62 72 6f 77 6e 20 211 66 6f 78 20 6a 75 6d 70 212 73 20 6f 76 65 72 20 74 213 68 65 20 6c 61 7a 79 20 214 64 6f 67 2e 04 04 04 04 215 - The quick brown fox jumps over the lazy dog.0x04,0x04,0x04,0x04 216 217 .. list-table:: Cipher text: 218 :header-rows: 1 219 :widths: auto 220 221 * - Data 222 - Comments 223 * - 224 225 :: 226 227 64 20 3d 5b 24 68 8e 25 228 47 bb a3 45 fa 13 9a 5a 229 1d 96 22 20 d4 d4 8a 0c 230 f3 b1 57 2c 0d 95 b6 16 231 43 a6 f9 a0 d7 5a f7 ea 232 cc 1b d9 57 14 7b f7 23 233 - 3 blocks of 16 bytes of encrypted data. 234 235 .. list-table:: MAC: 236 :header-rows: 1 237 :widths: auto 238 239 * - Data 240 - Comments 241 * - 242 243 :: 244 245 f2 52 6d 61 b4 85 1f b2 246 34 09 86 38 26 fd 20 61 247 65 ed c0 21 36 8c 79 46 248 57 1c ea d6 90 46 e6 19 249 - 32 bytes hash 250 251 252 .. rubric:: Footnotes 253 254 .. [#f1] The pyelliptic implementation used in PyBitmessage takes unpadded data, 255 see :obj:`.pyelliptic.Cipher.ciphering`. 256 .. [#f2] The pyelliptic encodes the pubkey with curve and length, 257 see :obj:`.pyelliptic.ECC.get_pubkey`