Pki.PfsAuthHostCert

This command authenticates the host's certificate chain to the reader. If the certificate chain is longer than one certificate, this command has to be called multiple times with the IsEndCert flag of the EncryptedPayload parameter set to 0, until the last certificate has been reached in which case it must be set to 1.

The certificates must comply with the following limitations:

Certificates have to be X.509 v3 certificates.
As signing algorithms, only ECC P-256 and SHA256 are allowed.
The only allowed extensions are basicConstraints (indicating the certificate is a CA certificate) and the (optional) Baltech proprietary certificate acMask using the ASN.1 object identifier (OID) 1.3.6.1.4.1.44885.1.

The 32-bit acMask extension makes it possible to further restrict the allowed operations by the reader in the Security Level corresponding to the certificate since it will be combined with the reader's internal 32-bit Access Condition Mask, using a logical AND operator.

If this command is called multiple times (since the certificate chain contains multiple entries), it is required that the SecLevel and SessionTimeout field always have the same value.

If the format of HostCert is invalid or if the signature verification fails, the ERR_CERT status code is returned.

This command needs a long timeout, since the ECC operations may take up to 15 seconds.

Properties

Command code: 0x0902
Command timeout: 16000 ms
Possible status codes: General status codes, Pki.ErrCert, Pki.ErrSeclevelUnsupported

Parameters (request frame)

Name	Type/Size	Description
Length of EncryptedPayload	Integer (16 bits)	Length of EncryptedPayload in bytes
EncryptedPayload	Raw data	This parameter specifies the host certificate. The data is encrypted via AES-128 with Cipher Block Chaining (CBC) using the key and initial vector (IV) generated by the Pki.PfsGenKey command. The certificate is accompanied by some additional data fields. Before encryption, this parameter is split up into the following fields: SecLevel (1 Byte): The Security Level (1-3) which has to be authenticated. SessionTimeout (4 Bytes): Specifies how long the generated session key shall be valid after running this command. If this value is between 1 and 0xffff159f (higher values must not be used!) it specifies the validity time in milliseconds. Internally the reader will add one additional minute, to ensure that the host has enough time to setup a new session. If this value is set to 0, no timeout will be set and the session key will be valid until the reader is restarted or until the Pki.PfsGenKey command is called again. IsEndCert (1 Byte): Has to be set to 1 if the current certificate is the last certificate in the host's certificate chain. Has to be set to 0 if more certificates are following (i.e. if Pki.PfsAuthHostCert must be called again for another certificate). HostCertLen (2 Bytes): Length of the host certificate in Bytes. HostCert (n Bytes): An X.509 host certificate encoded in ASN.1 DER format. Several Bytes of padding zeros to ensure that the total length of EncryptedPayload is a multiple of 16.

Name

Type/Size

Description

Length of EncryptedPayload

Integer (16 bits)

Length of EncryptedPayload in bytes

EncryptedPayload

Raw data

This parameter specifies the host certificate. The data is encrypted via AES-128 with Cipher Block Chaining (CBC) using the key and initial vector (IV) generated by the Pki.PfsGenKey command.

The certificate is accompanied by some additional data fields. Before encryption, this parameter is split up into the following fields:

SecLevel (1 Byte): The Security Level (1-3) which has to be authenticated.
SessionTimeout (4 Bytes): Specifies how long the generated session key shall be valid after running this command. If this value is between 1 and 0xffff159f (higher values must not be used!) it specifies the validity time in milliseconds. Internally the reader will add one additional minute, to ensure that the host has enough time to setup a new session. If this value is set to 0, no timeout will be set and the session key will be valid until the reader is restarted or until the Pki.PfsGenKey command is called again.
IsEndCert (1 Byte): Has to be set to 1 if the current certificate is the last certificate in the host's certificate chain. Has to be set to 0 if more certificates are following (i.e. if Pki.PfsAuthHostCert must be called again for another certificate).
HostCertLen (2 Bytes): Length of the host certificate in Bytes.
HostCert (n Bytes): An X.509 host certificate encoded in ASN.1 DER format.
Several Bytes of padding zeros to ensure that the total length of EncryptedPayload is a multiple of 16.

Returned values (response frame)

None