Encryption - Revision history

Atheros: MAC calculation change to match pyelliptic

2014-11-21T22:16:36Z

MAC calculation change to match pyelliptic

ISibboI: Additional reformatting

2013-08-19T19:49:22Z

Additional reformatting

ISibboI: /* Encrypted payload */ Some reformatting

2013-08-19T19:47:27Z

Encrypted payload: Some reformatting

ISibboI: Copied stuff over from the Protocol specification to create this page

2013-08-19T19:45:26Z

Copied stuff over from the Protocol specification to create this page

New page

=== Encrypted payload ===

Bitmessage uses the Elliptic Curve Integrated Encryption Scheme (ECIES)[http://en.wikipedia.org/wiki/Integrated_Encryption_Scheme] to encrypt the payload of the Message and Broadcast objects.

The scheme uses Elliptic Curve Diffie-Hellman (ECDH)[http://en.wikipedia.org/wiki/ECDH] to generate a shared secret used to generate the encryption parameters for Advanced Encryption Standard with 256bit key and Cipher-Block Chaining (AES-256-CBC)[http://en.wikipedia.org/wiki/Advanced_Encryption_Standard]. The encrypted data will be padded to a 16 byte boundary in accordance to PKCS7[http://en.wikipedia.org/wiki/Cryptographic_Message_Syntax]. This means that the data is padded with N bytes of value N.

The Key Derivation Function (KDF)[http://en.wikipedia.org/wiki/Key_derivation_function] used to generate the key material for AES is SHA512[http://en.wikipedia.org/wiki/Sha512]. The Message Authentication Code (MAC) scheme used is HMACSHA256[http://en.wikipedia.org/wiki/Hmac].

==== Format ====

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 16||IV||uchar[]||Initialization Vector used for AES-256-CBC
|-
| 2||uint16_t||Curve type||Elliptic Curve type 0x02CA (714)
|-
| 2||uint16_t||X length||Length of X component of public key R
|-
| X length||uchar[]||X||X component of public key R
|-
| 2||uint16_t||Y length||Length of Y component of public key R
|-
| Y length||uchar[]||Y||Y component of public key R
|-
| ?||encrypted||uchar[]||Cipher text
|-
| 32||MAC|| uchar[]||HMACSHA256 Message Authentication Code
|}

In order to reconstitute a usable (65 byte) public key (starting with 0x04), the X and Y components need to be expanded by prepending them with 0x00 bytes until the individual component lengths are 32 bytes.

==== Encryption ====

# The destination public key is called K.
# Generate 16 random bytes using a secure random number generator. Call them IV.
# Generate a new random EC key pair with private key called r and public key called R.
# Do an EC point multiply with public key K and private key r. This gives you public key P.
# Use the X component of public key P and calculate the SHA512 hash H.
# The first 32 bytes of H are called key_e and the last 32 bytes are called key_m.
# Pad the input text to a multiple of 16 bytes, in accordance to PKCS7.
# Encrypt the data with AES-256-CBC, using IV as initialization vector, key_e as encryption key and the padded input text as payload. Call the output cipher text.
# Calculate a 32 byte MAC with HMACSHA256, using key_m as salt and cipher text as data. Call the output MAC.

The resulting data is: IV + R + cipher text + MAC

==== Decryption ====

# The private key used to decrypt is called k.
# Do an EC point multiply with private key k and public key R. This gives you public key P.
# Use the X component of public key P and calculate the SHA512 hash H.
# The first 32 bytes of H are called key_e and the last 32 bytes are called key_m.
# Calculate MAC' with HMACSHA256, using key_m as salt and cipher text as data.
# Compare MAC with MAC'. If not equal, decryption will fail.
# Decrypt the cipher text with AES-256-CBC, using IV as initialization vector, key_e as decryption key and the cipher text as payload. The output is the padded input text.

==== Example ====

Public key K:

{|class="wikitable"
! Data !! Comments
|-
|<pre>
04 09 d4 e5 c0 ab 3d 25
fe 04 8c 64 c9 da 1a 24
2c 7f 19 41 7e 95 17 cd
26 69 50 d7 2c 75 57 13
58 5c 61 78 e9 7f e0 92
fc 89 7c 9a 1f 17 20 d5
77 0a e8 ea ad 2f a8 fc
bd 08 e9 32 4a 5d de 18
57</pre>||Public key, 0x04 prefix, then 32 bytes X and 32 bytes Y.
|}

Initialization Vector IV:

{|class="wikitable"
! Data !! Comments
|-
|<pre>bd db 7c 28 29 b0 80 38
75 30 84 a2 f3 99 16 81</pre>||16 bytes generated with a secure random number generator.
|}

Randomly generated key pair with private key r and public key R:

{|class="wikitable"
! Data !! Comments
|-
|<pre>5b e6 fa cd 94 1b 76 e9
d3 ea d0 30 29 fb db 6b
6e 08 09 29 3f 7f b1 97
d0 c5 1f 84 e9 6b 8b a4</pre>||Private key r
|-
|<pre>04 02 93 21 3d cf 13 88
b6 1c 2a e5 cf 80 fe e6
ff ff c0 49 a2 f9 fe 73
65 fe 38 67 81 3c a8 12
92 df 94 68 6c 6a fb 56
5a c6 14 9b 15 3d 61 b3
b2 87 ee 2c 7f 99 7c 14
23 87 96 c1 2b 43 a3 86
5a</pre>||Public key R
|}

Derived public key P (point multiply r with K):

{|class="wikitable"
! Data !! Comments
|-
|<pre>04 0d b8 e3 ad 8c 0c d7
3f a2 b3 46 71 b7 b2 47
72 9b 10 11 41 57 9d 19
9e 0d c0 bd 02 4e ae fd
89 ca c8 f5 28 dc 90 b6
68 11 ab ac 51 7d 74 97
be 52 92 93 12 29 be 0b
74 3e 05 03 f4 43 c3 d2
96</pre>||Public key P
|-
|<pre>0d b8 e3 ad 8c 0c d7 3f
a2 b3 46 71 b7 b2 47 72
9b 10 11 41 57 9d 19 9e
0d c0 bd 02 4e ae fd 89</pre>||X component of public key P
|}

SHA512 of public key P X component (H):

{|class="wikitable"
! Data !! Comments
|-
|<pre>17 05 43 82 82 67 86 71
05 26 3d 48 28 ef ff 82
d9 d5 9c bf 08 74 3b 69
6b cc 5d 69 fa 18 97 b4</pre>||First 32 bytes of H called key_e
|-
|<pre>f8 3f 1e 9c c5 d6 b8 44
8d 39 dc 6a 9d 5f 5b 7f
46 0e 4a 78 e9 28 6e e8
d9 1c e1 66 0a 53 ea cd</pre>||Last 32 bytes of H called key_m
|}

Padded input:

{|class="wikitable"
! Data !! Comments
|-
|<pre>54 68 65 20 71 75 69 63
6b 20 62 72 6f 77 6e 20
66 6f 78 20 6a 75 6d 70
73 20 6f 76 65 72 20 74
68 65 20 6c 61 7a 79 20
64 6f 67 2e 04 04 04 04</pre>||The quick brown fox jumps over the lazy dog.0x04,0x04,0x04,0x04
|}

Cipher text:

{|class="wikitable"
! Data !! Comments
|-
|<pre>64 20 3d 5b 24 68 8e 25
47 bb a3 45 fa 13 9a 5a
1d 96 22 20 d4 d4 8a 0c
f3 b1 57 2c 0d 95 b6 16
43 a6 f9 a0 d7 5a f7 ea
cc 1b d9 57 14 7b f7 23</pre>||3 blocks of 16 bytes of encrypted data.
|}

MAC:

{|class="wikitable"
! Data !! Comments
|-
|<pre>4c 08 ac 6c 93 c7 37 7b
ac 5a 2e 87 3d d3 51 1b
12 7a ff 6d 0d 16 38 cd
ae 49 89 c4 d2 fe 7d e1</pre>||HMACSHA256 with key_m as salt and cipher text as input.
|}

Resulting encrypted data:

{|class="wikitable"
! Data !! Comments
|-
|<pre>bd db 7c 28 29 b0 80 38
75 30 84 a2 f3 99 16 81</pre>||IV
|-
|<pre>02 ca</pre>||Curve Type
|-
|<pre>00 20</pre>||X Length
|-
|<pre>02 93 21 3d cf 13 88 b6
1c 2a e5 cf 80 fe e6 ff
ff c0 49 a2 f9 fe 73 65
fe 38 67 81 3c a8 12 92</pre>||X
|-
|<pre>00 20</pre>||Y Length
|-
|<pre>df 94 68 6c 6a fb 56 5a
c6 14 9b 15 3d 61 b3 b2
87 ee 2c 7f 99 7c 14 23
87 96 c1 2b 43 a3 86 5a</pre>||Y
|-
|<pre>64 20 3d 5b 24 68 8e 25
47 bb a3 45 fa 13 9a 5a
1d 96 22 20 d4 d4 8a 0c
f3 b1 57 2c 0d 95 b6 16
43 a6 f9 a0 d7 5a f7 ea
cc 1b d9 57 14 7b f7 23</pre>||Cipher text
|-
|<pre>4c 08 ac 6c 93 c7 37 7b
ac 5a 2e 87 3d d3 51 1b
12 7a ff 6d 0d 16 38 cd
ae 49 89 c4 d2 fe 7d e1</pre>||MAC
|}

Private key k:

{|class="wikitable"
! Data !! Comments
|-
|<pre>02 ba 27 44 e6 5c cd 7b
19 54 b0 a3 3b 80 d7 5e
16 ca b4 7f 2b 33 1f f0
b6 d1 84 b7 19 83 da 85</pre>||Private key k used to decrypt the above encrypted data.
|}

@@ Line 42: / Line 42: @@
 # Pad the input text to a multiple of 16 bytes, in accordance to PKCS7.
 # Encrypt the data with AES-256-CBC, using IV as initialization vector, key_e as encryption key and the padded input text as payload. Call the output cipher text.
-# Calculate a 32 byte MAC with HMACSHA256, using key_m as salt and cipher text as data. Call the output MAC.
+# Calculate a 32 byte MAC with HMACSHA256, using key_m as salt and IV + R + cipher text as data. Call the output MAC.
 The resulting data is: IV + R + cipher text + MAC
@@ Line 52: / Line 52: @@
 # Use the X component of public key P and calculate the SHA512 hash H.
 # The first 32 bytes of H are called key_e and the last 32 bytes are called key_m.
-# Calculate MAC' with HMACSHA256, using key_m as salt and cipher text as data.
+# Calculate MAC' with HMACSHA256, using key_m as salt and IV + R + cipher text as data.
 # Compare MAC with MAC'. If not equal, decryption will fail.
 # Decrypt the cipher text with AES-256-CBC, using IV as initialization vector, key_e as decryption key and the cipher text as payload. The output is the padded input text.
-== Example ==
+== Partial Example ==
 Public key K:
@@ Line 167: / Line 167: @@
 a6 f9 a0  d7 5a f7 ea
 cc 1b d9 57  14 7b f7 23</pre>||3 blocks of 16 bytes of encrypted data.
 |}

@@ Line 5: / Line 5: @@
 The Key Derivation Function (KDF)[http://en.wikipedia.org/wiki/Key_derivation_function] used to generate the key material for AES is SHA512[http://en.wikipedia.org/wiki/Sha512]. The Message Authentication Code (MAC) scheme used is HMACSHA256[http://en.wikipedia.org/wiki/Hmac].
-=== Format ===
+== Format ==
 {|class="wikitable"
@@ Line 30: / Line 32: @@
-=== Encryption ===
+== Encryption ==
 # The destination public key is called K.
@@ Line 44: / Line 46: @@
 The resulting data is: IV + R + cipher text + MAC
-=== Decryption ===
+== Decryption ==
 # The private key used to decrypt is called k.
@@ Line 54: / Line 56: @@
 # Decrypt the cipher text with AES-256-CBC, using IV as initialization vector, key_e as decryption key and the cipher text as payload. The output is the padded input text.
-=== Example ===
+== Example ==
 Public key K: