nl::Weave::Profiles::Security::CertProvisioning::WeaveCertProvEngine

#include <src/lib/profiles/security/WeaveCertProvisioning.h>

Implements the core logic of the Weave Certificate Provisioning protocol object.

Summary

Constructors and Destructors
WeaveCertProvEngine(void)

Public types
@246{
  kReqType_GetInitialOpDeviceCert = 0,
  kReqType_RotateOpDeviceCert = 1
} 		enum
EventCallback)(void *appState, EventType eventType, const InEventParam &inParam, OutEventParam &outParam) typedef
void(*
This function is the application callback that is invoked on Certificate Provisioning Engine API events.
EventType{
  kEvent_PrepareAuthorizeInfo = 1,
  kEvent_ResponseReceived = 2,
  kEvent_CommunicationError = 3
} 		enum
State{
  kState_NotInitialized = 0,
  kState_Idle = 1,
  kState_PreparingBinding = 2,
  kState_RequestInProgress = 3
} 		enum

Public attributes
AppState
void *
A pointer to application-specific data.

Public functions
AbortCertificateProvisioning(void)
void
Stops any GetCertificate exchange in progress.
GenerateGetCertificateRequest(PacketBuffer *msgBuf, uint8_t reqType, bool doMfrAttest)
Generate GetCertificateRequest message.
GetBinding(void) const
Returns a pointer to the Binding object associated with the WeaveCertProvEngine.
GetEventCallback(void) const
Returns a pointer to the API event callback function currently configured on the WeaveCertProvEngine object.
GetMfrAttestDelegate(void) const
Returns a pointer to the manufacturer attestation delegate object currently configured on the WeaveCertProvEngine object.
GetOpAuthDelegate(void) const
Returns a pointer to the operational authentication delegate object currently configured on the WeaveCertProvEngine object.
GetReqType(void) const
uint8_t
Retrieve the current request type.
GetState(void) const
Retrieve the current state of the WeaveCertProvEngine object.
Init(Binding *binding, WeaveNodeOpAuthDelegate *opAuthDelegate, WeaveNodeMfrAttestDelegate *mfrAttestDelegate, EventCallback eventCallback, void *appState)
Initialize a WeaveCertProvEngine object in preparation for sending get certificate request message.
ProcessGetCertificateResponse(PacketBuffer *msgBuf)
Process GetCertificateResponse message.
SetBinding(Binding *binding)
void
Sets the binding object on the WeaveCertProvEngine object.
SetEventCallback(EventCallback eventCallback)
void
Sets the API event callback function on the WeaveCertProvEngine object.
SetMfrAttestDelegate(WeaveNodeMfrAttestDelegate *mfrAttestDelegate)
void
Sets the manufacturer attestation delegate object on the WeaveCertProvEngine object.
SetOpAuthDelegate(WeaveNodeOpAuthDelegate *opAuthDelegate)
void
Sets the operational authentication delegate object on the WeaveCertProvEngine object.
Shutdown(void)
void
Shutdown a previously initialized WeaveCertProvEngine object.
StartCertificateProvisioning(uint8_t reqType, bool doMfrAttest)
Start Certificate Provisioning Protocol.

Structs
nl::Weave::Profiles::Security::CertProvisioning::WeaveCertProvEngine::InEventParam

Input parameters to Weave Certificate Provisioning API event.

nl::Weave::Profiles::Security::CertProvisioning::WeaveCertProvEngine::OutEventParam

Output parameters to Weave Certificate Provisioning API event.

Public types

@246

 @246
Properties
kReqType_GetInitialOpDeviceCert

The Get Certificate request type is to obtain initial operational certificatete.

kReqType_RotateOpDeviceCert

The Get Certificate request type is to rotate the current operational certificatete.

EventCallback

void(* EventCallback)(void *appState, EventType eventType, const InEventParam &inParam, OutEventParam &outParam)

This function is the application callback that is invoked on Certificate Provisioning Engine API events.

Details
Parameters
[in] appState
A pointer to application-defined state information associated with the engine object.
[in] eventType
Event ID passed by the event callback.
[in] inParam
Reference of input event parameters passed by the event callback.
[in] outParam
Reference of output event parameters passed by the event callback.

EventType

 EventType
Properties
kEvent_CommunicationError

A communication error occurred while sending a GetCertificateRequest or waiting for a response.

kEvent_PrepareAuthorizeInfo

The application is requested to prepare the payload for the GetCertificateRequest.

kEvent_ResponseReceived

A GetCertificateResponse message was received from the peer.

State

 State
Properties
kState_Idle

The engine object is idle.

kState_NotInitialized

The engine object is not initialized.

kState_PreparingBinding

The engine object is waiting for the binding to become ready.

kState_RequestInProgress

A GetCertificateRequest message has been sent and the engine object is awaiting a response.

Public attributes

AppState

void * AppState

A pointer to application-specific data.

Public functions

AbortCertificateProvisioning

void AbortCertificateProvisioning(
  void
)

Stops any GetCertificate exchange in progress.

GenerateGetCertificateRequest

WEAVE_ERROR GenerateGetCertificateRequest(
  PacketBuffer *msgBuf,
  uint8_t reqType,
  bool doMfrAttest
)

Generate GetCertificateRequest message.

This method generates Weave GetCertificateRequest structure encoded in the Weave TLV format.

When forming the GetCertificateRequest message, the method makes a request to the application, via WeaveNodeOpAuthDelegate and WeaveNodeMfrAttestDelegate functions and the PrepareAuthorizeInfo API event, to prepare the payload of the message.

Details
Parameters
[in] msgBuf
A pointer to the PacketBuffer object holding the GetCertificateRequest message.
[in] reqType
Get certificate request type.
[in] doMfrAttest
A boolean flag that indicates whether request should include manufacturer attestation data.
Return Values
WEAVE_NO_ERROR
If GetCertificateRequest was successfully generated.

GetBinding

Binding * GetBinding(
  void
) const

Returns a pointer to the Binding object associated with the WeaveCertProvEngine.

GetEventCallback

EventCallback GetEventCallback(
  void
) const

Returns a pointer to the API event callback function currently configured on the WeaveCertProvEngine object.

GetMfrAttestDelegate

WeaveNodeMfrAttestDelegate * GetMfrAttestDelegate(
  void
) const

Returns a pointer to the manufacturer attestation delegate object currently configured on the WeaveCertProvEngine object.

GetOpAuthDelegate

WeaveNodeOpAuthDelegate * GetOpAuthDelegate(
  void
) const

Returns a pointer to the operational authentication delegate object currently configured on the WeaveCertProvEngine object.

GetReqType

uint8_t GetReqType(
  void
) const

Retrieve the current request type.

GetState

State GetState(
  void
) const

Retrieve the current state of the WeaveCertProvEngine object.

Init

WEAVE_ERROR Init(
  Binding *binding,
  WeaveNodeOpAuthDelegate *opAuthDelegate,
  WeaveNodeMfrAttestDelegate *mfrAttestDelegate,
  EventCallback eventCallback,
  void *appState
)

Initialize a WeaveCertProvEngine object in preparation for sending get certificate request message.

Details
Parameters
[in] binding
A Binding object that will be used to establish communication with the peer node.
[in] opAuthDelegate
A pointer to a operational authentication delegate object that will be used to construct and sign using node's operatational credentials.
[in] mfrAttestDelegate
A pointer to a manufacturer attestation delegate object that will be used to construct and sign request using node's manufacturer provisioned credentials.
[in] eventCallback
A pointer to a function that will be called by the WeaveCertProvEngine object to deliver API events to the application.
[in] appState
A pointer to an application-defined object which will be passed back to the application whenever an API event occurs.

ProcessGetCertificateResponse

WEAVE_ERROR ProcessGetCertificateResponse(
  PacketBuffer *msgBuf
)

Process GetCertificateResponse message.

This method processes Weave GetCertificateResponse structure encoded in the Weave TLV format.

When processing of the GetCertificateResponse message is complete successfully, the method makes a call to the application, via the ResponseReceived API event, to deliver the result.

If processing of the GetCertificateResponse message fails, the method makes a call to the application, via the CommunicationError API event, to report the error.

Details
Parameters
[in] msgBuf
A pointer to the PacketBuffer object holding the GetCertificateResponse message.
Return Values
WEAVE_NO_ERROR
If GetCertificateResponse message was successfully processed.

SetBinding

void SetBinding(
  Binding *binding
)

Sets the binding object on the WeaveCertProvEngine object.

SetEventCallback

void SetEventCallback(
  EventCallback eventCallback
)

Sets the API event callback function on the WeaveCertProvEngine object.

SetMfrAttestDelegate

void SetMfrAttestDelegate(
  WeaveNodeMfrAttestDelegate *mfrAttestDelegate
)

Sets the manufacturer attestation delegate object on the WeaveCertProvEngine object.

SetOpAuthDelegate

void SetOpAuthDelegate(
  WeaveNodeOpAuthDelegate *opAuthDelegate
)

Sets the operational authentication delegate object on the WeaveCertProvEngine object.

Shutdown

void Shutdown(
  void
)

Shutdown a previously initialized WeaveCertProvEngine object.

Note that this method can only be called if the Init() method has been called previously.

StartCertificateProvisioning

WEAVE_ERROR StartCertificateProvisioning(
  uint8_t reqType,
  bool doMfrAttest
)

Start Certificate Provisioning Protocol.

This method initiates the process of sending a GetCertificateRequest message to the CA service. If and when a corresponding GetCertificateResponse message is received it will be delivered to the application via the ResponseReceived API event.

If the Binding object is not in the Ready state when this method is called, a request will be made to Binding::RequestPrepare() method to initiate on-demand preparation. The request operation will then be waiting until this process completes. Any call to StartCertificateProvisioning() while there is a previous request in process will be ignored.

Details
Parameters
[in] reqType
Get certificate request type.
[in] doMfrAttest
A boolean flag that indicates whether protocol should include manufacturer attestation data.
Return Values
WEAVE_NO_ERROR
If StartCertificateProvisioning() was processed successfully.

WeaveCertProvEngine

 WeaveCertProvEngine(
  void
)