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.

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]
Encoded block sets parameters.
sBufferAllocationMask = { kNetworkBuffer0BlockAllocationMask, kNetworkBuffer1BlockAllocationMask, }[kNumberOfNetworkBuffers]
const BlockMark_t
Set of buffer block masks.
sMemBlocksAllocated = 0
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)
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)
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)
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.