AUTOSAR SWS CryptoInterface
AUTOSAR SWS CryptoInterface
AUTOSAR CP R19-11
Disclaimer
This work (specification and/or software implementation) and the material contained
in it, as released by AUTOSAR, is for the purpose of information only. AUTOSAR
and the companies that have contributed to it shall not be liable for any use of the
work.
The material contained in this work is protected by copyright and other types of
intellectual property rights. The commercial exploitation of the material contained in
this work requires a license to such intellectual property rights.
This work may be utilized or reproduced without any modification, in any form or by
any means, for informational purposes only. For any other purpose, no part of the
work may be utilized or reproduced, in any form or by any means, without permission
in writing from the publisher.
The work has been developed for automotive applications only. It has neither been
developed, nor tested for non-automotive applications.
The word AUTOSAR and the AUTOSAR logo are registered trademarks.
Table of Contents
The Crypto Interface module is located between the low level Crypto solutions
(Crypto Driver [4] and SW-based CDD) and the upper service layer (Crypto Service
Manager [5]). It represents the interface to the services of the Crypto Driver(s) for the
upper service layer. A AUTOSAR Layered View can be found in Figure 7.1.
The Crypto Interface module provides a unique interface to manage different Crypto
HW and SW solutions like HSM, SHE or SW-based CDD. Thus multiple underlying
internal and external Crypto HW as well as SW solutions can be utilized by the
Crypto Service Manager module based on a mapping scheme maintained by Crypto
Interface.
Abbreviation / Description:
Acronym:
CDD Complex Device Driver
CSM Crypto Service Manager
CRYIF Crypto Interface
CRYPTO Crypto Driver
DET Default Error Tracer
HSM Hardware Security Module
HW Hardware
SHE Security Hardware Extension
SW Software
Terms: Description:
Crypto Driver A Crypto Driver Object is an instance of a crypto module (hardware
Object or software), which is able to perform one or more different crypto
operations.
Key A Key can be referenced by a job in the Csm.
In the Crypto Driver, the key references a specific key type.
Key Type A key type consists of references to key elements.
The key types are typically pre-configured by the vendor of the
Crypto Driver.
Key Element Key elements are used to store data. This data can be e.g. key
material or the IV needed for AES encryption.
It can also be used to configure the behavior of the key
management functions.
Channel A channel is the path from a Crypto Service Manager queue via the
Crypto Interface to a specific Crypto Driver Object.
Job A 'Job' is a configured 'CsmJob'. Among others, it refers to a key, a
cryptographic primitive and a reference channel.
Crypto Primitive A crypto primitive is an instance of a configured cryptographic
algorithm.
Operation An operation of a crypto primitive declares what part of the crypto
primitive shall be performed. There are three different operations:
START Operation indicates a new request of a crypto primitive,
and it shall cancel all previous requests.
UPDATE Operation indicates, that the crypto primitive expect
input data.
FINISH Operation indicates, that after this part all data are fed
completely and the crypto primitive can finalize the
calculations.
It is also possible to perform more than one operation at once by
6 of 45 Document ID 806: AUTOSAR_SWS_CryptoInterface
- AUTOSAR confidential -
Specification of Crypto Interface
AUTOSAR CP R19-11
3 Related documentation
[7] Glossary
AUTOSAR_TR_Glossary
Thus, the specification SWS BSW General [3] shall be considered as additional and
required specification for Crypto Interface.
4.1 Limitations
The Crypto Interface is specifically designed to operate with one or multiple
underlying Crypto Drivers. Several Crypto Driver modules covering different HW
processing units or cores are represented by just one generic interface as specified
in the Crypto Driver specification [4].
Any software based Crypto Driver shall be implemented as a CDD represented by
the same interface above.
[SWS_CryIf_00003] ⌈ The code file structure shall not be defined within this
specification completely.
⌋()
[SWS_CryIf_00004] ⌈ The code file structure shall contain one source file CryIf.c,
that contains the entire CRYIF code.
⌋()
6 Requirements traceability
SWS_CryIf_00117, SWS_CryIf_00118,
SWS_CryIf_00119, SWS_CryIf_00121,
SWS_CryIf_00122, SWS_CryIf_00129,
SWS_CryIf_00130, SWS_CryIf_00131,
SWS_CryIf_00139
SRS_CryptoStack_00086 The CSM module shall SWS_CryIf_00009
distinguish between
error types
SWS_BSW_00050 Check parameters SWS_CryIf_91019
passed to Initialization
functions
SWS_BSW_00216 - SWS_CryIf_91118
7 Functional specification
The Crypto Interface is located between the Crypto Service Manager and the
underlying crypto drivers and is the unique interface to access cryptographic
operations for all upper layers (BSW). The Crypto Interface is also the only user of
the crypto drivers and provides a unique interface to manage different crypto
hardware and software solutions. The Abstraction Layer encapsulates different
mechanisms of hardware and software access, so the Crypto Interface
implementation is independent from the underlying Crypto Drivers which can be
realized in hardware or software.
Also it ensures the concurrent access to crypto services to enable the possibility to
process multiple crypto tasks at the same time.
pointer).
API request called with CRYIF_E_PARAM_HANDLE 0x03
invalid parameter (out of
range).
API request called with CRYIF_E_PARAM_VALUE 0x04
invalid parameter (invalid
value).
Source key element size CRYIF_E_KEY_SIZE_MISMATCH 0x05
does not match the target
key elements size.
⌋ (SRS_CryptoStack_00086)
8 API specification
Crypto_GeneralTypes.h Crypto_AlgorithmFamilyType
Crypto_GeneralTypes.h Crypto_AlgorithmInfoType
Crypto_GeneralTypes.h Crypto_AlgorithmModeType
Crypto_GeneralTypes.h Crypto_JobInfoType
Crypto_GeneralTypes.h Crypto_JobPrimitiveInfoType
Crypto_GeneralTypes.h Crypto_JobPrimitiveInputOutputType
Crypto_GeneralTypes.h Crypto_JobRedirectionInfoType
Crypto_GeneralTypes.h Crypto_JobType
Crypto_GeneralTypes.h Crypto_PrimitiveInfoType
Crypto_GeneralTypes.h Crypto_ProcessingType
Crypto_GeneralTypes.h Crypto_ServiceInfoType
Rte_Csm_Type.h Crypto_OperationModeType
Rte_Csm_Type.h Crypto_ResultType
Rte_Csm_Type.h Crypto_VerifyResultType
Std_Types.h Std_ReturnType
Std
Std_Types.h Std_VersionInfoType
⌋()⌋()
The Crypto Stack API uses this type as an extension to Std_ReturnType to return
additional error codes within the crypto stack (see also SWS_Csm_91043 for
reference).
Note:
Furthermore, it should be noted, that the Crypto Stack API uses the key element
index definition from the CSM module (see SWS_Csm_00122).
[SWS_CryIf_91118]⌈
Name CryIf_ConfigType
Kind Structure
implementation specific
Type --
Elements
The content of the configuration data structure is implementation
Comment
specific.
Available
CryIf.h
via
⌋(SWS_BSW_00216)
There are no type definitions.
8.3.1.1 CryIf_Init
[SWS_CryIf_91000]⌈
Service Name CryIf_Init
void CryIf_Init (
Syntax const CryIf_ConfigType* configPtr
)
Sync/Async Synchronous
The Configuration pointer configPtr is currently not used and shall therefore be set
to null pointer value.
[SWS_CryIf_00014] ⌈ If the initialization of the CRYIF module fails, the CRYIF shall
report CRYIF_E_INIT_FAILED to the DET.
⌋ (SRS_CryptoStack_00034)
8.3.1.2 CryIf_GetVersionInfo
[SWS_CryIf_91001]⌈
Service Name CryIf_GetVersionInfo
void CryIf_GetVersionInfo (
Syntax Std_VersionInfoType* versioninfo
)
Sync/Async Synchronous
Reentrancy Reentrant
Parameters (in) versioninfo Pointer to where to store the version information of this module.
⌋(SRS_BSW_00407)
8.3.2.1 CryIf_ProcessJob
To unite a single call function and a streaming approach for the crypto services, there
is one interface CryIf_ProcessJob(). Its Crypto_JobType job parameter
contains a Crypto_OperationModeType flag field (job-
>jobPrimitiveInputOutput.mode), which can be set as “START”, “UPDATE”,
“FINISH” or combination of them. It declares explicitly what operation shall be
performed. These operation modes can be mixed, and execute multiple operations at
once.
[SWS_CryIf_91003]⌈
Service Name CryIf_ProcessJob
Std_ReturnType CryIf_ProcessJob (
uint32 channelId,
Syntax
Crypto_JobType* job
)
Service ID
0x03
[hex]
Reentrancy Reentrant
Parameters Pointer to the configuration of the job. Contains structures with user
job
(inout) and primitive relevant information.
Parameters
None
(out)
Description This interface dispatches the received jobs to the configured crypto driver object.
⌋()
[SWS_CryIf_00142] ⌈
If a job is called and the parameter job->jobPrimitiveInfo-
>primitiveInfo->service is either set to CRYPTO_MACGENERATE,
CRYPTO_MACVERIFY, CRYPTO_ENCRYPT, CRYPTO_DECRYPT,
CRYPTO_AEADENCRYPT, CRYPTO_AEADDECRYPT,
CRYPTO_SIGNATUREGENERATE or CRYPTO_SIGNATUREVERIFY, the parameter
job->jobPrimitiveInfo->cryIfKeyId have to be checked if it is in a valid
range.
21 of 45 Document ID 806: AUTOSAR_SWS_CryptoInterface
- AUTOSAR confidential -
Specification of Crypto Interface
AUTOSAR CP R19-11
If so, CryIf shall set job->cryptoKeyId with the key ID of the crypto driver that
corresponds to job->jobPrimitiveInfo->cryIfKeyId.
⌋()
8.3.3.1 CryIf_CancelJob
[SWS_CryIf_91014]⌈
Service Name CryIf_CancelJob
Std_ReturnType CryIf_CancelJob (
uint32 channelId,
Syntax
Crypto_JobType* job
)
Sync/Async Synchronous
Reentrancy Reentrant
Parameters
None
(out)
This interface dispatches the job cancellation function to the configured crypto
Description
driver object.
⌋()
Std_ReturnType CryIf_KeyElementSet (
uint32 cryIfKeyId,
uint32 keyElementId,
Syntax
const uint8* keyPtr,
uint32 keyLength
)
Service ID
0x04
[hex]
Sync/Async Synchronous
cryIfKeyId Holds the identifier of the key whose key element shall be set.
keyElement
Holds the identifier of the key element which shall be set.
Id
Parameters (in)
Holds the pointer to the key data which shall be set as key
keyPtr
element.
Parameters
None
(inout)
Parameters
None
(out)
This function shall dispatch the set key element function to the configured crypto
Description
driver object.
⌋()
[SWS_CryIf_00049] ⌈ If development error detection for the CRYIF module is
enabled: The function CryIf_KeyElementSet shall report CRYIF_E_UNINIT to
the DET and return E_NOT_OK if the module is not yet initialized.
⌋ (SRS_CryptoStack_00034)
8.3.4.1.2 CryIf_KeySetValid
[SWS_CryIf_91005]⌈
Service Name CryIf_KeySetValid
Std_ReturnType CryIf_KeySetValid (
Syntax uint32 cryIfKeyId
)
Sync/Async Synchronous
Holds the identifier of the key whose key elements shall be set
Parameters (in) cryIfKeyId
to valid.
Parameters None
(inout)
This function shall dispatch the set key valid function to the configured crypto
Description
driver object.
⌋()
Std_ReturnType CryIf_KeyElementGet (
uint32 cryIfKeyId,
uint32 keyElementId,
Syntax
uint8* resultPtr,
uint32* resultLengthPtr
)
Service ID
0x06
[hex]
Sync/Async Synchronous
Reentrancy Reentrant
Parameters cryIfKey
Holds the identifier of the key whose key element shall be returned.
(in) Id
key
Element Holds the identifier of the key element which shall be returned.
Id
Parameters
resultPtr Holds the pointer of the buffer for the returned key element
(out)
This function shall dispatch the get key element function to the configured crypto
Description
driver object.
⌋()
⌋ (SRS_CryptoStack_00034)
Std_ReturnType CryIf_KeyElementCopy (
uint32 cryIfKeyId,
uint32 keyElementId,
Syntax
uint32 targetCryIfKeyId,
uint32 targetKeyElementId
)
Sync/Async Synchronous
Holds the identifier of the key whose key element shall be the
cryIfKeyId
source element.
Holds the identifier of the key element which shall be the source
keyElementId
for the copy operation.
Parameters (in)
targetCryIfKey Holds the identifier of the key whose key element shall be the
Id destination element.
targetKey Holds the identifier of the key element which shall be the
ElementId destination for the copy operation.
Parameters
None
(inout)
Parameters
None
(out)
Description This function shall copy a key elements from one key to a target key.
⌋()
[SWS_CryIf_00115] ⌈
If development error detection for the CRYIF is enabled: If requested key element of
cryIfKeyId is available in targetCryIfKeyId, and if the source element size
does not match the target key elements size, CryIf_KeyElementCopy() shall report
CRYIF_E_KEY_SIZE_MISMATCH to the DET.
⌋ (SRS_CryptoStack_00034)
8.3.4.3.2 CryIf_KeyElementCopyPartial
[SWS_CryIf_91018]⌈
Service Name CryIf_KeyElementCopyPartial
Std_ReturnType CryIf_KeyElementCopyPartial (
uint32 cryIfKeyId,
uint32 keyElementId,
uint32 keyElementSourceOffset,
Syntax uint32 keyElementTargetOffset,
uint32 keyElementCopyLength,
uint32 targetCryIfKeyId,
uint32 targetKeyElementId
)
Service ID
0x12
[hex]
Sync/Async Synchronous
Holds the identifier of the key whose key element shall be the
cryIfKeyId
source element.
keyElementSource This is the offset of the source key element indicating the start
Offset index of the copy operation.
Parameters keyElementTarget This is the offset of the target key element indicating the start
(in) Offset index of the copy operation.
keyElementCopy
Specifies the number of bytes that shall be copied.
Length
Holds the identifier of the key whose key element shall be the
targetCryIfKeyId
destination element.
targetKeyElement Holds the identifier of the key element which shall be the
Id destination for the copy operation.
Parameters
None
(inout)
Parameters
None
(out)
Copies a key element to another key element. The keyElementOffsets and key
Description ElementCopyLength allows to copy just parts of the source key element into the
destination key element.
⌋()
8.3.4.3.3 CryIf_KeyCopy
[SWS_CryIf_91016]⌈
Service Name CryIf_KeyCopy
Std_ReturnType CryIf_KeyCopy (
uint32 cryIfKeyId,
Syntax
uint32 targetCryIfKeyId
)
Sync/Async Synchronous
Holds the identifier of the key whose key element shall be the
cryIfKeyId
source element.
Parameters (in)
targetCryIf Holds the identifier of the key whose key element shall be the
KeyId destination element.
Parameters
None
(inout)
Parameters
None
(out)
Description This function shall copy all key elements from the source key to a target key.
⌋()
⌋ (SRS_CryptoStack_00034)
[SWS_CryIf_00121] ⌈
If development error detection for the CRYIF is enabled: For all key elements of
cryIfKeyId that are available in targetCryIfKeyId, if the source element size
does not match the target key elements size, CryIf_KeyCopy() shall report
CRYIF_E_KEY_SIZE_MISMATCH to the DET.
⌋ (SRS_CryptoStack_00034)
Std_ReturnType CryIf_RandomSeed (
uint32 cryIfKeyId,
Syntax const uint8* seedPtr,
uint32 seedLength
)
Reentrancy Reentrant
Holds the identifier of the key for which a new seed shall be
cryIfKeyId
generated.
Parameters (in) Holds a pointer to the memory location which contains the data
seedPtr
to feed the seed.
Parameters
None
(inout)
This function shall dispatch the random seed function to the configured crypto
Description
driver object.
⌋()
8.3.4.4.2 CryIf_KeyGenerate
[SWS_CryIf_91008]⌈
Service Name CryIf_KeyGenerate
Std_ReturnType CryIf_KeyGenerate (
Syntax uint32 cryIfKeyId
)
Reentrancy Reentrant
Parameters
None
(inout)
Parameters
None
(out)
This function shall dispatch the key generate function to the configured crypto
Description
driver object.
⌋()
8.3.4.5.1 CryIf_KeyDerive
[SWS_CryIf_91009]⌈
Service Name CryIf_KeyDerive
Std_ReturnType CryIf_KeyDerive (
uint32 cryIfKeyId,
Syntax
uint32 targetCryIfKeyId
)
Sync/Async Synchronous
Reentrancy Reentrant
cryIfKeyId Holds the identifier of the key which is used for key derivation.
Parameters (in)
targetCryIf Holds the identifier of the key which is used to store the derived
KeyId key.
Parameters
None
(inout)
Parameters
None
(out)
This function shall dispatch the key derive function to the configured crypto driver
Description
object.
⌋()
The key derivation service needs a salt and password to derivate a new key. The salt
and the password therefore are stored as key elements in the key referred by
cryIfKeyId.
Std_ReturnType CryIf_KeyExchangeCalcPubVal (
uint32 cryIfKeyId,
Syntax uint8* publicValuePtr,
uint32* publicValueLengthPtr
)
Service ID 0x0a
35 of 45 Document ID 806: AUTOSAR_SWS_CryptoInterface
- AUTOSAR confidential -
Specification of Crypto Interface
AUTOSAR CP R19-11
[hex]
Sync/Async Synchronous
Reentrancy Reentrant
Parameters Holds the identifier of the key which shall be used for the key exchange
cryIfKeyId
(in) protocol.
Holds a pointer to the memory location in which the public value length
public information is stored. On calling this function, this parameter shall
Parameters
Value contain the size of the buffer provided by publicValuePtr. When the
(inout)
LengthPtr request has finished, the actual length of the returned value shall be
stored.
Parameters public
Contains the pointer to the data where the public value shall be stored.
(out) ValuePtr
This function shall dispatch the key exchange public value calculation function to the
Description
configured crypto driver object.
⌋()
[SWS_CryIf_00082] ⌈ If development error detection for the CRYIF module is
enabled: The function CryIf_KeyExchangeCalcPubVal shall report
CRYIF_E_UNINIT to the DET and return E_NOT_OK if the module is not yet
initialized.
⌋ (SRS_CryptoStack_00034)
8.3.4.6.2 CryIf_KeyExchangeCalcSecret
[SWS_CryIf_91011]⌈
Service Name CryIf_KeyExchangeCalcSecret
Std_ReturnType CryIf_KeyExchangeCalcSecret (
uint32 cryIfKeyId,
Syntax const uint8* partnerPublicValuePtr,
uint32 partnerPublicValueLength
)
Service ID
0x0b
[hex]
Sync/Async Synchronous
Reentrancy Reentrant
Holds the identifier of the key which shall be used for the
cryIfKeyId
key exchange protocol.
partnerPublicValue Holds the pointer to the memory location which contains the
Parameters (in)
Ptr partner's public value.
partnerPublicValue
Contains the length of the partner's public value in bytes.
Length
Parameters
None
(inout)
Parameters
None
(out)
This function shall dispatch the key exchange common shared secret calculation
Description
function to the configured crypto driver object.
⌋()
8.4.1 CryIf_CallbackNotification
[SWS_CryIf_91013]⌈
Service Name CryIf_CallbackNotification
void CryIf_CallbackNotification (
Crypto_JobType* job,
Syntax
Crypto_ResultType result
)
Sync/Async Synchronous
Parameters
None
(inout)
Parameters
None
(out)
Notifies the CRYIF about the completion of the request with the result of the
Description
cryptographic operation.
⌋(SRS_BSW_00359, SRS_BSW_00360)
This chapter defines all interfaces, which are required to fulfill the core functionality of
the CryIf module.
[SWS_CryIf_91100]⌈
Header
API Function Description
File
Notifies the CSM that a job has finished. This function is used by the
Csm_Callback-
Csm.h underlying layer (CRYIF). The function name itself is derived from
Notification
"{CsmJob/CsmJobPrimitiveCallbackRef}/CsmCallbackFunc".
Det_Report- Service to report runtime errors. If a callout has been configured then
Det.h
RuntimeError this callout shall be called.
⌋()
This chapter defines all interfaces, which are required to fulfill an optional
functionality of the CryIf module.
[SWS_CryIf_91101]⌈
API Function Header File Description
⌋()
9 Sequence diagrams
N/A.
10 Configuration specification
Chapter 10.1 specifies the structure (containers) and the parameters of the module
CRYIF.
10.1.1 Variants
10.1.2 CryIf
Included Containers
Container Name Multiplicity Scope / Dependency
CryIfChannel 0..* Container for incorporation of CryIfChannel.
CryIfGeneral 1 Container for incorporation of CryIfGeneral.
CryIfKey 0..* Container for incorporation of CryIfKey.
CryIf: EcucModuleDef
lowerMultiplicity = 0
upperMultiplicity = 1
+container +container
CryIfChannel: CryIfKey:
EcucParamConfContainerDef EcucParamConfContainerDef
lowerMultiplicity = 0 lowerMultiplicity = 0
upperMultiplicity = * upperMultiplicity = *
+container
CryIfGeneral:
EcucParamConfContainerDef
10.1.3 CryIfGeneral
No Included Containers
CryIfGeneral:
+parameter CryIfDevErrorDetect:
EcucParamConfContainerDef
EcucBooleanParamDef
defaultValue = false
+parameter CryIfVersionInfoApi:
EcucBooleanParamDef
defaultValue = false
10.1.4 CryIfChannel
No Included Containers
CryIfChannel:
CryIfChannelId:
EcucParamConfContainerDef
+parameter EcucIntegerParamDef
lowerMultiplicity = 0
min = 0
upperMultiplicity = *
max = 4294967295
symbolicNameValue = true
CryptoDriverObject:
+reference CryIfDriverObjectRef: EcucReferenceDef
+destination EcucParamConfContainerDef
10.1.5 CryIfKey
No Included Containers
CryIfKey:
CryIfKeyId:
EcucParamConfContainerDef
+parameter EcucIntegerParamDef
lowerMultiplicity = 0
min = 0
upperMultiplicity = *
max = 4294967295
symbolicNameValue = true