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.

Functions

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.

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

Functions

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.