V2 implementation of a SecureChannel class. More...

Inheritance diagram for OSDP.Net.Messages.SecureChannel.MessageSecureChannel:

Public Member Functions

byte[] DecodePayload (byte[] payload)

Decodes the payload using the secure channel context.This function can only be called once IsSecurityEstablished is true

Parameters

payload Payload to be decrypted

Returns: Plaintext message payload. Similarly to how original payload must have been padded prior to being encrypted, the plaintext byte buffer returned here will also be padded and therefore its length will always be divisible by 16. The padding at the end of the buffer will always consist of zero or more 0x00 bytes preceeded by 0x80 byte.

void EncodePayload (byte[] payload, Span< byte > destination)

Encrypts the payload using the secure channel context.This function can only be called once IsSecurityEstablished is true.

Parameters

payload	Payload to be encrypted. NOTE: This data MUST already be padded in according to OSDP specification: a) there must be at least one byte of padding; b) payloaded is padded with 0x00, except for the very first byte of padding which must be 0x80; c) total length must be divisible by AES block size of 16 bytes.
destination	Identifies where encoded data is to written to

ReadOnlySpan< byte > GenerateMac (ReadOnlySpan< byte > message, bool isIncoming)

Generates a new Message Authentication Code.Note this command IS NOT idempotent as every time it is called it will calculate a new rolling MAC value based on the results of the previous call

Parameters

message	Message to be signed with a MAC
isIncoming	If true, indicates that the message was received from the wire. If false, indicates that the message is being sent out on the wire

Returns: 16-byte MAC value of the message

void InitializeACU (byte[] clientRandomNumber, byte[] clientCryptogram)

Initializes the Access Control Unit (ACU) in the secure channel context.

Parameters

clientRandomNumber	The client random number.
clientCryptogram	The client cryptogram.

void ResetSecureChannelSession ()

Resets the secure channel session by creating a new random number.

void Establish (byte[] rmac)

Establishes the secure channel with the provided RMAC.

Parameters

rmac The RMAC.

ReadOnlySpan< byte > PadTheData (ReadOnlySpan< byte > data)

Pads the given data with padding bytes to make it a multiple of a specified length.

Parameters

payload The payload data to pad.

Returns: The padded data.

Protected Member Functions
	MessageSecureChannel (SecurityContext context=null, ILoggerFactory loggerFactory=null)
	Initializes a new instance of MessageSecureChannel class.
byte[]	GenerateCommandMac (ReadOnlySpan< byte > message)
	Generates a MAC for a command message.
byte[]	GenerateReplyMac (ReadOnlySpan< byte > message)
	Generates a MAC for a reply message.
byte[]	DecodePayload (byte[] payload, byte[] iv)
	Decodes the payload.
void	EncodePayload (byte[] payload, byte[] iv, Span< byte > destination)
	Encodes the payload.

Properties
ILogger	Logger `[get]`
	Optional logger instance.
SecurityContext	Context `[get]`
	Security state used by the channel.
bool	IsSecurityEstablished `[get]`
	Indicates whether or not a secure channel has been established on the current message channel.
bool	IsInitialized `[get]`
	Gets a value indicating whether the secure channel is initialized.`true` if the secure channel is initialized; otherwise, `false`.
byte[]	ServerRandomNumber `[get]`
	Represents the server random number used in the secure channel context.
byte[]	ServerCryptogram `[get]`
	Represents the secure channel cryptogram used by the server.This property is used to retrieve the server cryptogram for the secure channel context within which a message is packed/unpacked.
bool	IsUsingDefaultKey `[get]`
	Gets a value indicating whether the secure channel is using the default key.

Detailed Description

V2 implementation of a SecureChannel class.

With introduction of OSDP PD simulator as well as CLI tool to parse pcap files generated by this library, we had to do some refactoring. In doing so, we introduced a new Message class hierarchy based on Message -> IncomingMessage inheritance (we are yet to add OutgoingMessage but most of the logic that would go in that, is presently in OSDP.NET.Messages.PD.Reply class)

Whereas the older SecureChannel class was passed directly into Message parsing/building code, this new class hierarchy depends on IMessageChannel interface to interact with the secure channel context and this class is the base implementation for that

Definition at line 19 of file MessageSecureChannel.cs.

Constructor & Destructor Documentation

◆ MessageSecureChannel()

OSDP.Net.Messages.SecureChannel.MessageSecureChannel.MessageSecureChannel	(	SecurityContext	context = null,
		ILoggerFactory	loggerFactory = null )

inlineprotected

Initializes a new instance of MessageSecureChannel class.

Parameters

context	Optional security context state to be used by the channel. If one is not provided, new default instance of the context will be created internally. This is useful when more than one channel have a need to share the same security state (i.e. in cases of implementing a spy that analyzes traffic flow through the two inbound and outbound channels
loggerFactory	Optional logger factory from which a logger object for the message channel will be acquired

Definition at line 31 of file MessageSecureChannel.cs.

References Context, and Logger.

Member Function Documentation

◆ DecodePayload() [1/2]

byte[] OSDP.Net.Messages.SecureChannel.MessageSecureChannel.DecodePayload ( byte[] payload )

abstract

Decodes the payload using the secure channel context.This function can only be called once IsSecurityEstablished is true

Parameters

payload Payload to be decrypted

Returns: Plaintext message payload. Similarly to how original payload must have been padded prior to being encrypted, the plaintext byte buffer returned here will also be padded and therefore its length will always be divisible by 16. The padding at the end of the buffer will always consist of zero or more 0x00 bytes preceeded by 0x80 byte.

Implements OSDP.Net.Messages.SecureChannel.IMessageSecureChannel.

◆ DecodePayload() [2/2]

byte[] OSDP.Net.Messages.SecureChannel.MessageSecureChannel.DecodePayload	(	byte[]	payload,
		byte[]	iv )

inlineprotected

Decodes the payload.

Parameters

payload	Cyphertext of the message payload
iv	crypto initialization vector

Returns: Message payload as plaintext

Definition at line 142 of file MessageSecureChannel.cs.

References Context, and IsSecurityEstablished.

◆ EncodePayload() [1/2]

void OSDP.Net.Messages.SecureChannel.MessageSecureChannel.EncodePayload	(	byte[]	payload,
		byte[]	iv,
		Span< byte >	destination )

inlineprotected

Encodes the payload.

Parameters

payload	Message payload as plaintext
iv	Crypto initialization vector
destination	Destination where cyphertext is to be written

Returns: Cyphertext of the message payload

Definition at line 172 of file MessageSecureChannel.cs.

References Context, and IsSecurityEstablished.

◆ EncodePayload() [2/2]

void OSDP.Net.Messages.SecureChannel.MessageSecureChannel.EncodePayload	(	byte[]	payload,
		Span< byte >	destination )

abstract

Encrypts the payload using the secure channel context.This function can only be called once IsSecurityEstablished is true.

Parameters

payload	Payload to be encrypted. NOTE: This data MUST already be padded in according to OSDP specification: a) there must be at least one byte of padding; b) payloaded is padded with 0x00, except for the very first byte of padding which must be 0x80; c) total length must be divisible by AES block size of 16 bytes.
destination	Identifies where encoded data is to written to

Implements OSDP.Net.Messages.SecureChannel.IMessageSecureChannel.

◆ Establish()

void OSDP.Net.Messages.SecureChannel.MessageSecureChannel.Establish ( byte[] rmac )

Establishes the secure channel with the provided RMAC.

Parameters

rmac The RMAC.

Implements OSDP.Net.Messages.SecureChannel.IMessageSecureChannel.

References Context.

◆ GenerateCommandMac()

byte[] OSDP.Net.Messages.SecureChannel.MessageSecureChannel.GenerateCommandMac ( ReadOnlySpan< byte > message )

protected

Generates a MAC for a command message.

Parameters

message Message bytes to generate code from

Returns: Newly generated MAC

Exceptions

SecureChannelRequired Thrown if secure channel has not been established

References Context.

Referenced by OSDP.Net.Messages.SecureChannel.ACUMessageSecureChannel.GenerateMac().

◆ GenerateMac()

ReadOnlySpan< byte > OSDP.Net.Messages.SecureChannel.MessageSecureChannel.GenerateMac	(	ReadOnlySpan< byte >	message,
		bool	isIncoming )

abstract

Generates a new Message Authentication Code.Note this command IS NOT idempotent as every time it is called it will calculate a new rolling MAC value based on the results of the previous call

Parameters

message	Message to be signed with a MAC
isIncoming	If true, indicates that the message was received from the wire. If false, indicates that the message is being sent out on the wire

Returns: 16-byte MAC value of the message

Implements OSDP.Net.Messages.SecureChannel.IMessageSecureChannel.

◆ GenerateReplyMac()

byte[] OSDP.Net.Messages.SecureChannel.MessageSecureChannel.GenerateReplyMac ( ReadOnlySpan< byte > message )

protected

Generates a MAC for a reply message.

Parameters

message Message bytes to generate code from

Returns: Newly generated MAC

Exceptions

SecureChannelRequired Thrown if secure channel has not been established

References Context, and IsSecurityEstablished.

◆ InitializeACU()

void OSDP.Net.Messages.SecureChannel.MessageSecureChannel.InitializeACU	(	byte[]	clientRandomNumber,
		byte[]	clientCryptogram )

inline

Initializes the Access Control Unit (ACU) in the secure channel context.

Parameters

clientRandomNumber	The client random number.
clientCryptogram	The client cryptogram.

Implements OSDP.Net.Messages.SecureChannel.IMessageSecureChannel.

Definition at line 72 of file MessageSecureChannel.cs.

References Context.

◆ PadTheData()

ReadOnlySpan< byte > OSDP.Net.Messages.SecureChannel.MessageSecureChannel.PadTheData ( ReadOnlySpan< byte > data )

inline

Pads the given data with padding bytes to make it a multiple of a specified length.

Parameters

payload The payload data to pad.

Returns: The padded data.

Implements OSDP.Net.Messages.SecureChannel.IMessageSecureChannel.

Definition at line 195 of file MessageSecureChannel.cs.

◆ ResetSecureChannelSession()

void OSDP.Net.Messages.SecureChannel.MessageSecureChannel.ResetSecureChannelSession ( )

Resets the secure channel session by creating a new random number.

Implements OSDP.Net.Messages.SecureChannel.IMessageSecureChannel.

References Context.

Property Documentation

◆ Context

SecurityContext OSDP.Net.Messages.SecureChannel.MessageSecureChannel.Context

getprotected

Security state used by the channel.

Definition at line 45 of file MessageSecureChannel.cs.

Referenced by OSDP.Net.Messages.SecureChannel.ACUMessageSecureChannel.DecodePayload(), DecodePayload(), OSDP.Net.Messages.SecureChannel.ACUMessageSecureChannel.EncodePayload(), EncodePayload(), Establish(), GenerateCommandMac(), GenerateReplyMac(), InitializeACU(), MessageSecureChannel(), and ResetSecureChannelSession().

◆ IsInitialized

bool OSDP.Net.Messages.SecureChannel.MessageSecureChannel.IsInitialized

get

Gets a value indicating whether the secure channel is initialized.true if the secure channel is initialized; otherwise, false.

Implements OSDP.Net.Messages.SecureChannel.IMessageSecureChannel.

Definition at line 51 of file MessageSecureChannel.cs.

◆ IsSecurityEstablished

bool OSDP.Net.Messages.SecureChannel.MessageSecureChannel.IsSecurityEstablished

get

Indicates whether or not a secure channel has been established on the current message channel.

Implements OSDP.Net.Messages.SecureChannel.IMessageSecureChannel.

Definition at line 48 of file MessageSecureChannel.cs.

Referenced by DecodePayload(), EncodePayload(), and GenerateReplyMac().

◆ IsUsingDefaultKey

bool OSDP.Net.Messages.SecureChannel.MessageSecureChannel.IsUsingDefaultKey

get

Gets a value indicating whether the secure channel is using the default key.

Implements OSDP.Net.Messages.SecureChannel.IMessageSecureChannel.

Definition at line 60 of file MessageSecureChannel.cs.

◆ Logger

ILogger OSDP.Net.Messages.SecureChannel.MessageSecureChannel.Logger

getprotected

Optional logger instance.

Definition at line 40 of file MessageSecureChannel.cs.

Referenced by MessageSecureChannel().

◆ ServerCryptogram

byte [] OSDP.Net.Messages.SecureChannel.MessageSecureChannel.ServerCryptogram

get

Represents the secure channel cryptogram used by the server.This property is used to retrieve the server cryptogram for the secure channel context within which a message is packed/unpacked.

Implements OSDP.Net.Messages.SecureChannel.IMessageSecureChannel.

Definition at line 57 of file MessageSecureChannel.cs.

◆ ServerRandomNumber

byte [] OSDP.Net.Messages.SecureChannel.MessageSecureChannel.ServerRandomNumber

get

Represents the server random number used in the secure channel context.

Implements OSDP.Net.Messages.SecureChannel.IMessageSecureChannel.

Definition at line 54 of file MessageSecureChannel.cs.

The documentation for this class was generated from the following file:

OSDP.Net/Messages/SecureChannel/MessageSecureChannel.cs

Public Member Functions

Protected Member Functions

Properties

Detailed Description

Constructor & Destructor Documentation

◆ MessageSecureChannel()

Member Function Documentation

◆ DecodePayload() [1/2]

◆ DecodePayload() [2/2]

◆ EncodePayload() [1/2]

◆ EncodePayload() [2/2]

◆ Establish()

◆ GenerateCommandMac()

◆ GenerateMac()

◆ GenerateReplyMac()

◆ InitializeACU()

◆ PadTheData()

◆ ResetSecureChannelSession()

Property Documentation

◆ Context

◆ IsInitialized

◆ IsSecurityEstablished

◆ IsUsingDefaultKey

◆ Logger

◆ ServerCryptogram

◆ ServerRandomNumber