class ara::diag::SecurityAccess

use

The pure virtual method CompareKey from class ara::diag::SecurityAccess [SWS_DM_00765] is implemented application-side to validate the key transmitted by the client in UDS service 0x27 (SecurityAccess) SWS Diagnostics §7.3.2.8.9 “Service 0x27 – SecurityAccess”. Together with GetSeed, it forms the basis for the static seed-key mechanism according to ISO 14229-1 [SWS_DM_00863].

The parameters of the function include:

• key: A ara::core::Span<const std::uint8_t> to the key data to be verified. The buffer remains valid until the associated promise is fulfilled or processing is canceled via cancellationHandler [SWS_DM_00765].
• metaInfo: Meta-information of the incoming diagnostic request [SWS_DM_00765].
• cancellationHandler: Enables querying a cancellation via cancellationHandler.IsCanceled as well as registering a notification function via cancellationHandler.SetNotifier upon cancellation of conversation [SWS_DM_00765].

The check result is provided asynchronously via ara::core::Future<KeyCompareResultType> [SWS_DM_00765].

Error Handling and Interaction

If key comparison fails or an error occurs during processing, an appropriate Negative Response Code (NRC) in accordance with ISO 14229-1 must be passed via the future using DiagUdsNrcErrc [SWS_DM_00765]. If the requested sub-function is not configured for CompareKey, the request is answered with NRC 0x12 (kSubFunctionNotSupported) [SWS_DM_00363]. The Diagnostic Server counts failed attempts [SWS_DM_00270] and compares them with threshold values [SWS_DM_00271].

If security access is successfully unlocked, the server updates the security level internally [SWS_DM_00846], resets the failed attempt counter [SWS_DM_00270], and reports the security event SEV_UDS_SECURITY_ACCESS_SUCCESSFUL to the IdsM [SWS_DM_02019].

Concurrency and Limitations

The interface is declared as noexcept and exception safe [SWS_DM_00765]. Thread safety is conditional: whether the implementation must be thread-safe is determined via the ConcurrencyType passed in the constructor of SecurityAccess [SWS_DM_00765].

use

The pure virtual method ara::diag::SecurityAccess::GetSeed is called by the diagnostic server instance as soon as a UDS request for service 0x27 SecurityAccess is received and the transmitted subfunction value matches the configured requestSeedId [SWS_DM_00863]. This is part of the standard-compliant implementation of service 0x27 according to ISO 14229-1 [SWS_DM_00236].

The call passes the payload provided by the diagnostic client via parameter securityAccessDataRecord (as ara::core::Span), the context information in metaInfo, and an object of type CancellationHandler [SWS_DM_00764]. If the client has sent no data, the data span is passed empty [SWS_DM_00863]. The passed data remains valid until the associated promise is fulfilled or processing is canceled [SWS_DM_00764].

Asynchronous Semantics and Concurrency

The function asynchronously returns a ara::core::Future<ara::core::Vector<std::uint8_t>> containing the generated seed [SWS_DM_00764]. Via cancellationHandler, the application can check by means of IsCanceled whether the conversation was canceled, or register a notification via SetNotifier [SWS_DM_00764]. A static seed mechanism according to ISO 14229-1 must also be implemented application-side in GetSeed SWS Diagnostics §7.3.2.8.9 “Service 0x27 – SecurityAccess”.

Regarding concurrency, the method is conditionally thread-safe: Whether the implementation must be thread-safe is determined via ConcurrencyType passed to the constructor of SecurityAccess SWS Diagnostics §8.24.2.1.3.2 “GetSeed”.

Error handling

If no valid seed can be determined, the future must be completed with a matching Negative Response Code (NRC) according to ISO 14229-1 via DiagUdsNrcErrc [SWS_DM_00764]. The interface is declared as noexcept and exception-safe [SWS_DM_00764].

use

The ara::diag::SecurityAccess::Offer method ([SWS_DM_00766]) from the header ara/diag/security_access.h enables the Diagnostic Manager (DM) to forward incoming request messages to the registered handler for security access. The call is synchronous without input parameters and returns a ara::core::Result<void>.

Error handling

In case of an error, the return object provides an error code. If the service is already registered on the instance, DiagOfferErrc::kAlreadyOffered is returned ([SWS_DM_00766]). The function is declared as noexcept and guarantees exception safety (exception safe).

Concurrency and Limitations

The interface is specified as not thread-safe (not thread-safe) ([SWS_DM_00766]). Concurrent calls on the same instance must be synchronized by the application. Interpretation: Multiple uncoordinated calls without previously revoking the offer are likely to always be rejected with kAlreadyOffered. Question Q-848ccd3c78403eea (open)

Interaction

Offering functionality via Offer follows the uniform activation pattern of AUTOSAR Adaptive diagnostics, as is also defined for ServiceValidation ([SWS_DM_00776]) or DoIPGroupIdentification ([SWS_DM_00725]). Despite having the same name as communication interfaces, it is a diagnostic-specific implementation that must not be mixed with ara::com (SWS Diagnostics §7.3.4.1.2 “Monitors”).

use

The explicit constructor initializes an instance of ara::diag::SecurityAccess synchronously and exception-safely ([SWS_DM_00762]). As parameters, it takes a reference to a ara::core::InstanceSpecifier as well as a ConcurrencyType. The parameter specifier must reference a modeled PortPrototype that is typed by a DiagnosticSecurityLevelInterface. Via concurrencyType, it is defined whether the callback methods of the interface are processed concurrently (kConcurrent) or non-concurrently (kNotConcurrent).

Error handling

The function is declared with noexcept ([SWS_DM_00762]). In case of misconfigurations of the modeling, the following violations can occur:

• InstanceSpecifierMappingIntegrityViolation: The InstanceSpecifier cannot be resolved in the execution context or does not refer to a PortPrototype.
• PortInterfaceMappingViolation: The referenced PortPrototype is not typed as DiagnosticSecurityLevelInterface.
• ProcessMappingViolation: No matching modeled process exists at runtime for the instance identifier.
• InstanceSpecifierAlreadyInUseViolation: The InstanceSpecifier is already being used within the process.

Interpretation: The occurrence of such a violation is likely to lead framework-internally to a runtime abort or security handling, since the constructor does not report error codes via a return value. Question Q-de6e36dc7947326e (open)

Concurrency and Limitations

The constructor itself is specified as thread-safe ([SWS_DM_00762]). Copy and move constructors as well as the associated assignment operators are explicitly deleted ([SWS_DM_01617], [SWS_DM_01618], [SWS_DM_01615], [SWS_DM_01616]); an instance can thus neither be copied nor moved. The concurrencyType passed to the constructor determines whether the virtual methods GetSeed ([SWS_DM_00764]) and CompareKey ([SWS_DM_00765]) must be provided thread-safely. The destructor, on the other hand, is not thread-safe ([SWS_DM_00763]).

Interaction

After instantiation, the application must call Offer ([SWS_DM_00766]) so that the Diagnostic Server (DM) forwards incoming UDS requests for service 0x27 (SWS Diagnostics §7.3.2.8.9 “Service 0x27 – SecurityAccess”, [SWS_DM_00236]). If the subfunction matches, the server forwards requests to GetSeed ([SWS_DM_00863]). Forwarding can be deactivated again with StopOffer ([SWS_DM_00767]).

use

The member function StopOffer of class ara::diag::SecurityAccess (header ara/diag/security_access.h) serves to disable the forwarding of incoming request messages from Diagnostic Management (DM) to the instance [SWS_DM_00767]. The call is synchronous, accepts no parameters, and returns no value (void) [SWS_DM_00767].

Error handling

The function is declared with noexcept and classified as exception safe (exception safe) [SWS_DM_00767]. Neither error codes nor C++ exceptions are reported; malfunction or an exceptional state during deregistration is not provided for in the interface specification [SWS_DM_00767].

Concurrency and Limitations

According to the specification, StopOffer is not thread-safe (not thread-safe) [SWS_DM_00767]. If multiple threads of an Adaptive Application access the same instance of ara::diag::SecurityAccess concurrently, the call must be synchronized externally.

Interaction

The method is part of a cross-module functional pattern in the DM area. Similar StopOffer methods exist for numerous other diagnostic services such as:

• ara::diag::Authentication [SWS_DM_01131],
• ara::diag::CommunicationControl [SWS_DM_00810],
• ara::diag::DownloadService [SWS_DM_00793],
• ara::diag::EcuResetRequest [SWS_DM_01017] as well as
• ara::diag::GenericRoutine [SWS_DM_00558] and ara::diag::Monitor [SWS_DM_01089].

Although the naming is modeled after service provision in ara::com, it is an independent diagnostic implementation for controlling message flow within ara::diag AUTOSAR_AP_SWS_Diagnostics §7.3.4.1.2 “Monitors”.

The virtual destructor ~SecurityAccess [SWS_DM_00763] terminates the lifecycle of an instance of service class ara::diag::SecurityAccess in the Diagnostics module AUTOSAR_AP_SWS_Diagnostics §8.24.2.1.1.3 “Destructor”. The interface is provided via header #include "ara/diag/security_access.h" [SWS_DM_00763]. Execution is synchronous, with the function neither accepting parameters nor returning a value [SWS_DM_00763].

Regarding error handling, the operation is classified as exception safe and declared with noexcept [SWS_DM_00763]. Consequently, it does not throw exceptions. Specific error codes and error messages to development or diagnostic error managers (DET or DEM) are not provided in the specification for the destruction of the object [SWS_DM_00763].

Regarding concurrency, the function is explicitly classified as not thread-safe [SWS_DM_00763]. Destruction of the object must never occur simultaneously with calls to other methods on the same instance. As an interpretation: It is likely required to orderly terminate all running diagnostic and security access activities of this instance prior to destruction, since simultaneous accesses lead to undefined behavior. Question Q-12c13e3eebd9e574 (open)

In interaction with the platform, the function serves to implement upstream requirements RS_AP_00134 and RS_Diag_04005 AUTOSAR_AP_SWS_Diagnostics §8.24.2.1.1.3 “Destructor”.