Diag Security Service

API Reference

---

The diag security service APIs are part of the diagnostic service. The diag security service provides diag SessionControl(0x10) and SecurityAccess(0x27) service. The SessionControl service is used to enable different diagnostic sessions in the server. It enables a specific set of diagnostic services or functionality in the server. There shall always be exactly one diagnostic session active in a server. A server shall always start the default diagnostic session when powered up. The SecurityAccess service provides a means to access data and/or diagnostic services, which have restricted access for security, emissions, or safety reasons.

IPC interfaces binding

The functions of this API are provided by the tafDiagSvc platform service.

The following example illustrates how to bind to the diag security service.

bindings:
{
     clientExe.clientComponent.taf_diagSecurity -> tafDiagSvc.taf_diagSecurity
}

Server Service APIs

A diag security service reference can be got using taf_diagSecurity_GetService(). Use the returned reference for subsequent operations.

The following example illustrates how to set up a diag security server-service-instance.

taf_diagSecurity_ServiceRef_t svcRef;    // Service reference

// Get the service reference.
svcRef = taf_diagSecurity_GetService();
LE_ASSERT(svcRef != NULL);

SessionControl(0x10) service

After getting the service reference, an application can call taf_diagSecurity_AddRxSesTypeCheckHandler() to register a message handler for SessionControl(0x10) service. Once a diag session control request message is received, the handler will be called with the message reference and received session type passed as input parameters. The application will check condition for the received session type and uses the message reference to send a response message using taf_diagSecurity_SendSesTypeCheckResp().

// Rx message handler function for SessionControl.
void RxSesTypeHandler
(
     taf_diagSecurity_RxSesTypeCheckRef_t rxSesTypeRef,
     taf_diagSecurity_SessionType_t sesCtrlType,
     void* contextPtr
)
{
     // Process after succesfully receiving message
}

// Register the message handler.
taf_diagSecurity_RxSesTypeCheckHandlerRef_t RxSesTypeCheckHandlerRef
    taf_diagSecurity_AddRxSesTypeCheckHandler(SvcRef,
         (taf_diagSecurity_RxSesTypeHandlerFunc_t)RxSesTypeHandler, NULL);
LE_ASSERT(RxSesTypeCheckHandlerRef != NULL);

// To remove the handler function.
taf_diagSecurity_RemoveRxSesTypeCheckHandler(RxSesTypeCheckHandlerRef);

// To send a response for condition check of requested session type.
le_result_t result = taf_diagSecurity_SendSesTypeCheckResp(rxSesTypeRef,
        TAF_DIAGSECURITY_SES_CONTROL_NO_ERROR);
if (result != LE_OK)
{
   LE_ERROR("Fail to send response.");
   return result;
}

If the application sends a positive response with TAF_DIAGSECURITY_SES_CONTROL_NO_ERROR for the requested session type using taf_diagSecurity_SendSesTypeCheckResp(), then service will change the session type and maintain it. An application can call taf_diagSecurity_AddSesChangeHandler() to register a message handler for session type change. Once session type is changed in diag service, the handler will be called with message reference and receive the previous and current session type. An application can also get the current active session type using taf_diagSecurity_GetCurrentSesType().

// Rx message handler function for session type change.
void SesChangeHandler
(
     taf_diagSecurity_SesChangeRef_t sesChangeRef,
     taf_diagSecurity_SessionType_t previousType,
     taf_diagSecurity_SessionType_t currentType,
     void* contextPtr
)
{
     // Process after succesfully session type change
}

// Register the message handler.
taf_diagSecurity_SesChangeHandlerRef_t SesChangeHandlerRef
    taf_diagSecurity_AddSesChangeHandler(SvcRef,
         (taf_diagSecurity_SesChangeHandlerFunc_t)SesChangeHandler, NULL);
LE_ASSERT(SesChangeHandlerRef != NULL);

// To remove the handler function.
taf_diagSecurity_RemoveSesChangeHandler(SesChangeHandlerRef);

The API of taf_diagSecurity_GetCurrentSesType() is provided to get the current active session type.

Finally call taf_diagSecurity_RemoveSvc() to remove the created service.

SecurityAccess(0x27) service

After getting the service reference, an application can call taf_diagSecurity_AddRxSecAccessMsgHandler() to register a message handler for SecurityAccess(0x27) service. Once a diag security access request message is received, the handler will be called with the message reference and received security accessType passed as input parameters. The application performs the requested security operation based on the received security accessType and uses the message reference to send a response message using taf_diagSecurity_SendSecAccessResp(). Finally call taf_diagSecurity_RemoveSvc() to remove the created service.

// Rx message handler function for SecurityAccess.
void RxSecAccessMsgHandler
(
     taf_diagSecurity_RxSecAccessMsgRef_t rxMsgRef,
     uint8_t accessType,
     void* contextPtr
)
{
     // Process after succesfully receiving message
}

// Register the message handler.
taf_diagSecurity_RxSecAccessMsgHandlerRef_t RxSecAccessMsgHandlerRef =
    taf_diagSecurity_AddRxSecAccessMsgHandler(SvcRef,
         (taf_diagSecurity_RxSecAccessMsgHandlerFunc_t)RxSecAccessMsgHandler, NULL);
LE_ASSERT(RxSecAccessMsgHandlerRef != NULL);

// To remove the handler function.
taf_diagSecurity_RemoveRxSecAccessMsgHandler(RxSecAccessMsgHandlerRef);

The following APIs are provided to get the security access payload. The payload can be either securityAccessDataRecord or securityKey based on the accessType input of the registered RxSecAccessMsgHandler. The payload of requestSeed(0x01) acessType is securityAccessDataRecord and sendKey(0x02) accessType is securityKey.

• taf_diagSecurity_GetSecAccessPayloadLen() – Gets the security access payload length.
• taf_diagSecurity_GetSecAccessPayload() – Gets the security access payload.

An application can send a response by calling taf_diagSecurity_SendSecAccessResp().

le_result_t result = taf_diagSecurity_SendSecAccessResp(rxMsgRef,
        TAF_DIAGSECURITY_SEC_ACCESS_NO_ERROR, NULL, 0);
if (result != LE_OK)
{
   LE_ERROR("Fail to send response.");
   return result;
}

An application can remove the diag security server service by calling taf_diagSecurity_RemoveSvc().

le_result_t result = taf_diagSecurity_RemoveSvc(svcRef);
LE_ASSERT(result == LE_OK);

---