PACEMapping

internal enum PACEMapping

PACEMapping manages the possible algorithm-specific mapping functions used during the PACE security protocol for accessing the contactless IC.

In PACE, a nonce s is encrypted using a chosen block cipher E() and a derived key Kπ. This nonce is then mapped to a random generator using an algorithm-specific mapping function Map.

PACE supports three mapping functions:

Generic Mapping (GM): This mapping uses either DH or ECDH. The function Map:g → ĝ is defined differently for DH and ECDH:
- Using DH: ĝ = g^s * h, where h is calculated by anonymous Diffie-Hellman Key Agreement.
- Using ECDH: Ĝ = s × G + H, where H is calculated by anonymous EC Diffie-Hellman Key Agreement.
Integrated Mapping (IM): IM uses either DH or ECDH. It utilizes a pseudo-random function Rp(s,t) and a function f_g(x) to map nonces to group elements.
Chip Authentication Mapping (CAM): The mapping phase of PACE-CAM is identical to PACE-GM.

Important

The description includes high-level details of PACE mapping. For precise specifications, consult relevant standards documents.

GM
Generic Mapping
Declaration
Swift

case GM
IM
Integrated Mapping
Declaration
Swift

case IM
CAM
Chip Authentication Mapping
Declaration
Swift

case CAM


                    
                    
                    map(nonce:sharedSecret:config:with:using:)

Maps the nonce to a random generator using the specified algorithm-specific mapping function and key agreement algorithm.

Throws

An error if mapping is not yet supported or if mapping fails.

Important

The returned reference must be freed by the caller after use. The pointer will reference a EVP_KEY structure (so use EVP_PKEY_free then).

Declaration

Swift

internal static func map(
    nonce: OpaquePointer,
    sharedSecret: OpaquePointer,
    config: OpaquePointer,
    with mapping: PACEMapping,
    using algorithm: KeyAgreementAlgorithm
) throws -> OpaquePointer

Parameters

`nonce`	The decrypted nonce from the IC.
`sharedSecret`	The shared secret/key computed with a `KeyAgreementAlgorithm` for mapping.
`config`	The current structure containing Key Agreement Algorithm data.
`mapping`	The mapping function to use.
`algorithm`	The `KeyAgreementAlgorithm` to use.

Return Value

A reference to the new mapped parameters data structure for use in subsequent Key Agreement Algorithm operations.


                    
                    
                    map(nonce:sharedSecret:config:using:)

Maps the nonce to a random generator using the specified algorithm-specific mapping function and key agreement algorithm.

Throws

An error if mapping is not yet supported or if mapping fails.

Important

The returned reference must be freed by the caller after use. The pointer will reference a EVP_KEY structure (so use EVP_PKEY_free then).

Declaration

Swift

internal func map(
    nonce: OpaquePointer,
    sharedSecret: OpaquePointer,
    config: OpaquePointer,
    using algorithm: KeyAgreementAlgorithm
) throws -> OpaquePointer

Parameters

`nonce`	The decrypted nonce from the IC.
`sharedSecret`	The shared secret/key computed with a `KeyAgreementAlgorithm` for mapping.
`config`	The current structure containing Key Agreement Algorithm data.
`algorithm`	The `KeyAgreementAlgorithm` to use.

Return Value

A reference to the new mapped parameters data structure for use in subsequent Key Agreement Algorithm operations.