nl::Weave::Platform::Security

This namespace includes all interfaces within Weave for the Weave Security Monitor memory manager.

Summary

Functions in this namespace are to be implemented by platforms that use Weave, according to the needs/constraints of the particular environment.

Enumerations
`BlockSetParamFields{ kBlockSetSizeMask = 0x07, kBlockSetSizeShift = 0, kBlockSetSizeValueShift = 7, kBlockSetCountMask = 0x18, kBlockSetCountShift = 3, kBlockSetBufferIndexMask = 0x60, kBlockSetBufferIndexShift = 5, kBlockSetIsLongTermMask = 0x80, kBlockSetIsLongTermShift = 7 }`	enum Block set parameter fields location in an 8-bit encoded form.
BlockSetParams{ kNumberOfNetworkBuffers = 2, kNumberOfBlockSets = 4, kNetworkBuffer0BlockAllocationMask = 0x07, kNetworkBuffer1BlockAllocationMask = 0x18, kBlockSet1Size = 1, kBlockSet1Count = 1, kBlockSet1BufferIndex = 0, kBlockSet1isLongTerm = 1, kBlockSet2Size = 4, kBlockSet2Count = 1, kBlockSet2BufferIndex = 0, kBlockSet2isLongTerm = 1, kBlockSet3Size = 4, kBlockSet3Count = 1, kBlockSet3BufferIndex = 0, kBlockSet3isLongTerm = 0, kBlockSet4Size = 5, kBlockSet4Count = 2, kBlockSet4BufferIndex = 1, kBlockSet4isLongTerm = 0, kTotalMemorySize = (kBlockSet1Size * kBlockSet1Count + kBlockSet2Size * kBlockSet2Count + kBlockSet3Size * kBlockSet3Count + kBlockSet4Size * kBlockSet4Count) << kBlockSetSizeValueShift, kMaxBlockSize = 600, kMinBufferSize = 1240 }	enum Defines block set parameters.

Enumerations

BlockSetParamFields{
  kBlockSetSizeMask = 0x07,
  kBlockSetSizeShift = 0,
  kBlockSetSizeValueShift = 7,
  kBlockSetCountMask = 0x18,
  kBlockSetCountShift = 3,
  kBlockSetBufferIndexMask = 0x60,
  kBlockSetBufferIndexShift = 5,
  kBlockSetIsLongTermMask = 0x80,
  kBlockSetIsLongTermShift = 7
}

enum

Block set parameter fields location in an 8-bit encoded form.

BlockSetParams{
  kNumberOfNetworkBuffers = 2,
  kNumberOfBlockSets = 4,
  kNetworkBuffer0BlockAllocationMask = 0x07,
  kNetworkBuffer1BlockAllocationMask = 0x18,
  kBlockSet1Size = 1,
  kBlockSet1Count = 1,
  kBlockSet1BufferIndex = 0,
  kBlockSet1isLongTerm = 1,
  kBlockSet2Size = 4,
  kBlockSet2Count = 1,
  kBlockSet2BufferIndex = 0,
  kBlockSet2isLongTerm = 1,
  kBlockSet3Size = 4,
  kBlockSet3Count = 1,
  kBlockSet3BufferIndex = 0,
  kBlockSet3isLongTerm = 0,
  kBlockSet4Size = 5,
  kBlockSet4Count = 2,
  kBlockSet4BufferIndex = 1,
  kBlockSet4isLongTerm = 0,
  kTotalMemorySize = (kBlockSet1Size * kBlockSet1Count +
                                             kBlockSet2Size * kBlockSet2Count +
                                             kBlockSet3Size * kBlockSet3Count +
                                             kBlockSet4Size * kBlockSet4Count) << kBlockSetSizeValueShift,
  kMaxBlockSize = 600,
  kMinBufferSize = 1240
}

enum

Defines block set parameters.

Typedefs
`BlockMark_t`	typedef `uint8_t` The type used to mark which block is currently allocated/unallocated.
`BlockSetParams_t`	typedef `uint8_t` This type is used to encode block set information.

Variables
sBlockSetParams = { ((kBlockSet1Size << kBlockSetSizeShift) & kBlockSetSizeMask) \| ((kBlockSet1Count << kBlockSetCountShift) & kBlockSetCountMask) \| ((kBlockSet1BufferIndex << kBlockSetBufferIndexShift) & kBlockSetBufferIndexMask) \| ((kBlockSet1isLongTerm << kBlockSetIsLongTermShift) & kBlockSetIsLongTermMask), ((kBlockSet2Size << kBlockSetSizeShift) & kBlockSetSizeMask) \| ((kBlockSet2Count << kBlockSetCountShift) & kBlockSetCountMask) \| ((kBlockSet2BufferIndex << kBlockSetBufferIndexShift) & kBlockSetBufferIndexMask) \| ((kBlockSet2isLongTerm << kBlockSetIsLongTermShift) & kBlockSetIsLongTermMask), ((kBlockSet3Size << kBlockSetSizeShift) & kBlockSetSizeMask) \| ((kBlockSet3Count << kBlockSetCountShift) & kBlockSetCountMask) \| ((kBlockSet3BufferIndex << kBlockSetBufferIndexShift) & kBlockSetBufferIndexMask) \| ((kBlockSet3isLongTerm << kBlockSetIsLongTermShift) & kBlockSetIsLongTermMask), ((kBlockSet4Size << kBlockSetSizeShift) & kBlockSetSizeMask) \| ((kBlockSet4Count << kBlockSetCountShift) & kBlockSetCountMask) \| ((kBlockSet4BufferIndex << kBlockSetBufferIndexShift) & kBlockSetBufferIndexMask) \| ((kBlockSet4isLongTerm << kBlockSetIsLongTermShift) & kBlockSetIsLongTermMask), }[kNumberOfBlockSets]	`const BlockSetParams_t` Encoded block sets parameters.
`sBufferAllocationMask = { kNetworkBuffer0BlockAllocationMask, kNetworkBuffer1BlockAllocationMask, }[kNumberOfNetworkBuffers]`	`const BlockMark_t` Set of buffer block masks.
`sMemBlocksAllocated = 0`	`BlockMark_t` Indicates which block is allocated/unallocated.
`sMemBufs = { NULL }[kNumberOfNetworkBuffers]`	`void *` Pointers to memory buffers initialized to NULL.
`sNetworkBuffersUsed = true`	`bool` A boolean indicating whether (true) or not (false) the network buffers are used by Simple Allocator.

Functions
`DecodeBlockSetParams(BlockSetParams_t blockSetParams, uint16_t & blockSize, uint8_t & blockCount, uint8_t & blockBufferIndex, bool & blockIsLongTerm)`	`void`
`GetSecureRandomData(uint8_t *buf, uint16_t len)`	`WEAVE_ERROR` This function is called by the Weave layer to generate random data.
`InitSecureRandomDataSource(nl::Weave::Crypto::EntropyFunct entropyFunct, uint16_t entropyLen, const uint8_t *personalizationData, uint16_t perDataLen)`	`WEAVE_ERROR` This function is called by the Weave layer to initialize random data source.
`MemoryAlloc(size_t size)`	`void *` This function is called by the Weave layer to allocate a block of memory of "size" bytes.
`MemoryAlloc(size_t size, bool isLongTermAlloc)`	`void *` This function is called by the Weave layer to allocate a block of memory of "size" bytes.
`MemoryFree(void *p)`	`void` This function is called by the Weave layer to release a memory block allocated by the MemeoryAlloc() function.
`MemoryInit(void *buf, size_t bufSize)`	`WEAVE_ERROR` This function is called by the Weave layer to initialize memory and resources required for proper functionality of the Weave Security Manager memory allocator.
`MemoryShutdown(void)`	`void` This function is called by the Weave layer to releases all resources that were allocated by MemoryInit() function.
`OnTimeConsumingCryptoDone(void)`	`void` This function is called to notify the application when a time-consuming cryptographic operation has just finished.
`OnTimeConsumingCryptoStart(void)`	`void` This function is called to notify the application when a time-consuming cryptographic operation is about to start.

Classes
nl::Weave::Platform::Security::AES128BlockCipher
nl::Weave::Platform::Security::AES128BlockCipherDec
nl::Weave::Platform::Security::AES128BlockCipherEnc
nl::Weave::Platform::Security::AES256BlockCipher
nl::Weave::Platform::Security::AES256BlockCipherDec
nl::Weave::Platform::Security::AES256BlockCipherEnc
nl::Weave::Platform::Security::SHA1
nl::Weave::Platform::Security::SHA256

Enumerations

BlockSetParamFields

 BlockSetParamFields

Block set parameter fields location in an 8-bit encoded form.

Properties
`kBlockSetBufferIndexMask`	Buffer index field mask.
`kBlockSetBufferIndexShift`	Buffer index field shift.
`kBlockSetCountMask`	Count field mask.
`kBlockSetCountShift`	Count field shift.
`kBlockSetIsLongTermMask`	Type field mask.
`kBlockSetIsLongTermShift`	Type field shift.
`kBlockSetSizeMask`	Size field mask.
`kBlockSetSizeShift`	Size field shift.
`kBlockSetSizeValueShift`	Size field decoding shift (multiply by 128).

BlockSetParams

 BlockSetParams

Defines block set parameters.

Properties
`kBlockSet1BufferIndex`	Set #1 buffer index is 0.
`kBlockSet1Count`	Set #1 block count is 1.
`kBlockSet1Size`	Set #1 size is 128 bytes.
`kBlockSet1isLongTerm`	Set #1 type is long term.
`kBlockSet2BufferIndex`	Set #2 buffer index is 0.
`kBlockSet2Count`	Set #2 block count is 1.
`kBlockSet2Size`	Set #2 size is 512 bytes.
`kBlockSet2isLongTerm`	Set #2 type is long term.
`kBlockSet3BufferIndex`	Set #3 buffer index is 0.
`kBlockSet3Count`	Set #3 block count is 1.
`kBlockSet3Size`	Set #3 size is 512 bytes.
`kBlockSet3isLongTerm`	Set #3 type is short term.
`kBlockSet4BufferIndex`	Set #4 buffer index is 1.
`kBlockSet4Count`	Set #4 block count is 2.
`kBlockSet4Size`	Set #4 size is 640 bytes.
`kBlockSet4isLongTerm`	Set #4 type is short term.
`kMaxBlockSize`	Maximum block size supported by Simple Allocator.
`kMinBufferSize`	Minimum network buffer size required to support Simple Allocator use cases. This parameter is derived from sizes of two memory block (640 + 600) allocated in the network buffer #1.
`kNetworkBuffer0BlockAllocationMask`	This mask identifies all memory blocks allocated from network buffer #0.
`kNetworkBuffer1BlockAllocationMask`	This mask identifies all memory blocks allocated from network buffer #1.
`kNumberOfBlockSets`	Number of block sets used by Simple Allocator.
`kNumberOfNetworkBuffers`	Number of network buffers used by Simple Allocator.
`kTotalMemorySize`	Total memory used by Simple Allocator.

Typedefs

BlockMark_t

uint8_t BlockMark_t

The type used to mark which block is currently allocated/unallocated.

uint8_t - supports upto 8 memory blocks total uint16_t - supports upto 16 memory blocks total uint32_t - supports upto 32 memory blocks total

BlockSetParams_t

uint8_t BlockSetParams_t

This type is used to encode block set information.

A block set is a group of memory chunks that have same properties (size, type, and belong to the same buffer). Diagram below presents how block set information encoded in an 8-bit format:

Is Long Term	Block Index	Number of Blocks	Block Size
[7]	[6:5]	[4:3]	[2:0]

[2:0] - Size of memory block in a set. Size value is encoded with 128-byte granularity.

[2:0]	Decoding
000	0 bytes
001	128 bytes
010	256 bytes
...	-
111	896 bytes

[4:3] - Number of blocks in a set.

[4:3]	Decoding
00	4 blocks
01	1 block
10	2 blocks
11	3 blocks

[6:5] - Network buffer index where memory blocks reside. Note that when dedicated buffer is used all memory blocks are allocated from dedicated buffer and this index parameter is ignored.

[6:5]	Decoding
00	Network buffer #0
...	-
11	Network buffer #3

[7] - Specifies if blocks are for long/short term storage.

[7]	Decoding
0	Short term memory blocks
1	Long term memory blocks

Variables

sBlockSetParams

const BlockSetParams_t sBlockSetParams[kNumberOfBlockSets] = {
    
    ((kBlockSet1Size << kBlockSetSizeShift) & kBlockSetSizeMask) | 
    ((kBlockSet1Count << kBlockSetCountShift) & kBlockSetCountMask) | 
    ((kBlockSet1BufferIndex << kBlockSetBufferIndexShift) & kBlockSetBufferIndexMask) | 
    ((kBlockSet1isLongTerm << kBlockSetIsLongTermShift) & kBlockSetIsLongTermMask),
    
    ((kBlockSet2Size << kBlockSetSizeShift) & kBlockSetSizeMask) | 
    ((kBlockSet2Count << kBlockSetCountShift) & kBlockSetCountMask) | 
    ((kBlockSet2BufferIndex << kBlockSetBufferIndexShift) & kBlockSetBufferIndexMask) | 
    ((kBlockSet2isLongTerm << kBlockSetIsLongTermShift) & kBlockSetIsLongTermMask),
    
    ((kBlockSet3Size << kBlockSetSizeShift) & kBlockSetSizeMask) | 
    ((kBlockSet3Count << kBlockSetCountShift) & kBlockSetCountMask) | 
    ((kBlockSet3BufferIndex << kBlockSetBufferIndexShift) & kBlockSetBufferIndexMask) | 
    ((kBlockSet3isLongTerm << kBlockSetIsLongTermShift) & kBlockSetIsLongTermMask),
    
    ((kBlockSet4Size << kBlockSetSizeShift) & kBlockSetSizeMask) | 
    ((kBlockSet4Count << kBlockSetCountShift) & kBlockSetCountMask) | 
    ((kBlockSet4BufferIndex << kBlockSetBufferIndexShift) & kBlockSetBufferIndexMask) | 
    ((kBlockSet4isLongTerm << kBlockSetIsLongTermShift) & kBlockSetIsLongTermMask),







}

Encoded block sets parameters.

sBufferAllocationMask

const BlockMark_t sBufferAllocationMask[kNumberOfNetworkBuffers] = {
                                                   kNetworkBuffer0BlockAllocationMask,
                                                   kNetworkBuffer1BlockAllocationMask,




                                                                                       }

Set of buffer block masks.

Identifies if all blocks in the buffer and unallocated and then the buffer can be relieazed.

sMemBlocksAllocated

BlockMark_t sMemBlocksAllocated = 0

Indicates which block is allocated/unallocated.

Initialized to 0 - means that all memory blocks and unallocated.

sMemBufs

void * sMemBufs[kNumberOfNetworkBuffers] = { NULL }

Pointers to memory buffers initialized to NULL.

When network buffers are used sMemBufs[] point to the PacketBuffer objects. When dedicated buffer is used sMemBufs[0] points to that buffer and other sMemBufs[] pointers are ignored.

sNetworkBuffersUsed

bool sNetworkBuffersUsed = true

A boolean indicating whether (true) or not (false) the network buffers are used by Simple Allocator.

When false - dedicated buffer provided with MemoryInit() function is used.

Functions

DecodeBlockSetParams

void DecodeBlockSetParams(
  BlockSetParams_t blockSetParams,
  uint16_t & blockSize,
  uint8_t & blockCount,
  uint8_t & blockBufferIndex,
  bool & blockIsLongTerm
)

GetSecureRandomData

WEAVE_ERROR GetSecureRandomData(
  uint8_t *buf,
  uint16_t len
)

This function is called by the Weave layer to generate random data.

Details

Parameters

`[in] buf`	Pointer to a memory buffer, where requested random data should be stored.
`[in] len`	Specifies requested random data size in bytes.

Return Values

`WEAVE_ERROR_DRBG_ENTROPY_SOURCE_FAILED`	If entropy source fails to generate entropy requested by the random data generator.
`WEAVE_ERROR_RANDOM_DATA_UNAVAILABLE`	If random data source fails to generate random data.
`WEAVE_ERROR_INCORRECT_STATE`	If random data source is found in a wrong state.
`WEAVE_NO_ERROR`	On success.

InitSecureRandomDataSource

WEAVE_ERROR InitSecureRandomDataSource(
  nl::Weave::Crypto::EntropyFunct entropyFunct,
  uint16_t entropyLen,
  const uint8_t *personalizationData,
  uint16_t perDataLen
)

This function is called by the Weave layer to initialize random data source.

This function is platform specific and might be empty when no initialization of random data source is required.

Details

Parameters

`[in] entropyFunct`	Pointer to a function that generates entropy to the random data generator. When entropy input is not required by the algorith this input can be NULL, which is the case when OpenSSL version of the random data generator is used.
`[in] entropyLen`	Specifies entropy size in bytes that should be generated by the entropy function when it is used.
`[in] personalizationData`	Pointer to a memory buffer that stores personalization data input. This data input should be device specific and it helps to improve statistical properties of the random data.
`[in] perDataLen`	Specifies personalization data size in bytes.

Return Values

`WEAVE_ERROR_INVALID_ARGUMENT`	If an invalid argument was passed to this function.
`WEAVE_NO_ERROR`	On success.

MemoryAlloc

void * MemoryAlloc(
  size_t size
)

This function is called by the Weave layer to allocate a block of memory of "size" bytes.

This function is equivalent to MemoryAlloc(size, false).

Details

Parameters

[in] size

Specifies requested memory size in bytes.

Return Values

`Pointer`	to a memory block in case of success.
`NULL-pointer`	if memory allocation fails.

MemoryAlloc

void * MemoryAlloc(
  size_t size,
  bool isLongTermAlloc
)

This function is called by the Weave layer to allocate a block of memory of "size" bytes.

Details

Parameters

[in] size

Specifies requested memory size in bytes.

[in] isLongTermAlloc

A Boolean indicating whether (true) or not (false) the requested memory block is for long term use. A long term allocation is memory that should stay allocated until secure session/handshake is complete. Examples of a long term allocation include blocks allocated for CASE/PASE objects and their context data. A short term allocation is a memory needed to perform specific operation and can be released immediately after that. This input helps to optimize memory utilization in a memory constrained system. Use of this parameter is arbitrary and depends on function implementer. For example, this parameter is ignored when the C Standard Library malloc() is used.

Return Values

`Pointer`	to a memory block in case of success.
`NULL-pointer`	if memory allocation fails.

MemoryFree

void MemoryFree(
  void *p
)

This function is called by the Weave layer to release a memory block allocated by the MemeoryAlloc() function.

Details

Parameters

[in] p

Pointer to a memory block that should be released.

MemoryInit

WEAVE_ERROR MemoryInit(
  void *buf,
  size_t bufSize
)

This function is called by the Weave layer to initialize memory and resources required for proper functionality of the Weave Security Manager memory allocator.

This function is platform specific and might be empty in certain cases. For example, this function is doing nothing when the C Standard Library malloc() and free() functions are used for memory allocation.

Details

Parameters

`[in] buf`	A pointer to a dedicated memory buffer, which should be used as a memory pool for Weave Security Manager memory allocation. This input is optional (defaults to NULL) and shouldn't be used if a dedicated memory buffer is not used.
`[in] bufSize`	Size of a dedicated memory buffer. This input is optional (defaults to 0) and shouldn't be used if dedicated memory buffer is not used. When a dedicated memory buffer is used the function checks and generates an error if buffer size is not big enough to support Weave Security Manager use cases.

Return Values

`WEAVE_ERROR_BUFFER_TOO_SMALL`	If dedicated input buffer size is not sufficient to support Weave Security Manager use cases.
`WEAVE_NO_ERROR`	On success.
`other`	An error generated by platform-specific memory initialization function.

MemoryShutdown

void MemoryShutdown(
  void
)

This function is called by the Weave layer to releases all resources that were allocated by MemoryInit() function.

This function can be an empty call if there is no need to release resources. For example, this is the case when the C Standard Library malloc() and free() functions are used for memory allocation.

OnTimeConsumingCryptoDone

void OnTimeConsumingCryptoDone(
  void
)

This function is called to notify the application when a time-consuming cryptographic operation has just finished.

OnTimeConsumingCryptoStart

void OnTimeConsumingCryptoStart(
  void
)

This function is called to notify the application when a time-consuming cryptographic operation is about to start.

nl::Weave::Platform::Security

Summary

Enumerations

Typedefs

Variables

Functions

Classes

Enumerations

BlockSetParamFields

BlockSetParams

Typedefs

BlockMark_t

BlockSetParams_t

Variables

sBlockSetParams

sBufferAllocationMask

sMemBlocksAllocated

sMemBufs

sNetworkBuffersUsed

Functions

DecodeBlockSetParams

GetSecureRandomData

InitSecureRandomDataSource

MemoryAlloc

MemoryAlloc

MemoryFree

MemoryInit

MemoryShutdown

OnTimeConsumingCryptoDone

OnTimeConsumingCryptoStart