Documentation
¶
Overview ¶
Package handshake contains the code that implements authentication handshake performed when a new connection between two peers is established, as described in the network security implementation [RFC], section 1.2.3 and 1.2.4.
Each peer wanting to join a network needs to provide a proof of ownership of an on-chain identity with an associated stake. As part of the network join handshake, peer responding to the handshake will also provide proof of its own stake. The same handshake is executed when two peers already being a part of the network establish a new connection with each other.
The handshake is a 3-round procedure when two parties called initiator and responder exchange messages. The entire handshake procedure can be described with the following diagram:
INITIATOR RESPONDER ¶
[Act 1] nonce1 = random_nonce() act1Message{nonce1, protocol_id1} ---->
[Act 2]
nonce2 = random_nonce()
challenge = sha256(nonce1 || nonce2)
<---- act2Message{challenge, nonce2, protocol_id2}
[Act 3] challenge = sha256(nonce1 || nonce2) act3Message{challenge} ---->
act1Message, act2Message, and act3Message are messages exchanged between initiator and responder in acts one, two, and three of the handshake, respectively.
initiatorAct1, initiatorAct2, and initiatorAct3 represent the state of the initiator in rounds one, two, and three of the handshake, respectively.
responderAct2 and responderAct3 represent the state of the responder in rounds two and three of the handshake, respectively. Since the first act of the handshake is initiated by the initiator and the responder has no internal state before receiving the first message, there is no representation for responder state in the act one.
[RFC]: /docs/rfc/rfc-2-network-security-implementation.adoc
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AnswerHandshake ¶
func AnswerHandshake(message *Act1Message, protocol string) (*responderAct2, error)
AnswerHandshake is used to initiate a responder as a result of receiving message from initiator in the first act of the handshake protocol. The returned responder is in a state ready to execute the second act of the handshake protocol. The function also validates if both parties run the same protocol.
func InitiateHandshake ¶
InitiateHandshake function allows to initiate a handshake by creating and initializing a state machine representing initiator in the first round of the handshake, ready to execute the protocol.
Types ¶
type Act1Message ¶
type Act1Message struct {
// contains filtered or unexported fields
}
Act1Message is sent in the first handshake act by the initiator to the responder. It contains randomly generated `nonce1`, an 8-byte (64-bit) unsigned integer as well as the protocol identifier.
act1Message should be signed with initiator's static private key.
func (*Act1Message) Marshal ¶
func (am *Act1Message) Marshal() ([]byte, error)
Marshal converts this Act1Message to a byte array suitable for network communication.
func (*Act1Message) Unmarshal ¶
func (am *Act1Message) Unmarshal(bytes []byte) error
Unmarshal converts a byte array produced by Marshal to a Act1Message.
type Act2Message ¶
type Act2Message struct {
// contains filtered or unexported fields
}
Act2Message is sent in the second handshake act by the responder to the initiator. It contains randomly generated `nonce2`, which is an 8-byte unsigned integer, `challenge`, which is the result of SHA256 on the concatenated bytes of `nonce1` and `nonce2`, and the protocol identifier.
act2Message should be signed with responder's static private key.
func (*Act2Message) Marshal ¶
func (am *Act2Message) Marshal() ([]byte, error)
Marshal converts this Act2Message to a byte array suitable for network communication.
func (*Act2Message) Unmarshal ¶
func (am *Act2Message) Unmarshal(bytes []byte) error
Unmarshal converts a byte array produced by Marshal to a Act2Message.
type Act3Message ¶
type Act3Message struct {
// contains filtered or unexported fields
}
Act3Message is sent in the third handshake act by the initiator to the responder. It contains the challenge that has been recomputed by the initiator as a SHA256 of the concatenated bytes of `nonce1` and `nonce2`.
act3Message should be signed with initiator's static private key.
func (*Act3Message) Marshal ¶
func (am *Act3Message) Marshal() ([]byte, error)
Marshal converts this Act3Message to a byte array suitable for network communication.
func (*Act3Message) Unmarshal ¶
func (am *Act3Message) Unmarshal(bytes []byte) error
Unmarshal converts a byte array produced by Marshal to a Act3Message.
Source Files