class ara::diag::ClientAuthentication

Usage and Invocation

The function ara::diag::ClientAuthentication::Authenticate is called by an application to notify the Diagnostic Server instance of the successful authentication of a diagnostic client [SWS_DM_01142]. This can occur after authentication via the interfaces of the Diagnostic Server or via application-own mechanisms [SWS_DM_01142].

As an input parameter, the function accepts userRoles (of type ara::core::Vector<DiagnosticAuthRole>). Upon a successful call, the instance's authentication status transitions to kAuthenticated, and the passed user roles are firmly adopted [SWS_DM_01206]. As a return value, it provides a ara::core::Result<ClientAuthenticationHandle> [SWS_DM_01142]. Since a result object is provided immediately, the processing is likely to take place synchronously in the calling context. Question Q-dae22c82694f2103 (open)

Error Handling and Concurrency

The method is declared as noexcept and is considered exception safe (exception safe) [SWS_DM_01142]. If an error occurs because fundamental functionalities of the Diagnostic Manager are not available at invocation time, the operation fails with rollback semantics and returns DiagErrc::kServiceNotAvailable in the result object [SWS_DM_01142].

Regarding concurrency, the method is explicitly specified as not thread-safe [SWS_DM_01142]. Parallel calls on the same ClientAuthentication object are therefore not permitted and must be synchronized by the application.

Interaction and Lifecycle

The received ClientAuthenticationHandle allows the application to define or extend a DynamicAccessList for the authenticated client [SWS_DM_01142]. In addition, the call starts or references the inactivity monitoring of the client: if no further UDS request occurs after successful authentication in the default session state for the duration of authenticationTimeout, the Diagnostic Server instance automatically resets the client to kDeAuthenticated [SWS_DM_01210]. To prevent this timeout, the application can update the timer via method Refresh of the handle [SWS_DM_01155].

With the synchronous method OverrideDefaultRoles of class ara::diag::ClientAuthentication, an application can temporarily override the default authentication roles (defaultRoles) of a diagnostic client [SWS_DM_01141]. The diagnostic services enabled for the passed roles are available to the tester for the period of time defined in parameter timeout [SWS_DM_01141]. The prerequisite for this is that the client is in state kDeAuthenticated [SWS_DM_01209]. Interpretation: If the call is not made in state kDeAuthenticated, the role override is likely to be rejected or remain without effect, as the specification mandates the behavior exclusively for this initial state. Question Q-81189f2c2fe0f301 (open)

Upon successful execution, the method returns an instance of ClientAuthenticationHandle within a ara::core::Result to the application [SWS_DM_01141], [SWS_DM_01209]. If the call cannot be executed because essential functionality of the Diagnostic Manager is currently unavailable, error code DiagErrc::kServiceNotAvailable is returned [SWS_DM_01141]. The function is declared as noexcept and is exception safe [SWS_DM_01141].

For concurrency and interaction with further components, the following requirements apply:

• Concurrency: The method is specified as not thread-safe [SWS_DM_01141]. Concurrent calls on the same instance must be synchronized on the application side.
• Handle management: Via the returned instance of ClientAuthenticationHandle, the running timer can be extended with Refresh() [SWS_DM_01155]. In addition, the handle enables management of the DynamicAccessList for additional diagnostic resources AUTOSAR_AP_SWS_Diagnostics §7.3.2.3.3 “ClientAuthenticationHandle”.

use

Method [SWS_DM_01144] of class ara::diag::ClientAuthentication is used by the application to register a callback function of type ClientAuthenticationSetNotifier. This function is called by the Diagnostic Server instance as soon as the authentication status of a client changes [SWS_DM_01144]. This enables the application to respond immediately to state transitions, for example when an automatic transition to state kDeAuthenticated occurs after an S3 server timeout [SWS_DM_01211] or a timeout due to client inactivity occurs [SWS_DM_01210].

Error Handling and Return Value

The function returns a ara::core::Result<void> and is declared as noexcept as well as exception safe [SWS_DM_01144]. No standardized error codes are specified [SWS_DM_01144]; presumably the Result object always returns success (void) in regular operation. Question Q-0d7d43cc37d57944 (open)

Concurrency and Interaction

Regarding thread safety, the method is specified as "not thread-safe" [SWS_DM_01144]. Calls on the same instance must therefore not be made unprotected from concurrent threads. In addition, an overwrite behavior applies to the registration: a subsequent call to SetNotifier completely replaces the previously registered notifier [SWS_DM_01144]. This behavior complies with the unified registration pattern in Diagnostic Management, as defined analogously for [SWS_DM_00615] (CancellationHandler), [SWS_DM_00745] (Indicator), and [SWS_DM_00755] (OperationCycle).

The destructor [SWS_DM_01136] of class ara::diag::ClientAuthentication serves for releasing and cleanly tearing down an instance for client authentication in Diagnostic Management. The function is defined in header file #include "ara/diag/client_authentication.h" and is called synchronously at the end of the object lifecycle (AUTOSAR_AP_SWS_Diagnostics §8.5.1.2.1.2 “Destructor”).

The following specifications apply to usage and execution properties:

• Call and parameters: As a destructor, ~ClientAuthentication() has neither input parameters nor a return value.
• Error and exception safety: The operation is specified as noexcept and exception safe [SWS_DM_01136]; no exceptions are guaranteed to be thrown when tearing down the object.
• Concurrency: The call is explicitly classified as not thread-safe. Consequently, destroying the object must not occur concurrently with other method calls on the same instance.

The element implements the upstream requirement RS_Diag_04251 (AUTOSAR_AP_SWS_Diagnostics §8.5.1.2.1.2 “Destructor”). Interpretation: Before destroying the instance, active authentication or communication processes of the application are likely to need to be terminated in an orderly manner to avoid undefined behavior due to the lack of thread safety. Question Q-cedd6f523eb2c1c3 (open)