Adding Protocol specification to docs (WIP) #1727

Closed
g1itch wants to merge 12 commits from doc into v0.6
Showing only changes of commit 1c6cdc8733 - Show all commits

View File

@ -500,13 +500,201 @@ getpubkey
When a node has the hash of a public key (from an address) but not the public
key itself, it must send out a request for the public key.
.. list-table::
:header-rows: 1
:widths: auto
* - Field Size
- Description
- Data type
- Comments
* - 20
- ripe
- uchar[]
- The ripemd hash of the public key. This field is only included when the
address version is <= 3.
* - 32
- tag
- uchar[]
- The tag derived from the address version, stream number, and ripe. This
field is only included when the address version is >= 4.
pubkey
^^^^^^
A version 2 pubkey. This is still in use and supported by current clients but
new v2 addresses are not generated by clients.
*new* v2 addresses are not generated by clients.
.. list-table::
:header-rows: 1
:widths: auto
* - Field Size
- Description
- Data type
- Comments
* - 4
- behavior bitfield
- uint32_t
- A bitfield of optional behaviors and features that can be expected from
the node receiving the message.
* - 64
- public signing key
- uchar[]
- The ECC public key used for signing (uncompressed format;
normally prepended with \x04 )
* - 64
- public encryption key
- uchar[]
- The ECC public key used for encryption (uncompressed format;
normally prepended with \x04 )
.. list-table:: A version 3 pubkey
:header-rows: 1
:widths: auto
* - Field Size
- Description
- Data type
- Comments
* - 4
- behavior bitfield
- uint32_t
- A bitfield of optional behaviors and features that can be expected from
the node receiving the message.
* - 64
- public signing key
- uchar[]
- The ECC public key used for signing (uncompressed format;
normally prepended with \x04 )
* - 64
- public encryption key
- uchar[]
- The ECC public key used for encryption (uncompressed format;
normally prepended with \x04 )
* - 1+
- nonce_trials_per_byte
- var_int
- Used to calculate the difficulty target of messages accepted by this
node. The higher this value, the more difficult the Proof of Work must
be before this individual will accept the message. This number is the
average number of nonce trials a node will have to perform to meet the
Proof of Work requirement. 1000 is the network minimum so any lower
values will be automatically raised to 1000.
* - 1+
- extra_bytes
- var_int
- Used to calculate the difficulty target of messages accepted by this
node. The higher this value, the more difficult the Proof of Work must
be before this individual will accept the message. This number is added
to the data length to make sending small messages more difficult.
1000 is the network minimum so any lower values will be automatically
raised to 1000.
* - 1+
- sig_length
- var_int
- Length of the signature
* - sig_length
- signature
- uchar[]
- The ECDSA signature which, as of protocol v3, covers the object
header starting with the time, appended with the data described in this
table down to the extra_bytes.
.. list-table:: A version 4 pubkey
:header-rows: 1
:widths: auto
* - Field Size
- Description
- Data type
- Comments
* - 32
- tag
- uchar[]
- The tag, made up of bytes 32-64 of the double hash of the address data
(see example python code below)
* - ?
- encrypted
- uchar[]
- Encrypted pubkey data.
When version 4 pubkeys are created, most of the data in the pubkey is encrypted.
This is done in such a way that only someone who has the Bitmessage address
which corresponds to a pubkey can decrypt and use that pubkey. This prevents
people from gathering pubkeys sent around the network and using the data from
them to create messages to be used in spam or in flooding attacks.
In order to encrypt the pubkey data, a double SHA-512 hash is calculated from
the address version number, stream number, and ripe hash of the Bitmessage
address that the pubkey corresponds to. The first 32 bytes of this hash are used
to create a public and private key pair with which to encrypt and decrypt the
pubkey data, using the same algorithm as message encryption
(see :doc:`encryption`). The remaining 32 bytes of this hash are added to the
unencrypted part of the pubkey and used as a tag, as above. This allows nodes to
determine which pubkey to decrypt when they wish to send a message.
In PyBitmessage, the double hash of the address data is calculated using the
python code below:
.. code-block:: python
doubleHashOfAddressData = hashlib.sha512(hashlib.sha512(
encodeVarint(addressVersionNumber) + encodeVarint(streamNumber) + hash
).digest()).digest()
.. list-table:: Encrypted data in version 4 pubkeys:
:header-rows: 1
:widths: auto
* - Field Size
- Description
- Data type
- Comments
* - 4
- behavior bitfield
- uint32_t
- A bitfield of optional behaviors and features that can be expected from
the node receiving the message.
* - 64
- public signing key
- uchar[]
- The ECC public key used for signing (uncompressed format;
normally prepended with \x04 )
* - 64
- public encryption key
- uchar[]
- The ECC public key used for encryption (uncompressed format;
normally prepended with \x04 )
* - 1+
- nonce_trials_per_byte
- var_int
- Used to calculate the difficulty target of messages accepted by this
node. The higher this value, the more difficult the Proof of Work must
be before this individual will accept the message. This number is the
average number of nonce trials a node will have to perform to meet the
Proof of Work requirement. 1000 is the network minimum so any lower
values will be automatically raised to 1000.
* - 1+
- extra_bytes
- var_int
- Used to calculate the difficulty target of messages accepted by this
node. The higher this value, the more difficult the Proof of Work must
be before this individual will accept the message. This number is added
to the data length to make sending small messages more difficult.
1000 is the network minimum so any lower values will be automatically
raised to 1000.
* - 1+
- sig_length
- var_int
- Length of the signature
* - sig_length
- signature
- uchar[]
- The ECDSA signature which covers everything from the object header
starting with the time, then appended with the decrypted data down to
the extra_bytes. This was changed in protocol v3.
msg
^^^