class ara::diag::Authentication

The constructor synchronously initializes an object of handler class ara::diag::Authentication to process diagnostic authentication requests on a software port [SWS_DM_01124]. The parameter specifier refers to the modeled PortPrototype, which must mandatory be typed by a DiagnosticAuthenticationInterface via a DiagnosticAuthenticationPortMapping [SWS_DM_01124]. Via the parameter concurrencyType, it is defined whether the framework delivers method calls concurrently (kConcurrent) or non-thread-safely (kNotConcurrent) [SWS_DM_01124].

Since the function is declared as noexcept, incorrect calls are not reported via exceptions, but trigger framework violations [SWS_DM_01124]:

• InstanceSpecifierMappingIntegrityViolation: The identifier cannot be resolved in the context of the Executable or does not reference a PortPrototype [SWS_DM_01124].
• PortInterfaceMappingViolation: The referenced PortPrototype is not modeled as a DiagnosticAuthenticationInterface [SWS_DM_01124].
• ProcessMappingViolation: At runtime, no matching modeled process is found [SWS_DM_01124].
• InstanceSpecifierAlreadyInUseViolation: The InstanceSpecifier has already been used for an instance in the current process [SWS_DM_01124].

The constructor itself is thread-safe and exception-safe [SWS_DM_01124], whereas the associated destructor ~Authentication() is specified as not thread-safe [SWS_DM_01125]. Immediately after instantiation, no diagnostic requests are forwarded yet: the application must first call Offer() to activate forwarding for the UDS service 0x29 (Authentication with PKI Certificate Exchange, APCE AUTOSAR_AP_SWS_Diagnostics Tab. 4.1 “Limitations of sub-functions of 0x19 ReadDTCInformation”) by the Diagnostic Manager [SWS_DM_01130]. Certificate validation is subsequently processed via VerifyCertificateUnidirectional [SWS_DM_01126], VerifyCertificateBidirectional [SWS_DM_01127], and VerifyOwnership [SWS_DM_01128]. Before object destruction, forwarding must be stopped with StopOffer() [SWS_DM_01131].

With the synchronous method Offer() of class ara::diag::Authentication ([SWS_DM_01130]), an Adaptive Application registers its authentication handler with Diagnostic Management (DM). As a result, the DM is authorized and enabled to forward incoming requests to this handler (AUTOSAR_AP_SWS_Diagnostics §8.3.1.1.3.1 “Offer”). The function takes no input parameters and indicates the outcome of the operation via the return type ara::core::Result<void>.

The call is declared as noexcept and is thus exception-safe ([SWS_DM_01130]). If registration fails because the service has already been provided for this instance previously, the specific error code DiagOfferErrc::kAlreadyOffered is returned in the result object ([SWS_DM_01130]). In addition, the interface is specified as not thread-safe; parallel accesses to the same instance must presumably not occur unprotected and must be synchronized on the application side. Question Q-51ab72e4e72a7351 (open)

In the lifecycle of diagnostic processing, Offer() corresponds directly to the counter-function StopOffer() ([SWS_DM_01131], AUTOSAR_AP_SWS_Diagnostics §8.3.1.1.3.2 “StopOffer”), which terminates the forwarding of requests again. This pattern follows the uniform offering approach of diagnostic handlers, as also applied for example in ara::diag::CommunicationControl::Offer ([SWS_DM_00809]) or ara::diag::DoIPPowerMode::Offer ([SWS_DM_00735]), where requests can only be processed after explicit offering by the application ([SWS_DM_01525]).

use

The method StopOffer of class ara::diag::Authentication (defined in ara/diag/authentication.h) disables the forwarding of request messages by the Diagnostic Manager (DM) to the instance [SWS_DM_01131]. The call is executed synchronously, requires no input parameters, and has no return value AUTOSAR_AP_SWS_Diagnostics §8.3.1.1.3.2 “StopOffer”.

Error Handling and Execution Safety

The function is specified as exception safe (noexcept); specific error codes or exceptions are not defined [SWS_DM_01131].

Concurrency and Limitations

The operation is explicitly designated as not thread-safe (“not thread-safe”) [SWS_DM_01131]. Concurrent calls on the same instance must be synchronized by the calling application.

Interaction and Architectural Context

The design pattern of StopOffer is used consistently across various services and handlers in the Adaptive Diagnostic Manager, including SecurityAccess [SWS_DM_00767], CommunicationControl [SWS_DM_00810], DownloadService [SWS_DM_00793], and EcuResetRequest [SWS_DM_01017]. Although the naming is based on service offering in ara::com, it is a diagnostics-specific implementation AUTOSAR_AP_SWS_Diagnostics §7.3.4.1.2 “Monitors”. Interpretation: Prior to deactivation using StopOffer, the instance would typically have been actively receiving requests via an offering function. Question Q-da990416e53707ed (open)

The pure virtual callback method VerifyCertificateBidirectional of interface ara::diag::Authentication ([SWS_DM_01127]) is called by the Diagnostic Server as soon as a diagnostic request for UDS service 0x29 (Authentication) with sub-function 0x02 (verifyCertificateBidirectional) arrives and the initial checks have been passed successfully ([SWS_DM_01235], AUTOSAR_AP_SWS_Diagnostics §7.3.2.8.11.3 “Service 0x29 – verifyCertificateBidirectional (0x02)”).

Usage and semantics: The server passes the communication configuration and the certificate and challenge data received from the tester via communicationConfiguration, clientCertificate, and clientChallenge together with metaInfo and the cancellationHandler ([SWS_DM_01127], [SWS_DM_01235]). The buffers of the input spans remain valid until the returned ara::core::Future is satisfied via the associated promise or the operation is cancelled ([SWS_DM_01127]). Asynchronously, the method returns a 4-tuple consisting of server challenge, server certificate, calculated proof of ownership, and the ephemeral public key of the server to the Diagnostic Server ([SWS_DM_01127]).

Cancellation and concurrency: Via cancellationHandler, the application can poll the current status using IsCanceled or register a notification function for connection termination via SetNotifier ([SWS_DM_01127]). The interface is defined as noexcept and may be called reentrantly with respect to requests from different clients ([SWS_DM_01127]). Whether the implementation must be thread-safe is determined via the ConcurrencyType passed in the constructor ([SWS_DM_01127]).

Error handling and interaction: In the error case, the application returns an appropriate NRC in accordance with ISO 14229-1 via DiagUdsNrcErrc; negative return values are processed separately by the Diagnostic Server ([SWS_DM_01127], [SWS_DM_01236]). Within UDS authentication ([SWS_DM_01226]), configuration of this sub-function forms a necessary prerequisite if DiagnosticProofOfOwnership is configured ([SWS_DM_01227], [SWS_DM_01228]).

The callback method VerifyCertificateUnidirectional of class ara::diag::Authentication is called by the Diagnostic Server instance as soon as a request for UDS service 0x29 with sub-function verifyCertificateUnidirectional (0x01) has been received and successfully pre-checked (SWS Diagnostics §7.3.2.8.11.2 “Service 0x29 – verifyCertificateUnidirectional (0x01)”, [SWS_DM_01230]). It implements unidirectional authentication via PKI certificate exchange in accordance with ISO 14229-1 ([SWS_DM_01226]).

As parameters, the communication configuration (communicationConfiguration), the client certificate (clientCertificate), and the client challenge (clientChallenge) as well as meta information and a CancellationHandler are passed ([SWS_DM_01126]). The passed spans remain valid until the returned ara::core::Future is satisfied or processing is cancelled via the handler. The method asynchronously returns a tuple consisting of the generated server challenge and the ephemeral public key of the server ([SWS_DM_01126]).

If an error occurs during validation, the future must be completed with an appropriate negative response code (NRC) via DiagUdsNrcErrc ([SWS_DM_01126]).

The function is specified as exception safe and may be called reentrantly for requests from different diagnostic clients ([SWS_DM_01126]). Thread safety is conditional; whether the implementation must be thread-safe is determined by the ConcurrencyType specified in the constructor ([SWS_DM_01126]). In the overall process, configuration of this check is a mandatory prerequisite if sub-function DiagnosticProofOfOwnership is configured ([SWS_DM_01227]).

Usage and Call Context

The pure virtual method VerifyOwnership of class ara::diag::Authentication is called by the Diagnostic Server as soon as an authentication request of UDS service 0x29 with subfunction proofOfOwnership (0x03) has been received and the preparatory checks have succeeded [SWS_DM_01240]. The task of the implementation is to verify the proof of ownership transmitted by the tester against the generated server challenge using the public key from the previously exchanged client certificate [SWS_DM_01128].

Upon invocation, the Diagnostic Server passes the relevant cryptographic input data and context objects AUTOSAR_AP_SWS_Diagnostics §8.3.1.1.3.5 “VerifyOwnership”:

• clientPOWN: Contains the proof of ownership provided by the diagnostic tester for the previous server challenge.
• clientEphemeralPublicKey: The client's ephemeral public key for Diffie-Hellman key agreement according to ISO 14229-1:2020.
• metaInfo: Meta-information of the current diagnostic request.
• cancellationHandler: Allows querying a possible cancellation (cancellationHandler.IsCanceled) as well as registering a notification function (cancellationHandler.SetNotifier).

The function operates asynchronously and returns a ara::core::Future, which provides the session key information as a byte vector in case of success [SWS_DM_01128].

Error handling

If the ownership check cannot be performed successfully, the application sets a matching negative UDS return value (NRC) according to ISO 14229-1 via DiagUdsNrcErrc in the returned future [SWS_DM_01128]. If the method returns such a defined error code, the Diagnostic Server sends a negative response with the corresponding NRC to the client [SWS_DM_01241].

Concurrency and Constraints

The interface is defined as noexcept. Regarding thread safety, the behavior is considered conditional (conditional): whether the method must be implemented thread-safe is determined by the ConcurrencyType specified during the construction of the instance [SWS_DM_01128]. For the buffers clientPOWN and clientEphemeralPublicKey, it is ensured that their memory area remains valid until the promise is fulfilled or processing is canceled via the cancellationHandler [SWS_DM_01128].

The virtual destructor ~Authentication() terminates the lifecycle of an instance of class ara::diag::Authentication and releases its resources [SWS_DM_01125]. The method is declared in header file #include "ara/diag/authentication.h" of module Diagnostics AUTOSAR_AP_SWS_Diagnostics §8.3.1.1.1.3 “Destructor”.

The function takes no parameters, returns no return value, and is called synchronously when destructing the object [SWS_DM_01125]. Qualification as virtual ensures that in polymorphic deletion via pointers or references to base classes, resources of derived classes are also properly cleaned up.

With regard to error handling, the method is specified as exception safe and bears the specifier noexcept [SWS_DM_01125]. Error or status codes are not returned, and it is guaranteed that no C++ exceptions escape to the outside.

Regarding concurrency, ~Authentication() is classified as not thread-safe [SWS_DM_01125]. Destruction must therefore under no circumstances occur concurrently with other method calls on the same instance. Interpretation: The using application is likely required to complete all ongoing authentication or diagnostic operations prior to destruction and to protect the call externally against concurrent accesses. Question Q-41b1c115c1056759 (open) The destructor implements the upstream requirement RS_Diag_04251 AUTOSAR_AP_SWS_Diagnostics §8.3.1.1.1.3 “Destructor”.