Package org.drasyl.remote.protocol

Class RemoteEnvelope<T extends com.google.protobuf.MessageLite>

java.lang.Object

org.drasyl.remote.protocol.RemoteEnvelope<T>

All Implemented Interfaces:

io.netty.util.ReferenceCounted, AutoCloseable

public class RemoteEnvelope<T extends com.google.protobuf.MessageLite>
extends Object
implements io.netty.util.ReferenceCounted, AutoCloseable

This class allows to read a given ByteBuf encoded protobuf message in parts with only decoding the requested parts of the given ByteBuf. If a part was request it will be translated into a Java object.

Field Summary

Fields

Modifier and Type	Field	Description
static com.google.protobuf.ByteString	MAGIC_NUMBER
static short	MAGIC_NUMBER_LENGTH

Method Summary

Modifier and Type	Method	Description
static RemoteEnvelope<Protocol.Acknowledgement>	acknowledgement(int networkId, IdentityPublicKey sender, ProofOfWork proofOfWork, IdentityPublicKey recipient, Nonce correspondingId)	Creates new Protocol.Acknowledgement message (reply to Protocol.Discovery message).
static RemoteEnvelope<Protocol.Application>	application(int networkId, IdentityPublicKey sender, ProofOfWork proofOfWork, IdentityPublicKey recipient, String type, byte[] payload)	Creates new Protocol.Application message.
RemoteEnvelope<T>	arm(com.goterl.lazysodium.utils.SessionPair sessionPair)	Returns an armed version of this envelope for sending it through untrustworthy channels.
RemoteEnvelope<T>	armAndRelease(com.goterl.lazysodium.utils.SessionPair sessionPair)	Returns an armed version of this envelope for sending it through untrustworthy channels.
void	close()
io.netty.buffer.ByteBuf	copy()	This method returns a copy of the RemoteEnvelope and resets the reader index to 0.
RemoteEnvelope<T>	disarm(com.goterl.lazysodium.utils.SessionPair sessionPair)	Returns a disarmed version of this envelope.
RemoteEnvelope<T>	disarmAndRelease(com.goterl.lazysodium.utils.SessionPair sessionPair)	Returns a disarmed version of this envelope.
static RemoteEnvelope<Protocol.Discovery>	discovery(int networkId, IdentityPublicKey sender, ProofOfWork proofOfWork)	Creates a new multicast Protocol.Discovery message (sent by LocalNetworkDiscovery}.
static RemoteEnvelope<Protocol.Discovery>	discovery(int networkId, IdentityPublicKey sender, ProofOfWork proofOfWork, IdentityPublicKey recipient, long joinTime)	Creates a new Protocol.Discovery message (sent by InternetDiscovery).
AgreementId	getAgreementId()
T	getBody()	Reads only the body of the given message and retains the underlying byte representation of the full message.
T	getBodyAndRelease()	Reads only the body of the given message and releases the underlying byte representation of the full message.
UnsignedShort	getChunkNo()	Returns the number of the chunk.
byte	getHopCount()
io.netty.buffer.ByteBuf	getInternalByteBuf()	This method returns the internal wrapped ByteBuf of this RemoteEnvelope.
int	getNetworkId()
Nonce	getNonce()
io.netty.buffer.ByteBuf	getOrBuildByteBuf()	The external ByteBuf or if null builds it first.
Protocol.PrivateHeader	getPrivateHeader()	Reads only the (private) header of the given message and retains the underlying byte representation of the full message.
ProofOfWork	getProofOfWork()
Protocol.PublicHeader	getPublicHeader()	Reads only the public header of the given message and retains the underlying byte representation of the full message.
Pair<Protocol.PublicHeader,io.netty.buffer.ByteBuf>	getPublicHeaderAndRemainingBytes()	Reads the public header of the given message and returns a ByteBuf with all remaining bytes.
IdentityPublicKey	getRecipient()	Returns the IdentityPublicKey of the message recipient.
IdentityPublicKey	getSender()
UnsignedShort	getTotalChunks()	Returns the total chunks number.
void	incrementHopCount()
boolean	isChunk()	Returns true if this message is a chunk.
static RemoteEnvelope<Protocol.KeyExchange>	keyExchange(int networkId, IdentityPublicKey sender, ProofOfWork identityProofOfWork, IdentityPublicKey recipient, KeyAgreementPublicKey sessionKey)	Creates a new Protocol.KeyExchange message (sent by ArmHandler; used for perfect forwarded secrecy).
static RemoteEnvelope<Protocol.KeyExchangeAcknowledgement>	keyExchangeAcknowledgement(int networkId, IdentityPublicKey sender, ProofOfWork identityProofOfWork, IdentityPublicKey recipient, AgreementId agreementId)	Creates a new Protocol.KeyExchangeAcknowledgement message (sent by ArmHandler; used for perfect forwarded secrecy).
static <T extends com.google.protobuf.MessageLite> RemoteEnvelope<T>	of(io.netty.buffer.ByteBuf message)	Wraps the given ByteBuf into an RemoteEnvelope.
static <T extends com.google.protobuf.MessageLite> RemoteEnvelope<T>	of(Protocol.PublicHeader publicHeader, byte[] bytes)	Creates a message envelope from publicHeader and bytes
static <T extends com.google.protobuf.MessageLite> RemoteEnvelope<T>	of(Protocol.PublicHeader publicHeader, io.netty.buffer.ByteBuf bytes)	Creates a message envelope from publicHeader and bytes.
static <T extends com.google.protobuf.MessageLite> RemoteEnvelope<T>	of(Protocol.PublicHeader publicHeader, Protocol.PrivateHeader privateHeader, T body)	Creates a message envelope from publicHeader, privateHeader, and body.
int	refCnt()
boolean	release()
boolean	release(int decrement)
void	releaseAll()	This method does release all used ByteBufs.
io.netty.util.ReferenceCounted	retain()
io.netty.util.ReferenceCounted	retain(int increment)
RemoteEnvelope<T>	setAgreementId(AgreementId agreementId)
String	toString()
io.netty.util.ReferenceCounted	touch()
io.netty.util.ReferenceCounted	touch(Object hint)
static RemoteEnvelope<Protocol.Unite>	unite(int networkId, IdentityPublicKey sender, ProofOfWork proofOfWork, IdentityPublicKey recipient, IdentityPublicKey publicKey, InetSocketAddress address)	Creates a new Protocol.Unite message (sent by InternetDiscovery; used for UDP hole punching}.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

MAGIC_NUMBER

public static final com.google.protobuf.ByteString MAGIC_NUMBER

MAGIC_NUMBER_LENGTH

public static final short MAGIC_NUMBER_LENGTH

Method Detail

toString

public String toString()

Overrides:

toString in class Object

close

public void close()

Specified by:

close in interface AutoCloseable

of

public static <T extends com.google.protobuf.MessageLite> RemoteEnvelope<T> of(io.netty.buffer.ByteBuf message)
                                                                        throws InvalidMessageFormatException

Wraps the given ByteBuf into an RemoteEnvelope.

Note: The given message ByteBuf will not be modified. This object uses a duplicate of the given ByteBuf.

ReferenceCounted.release() ownership of message is transferred to this RemoteEnvelope.

Parameters:

message - the message that should be wrapped. ReferenceCounted.release() ownership is transferred to this RemoteEnvelope.

Returns:

an RemoteEnvelope

Throws:

InvalidMessageFormatException - if the given ByteBuf is not readable

of

public static <T extends com.google.protobuf.MessageLite> RemoteEnvelope<T> of(Protocol.PublicHeader publicHeader,
                                                                               Protocol.PrivateHeader privateHeader,
                                                                               T body)

Creates a message envelope from publicHeader, privateHeader, and body.

Parameters:

publicHeader - message's public header

privateHeader - message's private header

body - the message

Returns:

an RemoteEnvelope

of

public static <T extends com.google.protobuf.MessageLite> RemoteEnvelope<T> of(Protocol.PublicHeader publicHeader,
                                                                               byte[] bytes)
                                                                        throws InvalidMessageFormatException

Creates a message envelope from publicHeader and bytes

Parameters:

publicHeader - message's public header

bytes - message's remainder as bytes (may be encrypted)

Returns:

an RemoteEnvelope

Throws:

InvalidMessageFormatException - if publicHeader and bytes can not be serialized

of

public static <T extends com.google.protobuf.MessageLite> RemoteEnvelope<T> of(Protocol.PublicHeader publicHeader,
                                                                               io.netty.buffer.ByteBuf bytes)
                                                                        throws InvalidMessageFormatException

Creates a message envelope from publicHeader and bytes.

ReferenceCounted.release() ownership of bytes is transferred to this RemoteEnvelope.

Parameters:

publicHeader - message's public header

bytes - message's remainder as bytes (may be encrypted). ReferenceCounted.release() ownership is transferred to this RemoteEnvelope.

Returns:

an RemoteEnvelope

Throws:

InvalidMessageFormatException - if publicHeader and bytes can not be serialized

getPublicHeader

public Protocol.PublicHeader getPublicHeader()
                                      throws InvalidMessageFormatException

Reads only the public header of the given message and retains the underlying byte representation of the full message.

Returns:

header of the message

Throws:

InvalidMessageFormatException - if the public header cannot be read

getPrivateHeader

public Protocol.PrivateHeader getPrivateHeader()
                                        throws InvalidMessageFormatException

Reads only the (private) header of the given message and retains the underlying byte representation of the full message.

Returns:

the private header

Throws:

InvalidMessageFormatException - if the private header cannot be read

getBody

public T getBody()
          throws InvalidMessageFormatException

Reads only the body of the given message and retains the underlying byte representation of the full message.

Returns:

the body

Throws:

InvalidMessageFormatException - if the body cannot be read

getBodyAndRelease

public T getBodyAndRelease()
                    throws InvalidMessageFormatException

Reads only the body of the given message and releases the underlying byte representation of the full message.

Returns:

the body

Throws:

InvalidMessageFormatException - if the body cannot be read

copy

public io.netty.buffer.ByteBuf copy()

This method returns a copy of the RemoteEnvelope and resets the reader index to 0.

Returns:

the wrapped ByteBuf of this envelope

getInternalByteBuf

public io.netty.buffer.ByteBuf getInternalByteBuf()

This method returns the internal wrapped ByteBuf of this RemoteEnvelope.

Returns:

the internal wrapped ByteBuf

getOrBuildByteBuf

public io.netty.buffer.ByteBuf getOrBuildByteBuf()
                                          throws InvalidMessageFormatException

The external ByteBuf or if null builds it first.

Returns:

the envelope as ByteBuf

Throws:

InvalidMessageFormatException - if the envelope can't be build

refCnt

public int refCnt()

Specified by:

refCnt in interface io.netty.util.ReferenceCounted

retain

public io.netty.util.ReferenceCounted retain()

Specified by:

retain in interface io.netty.util.ReferenceCounted

retain

public io.netty.util.ReferenceCounted retain(int increment)

Specified by:

retain in interface io.netty.util.ReferenceCounted

touch

public io.netty.util.ReferenceCounted touch()

Specified by:

touch in interface io.netty.util.ReferenceCounted

touch

public io.netty.util.ReferenceCounted touch(Object hint)

Specified by:

touch in interface io.netty.util.ReferenceCounted

release

public boolean release()

Specified by:

release in interface io.netty.util.ReferenceCounted

release

public boolean release(int decrement)

Specified by:

release in interface io.netty.util.ReferenceCounted

releaseAll

public void releaseAll()

This method does release all used ByteBufs. The corresponding elements where also set to null.

getNonce

public Nonce getNonce()
               throws InvalidMessageFormatException

Throws:

InvalidMessageFormatException - if the public header cannot be read

getNetworkId

public int getNetworkId()
                 throws InvalidMessageFormatException

Throws:

InvalidMessageFormatException - if the public header cannot be read

getSender

public IdentityPublicKey getSender()
                            throws InvalidMessageFormatException

Throws:

InvalidMessageFormatException - if the public header cannot be read

getProofOfWork

public ProofOfWork getProofOfWork()
                           throws InvalidMessageFormatException

Throws:

InvalidMessageFormatException - if the public header cannot be read

getRecipient

public IdentityPublicKey getRecipient()
                               throws InvalidMessageFormatException

Returns the IdentityPublicKey of the message recipient. If the message has no recipient (e.g. because it is a multicast message) null is returned.

Throws:

InvalidMessageFormatException - if the public header cannot be read

getHopCount

public byte getHopCount()
                 throws InvalidMessageFormatException

Throws:

InvalidMessageFormatException - if the public header cannot be read

getAgreementId

public AgreementId getAgreementId()
                           throws InvalidMessageFormatException

Returns:

AgreementId or null if no key was used

Throws:

InvalidMessageFormatException - if the public header cannot be read or be updated

incrementHopCount

public void incrementHopCount()
                       throws InvalidMessageFormatException

Throws:

InvalidMessageFormatException - if the public header cannot be read or be updated

getPublicHeaderAndRemainingBytes

public Pair<Protocol.PublicHeader,io.netty.buffer.ByteBuf> getPublicHeaderAndRemainingBytes()
                                                                                           throws InvalidMessageFormatException

Reads the public header of the given message and returns a ByteBuf with all remaining bytes.

Note: The given ByteBuf is inherited from getInternalByteBuf() and will therefore use the same reference counter. Meaning that releasing getInternalByteBuf() will invalidate the returned ByteBuf and vice versa.

Returns:

Pair with public header as first element and ByteBuf with all remaining bytes as second element

Throws:

InvalidMessageFormatException - if the public header cannot be read

setAgreementId

public RemoteEnvelope<T> setAgreementId(AgreementId agreementId)
                                 throws InvalidMessageFormatException

Throws:

InvalidMessageFormatException - if the public header cannot be read or be updated

arm

public RemoteEnvelope<T> arm(com.goterl.lazysodium.utils.SessionPair sessionPair)
                      throws InvalidMessageFormatException

Returns an armed version of this envelope for sending it through untrustworthy channels.

Arming includes the following steps:

• getPublicHeader() will be added as authentication tag
• privateHeader and body will be encrypted with sessionPair

Note: Do not forget to release the original message

Parameters:

sessionPair - will be used for encryption

Returns:

the armed version of this envelope

Throws:

InvalidMessageFormatException - if arming was not possible

armAndRelease

public RemoteEnvelope<T> armAndRelease(com.goterl.lazysodium.utils.SessionPair sessionPair)
                                throws InvalidMessageFormatException

Returns an armed version of this envelope for sending it through untrustworthy channels.

Arming includes the following steps:

• getPublicHeader() will be added as authentication tag
• privateHeader and body will be encrypted with sessionPair

This method will release all resources even in case of an exception.

Parameters:

sessionPair - will be used for encryption

Returns:

the armed version of this envelope

Throws:

InvalidMessageFormatException - if arming was not possible

disarm

public RemoteEnvelope<T> disarm(com.goterl.lazysodium.utils.SessionPair sessionPair)
                         throws InvalidMessageFormatException

Returns a disarmed version of this envelope.

secretKey must match message's recipient (not implemented yet!).

Disarming includes the following steps:

• the encrypted privateHeader and encrypted body will be decrypted with secretKey (not implemented yet!)
• the signed portions of the message (privateHeader and body) are verified against sender's public key.

Note: Do not forget to release the original message

Returns:

the disarmed version of this envelope

Throws:

InvalidMessageFormatException - if disarming was not possible

disarmAndRelease

public RemoteEnvelope<T> disarmAndRelease(com.goterl.lazysodium.utils.SessionPair sessionPair)
                                   throws InvalidMessageFormatException

Returns a disarmed version of this envelope.

secretKey must match message's recipient (not implemented yet!).

Disarming includes the following steps:

• the encrypted privateHeader and encrypted body will be decrypted with secretKey (not implemented yet!)
• the signed portions of the message (privateHeader and body) are verified against sender's public key.

This method will release all resources even in case of an exception.

Returns:

the disarmed version of this envelope

Throws:

InvalidMessageFormatException - if disarming was not possible

acknowledgement

public static RemoteEnvelope<Protocol.Acknowledgement> acknowledgement(int networkId,
                                                                       IdentityPublicKey sender,
                                                                       ProofOfWork proofOfWork,
                                                                       IdentityPublicKey recipient,
                                                                       Nonce correspondingId)

Creates new Protocol.Acknowledgement message (reply to Protocol.Discovery message).

Parameters:

networkId - the network id of the node server

sender - the public key of the node server

proofOfWork - the proof of work of the node server

recipient - the public key of the recipient

correspondingId - the corresponding id of the previous join message

Throws:

NullPointerException - if sender, proofOfWork, recipient, or correspondingId is null

application

public static RemoteEnvelope<Protocol.Application> application(int networkId,
                                                               IdentityPublicKey sender,
                                                               ProofOfWork proofOfWork,
                                                               IdentityPublicKey recipient,
                                                               String type,
                                                               byte[] payload)

Creates new Protocol.Application message.

Parameters:

networkId - the network the sender belongs to

sender - the sender

proofOfWork - the sender's proof of work

recipient - the recipient

type - the payload type

payload - the data to be sent

Throws:

NullPointerException - if sender, proofOfWork, recipient, or payload is null

discovery

public static RemoteEnvelope<Protocol.Discovery> discovery(int networkId,
                                                           IdentityPublicKey sender,
                                                           ProofOfWork proofOfWork,
                                                           IdentityPublicKey recipient,
                                                           long joinTime)

Creates a new Protocol.Discovery message (sent by InternetDiscovery).

Parameters:

networkId - the network of the joining node

sender - the public key of the joining node

proofOfWork - the proof of work

recipient - the public key of the node to join

joinTime - if 0 greater then 0, node will join a children.

Throws:

NullPointerException - if sender, proofOfWork, or recipient is null

discovery

public static RemoteEnvelope<Protocol.Discovery> discovery(int networkId,
                                                           IdentityPublicKey sender,
                                                           ProofOfWork proofOfWork)

Creates a new multicast Protocol.Discovery message (sent by LocalNetworkDiscovery}.

Parameters:

networkId - the network of the joining node

sender - the public key of the joining node

proofOfWork - the proof of work

Throws:

NullPointerException - if sender, or proofOfWork is null

unite

public static RemoteEnvelope<Protocol.Unite> unite(int networkId,
                                                   IdentityPublicKey sender,
                                                   ProofOfWork proofOfWork,
                                                   IdentityPublicKey recipient,
                                                   IdentityPublicKey publicKey,
                                                   InetSocketAddress address)

Creates a new Protocol.Unite message (sent by InternetDiscovery; used for UDP hole punching}.

Parameters:

networkId - the network of the super peer node

sender - the public key of the super peer node

proofOfWork - the super peer's proof of work

recipient - the recipient of this message

publicKey - the public key of the node with which the receiver should unite

address - the InetSocketAddress of the node with which the receiver should unite

Throws:

NullPointerException - if sender, proofOfWork, recipient, publicKey, or address is null

IllegalArgumentException - if address is unresolved

keyExchange

public static RemoteEnvelope<Protocol.KeyExchange> keyExchange(int networkId,
                                                               IdentityPublicKey sender,
                                                               ProofOfWork identityProofOfWork,
                                                               IdentityPublicKey recipient,
                                                               KeyAgreementPublicKey sessionKey)

Creates a new Protocol.KeyExchange message (sent by ArmHandler; used for perfect forwarded secrecy).

Parameters:

networkId - the network of the node

sender - the public key of the node

identityProofOfWork - the node's proof of work

recipient - the recipient of this message

sessionKey - the ephemeral key agreement key

Returns:

Protocol.KeyExchange message or exception

Throws:

NullPointerException - if sender, identityProofOfWork, recipient, sessionKey, or sessionProofOfWork is null

keyExchangeAcknowledgement

public static RemoteEnvelope<Protocol.KeyExchangeAcknowledgement> keyExchangeAcknowledgement(int networkId,
                                                                                             IdentityPublicKey sender,
                                                                                             ProofOfWork identityProofOfWork,
                                                                                             IdentityPublicKey recipient,
                                                                                             AgreementId agreementId)

Creates a new Protocol.KeyExchangeAcknowledgement message (sent by ArmHandler; used for perfect forwarded secrecy).

Parameters:

networkId - the network of the node

sender - the public key of the node

identityProofOfWork - the node's proof of work

recipient - the recipient of this message

agreementId - the id of the used session

Returns:

Protocol.KeyExchangeAcknowledgement message or exception

Throws:

NullPointerException - if sender, identityProofOfWork, recipient, or keyId is null

isChunk

public boolean isChunk()
                throws InvalidMessageFormatException

Returns true if this message is a chunk. Otherwise false is returned.

Returns:

true if this message is a chunk. Otherwise false.

Throws:

InvalidMessageFormatException - if the public header cannot be read

getChunkNo

public UnsignedShort getChunkNo()
                         throws InvalidMessageFormatException

Returns the number of the chunk. If the message is not a chunk, 0 is returned.

Returns:

number of the chunk or 0 if message is not a chunk

Throws:

InvalidMessageFormatException - if the public header cannot be read

getTotalChunks

public UnsignedShort getTotalChunks()
                             throws InvalidMessageFormatException

Returns the total chunks number. If the message is not a chunk, 0 is returned.

Returns:

total chunks number or 0 if message is not a chunk

Throws:

InvalidMessageFormatException - if the public header cannot be read