Documentation
¶
Overview ¶
Package onion contains the functions required to generate onion packets and unwrap them one layer at a time.
An onion packet is a specially formed packet in which several layers of data are bundled together with layers of encryption between them in order to enable sending of information with forwarding instructions and per-hop data specific to the task of the onion.
This package provides for three main types of onions:
- Session purchases - acquiring the session seed and cipher for source routed onion hops.
- Acknowledgment reverse onions - special onions that can be embedded in a layer that can be anonymously returned to the originator of a packet so that the sender can track the progress of the path for latency guarantee, path failure diagnostics, or onion session purchase progress monitoring.
- Onion packets, which are much larger, 8, 16, 32, 48 or 64kb in size, in which are embedded routing instructions, potentially acknowledgment onions, for onion route circuits and the actual data payload and session bandwidth counters for authentication to sessions.
Index ¶
- func Encode(on types.Onion) (b slice.Bytes)
- func Gen3Nonces() (n [3]nonce.IV)
- func GenCiphers(prvs [3]*prv.Key, pubs [3]*pub.Key) (ciphers [3]sha256.Hash)
- func GenNonces(count int) (n []nonce.IV)
- func GenPingNonces() (n [6]nonce.IV)
- func Peel(b slice.Bytes, c *slice.Cursor) (on types.Onion, e error)
- type Skins
- func GetBalance(s traffic.Circuit, target int, returns [3]*traffic.Session, ks *signer.KeySet) (o Skins)
- func Ping(id nonce.ID, client *traffic.Session, s traffic.Circuit, ks *signer.KeySet) Skins
- func SendExit(payload slice.Bytes, port uint16, client *traffic.Session, s traffic.Circuit, ...) Skins
- func SendKeys(id nonce.ID, hdr, pld [5]*prv.Key, client *traffic.Session, ...) Skins
- func (o Skins) Assemble() (on types.Onion)
- func (o Skins) Balance(id nonce.ID, amt lnwire.MilliSatoshi) Skins
- func (o Skins) Confirmation(id nonce.ID) Skins
- func (o Skins) Crypt(to *pub.Key, from *prv.Key, n nonce.IV) Skins
- func (o Skins) Delay(d time.Duration) Skins
- func (o Skins) DirectBalance(id nonce.ID) Skins
- func (o Skins) Exit(port uint16, prvs [3]*prv.Key, pubs [3]*pub.Key, nonces [3]nonce.IV, ...) Skins
- func (o Skins) Forward(addr *netip.AddrPort) Skins
- func (o Skins) ForwardCrypt(s *traffic.Session, k *prv.Key, n nonce.IV) Skins
- func (o Skins) ForwardSession(s *traffic.Session, k *prv.Key, n nonce.IV, hdr, pld *prv.Key) Skins
- func (o Skins) GetBalance(id nonce.ID, prvs [3]*prv.Key, pubs [3]*pub.Key, nonces [3]nonce.IV) Skins
- func (o Skins) Response(hash sha256.Hash, res slice.Bytes) Skins
- func (o Skins) Reverse(ip *netip.AddrPort) Skins
- func (o Skins) ReverseCrypt(s *traffic.Session, k *prv.Key, n nonce.IV) Skins
- func (o Skins) Session(hdr, pld *prv.Key) Skins
- func (o Skins) Token(tok sha256.Hash) Skins
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Gen3Nonces ¶
func GenPingNonces ¶
Types ¶
type Skins ¶
func GetBalance ¶
func GetBalance(s traffic.Circuit, target int, returns [3]*traffic.Session, ks *signer.KeySet) (o Skins)
GetBalance sends out a request in a similar way to SendExit except the node being queried can be any of the 5 and the return path is always a further two hops until the client.
First and last hop sessions are just directly queried, and the rest the path goes to them and then through two return hops in the second last and last positions, because it cannot be concealed that the client is not a relay.
The first and last hops already have a payload session key ready to use and all that is then sent back is a crypt with the query ID and session balance addressed to the Header key.
func Ping ¶
Ping is a message which checks the liveness of relays by ensuring they are correctly relaying messages.
The pending ping records keep the identifiers of the 5 nodes that were in a ping onion and when the Confirmation is correctly received these nodes get an increment of their liveness score. By using this scheme, when nodes are offline their scores will fall to zero after a time whereas live nodes will have steadily increasing scores from successful pings.
func SendExit ¶
func SendExit(payload slice.Bytes, port uint16, client *traffic.Session, s traffic.Circuit, ks *signer.KeySet) Skins
SendExit constructs a message containing an arbitrary payload to a node (3rd hop) with a set of 3 ciphers derived from the hidden PayloadPub of the return hops that are layered progressively after the Exit message.
The Exit node forwards the packet it receives to the local port specified in the Exit message, and then uses the ciphers to encrypt the reply with the three ciphers provided, which don't enable it to decrypt the header, only to encrypt the payload.
The response is encrypted with the given layers, the ciphers are already given in reverse order, so they are decoded in given order to create the correct payload encryption to match the PayloadPub combined with the header's given public From key.
The header remains a constant size and each node in the Reverse trims off their section at the top, moves the next crypt header to the top and pads the remainder with noise, so it always looks like the first hop.
func SendKeys ¶
func SendKeys(id nonce.ID, hdr, pld [5]*prv.Key, client *traffic.Session, hop traffic.Circuit, ks *signer.KeySet) Skins
SendKeys provides a pair of private keys that will be used to generate the Purchase header bytes and to generate the ciphers provided in the Purchase message to encrypt the Session that is returned.
The OnionSkin key, its cloaked public key counterpart used in the To field of the Purchase message preformed header bytes, but the Ciphers provided in the Purchase message, for encrypting the Session to be returned, uses the Payload key, along with the public key found in the encrypted crypt of the header for the Reverse relay.
This message's last crypt is a Confirmation, which allows the client to know that the keys were successfully delivered.
This is the only onion that uses the node identity keys. The payment preimage hash must be available or the relay should not forward the remainder of the packet.
If hdr/pld cipher keys are nil there must be a HeaderPub available on the session for the hop. This allows this function to send keys to any number of hops, but the very first SendKeys must have all in order to create the first set of sessions. This is by way of indicating to not use the IdentityPub but the HeaderPub instead. Not allowing free relay at all prevents spam attacks.
func (Skins) Assemble ¶
Assemble inserts the slice of Layer s inside each other so the first then contains the second, second contains the third, and so on, and then returns the first onion, on which you can then call Encode and generate the wire message form of the onion.
Source Files
Directories