Class NoiseSocket

NoiseSocket provides an encoding layer for the Noise Protocol Framework. NoiseSocket can encode Noise messages and associated negotiation data into a form suitable for transmission over reliable, stream-based protocols such as TCP.

Inheritance
System.Object
NoiseSocket
Implements
System.IDisposable
Inherited Members
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.ToString()
Namespace: Noise
Assembly: NoiseSocket.dll
Syntax
public sealed class NoiseSocket : IDisposable

Constructors

| Improve this Doc View Source

NoiseSocket(Protocol, ProtocolConfig, Stream, Boolean)

Initializes a new instance of the NoiseSocket class.

Declaration
public NoiseSocket(Protocol protocol, ProtocolConfig config, Stream stream, bool leaveOpen = false)
Parameters
Type Name Description
Noise.Protocol protocol

A concrete Noise protocol (e.g. Noise_XX_25519_AESGCM_BLAKE2b).
Noise.ProtocolConfig config

A set of parameters used to instantiate an initial Noise.HandshakeState.
System.IO.Stream stream

The stream for reading and writing encoded protocol messages.
System.Boolean leaveOpen

True to leave the stream open after the NoiseSocket object is disposed, false otherwise.
Exceptions
Type Condition
System.ArgumentNullException

Thrown if either protocol, config, or stream is null.
System.ArgumentException

Thrown if the selected handshake pattern was a one-way pattern.
| Improve this Doc View Source

NoiseSocket(Stream, Boolean)

Initializes a new instance of the NoiseSocket class.

Declaration
public NoiseSocket(Stream stream, bool leaveOpen = false)
Parameters
Type Name Description
System.IO.Stream stream

The stream for reading and writing encoded protocol messages.
System.Boolean leaveOpen

True to leave the stream open after the NoiseSocket object is disposed, false otherwise.
Exceptions
Type Condition
System.ArgumentNullException

Thrown if stream is null.

Properties

| Improve this Doc View Source

HandshakeHash

A value that hashes all the handshake data that's been sent and received. It uniquely identifies the Noise session. It's available only after the handshake has been completed.

Declaration
public ReadOnlySpan<byte> HandshakeHash { get; }
Property Value
Type Description
System.ReadOnlySpan<System.Byte>
Exceptions
Type Condition
System.ObjectDisposedException

Thrown if the current instance has already been disposed.

Methods

| Improve this Doc View Source

Accept(Protocol, ProtocolConfig)

Initializes the current instance of the NoiseSocket class with an initiator's choice of the Noise protocol.

Declaration
public void Accept(Protocol protocol, ProtocolConfig config)
Parameters
Type Name Description
Noise.Protocol protocol

A concrete Noise protocol (e.g. Noise_XX_25519_AESGCM_BLAKE2b).
Noise.ProtocolConfig config

A set of parameters used to instantiate a Noise.HandshakeState.
Exceptions
Type Condition
System.ObjectDisposedException

Thrown if the current instance has already been disposed.
System.NotSupportedException

Thrown if the selected handshake pattern was a one-way pattern.
System.InvalidOperationException

Thrown if the handshake has already been completed, the protocol has already been changed once, or this method was called by the client.
System.ArgumentNullException

Thrown if either protocol or config is null.
System.ArgumentException

Thrown if the server attempted to accept a new protocol as an initiator.
| Improve this Doc View Source

Dispose()

Releases all resources used by the current instance of the NoiseSocket class.

Declaration
public void Dispose()
| Improve this Doc View Source

IgnoreHandshakeMessageAsync(CancellationToken)

Asynchronously consumes the handshake message from the input stream without attempting to decrypt it.

Declaration
public Task IgnoreHandshakeMessageAsync(CancellationToken cancellationToken = default(CancellationToken))
Parameters
Type Name Description
System.Threading.CancellationToken cancellationToken

The token to monitor for cancellation requests.
Returns
Type Description
System.Threading.Tasks.Task

A task that represents the asynchronous read operation.
Exceptions
Type Condition
System.ObjectDisposedException

Thrown if either the current instance, or the input stream has already been disposed.
System.InvalidOperationException

Thrown if the call to this method was unexpected in the current state of this object.
System.IO.IOException

Thrown if an I/O error occurs.
System.NotSupportedException

Thrown if the stream does not support reading.
| Improve this Doc View Source

ReadHandshakeMessageAsync(CancellationToken)

Asynchronously reads the handshake message from the input stream.

Declaration
public Task<byte[]> ReadHandshakeMessageAsync(CancellationToken cancellationToken = default(CancellationToken))
Parameters
Type Name Description
System.Threading.CancellationToken cancellationToken

The token to monitor for cancellation requests.
Returns
Type Description
System.Threading.Tasks.Task<System.Byte[]>

A task that represents the asynchronous read operation. The result of the task contains the decrypted message body.
Remarks

This method can also throw all exceptions that Noise.Protocol.Create(Noise.ProtocolConfig) and Noise.HandshakeState.Fallback(Noise.Protocol,Noise.ProtocolConfig) methods can throw. See Noise.Protocol and Noise.HandshakeState documentation for more details.

Exceptions
Type Condition
System.ObjectDisposedException

Thrown if either the current instance, or the input stream has already been disposed.
System.InvalidOperationException

Thrown if the call to this method was unexpected in the current state of this object.
System.ArgumentException

Thrown if the decrypted message body length was invalid.
System.Security.Cryptography.CryptographicException

Thrown if the decryption of the message has failed.
System.IO.IOException

Thrown if an I/O error occurs.
System.NotSupportedException

Thrown if the stream does not support reading.
| Improve this Doc View Source

ReadMessageAsync(CancellationToken)

Asynchronously reads the transport message from the input stream.

Declaration
public Task<byte[]> ReadMessageAsync(CancellationToken cancellationToken = default(CancellationToken))
Parameters
Type Name Description
System.Threading.CancellationToken cancellationToken

The token to monitor for cancellation requests.
Returns
Type Description
System.Threading.Tasks.Task<System.Byte[]>

A task that represents the asynchronous read operation. The result of the task contains the decrypted message body.
Exceptions
Type Condition
System.ObjectDisposedException

Thrown if either the current instance, or the input stream has already been disposed.
System.InvalidOperationException

Thrown if the handshake has not yet been completed, or the initiator has attempted to read a message from a one-way stream.
System.ArgumentException

Thrown if the decrypted message body length was invalid.
System.Security.Cryptography.CryptographicException

Thrown if the decryption of the message has failed.
System.IO.IOException

Thrown if an I/O error occurs.
System.NotSupportedException

Thrown if the stream does not support reading.
| Improve this Doc View Source

ReadNegotiationDataAsync(CancellationToken)

Asynchronously reads the negotiation data from the input stream.

Declaration
public Task<byte[]> ReadNegotiationDataAsync(CancellationToken cancellationToken = default(CancellationToken))
Parameters
Type Name Description
System.Threading.CancellationToken cancellationToken

The token to monitor for cancellation requests.
Returns
Type Description
System.Threading.Tasks.Task<System.Byte[]>

A task that represents the asynchronous read operation. The result of the task contains the negotiation data.
Exceptions
Type Condition
System.ObjectDisposedException

Thrown if either the current instance, or the input stream has already been disposed.
System.InvalidOperationException

Thrown if the call to this method was unexpected in the current state of this object.
System.IO.IOException

Thrown if an I/O error occurs.
System.NotSupportedException

Thrown if the stream does not support reading.
| Improve this Doc View Source

Retry(Protocol, ProtocolConfig)

Reinitializes the current instance of the NoiseSocket class with a new Noise protocol, different from the initial Noise protocol. The reason for the reinitialization was responder's retry request.

Declaration
public void Retry(Protocol protocol, ProtocolConfig config)
Parameters
Type Name Description
Noise.Protocol protocol

A concrete Noise protocol (e.g. Noise_XX_25519_AESGCM_BLAKE2b).
Noise.ProtocolConfig config

A set of parameters used to instantiate a Noise.HandshakeState.
Exceptions
Type Condition
System.ObjectDisposedException

Thrown if the current instance has already been disposed.
System.NotSupportedException

Thrown if the selected handshake pattern was a one-way pattern.
System.InvalidOperationException

Thrown if the handshake has already been completed or the protocol has already been changed once.
System.ArgumentNullException

Thrown if either protocol or config is null.
System.ArgumentException

Thrown if the client attempted to retry with a new protocol as a responder, or the server attempted to retry with a new protocol as an initiator.
| Improve this Doc View Source

Switch(Protocol, ProtocolConfig)

Reinitializes the current instance of the NoiseSocket class with a new Noise protocol, different from the initial Noise protocol. The reason for the reinitialization was responder's decision to switch protocol.

Declaration
public void Switch(Protocol protocol, ProtocolConfig config)
Parameters
Type Name Description
Noise.Protocol protocol

A concrete Noise protocol (e.g. Noise_XX_25519_AESGCM_BLAKE2b).
Noise.ProtocolConfig config

A set of parameters used to instantiate a Noise.HandshakeState.
Exceptions
Type Condition
System.ObjectDisposedException

Thrown if the current instance has already been disposed.
System.NotSupportedException

Thrown if the selected handshake pattern was a one-way pattern.
System.InvalidOperationException

Thrown if the handshake has already been completed, the protocol has already been changed once, or the server attempted to perform the fallback handshake without being previously initialized.
System.ArgumentNullException

Thrown if either protocol or config is null.
System.ArgumentException

Thrown if the client attempted to switch to a new protocol as an initiator, or the server attempted to switch to a new protocol as a responder.
| Improve this Doc View Source

WriteEmptyHandshakeMessageAsync(Memory<Byte>, CancellationToken)

Asynchronously writes the negotiation data and the empty handshake message to the input stream. Called by the server when rejecting the initial protocol, or requesting a retry from the client.

Declaration
public Task WriteEmptyHandshakeMessageAsync(Memory<byte> negotiationData = default(Memory<byte>), CancellationToken cancellationToken = default(CancellationToken))
Parameters
Type Name Description
System.Memory<System.Byte> negotiationData

The negotiation data.
System.Threading.CancellationToken cancellationToken

The token to monitor for cancellation requests.
Returns
Type Description
System.Threading.Tasks.Task

A task that represents the asynchronous write operation.
Exceptions
Type Condition
System.ObjectDisposedException

Thrown if either the current instance, or the output stream has already been disposed.
System.InvalidOperationException

Thrown if the call to this method was unexpected in the current state of this object.
System.ArgumentException

Thrown if the negotiation data was greater than Noise.Protocol.MaxMessageLength bytes in length.
System.IO.IOException

Thrown if an I/O error occurs.
System.NotSupportedException

Thrown if the stream does not support reading.
| Improve this Doc View Source

WriteHandshakeMessageAsync(Memory<Byte>, Memory<Byte>, UInt16, CancellationToken)

Asynchronously writes the negotiation data and the handshake message to the input stream.

Declaration
public Task WriteHandshakeMessageAsync(Memory<byte> negotiationData = default(Memory<byte>), Memory<byte> messageBody = default(Memory<byte>), ushort paddedLength = 0, CancellationToken cancellationToken = default(CancellationToken))
Parameters
Type Name Description
System.Memory<System.Byte> negotiationData

The negotiation data.
System.Memory<System.Byte> messageBody

The message body to encrypt.
System.UInt16 paddedLength

If this message has an encrypted payload and the length of the messageBody is less than paddedLength, messageBody is padded to make its length equal to paddedLength.
System.Threading.CancellationToken cancellationToken

The token to monitor for cancellation requests.
Returns
Type Description
System.Threading.Tasks.Task

A task that represents the asynchronous write operation.
Remarks

This method can also throw all exceptions that Noise.Protocol.Create(Noise.ProtocolConfig) and Noise.HandshakeState.Fallback(Noise.Protocol,Noise.ProtocolConfig) methods can throw. See Noise.Protocol and Noise.HandshakeState documentation for more details.

Exceptions
Type Condition
System.ObjectDisposedException

Thrown if either the current instance, or the output stream has already been disposed.
System.InvalidOperationException

Thrown if the call to this method was unexpected in the current state of this object.
System.ArgumentException

Thrown if either the negotiation data, or the Noise message was greater than Noise.Protocol.MaxMessageLength bytes in length.
System.IO.IOException

Thrown if an I/O error occurs.
System.NotSupportedException

Thrown if the stream does not support reading.
| Improve this Doc View Source

WriteMessageAsync(Memory<Byte>, UInt16, CancellationToken)

Asynchronously writes the transport message to the input stream.

Declaration
public Task WriteMessageAsync(Memory<byte> messageBody, ushort paddedLength = 0, CancellationToken cancellationToken = default(CancellationToken))
Parameters
Type Name Description
System.Memory<System.Byte> messageBody

The message body to encrypt.
System.UInt16 paddedLength

If the length of the messageBody is less than paddedLength, messageBody is padded to make its length equal to paddedLength.
System.Threading.CancellationToken cancellationToken

The token to monitor for cancellation requests.
Returns
Type Description
System.Threading.Tasks.Task

A task that represents the asynchronous write operation.
Exceptions
Type Condition
System.ObjectDisposedException

Thrown if either the current instance, or the output stream has already been disposed.
System.InvalidOperationException

Thrown if the handshake has not yet been completed, or the responder has attempted to write a message to a one-way stream.
System.ArgumentException

Thrown if the encrypted payload was greater than Noise.Protocol.MaxMessageLength bytes in length.
System.IO.IOException

Thrown if an I/O error occurs.
System.NotSupportedException

Thrown if the stream does not support writing.

Implements

System.IDisposable