nl::Weave::WeaveSecurityManager

Summary

Constructors and Destructors
WeaveSecurityManager(void)

Public types
KeyErrorMsgRcvdFunct)(uint16_t keyId, uint8_t encType, uint32_t messageId, uint64_t peerNodeId, WEAVE_ERROR keyErr) typedef
void(*
Type of key error message handling function.
KeyExportCompleteFunct)(WeaveSecurityManager *sm, WeaveConnection *con, void *reqState, uint32_t exportedKeyId, const uint8_t *exportedKey, uint16_t exportedKeyLen) typedef
void(*
Type of key export protocol complete handling function.
KeyExportErrorFunct)(WeaveSecurityManager *sm, WeaveConnection *con, void *reqState, WEAVE_ERROR localErr, StatusReport *statusReport) typedef
void(*
Type of key export protocol error handling function.
SessionErrorFunct)(WeaveSecurityManager *sm, WeaveConnection *con, void *reqState, WEAVE_ERROR localErr, uint64_t peerNodeId, StatusReport *statusReport) typedef
void(*
SessionEstablishedFunct)(WeaveSecurityManager *sm, WeaveConnection *con, void *reqState, uint16_t sessionKeyId, uint64_t peerNodeId, uint8_t encType) typedef
void(*
State enum

Public attributes
CASEUseKnownECDHKey
bool
ExchangeManager
FabricState
IdleSessionTimeout
uint32_t
InitiatorAllowedCASEConfigs
uint8_t
InitiatorAllowedCASECurves
uint8_t
InitiatorAllowedKeyExportConfigs
uint8_t
InitiatorCASEConfig
uint32_t
InitiatorCASECurveId
uint32_t
InitiatorKeyExportConfig
uint8_t
OnKeyErrorMsgRcvd
The key error callback function.
OnSessionError
SessionErrorFunct
OnSessionEstablished
SessionEstablishedFunct
ResponderAllowedCASEConfigs
uint8_t
ResponderAllowedCASECurves
uint8_t
ResponderAllowedKeyExportConfigs
uint8_t
SessionEstablishTimeout
uint32_t
State
uint8_t
mCASEEngine
mKeyExport
mPASEEngine
mStartKeyExport_OnComplete
The key export protocol complete callback function.
mStartKeyExport_OnError
The key export protocol error callback function.
mStartKeyExport_ReqState
void *
mStartSecureSession_OnComplete
SessionEstablishedFunct
mStartSecureSession_OnError
SessionErrorFunct
mStartSecureSession_ReqState
void *
mTAKEEngine

Public functions
CancelSessionEstablishment(void *reqState)
Cancel an in-progress session establishment.
Init(WeaveExchangeManager & aExchangeMgr, System::Layer & aSystemLayer)
IsKeyError(WEAVE_ERROR err)
bool
Checks if the specified Weave error code is one of the key error codes.
OnEncryptedMsgRcvd(uint16_t sessionKeyId, uint64_t peerNodeId, uint8_t encType)
void
ReleaseKey(uint64_t peerNodeId, uint16_t keyId)
void
Release a message encryption key reservation.
ReserveKey(uint64_t peerNodeId, uint16_t keyId)
void
Place a reservation on a message encryption key.
SendKeyErrorMsg(WeaveMessageInfo *rcvdMsgInfo, const IPPacketInfo *rcvdMsgPacketInfo, WeaveConnection *con, WEAVE_ERROR keyErr)
Send key error message.
SetCASEAuthDelegate(WeaveCASEAuthDelegate *delegate)
void
SetKeyExportDelegate(WeaveKeyExportDelegate *delegate)
void
SetTAKEAuthDelegate(WeaveTAKEChallengerAuthDelegate *delegate)
void
SetTAKETokenAuthDelegate(WeaveTAKETokenAuthDelegate *delegate)
void
Shutdown(void)
StartCASESession(WeaveConnection *con, uint64_t peerNodeId, const IPAddress & peerAddr, uint16_t peerPort, WeaveAuthMode requestedAuthMode, void *reqState, SessionEstablishedFunct onComplete, SessionErrorFunct onError, WeaveCASEAuthDelegate *authDelegate, uint64_t terminatingNodeId)
This method is called to establish new or find existing CASE session.
StartKeyExport(WeaveConnection *con, uint64_t peerNodeId, const IPAddress & peerAddr, uint16_t peerPort, uint32_t keyId, bool signMessage, void *reqState, KeyExportCompleteFunct onComplete, KeyExportErrorFunct onError, WeaveKeyExportDelegate *keyExportDelegate)
StartPASESession(WeaveConnection *con, WeaveAuthMode requestedAuthMode, void *reqState, SessionEstablishedFunct onComplete, SessionErrorFunct onError, const uint8_t *pw, uint16_t pwLen)
This method is called to establish secure PASE session.
StartTAKESession(WeaveConnection *con, WeaveAuthMode requestedAuthMode, void *reqState, SessionEstablishedFunct onComplete, SessionErrorFunct onError, bool encryptAuthPhase, bool encryptCommPhase, bool timeLimitedIK, bool sendChallengerId, WeaveTAKEChallengerAuthDelegate *authDelegate)
This method is called to establish secure TAKE session.

Public types

KeyErrorMsgRcvdFunct

void(* KeyErrorMsgRcvdFunct)(uint16_t keyId, uint8_t encType, uint32_t messageId, uint64_t peerNodeId, WEAVE_ERROR keyErr)

Type of key error message handling function.

Details
Parameters
[in] keyId
Encryption key caused the key error message response from the peer.
[in] encType
Encryption type associated with keyId.
[in] messageId
The identifier of the Weave message resulted in the key error response from the peer.
[in] peerNodeId
The identifier of the Weave node that sent key error message.
[in] keyErr
The error code received from the peer.

KeyExportCompleteFunct

void(* KeyExportCompleteFunct)(WeaveSecurityManager *sm, WeaveConnection *con, void *reqState, uint32_t exportedKeyId, const uint8_t *exportedKey, uint16_t exportedKeyLen)

Type of key export protocol complete handling function.

Details
Parameters
[in] sm
A pointer to WeaveSecurityManager object.
[in] con
A pointer to WeaveConnection object.
[in] reqState
A pointer to the key export requester state.
[in] keyId
Exported key ID.
[in] exportedKey
A pointer to the exported secret key.
[in] exportedKeyLen
A reference to the exported secret key length.

KeyExportErrorFunct

void(* KeyExportErrorFunct)(WeaveSecurityManager *sm, WeaveConnection *con, void *reqState, WEAVE_ERROR localErr, StatusReport *statusReport)

Type of key export protocol error handling function.

Details
Parameters
[in] sm
A pointer to WeaveSecurityManager object.
[in] con
A pointer to WeaveConnection object.
[in] reqState
A pointer to the key export requester state.
[in] localErr
The WEAVE_ERROR encountered during key export protocol.
[in] statusReport
A pointer to StatusReport object if error status received from peer.

SessionErrorFunct

void(* SessionErrorFunct)(WeaveSecurityManager *sm, WeaveConnection *con, void *reqState, WEAVE_ERROR localErr, uint64_t peerNodeId, StatusReport *statusReport)

SessionEstablishedFunct

void(* SessionEstablishedFunct)(WeaveSecurityManager *sm, WeaveConnection *con, void *reqState, uint16_t sessionKeyId, uint64_t peerNodeId, uint8_t encType)

State

 State

Public attributes

CASEUseKnownECDHKey

bool CASEUseKnownECDHKey

ExchangeManager

WeaveExchangeManager * ExchangeManager

FabricState

WeaveFabricState * FabricState

IdleSessionTimeout

uint32_t IdleSessionTimeout

InitiatorAllowedCASEConfigs

uint8_t InitiatorAllowedCASEConfigs

InitiatorAllowedCASECurves

uint8_t InitiatorAllowedCASECurves

InitiatorAllowedKeyExportConfigs

uint8_t InitiatorAllowedKeyExportConfigs

InitiatorCASEConfig

uint32_t InitiatorCASEConfig

InitiatorCASECurveId

uint32_t InitiatorCASECurveId

InitiatorKeyExportConfig

uint8_t InitiatorKeyExportConfig

OnKeyErrorMsgRcvd

KeyErrorMsgRcvdFunct OnKeyErrorMsgRcvd

The key error callback function.

This function is called when a key error message is received.

OnSessionError

SessionErrorFunct OnSessionError

OnSessionEstablished

SessionEstablishedFunct OnSessionEstablished

ResponderAllowedCASEConfigs

uint8_t ResponderAllowedCASEConfigs

ResponderAllowedCASECurves

uint8_t ResponderAllowedCASECurves

ResponderAllowedKeyExportConfigs

uint8_t ResponderAllowedKeyExportConfigs

SessionEstablishTimeout

uint32_t SessionEstablishTimeout

State

uint8_t State

mCASEEngine

WeaveCASEEngine * mCASEEngine

mKeyExport

WeaveKeyExport * mKeyExport

mPASEEngine

WeavePASEEngine * mPASEEngine

mStartKeyExport_OnComplete

KeyExportCompleteFunct mStartKeyExport_OnComplete

The key export protocol complete callback function.

This function is called when the secret key export process is complete.

mStartKeyExport_OnError

KeyExportErrorFunct mStartKeyExport_OnError

The key export protocol error callback function.

This function is called when an error is encountered during key export process.

mStartKeyExport_ReqState

void * mStartKeyExport_ReqState

mStartSecureSession_OnComplete

SessionEstablishedFunct mStartSecureSession_OnComplete

mStartSecureSession_OnError

SessionErrorFunct mStartSecureSession_OnError

mStartSecureSession_ReqState

void * mStartSecureSession_ReqState

mTAKEEngine

WeaveTAKEEngine * mTAKEEngine

Public functions

CancelSessionEstablishment

WEAVE_ERROR CancelSessionEstablishment(
  void *reqState
)

Cancel an in-progress session establishment.

Details
Parameters
[in] reqState
A pointer value that matches the value supplied by the application when the session was started.
Return Values
WEAVE_NO_ERROR
If a matching in-progress session establishment was found and canceled.
WEAVE_ERROR_INCORRECT_STATE
If there was no session establishment in progress, or the in-progress session did not match the supplied request state pointer.

Init

WEAVE_ERROR Init(
  WeaveExchangeManager & aExchangeMgr,
  System::Layer & aSystemLayer
)

IsKeyError

bool IsKeyError(
  WEAVE_ERROR err
)

Checks if the specified Weave error code is one of the key error codes.

This function is called to determine whether key error message should be sent to the initiator of the message that failed to find a correct key during decoding.

Details
Parameters
[in] err
A Weave error code.
Return Values
true
If specified Weave error code is a key error.
false
Otherwise.

OnEncryptedMsgRcvd

void OnEncryptedMsgRcvd(
  uint16_t sessionKeyId,
  uint64_t peerNodeId,
  uint8_t encType
)

ReleaseKey

void ReleaseKey(
  uint64_t peerNodeId,
  uint16_t keyId
)

Release a message encryption key reservation.

Release a reservations that was previously placed on a message encryption key.

For every reservation placed on a particular key, the ReleaseKey() method must be called no more than once.

This method accepts any form of key id, including None. Key ids that do not name actual keys are ignored.

Details
Parameters
[in] peerNodeId
The Weave node id of the peer with which the key shared.
[in] keyId
The id of the key whose reservation should be released.

ReserveKey

void ReserveKey(
  uint64_t peerNodeId,
  uint16_t keyId
)

Place a reservation on a message encryption key.

Key reservations are used to signal that a particular key is actively in use and should be retained. Note that placing reservation on a key does not guarantee that the key wont be removed by an explicit action such as the reception of a KeyError message.

For every reservation placed on a particular key, a corresponding call to ReleaseKey() must be made.

This method accepts any form of key id, including None. Key ids that do not name actual keys are ignored.

Details
Parameters
[in] peerNodeId
The Weave node id of the peer with which the key shared.
[in] keyId
The id of the key to be reserved.

SendKeyErrorMsg

WEAVE_ERROR SendKeyErrorMsg(
  WeaveMessageInfo *rcvdMsgInfo,
  const IPPacketInfo *rcvdMsgPacketInfo,
  WeaveConnection *con,
  WEAVE_ERROR keyErr
)

Send key error message.

This function is called when received Weave message decoding fails due to key error.

Details
Parameters
[in] rcvdMsgInfo
A pointer to the message information for the received Weave message.
[in] rcvdMsgPacketInfo
A pointer to the IPPacketInfo object of the received Weave message.
[in] con
A pointer to the WeaveConnection object.
[in] keyErr
Weave key error code.
Return Values
WEAVE_ERROR_NO_MEMORY
If memory could not be allocated for the new exchange context or new message buffer.
WEAVE_ERROR_BUFFER_TOO_SMALL
If buffer is too small
WEAVE_NO_ERROR
If the method succeeded.

SetCASEAuthDelegate

void SetCASEAuthDelegate(
  WeaveCASEAuthDelegate *delegate
)

SetKeyExportDelegate

void SetKeyExportDelegate(
  WeaveKeyExportDelegate *delegate
)

SetTAKEAuthDelegate

void SetTAKEAuthDelegate(
  WeaveTAKEChallengerAuthDelegate *delegate
)

SetTAKETokenAuthDelegate

void SetTAKETokenAuthDelegate(
  WeaveTAKETokenAuthDelegate *delegate
)

Shutdown

WEAVE_ERROR Shutdown(
  void
)

StartCASESession

WEAVE_ERROR StartCASESession(
  WeaveConnection *con,
  uint64_t peerNodeId,
  const IPAddress & peerAddr,
  uint16_t peerPort,
  WeaveAuthMode requestedAuthMode,
  void *reqState,
  SessionEstablishedFunct onComplete,
  SessionErrorFunct onError,
  WeaveCASEAuthDelegate *authDelegate,
  uint64_t terminatingNodeId
)

This method is called to establish new or find existing CASE session.

Details
Parameters
[in] con
A pointer to the WeaveConnection object.
[in] peerNodeId
The node identifier of the peer.
[in] peerAddr
The IP address of the peer node.
[in] peerPort
The port of the peer node.
[in] requestedAuthMode
The desired means by which the peer should be authenticated. This must be one of the CASE auth modes.
[in] reqState
A pointer to the requester state.
[in] onComplete
A pointer to the callback function, which will be called once requested secure session is established.
[in] onError
A pointer to the callback function, which will be called if requested session establishment fails.
[in] authDelegate
A pointer to the CASE authentication delegate object.
[in] terminatingNodeId
The node identifier of the session terminating node. When this input is different from kNodeIdNotSpecified that indicates that shared secure session was requested.
Return Values
WEAVE_NO_ERROR
On success.

StartKeyExport

WEAVE_ERROR StartKeyExport(
  WeaveConnection *con,
  uint64_t peerNodeId,
  const IPAddress & peerAddr,
  uint16_t peerPort,
  uint32_t keyId,
  bool signMessage,
  void *reqState,
  KeyExportCompleteFunct onComplete,
  KeyExportErrorFunct onError,
  WeaveKeyExportDelegate *keyExportDelegate
)

StartPASESession

WEAVE_ERROR StartPASESession(
  WeaveConnection *con,
  WeaveAuthMode requestedAuthMode,
  void *reqState,
  SessionEstablishedFunct onComplete,
  SessionErrorFunct onError,
  const uint8_t *pw,
  uint16_t pwLen
)

This method is called to establish secure PASE session.

Details
Parameters
[in] con
A pointer to the WeaveConnection object.
[in] requestedAuthMode
The desired means by which the peer should be authenticated. This must be one of the PASE auth modes.
[in] reqState
A pointer to the requester state.
[in] onComplete
A pointer to the callback function, which will be called once requested secure session is established.
[in] onError
A pointer to the callback function, which will be called if requested session establishment fails.
[in] pw
A pointer to the PASE secret password.
[in] pwLen
Length of the PASE secret password.
Return Values
WEAVE_NO_ERROR
On success.

StartTAKESession

WEAVE_ERROR StartTAKESession(
  WeaveConnection *con,
  WeaveAuthMode requestedAuthMode,
  void *reqState,
  SessionEstablishedFunct onComplete,
  SessionErrorFunct onError,
  bool encryptAuthPhase,
  bool encryptCommPhase,
  bool timeLimitedIK,
  bool sendChallengerId,
  WeaveTAKEChallengerAuthDelegate *authDelegate
)

This method is called to establish secure TAKE session.

Details
Parameters
[in] con
A pointer to the WeaveConnection object.
[in] requestedAuthMode
The desired means by which the peer should be authenticated. This must be one of the TAKE authentication modes.
[in] reqState
A pointer to the requester state.
[in] onComplete
A pointer to the callback function, which will be called once requested secure session is established.
[in] onError
A pointer to the callback function, which will be called if requested session establishment fails.
[in] encryptAuthPhase
A boolean flag that indicates whether protocol authentication phase should be encrypted.
[in] encryptCommPhase
A boolean flag that indicates whether protocol communication phase should be encrypted.
[in] timeLimitedIK
A boolean flag that indicates whether Identification Key (IK) is time limited.
[in] sendChallengerId
A boolean flag that indicates whether challenger identification should be included in the message. If it is not included the Weave node ID value is used as a challenger ID.
[in] authDelegate
A pointer to the TAKE challenger authentication delegate object.
Return Values
WEAVE_NO_ERROR
On success.

WeaveSecurityManager

 WeaveSecurityManager(
  void
)