1. Introduction

1.1. Scope

This application note contains details on how to configure and integrate SecOC into an existing RTA-CAR project. To be able to use SecOC you will also need to have a basic BSW security stack (CSM, CryIF, cryptodriver) already configured.
The aim of this example is to add an AES MAC code to an I-PDU to prevent potential tampering with the message. SecOC allows users to add security related features e.g. MAC codes to existing I-PDU within their system. SecOC operates at the PDUR level and intercepts the specific Secure-IPDUs to perform security tasks on them e.g. encrypt, decrypt. Additionally a "Freshness Value" will also be added to the I-PDU to prevent possible "replay attacks" from being conducted.

1.2. Toolchain

It is assumed you are using the RTA-CAR 12.0.0 toolchain:

2. Prerequisites

In order to successfully follow this guide, you must have the RTA-CAR toolchain, and you must be familiar with the AUTOSAR specifications, terminology and methodology.
The BSW security stack (CSM, CryIf, CryptoDriver) should already be configured in your project.

3. RTA-CAR Workflow

3.1. System Description Configuration

3.1.1. Security Configuration Package (Propset)

The Security Configuration Package object contains information relating to "freshness value" and/or MAC code for Secure IPDUs. These can be configure in ISOLAR-A as part the system description, one is required for each layout you use. If you wish you can split the "freshness value" and MAC code into their own separate propsets.
To create one, in ISOLAR-A right click on your "System description" → "Create System Common" → "Elements | Secure Communication Prop Set"

When filling out the Security Configuration Package, watch out for sizes, these are defined in bits not bytes.
For this example (MAC code) we will need 1 AuthenticationProps and 1 FreshnessProps.
For the AutheneticationProps, this is simple as we are only using a MAC code with no encryption the value is just the length of the MAC Code.

The FreshnessProps configuration refers to a Freshness Value (if you are setting one) to prevent replay attacks. The configuration of this will depend on what you are using to generate a freshness value, some example values can be seen below:

With this new SecureCommunicationPropset created, you can now create the Secure I-PDU. This propset can be reused for multiple I-PDUs if their layout is the same.

3.1.2. SecOC I-PDUs

For each I-PDU that needs to be sent using SecOC, a corresponding Secure-IPDU must be created in the system description. The I-PDU acts as payload and has the following information added:

• Header - An optional field that sets a fixed length header for each Secure-IPDU
• Authentic I-PDU - The actual I-PDU that is being used, in RTA-CAR this is just a reference to an existing I-PDU
• Freshness Value - An optional field, which attaches a generated number to the Secure I-PDU to prevent "replay attacks" 
• Authentication - The security feature being added to the I-PDU e.g. MAC code

3.1.3. ISignal I-PDU

An ISignal I-PDU can be imported by a DBC or configured manually in the project.
For this example we will use a ISignal I-PDU that is already present in the project.

3.1.4. Secure I-PDU

A Secure I-PDU can be added from the system editor, in ISOLAR-A go under "System" → "Pdus" right click and select "Create Elements | Secure IPdu"

After the Secure I-PDU is generated the user can open it with the generic editor and configure the following parameters:

• ShortName - Configure with something sensible (Not the same as the I-PDU being used)
• Length - The total length of the Secured I-PDU (in bytes), the size in this case would be I-PDU Size (e.g. 2 bytes) + MAC Code (authenticator) (e.g. 2 bytes)+ Freshness Value Size(e.g. 4 bytes)
• AuthenticationProps - reference to the SecureCommunicationAuthenticationProps configured before
• FreshnessProps - reference to the SecureCommunicationFreshnessProps configured before
• Payload - Use the drop down menu to select the required I-PDU Trigger of the ISignal I-PDU
  

A Secure Communication Props need to be created as well

3.1.5. Secure IPdu Port

A Secure IPdu Port need to be created for the Secure IPDU.

Go under "System" → "Ecus" → "Connectors" right click and select "New Child" → "Ecu Comm Port Instances | IPdu Port"

Open it with Generic Editor and simply configure the Communication Direction of it as follow:

3.1.6. Secure I-Pdu Triggering Mapping

A Secure IPdu Trigger need to be created for the Secure IPDU.

Go under "System" → "Network" → "Can Network" → "CAN" → "Channel" → "Pdu Triggerings" and right click and select "create Pdu Triggerings | Pdu Triggering"

Right click on it and open it with generic editor.

Configure the following parameter:

• IPdu: reference to the Secured I-PDU
• IPduPorts: reference to the Secure I-PDU Port

3.1.7. Secure Frame Triggering

The Secure IPdu Trigger, created in step before, need to be referenced inside the CanFrameTrigger.

To do it follow this image:

3.1.8. Can Frame Mapping

Now the configuration of the Secure I-Pdu is finished and the last step of the system configuration is to reference it in the ISignal Frame of the payload.
In the AR Explore menu right click on "System" → "Frames" and select "Open with" → "System Editor".
Go under the "PduToFrameMapping" and reference in the Pdu field the Secure Pdu as follow:

3.2. Update the ECU configuration

To update the ECU configuration run the ConfGen

After this step, the SecOC module is configured with the Secure I-PDU as shown in the images below:

3.3. SecOC BSW Configuration

3.3.1. SecOC General Configuration

Now that the SecOC is generated by the ConfGen, the user can configure the SecOCGeneral with some basic values:

• SecOCQueryFreshnessValue - Specifies if the freshness value shall be determined through a C-function (CD) or a software component (SW-C)

After having configured the SecOCQueryFreshnessValue all the other parameters are configured automatically. The user can modify them in function of its project:

• SecOCRbCryptDefaultInterface - Selects the default Cryptographic interface
• SecOCRbCryptDefaultMode - Choice of sync vs async. For this example we will leave Synchronous
• SecOCRbDefaultCryptAlgoFamily - Choice of what algorithm to use for generation and verification of MAC. For this example we will leave AES
• SecOCRbDefaultCryptAlgoMode - Choice of what algorithm mode to use for generation and verification of MAC. For this example we will leave CMAC

As shown here:

3.3.2. SecOC Tx PduProcessings Configuration

This container was already configured by Confgen, but the user need to add the configuration of the mandatory parameter SecOCTxPduUnusedAreasDefault.
An example here:

3.4. PduR BSW Configuration

All the SecOC mandatory parameters need to be configured inside the PduRBswModules. An example here: 

3.5. BswM Configuration

The SecOC module needs to be initialized by configuring BswM action list.
Create a new Action Item under the Arbitration Rule "BswM_AR_ReadAllComplete" and Action List "BswM_AL_BswModules_InitListReadAll" and call it "BswM_AI_SecOCInit" (if the name cannot be changed in the Abstraction Editor, open up BswMGeneral container to name the action). Select the action kind "BswMUserCallout" and write the function name used in the code.

The file SecOC.h needs to be added in the BswMUserIncludeFiles of the BswM.
To do so open the BswM with the generic editor and add it as explained in the image below:

3.6. Generate the BSW

Now the SecOC BSW configuration is ready and the BSW Generator can be run. Remember to select the SecOC module in the BSW generator.

3.7. Entity to Task mapping

After the BSW Generation we can map the SecOC main functions to the OsTask:

• SE_SecOC_MainFunctionTx
• SE_SecOC_MainFunctionRx

3.8. ASW Configuration

For freshness value nothing need to by configured in BSW as it is standard. After BSW Gen, in the Application layer the SecOC need to be included in the top level composition.
The SecOC needs to be connected with an ASW Component like a Cdd to share the Freshness value.
So, the user need to create a cdd component on asw and connect the cdd to the SecOC R port used for the freshness value management.