From 74fbcd173422e0abbce865f0e2497aef6c4570d5 Mon Sep 17 00:00:00 2001 From: Tobias Schwerdtfeger Date: Mon, 5 Jan 2026 10:43:28 +0100 Subject: [PATCH 01/20] OPEN-94: Add APDU recording and replay tools with a new `apdu-tools` feature (#24) - Introduced a new APDU recording and replay mechanism, including `RecordingChannel` and `ReplayChannel` implementations. - Added tools for deterministic APDU key generation and PC/SC communication via `FixedKeyGenerator` and `PcscChannel`. - Enabled the `apdu-tools` feature flag with optional dependencies on `clap`, `serde`, `serde_json`, and `pcsc`. - Created `apdu_record.rs` binary for recording and exporting APDU transcripts in JSONL format. - Extended tests for end-to-end APDU recording and replay validation. --- .gitignore | 30 - core-modules/crypto-openssl-sys/src/ossl.rs | 2 +- core-modules/healthcard/Cargo.toml | 7 +- .../healthcard/src/bin/apdu_record.rs | 122 +++++ .../healthcard/src/exchange/apdu_tools.rs | 518 ++++++++++++++++++ core-modules/healthcard/src/exchange/mod.rs | 2 + 6 files changed, 649 insertions(+), 32 deletions(-) create mode 100644 core-modules/healthcard/src/bin/apdu_record.rs create mode 100644 core-modules/healthcard/src/exchange/apdu_tools.rs diff --git a/.gitignore b/.gitignore index 32b65859..80d0dea0 100644 --- a/.gitignore +++ b/.gitignore @@ -44,36 +44,6 @@ captures/ *.a *.lib -# .NET specific ignores -bin/ -obj/ -*.user -*.userosscache -*.suo -*.userprefs -[Bb]in/ -[Oo]bj/ -[Ll]og/ -[Ll]ogs/ -net*/ -net[0-9]*/ -net[0-9][0-9]*/ -[Dd]ebug/ -[Rr]elease/ -x64/ -x86/ -[Ww][Ii][Nn]32/ -[Aa][Rr][Mm]/ -[Aa][Rr][Mm]64/ - -# NuGet packages -*.nupkg -*.snupkg -**/[Pp]ackages/* -!**/[Pp]ackages/build/ -*.nuget.props -*.nuget.targets - # IDE specific files .idea/ *.iml diff --git a/core-modules/crypto-openssl-sys/src/ossl.rs b/core-modules/crypto-openssl-sys/src/ossl.rs index 7ea0b0bb..3ec86e40 100644 --- a/core-modules/crypto-openssl-sys/src/ossl.rs +++ b/core-modules/crypto-openssl-sys/src/ossl.rs @@ -1,4 +1,4 @@ -/* automatically generated by rust-bindgen 0.72.0 */ +/* automatically generated by rust-bindgen 0.72.1 */ // SPDX-FileCopyrightText: Copyright 2025 gematik GmbH // diff --git a/core-modules/healthcard/Cargo.toml b/core-modules/healthcard/Cargo.toml index 4f4631d2..ec868c80 100644 --- a/core-modules/healthcard/Cargo.toml +++ b/core-modules/healthcard/Cargo.toml @@ -26,11 +26,12 @@ edition = "2021" license = "Apache-2.0" [lib] -crate-type = ["cdylib"] +crate-type = ["cdylib", "rlib"] name = "healthcard" [features] default = ["uniffi"] +apdu-tools = ["dep:clap", "dep:pcsc", "dep:serde", "dep:serde_json"] [dependencies] lazy_static = "1.5.0" @@ -42,3 +43,7 @@ once_cell = "1.21.3" num-bigint = "0.4" zeroize = { version = "1.8.1", features = ["zeroize_derive"] } uniffi = { version = "0.30.0", optional = true } +clap = { version = "4.5.31", features = ["derive"], optional = true } +pcsc = { version = "2.8.0", optional = true } +serde = { version = "1.0.219", features = ["derive"], optional = true } +serde_json = { version = "1.0.140", optional = true } diff --git a/core-modules/healthcard/src/bin/apdu_record.rs b/core-modules/healthcard/src/bin/apdu_record.rs new file mode 100644 index 00000000..64057c5d --- /dev/null +++ b/core-modules/healthcard/src/bin/apdu_record.rs @@ -0,0 +1,122 @@ +// SPDX-FileCopyrightText: Copyright 2025 gematik GmbH +// +// SPDX-License-Identifier: Apache-2.0 +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// +// ******* +// +// For additional notes and disclaimer from gematik and in case of changes by gematik, +// find details in the "Readme" file. + +#[cfg(not(feature = "apdu-tools"))] +fn main() { + eprintln!("This binary requires --features apdu-tools"); +} + +#[cfg(feature = "apdu-tools")] + fn main() { + use clap::Parser; + use healthcard::exchange::apdu_tools::{FixedKeyGenerator, PcscChannel, RecordingChannel}; + use healthcard::exchange::secure_channel::{establish_secure_channel, establish_secure_channel_with, CardAccessNumber}; + + if let Err(err) = run() { + eprintln!("{err}"); + std::process::exit(1); + } + + #[derive(Debug, Parser)] + #[command(name = "apdu_record")] + #[command(about = "Record APDU input/output for PACE establish", long_about = None)] + struct Args { + /// PC/SC reader name + #[arg(long, required_unless_present = "list_readers")] + reader: Option, + /// Card Access Number (6 digits) + #[arg(long, required_unless_present = "list_readers")] + can: Option, + /// Output transcript path (JSONL) + #[arg(long, required_unless_present = "list_readers")] + out: Option, + /// Use short APDUs only + #[arg(long, conflicts_with = "extended")] + no_extended: bool, + /// Use extended-length APDUs + #[arg(long, conflicts_with = "no_extended")] + extended: bool, + /// List available PC/SC readers and exit + #[arg(long)] + list_readers: bool, + /// Fixed private key(s) for deterministic PACE (hex, big endian). Can be passed multiple times. + #[arg(long, value_name = "HEX", num_args(1..))] + fixed_key: Vec, + } + + fn run() -> Result<(), String> { + let args = Args::parse(); + + if args.list_readers { + list_pcsc_readers()?; + return Ok(()); + } + + let reader = args.reader.ok_or_else(|| "missing --reader".to_string())?; + let out = args.out.ok_or_else(|| "missing --out".to_string())?; + let can = args.can.ok_or_else(|| "missing --can".to_string())?; + let supports_extended_length = !args.no_extended; + + let channel = + PcscChannel::connect(&reader, supports_extended_length).map_err(|err| format!("pcsc connect failed: {err}"))?; + let mut recorder = RecordingChannel::new(channel); + let card_access_number = CardAccessNumber::new(&can).map_err(|err| err.to_string())?; + + let fixed_keys = if args.fixed_key.is_empty() { + None + } else { + Some( + args.fixed_key + .iter() + .map(|k| hex::decode(k).map_err(|err| format!("invalid --fixed-key hex: {err}"))) + .collect::, _>>()?, + ) + }; + + match fixed_keys { + Some(keys) => { + let generator = FixedKeyGenerator::new(keys).generator(); + establish_secure_channel_with(&mut recorder, &card_access_number, generator) + } + None => establish_secure_channel(&mut recorder, &card_access_number), + } + .map_err(|err| format!("PACE failed: {err}"))?; + + let transcript = recorder.into_transcript(); + transcript.write_jsonl(out).map_err(|err| format!("write transcript failed: {err}"))?; + Ok(()) + } + + fn list_pcsc_readers() -> Result<(), String> { + let ctx = + pcsc::Context::establish(pcsc::Scope::User).map_err(|err| format!("pcsc context establish failed: {err}"))?; + let readers = ctx.list_readers_owned().map_err(|err| format!("pcsc list readers failed: {err}"))?; + if readers.is_empty() { + println!("no pcsc readers found"); + return Ok(()); + } + println!("pcsc readers:"); + for reader in readers { + println!(" {}", reader.to_string_lossy()); + } + Ok(()) + } +} diff --git a/core-modules/healthcard/src/exchange/apdu_tools.rs b/core-modules/healthcard/src/exchange/apdu_tools.rs new file mode 100644 index 00000000..a244dfd7 --- /dev/null +++ b/core-modules/healthcard/src/exchange/apdu_tools.rs @@ -0,0 +1,518 @@ +// SPDX-FileCopyrightText: Copyright 2025 gematik GmbH +// +// SPDX-License-Identifier: Apache-2.0 +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// +// ******* +// +// For additional notes and disclaimer from gematik and in case of changes by gematik, +// find details in the "Readme" file. + +#![cfg(feature = "apdu-tools")] + +use crate::command::apdu::{CardCommandApdu, CardResponseApdu}; +use crate::exchange::channel::CardChannel; +use crate::exchange::ExchangeError; +use crypto::ec::ec_key::{EcCurve, EcPrivateKey, EcPublicKey}; +use crypto::error::CryptoError; +use num_bigint::{BigInt, Sign}; +use serde::{Deserialize, Serialize}; +use std::ffi::CString; +use std::fs::File; +use std::io::{BufRead, BufReader, Write}; +use std::path::Path; +use thiserror::Error; + +#[derive(Debug, Error)] +pub enum TranscriptError { + #[error("io error: {0}")] + Io(#[from] std::io::Error), + #[error("json error: {0}")] + Json(#[from] serde_json::Error), + #[error("hex error: {0}")] + Hex(#[from] hex::FromHexError), + #[error("missing or invalid transcript header")] + InvalidHeader, + #[error("unexpected transcript entry: {0}")] + UnexpectedEntry(&'static str), + #[error("replay out of entries")] + ReplayExhausted, +} + +#[derive(Clone, Debug, Serialize, Deserialize)] +struct TranscriptHeader { + version: u32, + supports_extended_length: bool, + label: Option, +} + +#[derive(Clone, Debug, Serialize, Deserialize)] +#[serde(tag = "type", rename_all = "snake_case")] +enum TranscriptEntry { + Header { + version: u32, + supports_extended_length: bool, + label: Option, + }, + Exchange { + tx: String, + rx: String, + label: Option, + }, + Error { + tx: String, + error: String, + label: Option, + }, +} + +#[derive(Clone, Debug)] +pub struct Transcript { + header: TranscriptHeader, + entries: Vec, +} + +impl Transcript { + pub fn new(supports_extended_length: bool) -> Self { + Self { + header: TranscriptHeader { + version: 1, + supports_extended_length, + label: None, + }, + entries: Vec::new(), + } + } + + pub fn supports_extended_length(&self) -> bool { + self.header.supports_extended_length + } + + pub fn set_label(&mut self, label: impl Into) { + self.header.label = Some(label.into()); + } + + pub fn push_exchange(&mut self, tx: &[u8], rx: &[u8], label: Option) { + self.entries.push(TranscriptEntry::Exchange { + tx: hex::encode_upper(tx), + rx: hex::encode_upper(rx), + label, + }); + } + + pub fn push_error(&mut self, tx: &[u8], error: impl Into, label: Option) { + self.entries.push(TranscriptEntry::Error { + tx: hex::encode_upper(tx), + error: error.into(), + label, + }); + } + + pub fn to_jsonl_string(&self) -> Result { + let mut out = String::new(); + let header = TranscriptEntry::Header { + version: self.header.version, + supports_extended_length: self.header.supports_extended_length, + label: self.header.label.clone(), + }; + out.push_str(&serde_json::to_string(&header)?); + out.push('\n'); + for entry in &self.entries { + out.push_str(&serde_json::to_string(entry)?); + out.push('\n'); + } + Ok(out) + } + + pub fn write_jsonl>(&self, path: P) -> Result<(), TranscriptError> { + let mut file = File::create(path)?; + file.write_all(self.to_jsonl_string()?.as_bytes())?; + Ok(()) + } + + pub fn from_jsonl_str(input: &str) -> Result { + let mut lines = input.lines(); + let header_line = lines.next().ok_or(TranscriptError::InvalidHeader)?; + let header_entry: TranscriptEntry = serde_json::from_str(header_line)?; + let header = match header_entry { + TranscriptEntry::Header { + version, + supports_extended_length, + label, + } => TranscriptHeader { + version, + supports_extended_length, + label, + }, + _ => return Err(TranscriptError::InvalidHeader), + }; + let mut entries = Vec::new(); + for line in lines { + if line.trim().is_empty() { + continue; + } + entries.push(serde_json::from_str::(line)?); + } + Ok(Self { header, entries }) + } + + pub fn from_jsonl>(path: P) -> Result { + let file = File::open(path)?; + let mut lines = BufReader::new(file).lines(); + let header_line = lines.next().ok_or(TranscriptError::InvalidHeader)??; + let header_entry: TranscriptEntry = serde_json::from_str(&header_line)?; + let header = match header_entry { + TranscriptEntry::Header { + version, + supports_extended_length, + label, + } => TranscriptHeader { + version, + supports_extended_length, + label, + }, + _ => return Err(TranscriptError::InvalidHeader), + }; + let mut entries = Vec::new(); + for line in lines { + let line = line?; + if line.trim().is_empty() { + continue; + } + entries.push(serde_json::from_str::(&line)?); + } + Ok(Self { header, entries }) + } +} + +pub struct RecordingChannel { + inner: C, + transcript: Transcript, +} + +impl RecordingChannel { + pub fn new(inner: C) -> Self { + let transcript = Transcript::new(inner.supports_extended_length()); + Self { inner, transcript } + } + + pub fn transcript(&self) -> &Transcript { + &self.transcript + } + + pub fn into_transcript(self) -> Transcript { + self.transcript + } +} + +impl CardChannel for RecordingChannel +where + C: CardChannel, + C::Error: std::fmt::Debug, +{ + type Error = C::Error; + + fn supports_extended_length(&self) -> bool { + self.inner.supports_extended_length() + } + + fn transmit(&mut self, command: &CardCommandApdu) -> Result { + let tx = command.to_bytes(); + match self.inner.transmit(command) { + Ok(response) => { + self.transcript.push_exchange(&tx, &response.to_bytes(), None); + Ok(response) + } + Err(err) => { + self.transcript.push_error(&tx, format!("{err:?}"), None); + Err(err) + } + } + } +} + +impl CardChannel for &mut RecordingChannel +where + C: CardChannel, + C::Error: std::fmt::Debug, +{ + type Error = C::Error; + + fn supports_extended_length(&self) -> bool { + self.inner.supports_extended_length() + } + + fn transmit(&mut self, command: &CardCommandApdu) -> Result { + let tx = command.to_bytes(); + match self.inner.transmit(command) { + Ok(response) => { + self.transcript.push_exchange(&tx, &response.to_bytes(), None); + Ok(response) + } + Err(err) => { + self.transcript.push_error(&tx, format!("{err:?}"), None); + Err(err) + } + } + } +} + +pub struct ReplayChannel { + transcript: Transcript, + cursor: usize, +} + +impl ReplayChannel { + pub fn from_transcript(transcript: Transcript) -> Self { + Self { transcript, cursor: 0 } + } + + pub fn from_jsonl>(path: P) -> Result { + Ok(Self::from_transcript(Transcript::from_jsonl(path)?)) + } + + fn next_entry(&mut self) -> Result { + if self.cursor >= self.transcript.entries.len() { + return Err(TranscriptError::ReplayExhausted); + } + let entry = self.transcript.entries[self.cursor].clone(); + self.cursor += 1; + Ok(entry) + } +} + +impl CardChannel for ReplayChannel { + type Error = ExchangeError; + + fn supports_extended_length(&self) -> bool { + self.transcript.supports_extended_length() + } + + fn transmit(&mut self, command: &CardCommandApdu) -> Result { + let entry = self + .next_entry() + .map_err(|err| ExchangeError::Transport { code: 0, message: err.to_string() })?; + match entry { + TranscriptEntry::Exchange { tx, rx, .. } => { + let expected_tx = hex::decode(tx) + .map_err(|err| ExchangeError::Transport { code: 0, message: format!("invalid tx hex: {err}") })?; + let actual_tx = command.to_bytes(); + if expected_tx != actual_tx { + return Err(ExchangeError::Transport { + code: 0, + message: "replay mismatch: outgoing APDU does not match transcript".to_string(), + }); + } + let rx_bytes = hex::decode(rx) + .map_err(|err| ExchangeError::Transport { code: 0, message: format!("invalid rx hex: {err}") })?; + Ok(CardResponseApdu::new(&rx_bytes)?) + } + TranscriptEntry::Error { tx, error, .. } => { + let expected_tx = hex::decode(tx) + .map_err(|err| ExchangeError::Transport { code: 0, message: format!("invalid tx hex: {err}") })?; + let actual_tx = command.to_bytes(); + if expected_tx != actual_tx { + return Err(ExchangeError::Transport { + code: 0, + message: "replay mismatch: outgoing APDU does not match transcript".to_string(), + }); + } + Err(ExchangeError::Transport { code: 0, message: format!("replayed error: {error}") }) + } + TranscriptEntry::Header { .. } => Err(ExchangeError::Transport { + code: 0, + message: TranscriptError::UnexpectedEntry("header").to_string(), + }), + } + } +} + +pub struct FixedKeyGenerator { + keys: Vec>, +} + +impl FixedKeyGenerator { + pub fn new(keys: Vec>) -> Self { + Self { keys } + } + + pub fn generator(mut self) -> impl FnMut(EcCurve) -> Result<(EcPublicKey, EcPrivateKey), CryptoError> { + move |curve| { + if self.keys.is_empty() { + return Err(CryptoError::InvalidKeyMaterial { context: "fixed key generator ran out of keys" }); + } + let bytes = self.keys.remove(0); + let key_hex = hex::encode_upper(&bytes); + let (public_key, private_key) = derive_keypair_from_scalar(curve.clone(), bytes)?; + eprintln!("FixedKeyGenerator used key for {curve:?}: {key_hex}"); + Ok((public_key, private_key)) + } + } +} + +fn derive_keypair_from_scalar(curve: EcCurve, private_bytes: Vec) -> Result<(EcPublicKey, EcPrivateKey), CryptoError> { + let private_key = EcPrivateKey::from_bytes(curve.clone(), private_bytes); + let scalar = BigInt::from_bytes_be(Sign::Plus, private_key.as_bytes()); + let public_point = curve.g().mul(&scalar)?; + let public_key = public_point.to_ec_public_key()?; + Ok((public_key, private_key)) +} + +pub struct PcscChannel { + card: pcsc::Card, + supports_extended_length: bool, + recv_buffer: Vec, +} + +impl PcscChannel { + pub fn connect(reader: &str, supports_extended_length: bool) -> Result { + let ctx = + pcsc::Context::establish(pcsc::Scope::User).map_err(|err| ExchangeError::Transport { + code: 0, + message: format!("pcsc context establish failed: {err}"), + })?; + let reader_cstr = CString::new(reader) + .map_err(|err| ExchangeError::Transport { code: 0, message: format!("invalid reader name: {err}") })?; + let card = ctx + .connect(&reader_cstr, pcsc::ShareMode::Shared, pcsc::Protocols::ANY) + .map_err(|err| ExchangeError::Transport { code: 0, message: format!("pcsc connect failed: {err}") })?; + Ok(Self { + card, + supports_extended_length, + recv_buffer: vec![0u8; 65538], + }) + } + + pub fn connect_first(supports_extended_length: bool) -> Result { + let ctx = + pcsc::Context::establish(pcsc::Scope::User).map_err(|err| ExchangeError::Transport { + code: 0, + message: format!("pcsc context establish failed: {err}"), + })?; + let mut readers = ctx + .list_readers_owned() + .map_err(|err| ExchangeError::Transport { code: 0, message: format!("pcsc list readers failed: {err}") })?; + let reader = readers + .pop() + .ok_or_else(|| ExchangeError::Transport { code: 0, message: "no pcsc readers found".to_string() })?; + let card = ctx + .connect(reader.as_c_str(), pcsc::ShareMode::Shared, pcsc::Protocols::ANY) + .map_err(|err| ExchangeError::Transport { code: 0, message: format!("pcsc connect failed: {err}") })?; + Ok(Self { + card, + supports_extended_length, + recv_buffer: vec![0u8; 65538], + }) + } +} + +impl CardChannel for PcscChannel { + type Error = ExchangeError; + + fn supports_extended_length(&self) -> bool { + self.supports_extended_length + } + + fn transmit(&mut self, command: &CardCommandApdu) -> Result { + let tx = command.to_bytes(); + let response = self.card.transmit(&tx, &mut self.recv_buffer).map_err(|err| ExchangeError::Transport { + code: 0, + message: format!("pcsc transmit failed: {err}"), + })?; + CardResponseApdu::new(response).map_err(ExchangeError::from) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::command::apdu::CardCommandApdu; + use crate::command::health_card_command::HealthCardCommand; + use crate::exchange::channel::CardChannelExt; + use crate::exchange::test_utils::MockSession; + + #[test] + fn record_and_replay_roundtrip() { + let mut recorder = RecordingChannel::new(MockSession::new(vec![vec![0x90, 0x00]])); + let command = CardCommandApdu::header_only(0x00, 0xA4, 0x04, 0x00).unwrap(); + let _ = recorder.transmit(&command).unwrap(); + let transcript = recorder.into_transcript(); + + let jsonl = transcript.to_jsonl_string().unwrap(); + let replay = Transcript::from_jsonl_str(&jsonl).unwrap(); + let mut channel = ReplayChannel::from_transcript(replay); + let response = channel.transmit(&command).unwrap(); + assert_eq!(response.to_bytes(), vec![0x90, 0x00]); + } + + #[test] + fn fixed_key_generator_returns_keys() { + let curve = EcCurve::BrainpoolP256r1; + let keys = vec![vec![0x01; 32], vec![0x02; 32]]; + let mut generator = FixedKeyGenerator::new(keys).generator(); + let (pub1, priv1) = generator(curve.clone()).unwrap(); + assert_eq!(priv1.as_bytes().len(), 32); + assert_eq!(pub1.as_bytes().len(), 65); + let (_pub2, priv2) = generator(curve).unwrap(); + assert_eq!(priv2.as_bytes().len(), 32); + } + + #[test] + fn pcsc_record_and_replay_select_mf() { + let reader = match std::env::var("HEALTHCARD_PCSC_READER") { + Ok(reader) => reader, + Err(_) => return, + }; + + let channel = PcscChannel::connect(&reader, true).expect("pcsc connect"); + let mut recorder = RecordingChannel::new(channel); + let response = recorder + .execute_command(&HealthCardCommand::select(false, false)) + .expect("select MF"); + let response_bytes = response.apdu.to_bytes(); + + let transcript = recorder.into_transcript(); + let mut replay = ReplayChannel::from_transcript(transcript); + let replay_response = replay + .execute_command(&HealthCardCommand::select(false, false)) + .expect("replay select MF"); + assert_eq!(replay_response.apdu.to_bytes(), response_bytes); + } + + #[test] + fn list_pcsc_readers() { + let ctx = match pcsc::Context::establish(pcsc::Scope::User) { + Ok(ctx) => ctx, + Err(err) => { + println!("pcsc context establish failed: {err}"); + return; + } + }; + let readers = match ctx.list_readers_owned() { + Ok(readers) => readers, + Err(err) => { + println!("pcsc list readers failed: {err}"); + return; + } + }; + if readers.is_empty() { + println!("no pcsc readers found"); + return; + } + println!("pcsc readers:"); + for reader in readers { + println!(" {reader}"); + } + } +} diff --git a/core-modules/healthcard/src/exchange/mod.rs b/core-modules/healthcard/src/exchange/mod.rs index 1e596a81..26cf9b73 100644 --- a/core-modules/healthcard/src/exchange/mod.rs +++ b/core-modules/healthcard/src/exchange/mod.rs @@ -30,6 +30,8 @@ pub mod read_vsd; pub mod sign_challenge; #[cfg(test)] pub(crate) mod test_utils; +#[cfg(feature = "apdu-tools")] +pub mod apdu_tools; pub mod secure_channel; pub use certificate::retrieve_certificate; From 878c6526891a93ba7d5355772827f4bda7ee2d17 Mon Sep 17 00:00:00 2001 From: Tobias Schwerdtfeger Date: Mon, 5 Jan 2026 11:01:03 +0100 Subject: [PATCH 02/20] OPEN-94: Add APDU recording and replay tools with a new `apdu-tools` feature (#24) - Introduced a new APDU recording and replay mechanism, including `RecordingChannel` and `ReplayChannel` implementations. - Added tools for deterministic APDU key generation and PC/SC communication via `FixedKeyGenerator` and `PcscChannel`. - Enabled the `apdu-tools` feature flag with optional dependencies on `clap`, `serde`, `serde_json`, and `pcsc`. - Created `apdu_record.rs` binary for recording and exporting APDU transcripts in JSONL format. - Extended tests for end-to-end APDU recording and replay validation. --- .../healthcard/src/bin/apdu_record.rs | 72 ++++++++----------- .../healthcard/src/exchange/apdu_tools.rs | 45 ++++++++++++ 2 files changed, 76 insertions(+), 41 deletions(-) diff --git a/core-modules/healthcard/src/bin/apdu_record.rs b/core-modules/healthcard/src/bin/apdu_record.rs index 64057c5d..2cc27dcb 100644 --- a/core-modules/healthcard/src/bin/apdu_record.rs +++ b/core-modules/healthcard/src/bin/apdu_record.rs @@ -27,8 +27,9 @@ fn main() { #[cfg(feature = "apdu-tools")] fn main() { use clap::Parser; - use healthcard::exchange::apdu_tools::{FixedKeyGenerator, PcscChannel, RecordingChannel}; - use healthcard::exchange::secure_channel::{establish_secure_channel, establish_secure_channel_with, CardAccessNumber}; + use crypto::ec::ec_key::{EcCurve, EcKeyPairSpec}; + use healthcard::exchange::apdu_tools::{PcscChannel, RecordingChannel}; + use healthcard::exchange::secure_channel::{establish_secure_channel_with, CardAccessNumber}; if let Err(err) = run() { eprintln!("{err}"); @@ -55,50 +56,39 @@ fn main() { #[arg(long, conflicts_with = "no_extended")] extended: bool, /// List available PC/SC readers and exit - #[arg(long)] - list_readers: bool, - /// Fixed private key(s) for deterministic PACE (hex, big endian). Can be passed multiple times. - #[arg(long, value_name = "HEX", num_args(1..))] - fixed_key: Vec, - } - - fn run() -> Result<(), String> { - let args = Args::parse(); - - if args.list_readers { - list_pcsc_readers()?; - return Ok(()); - } + #[arg(long)] + list_readers: bool, + } + + fn run() -> Result<(), String> { + let args = Args::parse(); + + if args.list_readers { + list_pcsc_readers()?; + return Ok(()); + } - let reader = args.reader.ok_or_else(|| "missing --reader".to_string())?; - let out = args.out.ok_or_else(|| "missing --out".to_string())?; - let can = args.can.ok_or_else(|| "missing --can".to_string())?; - let supports_extended_length = !args.no_extended; + let reader = args.reader.ok_or_else(|| "missing --reader".to_string())?; + let out = args.out.ok_or_else(|| "missing --out".to_string())?; + let can = args.can.ok_or_else(|| "missing --can".to_string())?; + let supports_extended_length = !args.no_extended; - let channel = - PcscChannel::connect(&reader, supports_extended_length).map_err(|err| format!("pcsc connect failed: {err}"))?; - let mut recorder = RecordingChannel::new(channel); - let card_access_number = CardAccessNumber::new(&can).map_err(|err| err.to_string())?; + let channel = + PcscChannel::connect(&reader, supports_extended_length).map_err(|err| format!("pcsc connect failed: {err}"))?; + let mut recorder = RecordingChannel::new(channel); + let card_access_number = CardAccessNumber::new(&can).map_err(|err| err.to_string())?; - let fixed_keys = if args.fixed_key.is_empty() { - None - } else { - Some( - args.fixed_key - .iter() - .map(|k| hex::decode(k).map_err(|err| format!("invalid --fixed-key hex: {err}"))) - .collect::, _>>()?, - ) - }; + let mut generated_keys = Vec::new(); + establish_secure_channel_with(&mut recorder, &card_access_number, |curve: EcCurve| { + let (public_key, private_key) = EcKeyPairSpec { curve: curve.clone() }.generate_keypair()?; + generated_keys.push(hex::encode_upper(private_key.as_bytes())); + Ok((public_key, private_key)) + }) + .map_err(|err| format!("PACE failed: {err}"))?; - match fixed_keys { - Some(keys) => { - let generator = FixedKeyGenerator::new(keys).generator(); - establish_secure_channel_with(&mut recorder, &card_access_number, generator) - } - None => establish_secure_channel(&mut recorder, &card_access_number), + if !generated_keys.is_empty() { + recorder.set_keys(generated_keys); } - .map_err(|err| format!("PACE failed: {err}"))?; let transcript = recorder.into_transcript(); transcript.write_jsonl(out).map_err(|err| format!("write transcript failed: {err}"))?; diff --git a/core-modules/healthcard/src/exchange/apdu_tools.rs b/core-modules/healthcard/src/exchange/apdu_tools.rs index a244dfd7..a46e9532 100644 --- a/core-modules/healthcard/src/exchange/apdu_tools.rs +++ b/core-modules/healthcard/src/exchange/apdu_tools.rs @@ -55,6 +55,7 @@ struct TranscriptHeader { version: u32, supports_extended_length: bool, label: Option, + keys: Option>, } #[derive(Clone, Debug, Serialize, Deserialize)] @@ -64,6 +65,7 @@ enum TranscriptEntry { version: u32, supports_extended_length: bool, label: Option, + keys: Option>, }, Exchange { tx: String, @@ -90,6 +92,7 @@ impl Transcript { version: 1, supports_extended_length, label: None, + keys: None, }, entries: Vec::new(), } @@ -103,6 +106,29 @@ impl Transcript { self.header.label = Some(label.into()); } + pub fn set_keys(&mut self, keys: Vec) { + self.header.keys = Some(keys); + } + + pub fn keys(&self) -> Option<&[String]> { + self.header.keys.as_deref() + } + + pub fn fixed_key_generator( + &self, + ) -> Result Result<(EcPublicKey, EcPrivateKey), CryptoError>>, TranscriptError> { + match &self.header.keys { + Some(keys) => { + let decoded = keys + .iter() + .map(|k| Ok(hex::decode(k)?)) + .collect::, hex::FromHexError>>()?; + Ok(Some(FixedKeyGenerator::new(decoded).generator())) + } + None => Ok(None), + } + } + pub fn push_exchange(&mut self, tx: &[u8], rx: &[u8], label: Option) { self.entries.push(TranscriptEntry::Exchange { tx: hex::encode_upper(tx), @@ -125,6 +151,7 @@ impl Transcript { version: self.header.version, supports_extended_length: self.header.supports_extended_length, label: self.header.label.clone(), + keys: self.header.keys.clone(), }; out.push_str(&serde_json::to_string(&header)?); out.push('\n'); @@ -150,10 +177,12 @@ impl Transcript { version, supports_extended_length, label, + keys, } => TranscriptHeader { version, supports_extended_length, label, + keys, }, _ => return Err(TranscriptError::InvalidHeader), }; @@ -177,10 +206,12 @@ impl Transcript { version, supports_extended_length, label, + keys, } => TranscriptHeader { version, supports_extended_length, label, + keys, }, _ => return Err(TranscriptError::InvalidHeader), }; @@ -207,6 +238,14 @@ impl RecordingChannel { Self { inner, transcript } } + pub fn set_label(&mut self, label: impl Into) { + self.transcript.set_label(label); + } + + pub fn set_keys(&mut self, keys: Vec) { + self.transcript.set_keys(keys); + } + pub fn transcript(&self) -> &Transcript { &self.transcript } @@ -278,6 +317,12 @@ impl ReplayChannel { Self { transcript, cursor: 0 } } + pub fn fixed_key_generator( + &self, + ) -> Result Result<(EcPublicKey, EcPrivateKey), CryptoError>>, TranscriptError> { + self.transcript.fixed_key_generator() + } + pub fn from_jsonl>(path: P) -> Result { Ok(Self::from_transcript(Transcript::from_jsonl(path)?)) } From 3741c9ea54bf77c35ff0bbadbc23964f0b25c364 Mon Sep 17 00:00:00 2001 From: Tobias Schwerdtfeger Date: Tue, 6 Jan 2026 13:30:27 +0100 Subject: [PATCH 03/20] OPEN-94: Add support for CAN field in APDU transcript handling - Introduced a new `can` field in `Transcript` to manage Card Access Numbers. - Added methods to set and retrieve the `can` field in `Transcript` and `TranscriptHeader`. - Updated `apdu_record.rs` to support CAN handling during recording and playback. - Enhanced test coverage including JSONL replay with CAN support. --- core-modules/healthcard/Cargo.toml | 5 +++ .../healthcard/src/bin/apdu_record.rs | 17 +++---- .../healthcard/src/exchange/apdu_tools.rs | 45 +++++++++++++++++-- core-modules/healthcard/src/exchange/mod.rs | 2 +- .../healthcard/src/exchange/secure_channel.rs | 27 +++++++++++ 5 files changed, 84 insertions(+), 12 deletions(-) diff --git a/core-modules/healthcard/Cargo.toml b/core-modules/healthcard/Cargo.toml index ec868c80..85a716c7 100644 --- a/core-modules/healthcard/Cargo.toml +++ b/core-modules/healthcard/Cargo.toml @@ -47,3 +47,8 @@ clap = { version = "4.5.31", features = ["derive"], optional = true } pcsc = { version = "2.8.0", optional = true } serde = { version = "1.0.219", features = ["derive"], optional = true } serde_json = { version = "1.0.140", optional = true } + +[dev-dependencies] +pcsc = "2.8.0" +serde = { version = "1.0.219", features = ["derive"] } +serde_json = "1.0.140" diff --git a/core-modules/healthcard/src/bin/apdu_record.rs b/core-modules/healthcard/src/bin/apdu_record.rs index 2cc27dcb..116a9b34 100644 --- a/core-modules/healthcard/src/bin/apdu_record.rs +++ b/core-modules/healthcard/src/bin/apdu_record.rs @@ -73,15 +73,16 @@ fn main() { let can = args.can.ok_or_else(|| "missing --can".to_string())?; let supports_extended_length = !args.no_extended; - let channel = - PcscChannel::connect(&reader, supports_extended_length).map_err(|err| format!("pcsc connect failed: {err}"))?; - let mut recorder = RecordingChannel::new(channel); - let card_access_number = CardAccessNumber::new(&can).map_err(|err| err.to_string())?; + let channel = + PcscChannel::connect(&reader, supports_extended_length).map_err(|err| format!("pcsc connect failed: {err}"))?; + let mut recorder = RecordingChannel::new(channel); + let card_access_number = CardAccessNumber::new(&can).map_err(|err| err.to_string())?; + recorder.set_can(can.clone()); - let mut generated_keys = Vec::new(); - establish_secure_channel_with(&mut recorder, &card_access_number, |curve: EcCurve| { - let (public_key, private_key) = EcKeyPairSpec { curve: curve.clone() }.generate_keypair()?; - generated_keys.push(hex::encode_upper(private_key.as_bytes())); + let mut generated_keys = Vec::new(); + establish_secure_channel_with(&mut recorder, &card_access_number, |curve: EcCurve| { + let (public_key, private_key) = EcKeyPairSpec { curve: curve.clone() }.generate_keypair()?; + generated_keys.push(hex::encode_upper(private_key.as_bytes())); Ok((public_key, private_key)) }) .map_err(|err| format!("PACE failed: {err}"))?; diff --git a/core-modules/healthcard/src/exchange/apdu_tools.rs b/core-modules/healthcard/src/exchange/apdu_tools.rs index a46e9532..769bd85f 100644 --- a/core-modules/healthcard/src/exchange/apdu_tools.rs +++ b/core-modules/healthcard/src/exchange/apdu_tools.rs @@ -19,8 +19,6 @@ // For additional notes and disclaimer from gematik and in case of changes by gematik, // find details in the "Readme" file. -#![cfg(feature = "apdu-tools")] - use crate::command::apdu::{CardCommandApdu, CardResponseApdu}; use crate::exchange::channel::CardChannel; use crate::exchange::ExchangeError; @@ -56,6 +54,7 @@ struct TranscriptHeader { supports_extended_length: bool, label: Option, keys: Option>, + can: Option, } #[derive(Clone, Debug, Serialize, Deserialize)] @@ -66,6 +65,7 @@ enum TranscriptEntry { supports_extended_length: bool, label: Option, keys: Option>, + can: Option, }, Exchange { tx: String, @@ -93,6 +93,7 @@ impl Transcript { supports_extended_length, label: None, keys: None, + can: None, }, entries: Vec::new(), } @@ -110,10 +111,18 @@ impl Transcript { self.header.keys = Some(keys); } + pub fn set_can(&mut self, can: impl Into) { + self.header.can = Some(can.into()); + } + pub fn keys(&self) -> Option<&[String]> { self.header.keys.as_deref() } + pub fn can(&self) -> Option<&str> { + self.header.can.as_deref() + } + pub fn fixed_key_generator( &self, ) -> Result Result<(EcPublicKey, EcPrivateKey), CryptoError>>, TranscriptError> { @@ -152,6 +161,7 @@ impl Transcript { supports_extended_length: self.header.supports_extended_length, label: self.header.label.clone(), keys: self.header.keys.clone(), + can: self.header.can.clone(), }; out.push_str(&serde_json::to_string(&header)?); out.push('\n'); @@ -178,11 +188,13 @@ impl Transcript { supports_extended_length, label, keys, + can, } => TranscriptHeader { version, supports_extended_length, label, keys, + can, }, _ => return Err(TranscriptError::InvalidHeader), }; @@ -207,11 +219,13 @@ impl Transcript { supports_extended_length, label, keys, + can, } => TranscriptHeader { version, supports_extended_length, label, keys, + can, }, _ => return Err(TranscriptError::InvalidHeader), }; @@ -246,6 +260,10 @@ impl RecordingChannel { self.transcript.set_keys(keys); } + pub fn set_can(&mut self, can: impl Into) { + self.transcript.set_can(can); + } + pub fn transcript(&self) -> &Transcript { &self.transcript } @@ -484,6 +502,7 @@ mod tests { use super::*; use crate::command::apdu::CardCommandApdu; use crate::command::health_card_command::HealthCardCommand; + use crate::command::select_command::SelectCommand; use crate::exchange::channel::CardChannelExt; use crate::exchange::test_utils::MockSession; @@ -513,6 +532,26 @@ mod tests { assert_eq!(priv2.as_bytes().len(), 32); } + #[test] + fn transcript_keys_roundtrip_and_generator() { + let mut transcript = Transcript::new(true); + let key1 = vec![0xAA; 32]; + let key2 = vec![0xBB; 32]; + let keys_hex = vec![hex::encode_upper(&key1), hex::encode_upper(&key2)]; + transcript.set_keys(keys_hex.clone()); + + let jsonl = transcript.to_jsonl_string().unwrap(); + let parsed = Transcript::from_jsonl_str(&jsonl).unwrap(); + assert_eq!(parsed.keys().unwrap(), keys_hex.as_slice()); + + let mut generator = parsed.fixed_key_generator().unwrap().unwrap(); + let curve = EcCurve::BrainpoolP256r1; + let (_pub1, priv1) = generator(curve.clone()).unwrap(); + assert_eq!(priv1.as_bytes(), key1.as_slice()); + let (_pub2, priv2) = generator(curve).unwrap(); + assert_eq!(priv2.as_bytes(), key2.as_slice()); + } + #[test] fn pcsc_record_and_replay_select_mf() { let reader = match std::env::var("HEALTHCARD_PCSC_READER") { @@ -557,7 +596,7 @@ mod tests { } println!("pcsc readers:"); for reader in readers { - println!(" {reader}"); + println!(" {}", reader.to_string_lossy()); } } } diff --git a/core-modules/healthcard/src/exchange/mod.rs b/core-modules/healthcard/src/exchange/mod.rs index 26cf9b73..cb27519a 100644 --- a/core-modules/healthcard/src/exchange/mod.rs +++ b/core-modules/healthcard/src/exchange/mod.rs @@ -30,7 +30,7 @@ pub mod read_vsd; pub mod sign_challenge; #[cfg(test)] pub(crate) mod test_utils; -#[cfg(feature = "apdu-tools")] +#[cfg(any(feature = "apdu-tools", test))] pub mod apdu_tools; pub mod secure_channel; diff --git a/core-modules/healthcard/src/exchange/secure_channel.rs b/core-modules/healthcard/src/exchange/secure_channel.rs index ab1a5669..8ee8cb01 100644 --- a/core-modules/healthcard/src/exchange/secure_channel.rs +++ b/core-modules/healthcard/src/exchange/secure_channel.rs @@ -656,9 +656,22 @@ struct ResponseObjects { mod tests { use super::*; use crate::command::apdu::{CardCommandApdu, CardResponseApdu}; + use crate::exchange::apdu_tools::{ReplayChannel, Transcript}; use crate::exchange::channel::CardChannel; use hex::encode; + const JSONL_REPLAY_ESTABLISH_SECURE_CHANNEL: &str = r#"{"type":"header","version":1,"supports_extended_length":true,"label":null,"keys":["99472E124DE0FC6E4D80C797FAB3E512CD70351F521DE5556AD4FB7491911BF7","7C33C0F7883452F90759A14EECEBEDA9890DD20304680372FE85EF7E67A80B45"],"can":"123123"} +{"type":"exchange","tx":"00A4040400","rx":"6282015A82017883023F008A01058407D2760001448000A181FA9103010501AB81908F0480FA0000A03CAF32A02BB4199501307F4C1306082A8214004C048119530700800000000000B406950130830114B406950130830118B803950110A40695010883011F8F04808400008C02808290008F0410EA00008F0400EA0000AF32A02BB406950130830113B406950130830118B4199501307F4C1306082A8214004C048119530700800000000000B8039501109103020501AB5B8F0410EA00008F0400EA0000AF32A02BB406950130830113B406950130830118B4199501307F4C1306082A8214004C048119530700800000000000B8039501108F0480840000AF9000","label":null} +{"type":"exchange","tx":"00B09100000000","rx":"EF2BC003020000C103040502C210545359534954434F5345433230020400C403010000C503020000C7030100009000","label":null} +{"type":"exchange","tx":"00A4020C02011C","rx":"9000","label":null} +{"type":"exchange","tx":"00B00000000000","rx":"31143012060A04007F0007020204020202010202010D9000","label":null} +{"type":"exchange","tx":"0022C1A40F800A04007F00070202040202830102","rx":"9000","label":null} +{"type":"exchange","tx":"108600000000027C000000","rx":"7C12801096AB30ECC394284891D366125E04A6079000","label":null} +{"type":"exchange","tx":"108600000000457C438141049C389D3E545C2C82F2FA3D335E84CBED509F62213EDF95474678B2405AE19DAE54153F22D499E217C5F43F2A0451C95E97D5B2EDB32A374A809F1B95B132DFCE0000","rx":"7C438241049E44D2012F111DC87665453DCAD5875799FB3830F85D6C1AA89B8BBB04B292065C134EAED66BB7AE28B6BFE96C3544232CBF3397658BEF85001AB314B8234E529000","label":null} +{"type":"exchange","tx":"108600000000457C43834104231F205E8432E04687CBEF74159185449B89C16EED6ADE0DC65CC4839B038BBE7C09B3350AEE71A0AC31C0EAFDAA1C1714097DD1949328420E5449FC4493C2400000","rx":"7C43844104555A0E943EF0F39B5DE412E618AE59790069973C56C7009204B19701A97714F62363721EA76BDC33E77F08EB7A1D0439B124754AAAA4C20057CEE14849F8B3CF9000","label":null} +{"type":"exchange","tx":"0086000000000C7C0A850810ED17B40867E53B0000","rx":"7C0A860825AD01DE59F88A7B9000","label":null} +"#; + #[test] fn create_auth_token_matches_reference() { let curve = EcCurve::BrainpoolP256r1; @@ -710,6 +723,20 @@ mod tests { hex::encode_upper(apdu.to_bytes()) } + #[test] + fn integration_jsonl_replay_establish_secure_channel() { + let transcript = Transcript::from_jsonl_str(JSONL_REPLAY_ESTABLISH_SECURE_CHANNEL).expect("load transcript"); + let can = transcript.can().expect("CAN in transcript").to_string(); + let mut generator = transcript + .fixed_key_generator() + .expect("keys parse") + .expect("fixed key generator"); + let replay = ReplayChannel::from_transcript(transcript); + let card_access_number = CardAccessNumber::new(&can).expect("can format"); + establish_secure_channel_with(replay, &card_access_number, &mut generator) + .expect("replay establish secure channel"); + } + #[test] fn encrypt_case1_header_only() { let command = CardCommandApdu::new_without_data(0x01, 0x02, 0x03, 0x04, None).unwrap(); From d14890f0902197cb43fc5ae3e179ce812ba6237f Mon Sep 17 00:00:00 2001 From: Tobias Schwerdtfeger Date: Tue, 6 Jan 2026 13:30:49 +0100 Subject: [PATCH 04/20] OPEN-94: Add support for CAN field in APDU transcript handling - Introduced a new `can` field in `Transcript` to manage Card Access Numbers. - Added methods to set and retrieve the `can` field in `Transcript` and `TranscriptHeader`. - Updated `apdu_record.rs` to support CAN handling during recording and playback. - Enhanced test coverage including JSONL replay with CAN support. --- .../healthcard/src/bin/apdu_record.rs | 62 +++++----- .../healthcard/src/exchange/apdu_tools.rs | 114 +++++------------- core-modules/healthcard/src/exchange/mod.rs | 10 +- .../healthcard/src/exchange/secure_channel.rs | 5 +- 4 files changed, 69 insertions(+), 122 deletions(-) diff --git a/core-modules/healthcard/src/bin/apdu_record.rs b/core-modules/healthcard/src/bin/apdu_record.rs index 116a9b34..1cd331e5 100644 --- a/core-modules/healthcard/src/bin/apdu_record.rs +++ b/core-modules/healthcard/src/bin/apdu_record.rs @@ -25,16 +25,16 @@ fn main() { } #[cfg(feature = "apdu-tools")] - fn main() { - use clap::Parser; - use crypto::ec::ec_key::{EcCurve, EcKeyPairSpec}; - use healthcard::exchange::apdu_tools::{PcscChannel, RecordingChannel}; - use healthcard::exchange::secure_channel::{establish_secure_channel_with, CardAccessNumber}; +fn main() { + use clap::Parser; + use crypto::ec::ec_key::{EcCurve, EcKeyPairSpec}; + use healthcard::exchange::apdu_tools::{PcscChannel, RecordingChannel}; + use healthcard::exchange::secure_channel::{establish_secure_channel_with, CardAccessNumber}; - if let Err(err) = run() { - eprintln!("{err}"); - std::process::exit(1); - } + if let Err(err) = run() { + eprintln!("{err}"); + std::process::exit(1); + } #[derive(Debug, Parser)] #[command(name = "apdu_record")] @@ -56,25 +56,25 @@ fn main() { #[arg(long, conflicts_with = "no_extended")] extended: bool, /// List available PC/SC readers and exit - #[arg(long)] - list_readers: bool, - } - - fn run() -> Result<(), String> { - let args = Args::parse(); - - if args.list_readers { - list_pcsc_readers()?; - return Ok(()); - } + #[arg(long)] + list_readers: bool, + } + + fn run() -> Result<(), String> { + let args = Args::parse(); + + if args.list_readers { + list_pcsc_readers()?; + return Ok(()); + } - let reader = args.reader.ok_or_else(|| "missing --reader".to_string())?; - let out = args.out.ok_or_else(|| "missing --out".to_string())?; - let can = args.can.ok_or_else(|| "missing --can".to_string())?; - let supports_extended_length = !args.no_extended; + let reader = args.reader.ok_or_else(|| "missing --reader".to_string())?; + let out = args.out.ok_or_else(|| "missing --out".to_string())?; + let can = args.can.ok_or_else(|| "missing --can".to_string())?; + let supports_extended_length = !args.no_extended; - let channel = - PcscChannel::connect(&reader, supports_extended_length).map_err(|err| format!("pcsc connect failed: {err}"))?; + let channel = PcscChannel::connect(&reader, supports_extended_length) + .map_err(|err| format!("pcsc connect failed: {err}"))?; let mut recorder = RecordingChannel::new(channel); let card_access_number = CardAccessNumber::new(&can).map_err(|err| err.to_string())?; recorder.set_can(can.clone()); @@ -83,9 +83,9 @@ fn main() { establish_secure_channel_with(&mut recorder, &card_access_number, |curve: EcCurve| { let (public_key, private_key) = EcKeyPairSpec { curve: curve.clone() }.generate_keypair()?; generated_keys.push(hex::encode_upper(private_key.as_bytes())); - Ok((public_key, private_key)) - }) - .map_err(|err| format!("PACE failed: {err}"))?; + Ok((public_key, private_key)) + }) + .map_err(|err| format!("PACE failed: {err}"))?; if !generated_keys.is_empty() { recorder.set_keys(generated_keys); @@ -97,8 +97,8 @@ fn main() { } fn list_pcsc_readers() -> Result<(), String> { - let ctx = - pcsc::Context::establish(pcsc::Scope::User).map_err(|err| format!("pcsc context establish failed: {err}"))?; + let ctx = pcsc::Context::establish(pcsc::Scope::User) + .map_err(|err| format!("pcsc context establish failed: {err}"))?; let readers = ctx.list_readers_owned().map_err(|err| format!("pcsc list readers failed: {err}"))?; if readers.is_empty() { println!("no pcsc readers found"); diff --git a/core-modules/healthcard/src/exchange/apdu_tools.rs b/core-modules/healthcard/src/exchange/apdu_tools.rs index 769bd85f..ecf43157 100644 --- a/core-modules/healthcard/src/exchange/apdu_tools.rs +++ b/core-modules/healthcard/src/exchange/apdu_tools.rs @@ -88,13 +88,7 @@ pub struct Transcript { impl Transcript { pub fn new(supports_extended_length: bool) -> Self { Self { - header: TranscriptHeader { - version: 1, - supports_extended_length, - label: None, - keys: None, - can: None, - }, + header: TranscriptHeader { version: 1, supports_extended_length, label: None, keys: None, can: None }, entries: Vec::new(), } } @@ -128,10 +122,8 @@ impl Transcript { ) -> Result Result<(EcPublicKey, EcPrivateKey), CryptoError>>, TranscriptError> { match &self.header.keys { Some(keys) => { - let decoded = keys - .iter() - .map(|k| Ok(hex::decode(k)?)) - .collect::, hex::FromHexError>>()?; + let decoded = + keys.iter().map(|k| Ok(hex::decode(k)?)).collect::, hex::FromHexError>>()?; Ok(Some(FixedKeyGenerator::new(decoded).generator())) } None => Ok(None), @@ -139,19 +131,11 @@ impl Transcript { } pub fn push_exchange(&mut self, tx: &[u8], rx: &[u8], label: Option) { - self.entries.push(TranscriptEntry::Exchange { - tx: hex::encode_upper(tx), - rx: hex::encode_upper(rx), - label, - }); + self.entries.push(TranscriptEntry::Exchange { tx: hex::encode_upper(tx), rx: hex::encode_upper(rx), label }); } pub fn push_error(&mut self, tx: &[u8], error: impl Into, label: Option) { - self.entries.push(TranscriptEntry::Error { - tx: hex::encode_upper(tx), - error: error.into(), - label, - }); + self.entries.push(TranscriptEntry::Error { tx: hex::encode_upper(tx), error: error.into(), label }); } pub fn to_jsonl_string(&self) -> Result { @@ -183,19 +167,9 @@ impl Transcript { let header_line = lines.next().ok_or(TranscriptError::InvalidHeader)?; let header_entry: TranscriptEntry = serde_json::from_str(header_line)?; let header = match header_entry { - TranscriptEntry::Header { - version, - supports_extended_length, - label, - keys, - can, - } => TranscriptHeader { - version, - supports_extended_length, - label, - keys, - can, - }, + TranscriptEntry::Header { version, supports_extended_length, label, keys, can } => { + TranscriptHeader { version, supports_extended_length, label, keys, can } + } _ => return Err(TranscriptError::InvalidHeader), }; let mut entries = Vec::new(); @@ -214,19 +188,9 @@ impl Transcript { let header_line = lines.next().ok_or(TranscriptError::InvalidHeader)??; let header_entry: TranscriptEntry = serde_json::from_str(&header_line)?; let header = match header_entry { - TranscriptEntry::Header { - version, - supports_extended_length, - label, - keys, - can, - } => TranscriptHeader { - version, - supports_extended_length, - label, - keys, - can, - }, + TranscriptEntry::Header { version, supports_extended_length, label, keys, can } => { + TranscriptHeader { version, supports_extended_length, label, keys, can } + } _ => return Err(TranscriptError::InvalidHeader), }; let mut entries = Vec::new(); @@ -363,9 +327,7 @@ impl CardChannel for ReplayChannel { } fn transmit(&mut self, command: &CardCommandApdu) -> Result { - let entry = self - .next_entry() - .map_err(|err| ExchangeError::Transport { code: 0, message: err.to_string() })?; + let entry = self.next_entry().map_err(|err| ExchangeError::Transport { code: 0, message: err.to_string() })?; match entry { TranscriptEntry::Exchange { tx, rx, .. } => { let expected_tx = hex::decode(tx) @@ -424,7 +386,10 @@ impl FixedKeyGenerator { } } -fn derive_keypair_from_scalar(curve: EcCurve, private_bytes: Vec) -> Result<(EcPublicKey, EcPrivateKey), CryptoError> { +fn derive_keypair_from_scalar( + curve: EcCurve, + private_bytes: Vec, +) -> Result<(EcPublicKey, EcPrivateKey), CryptoError> { let private_key = EcPrivateKey::from_bytes(curve.clone(), private_bytes); let scalar = BigInt::from_bytes_be(Sign::Plus, private_key.as_bytes()); let public_point = curve.g().mul(&scalar)?; @@ -440,29 +405,23 @@ pub struct PcscChannel { impl PcscChannel { pub fn connect(reader: &str, supports_extended_length: bool) -> Result { - let ctx = - pcsc::Context::establish(pcsc::Scope::User).map_err(|err| ExchangeError::Transport { - code: 0, - message: format!("pcsc context establish failed: {err}"), - })?; + let ctx = pcsc::Context::establish(pcsc::Scope::User).map_err(|err| ExchangeError::Transport { + code: 0, + message: format!("pcsc context establish failed: {err}"), + })?; let reader_cstr = CString::new(reader) .map_err(|err| ExchangeError::Transport { code: 0, message: format!("invalid reader name: {err}") })?; let card = ctx .connect(&reader_cstr, pcsc::ShareMode::Shared, pcsc::Protocols::ANY) .map_err(|err| ExchangeError::Transport { code: 0, message: format!("pcsc connect failed: {err}") })?; - Ok(Self { - card, - supports_extended_length, - recv_buffer: vec![0u8; 65538], - }) + Ok(Self { card, supports_extended_length, recv_buffer: vec![0u8; 65538] }) } pub fn connect_first(supports_extended_length: bool) -> Result { - let ctx = - pcsc::Context::establish(pcsc::Scope::User).map_err(|err| ExchangeError::Transport { - code: 0, - message: format!("pcsc context establish failed: {err}"), - })?; + let ctx = pcsc::Context::establish(pcsc::Scope::User).map_err(|err| ExchangeError::Transport { + code: 0, + message: format!("pcsc context establish failed: {err}"), + })?; let mut readers = ctx .list_readers_owned() .map_err(|err| ExchangeError::Transport { code: 0, message: format!("pcsc list readers failed: {err}") })?; @@ -472,11 +431,7 @@ impl PcscChannel { let card = ctx .connect(reader.as_c_str(), pcsc::ShareMode::Shared, pcsc::Protocols::ANY) .map_err(|err| ExchangeError::Transport { code: 0, message: format!("pcsc connect failed: {err}") })?; - Ok(Self { - card, - supports_extended_length, - recv_buffer: vec![0u8; 65538], - }) + Ok(Self { card, supports_extended_length, recv_buffer: vec![0u8; 65538] }) } } @@ -489,10 +444,10 @@ impl CardChannel for PcscChannel { fn transmit(&mut self, command: &CardCommandApdu) -> Result { let tx = command.to_bytes(); - let response = self.card.transmit(&tx, &mut self.recv_buffer).map_err(|err| ExchangeError::Transport { - code: 0, - message: format!("pcsc transmit failed: {err}"), - })?; + let response = self + .card + .transmit(&tx, &mut self.recv_buffer) + .map_err(|err| ExchangeError::Transport { code: 0, message: format!("pcsc transmit failed: {err}") })?; CardResponseApdu::new(response).map_err(ExchangeError::from) } } @@ -561,16 +516,13 @@ mod tests { let channel = PcscChannel::connect(&reader, true).expect("pcsc connect"); let mut recorder = RecordingChannel::new(channel); - let response = recorder - .execute_command(&HealthCardCommand::select(false, false)) - .expect("select MF"); + let response = recorder.execute_command(&HealthCardCommand::select(false, false)).expect("select MF"); let response_bytes = response.apdu.to_bytes(); let transcript = recorder.into_transcript(); let mut replay = ReplayChannel::from_transcript(transcript); - let replay_response = replay - .execute_command(&HealthCardCommand::select(false, false)) - .expect("replay select MF"); + let replay_response = + replay.execute_command(&HealthCardCommand::select(false, false)).expect("replay select MF"); assert_eq!(replay_response.apdu.to_bytes(), response_bytes); } diff --git a/core-modules/healthcard/src/exchange/mod.rs b/core-modules/healthcard/src/exchange/mod.rs index cb27519a..8f4c4f36 100644 --- a/core-modules/healthcard/src/exchange/mod.rs +++ b/core-modules/healthcard/src/exchange/mod.rs @@ -19,6 +19,8 @@ // For additional notes and disclaimer from gematik and in case of changes by gematik, // find details in the "Readme" file. +#[cfg(any(feature = "apdu-tools", test))] +pub mod apdu_tools; pub mod certificate; pub mod channel; pub mod error; @@ -27,19 +29,15 @@ pub mod pace_info; pub mod pin; pub mod random; pub mod read_vsd; +pub mod secure_channel; pub mod sign_challenge; #[cfg(test)] pub(crate) mod test_utils; -#[cfg(any(feature = "apdu-tools", test))] -pub mod apdu_tools; -pub mod secure_channel; pub use certificate::retrieve_certificate; pub use error::ExchangeError; pub use pin::{unlock_egk, verify_pin, HealthCardVerifyPinResult, UnlockMethod}; pub use random::get_random; pub use read_vsd::read_vsd; +pub use secure_channel::{establish_secure_channel, establish_secure_channel_with, CardAccessNumber, SecureChannel}; pub use sign_challenge::sign_challenge; -pub use secure_channel::{ - establish_secure_channel, establish_secure_channel_with, CardAccessNumber, SecureChannel, -}; diff --git a/core-modules/healthcard/src/exchange/secure_channel.rs b/core-modules/healthcard/src/exchange/secure_channel.rs index 8ee8cb01..a570e610 100644 --- a/core-modules/healthcard/src/exchange/secure_channel.rs +++ b/core-modules/healthcard/src/exchange/secure_channel.rs @@ -727,10 +727,7 @@ mod tests { fn integration_jsonl_replay_establish_secure_channel() { let transcript = Transcript::from_jsonl_str(JSONL_REPLAY_ESTABLISH_SECURE_CHANNEL).expect("load transcript"); let can = transcript.can().expect("CAN in transcript").to_string(); - let mut generator = transcript - .fixed_key_generator() - .expect("keys parse") - .expect("fixed key generator"); + let mut generator = transcript.fixed_key_generator().expect("keys parse").expect("fixed key generator"); let replay = ReplayChannel::from_transcript(transcript); let card_access_number = CardAccessNumber::new(&can).expect("can format"); establish_secure_channel_with(replay, &card_access_number, &mut generator) From a5b7c0a1848cfafb53addf8189d2bf2c7ef298da Mon Sep 17 00:00:00 2001 From: Tobias Schwerdtfeger Date: Tue, 6 Jan 2026 13:34:49 +0100 Subject: [PATCH 05/20] OPEN-94: Add license headers --- .gitignore | 1 + CONTRIBUTING.md | 2 +- core-modules/healthcard/Cargo.toml | 1 + core-modules/healthcard/src/bin/apdu_record.rs | 1 + core-modules/healthcard/src/exchange/apdu_tools.rs | 1 + core-modules/healthcard/src/exchange/mod.rs | 1 + core-modules/healthcard/src/exchange/secure_channel.rs | 1 + 7 files changed, 7 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 80d0dea0..f42cbc20 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ # SPDX-FileCopyrightText: Copyright 2025 gematik GmbH +# SPDX-FileCopyrightText: Copyright 2026 gematik GmbH # # SPDX-License-Identifier: Apache-2.0 # diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3c85de98..50532180 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -75,7 +75,7 @@ This ensures proper tracking and management of open `TODOs`. Annotate all files with the following command: ```shell -git ls-files -z -- ':(exclude)LICENSES/**' \ +git diff -z --name-only origin/main HEAD -- ':(exclude)LICENSES/**' \ | xargs -0 reuse annotate \ --license Apache-2.0 \ --copyright "gematik GmbH" \ diff --git a/core-modules/healthcard/Cargo.toml b/core-modules/healthcard/Cargo.toml index 85a716c7..489047d3 100644 --- a/core-modules/healthcard/Cargo.toml +++ b/core-modules/healthcard/Cargo.toml @@ -1,4 +1,5 @@ # SPDX-FileCopyrightText: Copyright 2025 gematik GmbH +# SPDX-FileCopyrightText: Copyright 2026 gematik GmbH # # SPDX-License-Identifier: Apache-2.0 # diff --git a/core-modules/healthcard/src/bin/apdu_record.rs b/core-modules/healthcard/src/bin/apdu_record.rs index 1cd331e5..ab755c39 100644 --- a/core-modules/healthcard/src/bin/apdu_record.rs +++ b/core-modules/healthcard/src/bin/apdu_record.rs @@ -1,4 +1,5 @@ // SPDX-FileCopyrightText: Copyright 2025 gematik GmbH +// SPDX-FileCopyrightText: Copyright 2026 gematik GmbH // // SPDX-License-Identifier: Apache-2.0 // diff --git a/core-modules/healthcard/src/exchange/apdu_tools.rs b/core-modules/healthcard/src/exchange/apdu_tools.rs index ecf43157..4bc4d318 100644 --- a/core-modules/healthcard/src/exchange/apdu_tools.rs +++ b/core-modules/healthcard/src/exchange/apdu_tools.rs @@ -1,4 +1,5 @@ // SPDX-FileCopyrightText: Copyright 2025 gematik GmbH +// SPDX-FileCopyrightText: Copyright 2026 gematik GmbH // // SPDX-License-Identifier: Apache-2.0 // diff --git a/core-modules/healthcard/src/exchange/mod.rs b/core-modules/healthcard/src/exchange/mod.rs index 8f4c4f36..1218712f 100644 --- a/core-modules/healthcard/src/exchange/mod.rs +++ b/core-modules/healthcard/src/exchange/mod.rs @@ -1,4 +1,5 @@ // SPDX-FileCopyrightText: Copyright 2025 gematik GmbH +// SPDX-FileCopyrightText: Copyright 2026 gematik GmbH // // SPDX-License-Identifier: Apache-2.0 // diff --git a/core-modules/healthcard/src/exchange/secure_channel.rs b/core-modules/healthcard/src/exchange/secure_channel.rs index a570e610..e7e6325f 100644 --- a/core-modules/healthcard/src/exchange/secure_channel.rs +++ b/core-modules/healthcard/src/exchange/secure_channel.rs @@ -1,4 +1,5 @@ // SPDX-FileCopyrightText: Copyright 2025 gematik GmbH +// SPDX-FileCopyrightText: Copyright 2026 gematik GmbH // // SPDX-License-Identifier: Apache-2.0 // From 2426765dcafd77f16df31ac92f4ca6d2529ae6bb Mon Sep 17 00:00:00 2001 From: Tobias Schwerdtfeger Date: Wed, 7 Jan 2026 13:57:08 +0100 Subject: [PATCH 06/20] OPEN-94: Consolidate license copyright years in headers --- core-modules/healthcard/src/bin/apdu_record.rs | 3 +-- core-modules/healthcard/src/exchange/apdu_tools.rs | 3 +-- core-modules/healthcard/src/exchange/secure_channel.rs | 3 +-- 3 files changed, 3 insertions(+), 6 deletions(-) diff --git a/core-modules/healthcard/src/bin/apdu_record.rs b/core-modules/healthcard/src/bin/apdu_record.rs index ab755c39..652b689e 100644 --- a/core-modules/healthcard/src/bin/apdu_record.rs +++ b/core-modules/healthcard/src/bin/apdu_record.rs @@ -1,5 +1,4 @@ -// SPDX-FileCopyrightText: Copyright 2025 gematik GmbH -// SPDX-FileCopyrightText: Copyright 2026 gematik GmbH +// SPDX-FileCopyrightText: Copyright 2025 - 2026 gematik GmbH // // SPDX-License-Identifier: Apache-2.0 // diff --git a/core-modules/healthcard/src/exchange/apdu_tools.rs b/core-modules/healthcard/src/exchange/apdu_tools.rs index 4bc4d318..d490e235 100644 --- a/core-modules/healthcard/src/exchange/apdu_tools.rs +++ b/core-modules/healthcard/src/exchange/apdu_tools.rs @@ -1,5 +1,4 @@ -// SPDX-FileCopyrightText: Copyright 2025 gematik GmbH -// SPDX-FileCopyrightText: Copyright 2026 gematik GmbH +// SPDX-FileCopyrightText: Copyright 2025 - 2026 gematik GmbH // // SPDX-License-Identifier: Apache-2.0 // diff --git a/core-modules/healthcard/src/exchange/secure_channel.rs b/core-modules/healthcard/src/exchange/secure_channel.rs index e7e6325f..b9f63b3c 100644 --- a/core-modules/healthcard/src/exchange/secure_channel.rs +++ b/core-modules/healthcard/src/exchange/secure_channel.rs @@ -1,5 +1,4 @@ -// SPDX-FileCopyrightText: Copyright 2025 gematik GmbH -// SPDX-FileCopyrightText: Copyright 2026 gematik GmbH +// SPDX-FileCopyrightText: Copyright 2025 - 2026 gematik GmbH // // SPDX-License-Identifier: Apache-2.0 // From 98bef598b0951b8a7b43ba41fef9698053425df4 Mon Sep 17 00:00:00 2001 From: Tobias Schwerdtfeger Date: Thu, 8 Jan 2026 16:00:03 +0100 Subject: [PATCH 07/20] OPEN-94: Add `apdu-tools` feature flag and restructure PCSC integration tests --- Cargo.lock | 98 +++++++++++++++++++ core-modules-swift/healthcard/README.md | 2 +- core-modules/healthcard/Cargo.toml | 8 ++ .../healthcard/src/exchange/apdu_tools.rs | 93 ++++++++++-------- 4 files changed, 158 insertions(+), 43 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 8224d25e..9d7869e1 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -20,12 +20,56 @@ dependencies = [ "libc", ] +[[package]] +name = "anstream" +version = "0.6.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "43d5b281e737544384e969a5ccad3f1cdd24b48086a0fc1b2a5262a26b8f4f4a" +dependencies = [ + "anstyle", + "anstyle-parse", + "anstyle-query", + "anstyle-wincon", + "colorchoice", + "is_terminal_polyfill", + "utf8parse", +] + [[package]] name = "anstyle" version = "1.0.13" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "5192cca8006f1fd4f7237516f40fa183bb07f8fbdfedaa0036de5ea9b0b45e78" +[[package]] +name = "anstyle-parse" +version = "0.2.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4e7644824f0aa2c7b9384579234ef10eb7efb6a0deb83f9630a49594dd9c15c2" +dependencies = [ + "utf8parse", +] + +[[package]] +name = "anstyle-query" +version = "1.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc" +dependencies = [ + "windows-sys", +] + +[[package]] +name = "anstyle-wincon" +version = "3.0.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d" +dependencies = [ + "anstyle", + "once_cell_polyfill", + "windows-sys", +] + [[package]] name = "anyhow" version = "1.0.100" @@ -238,6 +282,7 @@ version = "4.5.52" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "02576b399397b659c26064fbc92a75fede9d18ffd5f80ca1cd74ddab167016e1" dependencies = [ + "anstream", "anstyle", "clap_lex", "strsim", @@ -261,6 +306,12 @@ version = "0.7.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a1d728cc89cf3aee9ff92b05e62b19ee65a02b5702cff7d5a377e32c6ae29d8d" +[[package]] +name = "colorchoice" +version = "1.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b05b61dc5112cbb17e4b6cd61790d9845d13888356391624cbe7e41efeac1e75" + [[package]] name = "core-foundation-sys" version = "0.8.7" @@ -377,11 +428,15 @@ name = "healthcard" version = "0.1.0" dependencies = [ "asn1", + "clap", "crypto", "hex", "lazy_static", "num-bigint", "once_cell", + "pcsc", + "serde", + "serde_json", "thiserror", "uniffi", "zeroize", @@ -441,6 +496,12 @@ dependencies = [ "serde_core", ] +[[package]] +name = "is_terminal_polyfill" +version = "1.70.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695" + [[package]] name = "itertools" version = "0.13.0" @@ -566,12 +627,43 @@ version = "1.21.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "42f5e15c9953c5e4ccceeb2e7382a716482c34515315f7b03532b8b4e8393d2d" +[[package]] +name = "once_cell_polyfill" +version = "1.70.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe" + +[[package]] +name = "pcsc" +version = "2.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7dd833ecf8967e65934c49d3521a175929839bf6d0e497f3bd0d3a2ca08943da" +dependencies = [ + "bitflags", + "pcsc-sys", +] + +[[package]] +name = "pcsc-sys" +version = "1.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e14ef017e15d2e5592a9e39a346c1dbaea5120bab7ed7106b210ef58ebd97003" +dependencies = [ + "pkg-config", +] + [[package]] name = "percent-encoding" version = "2.3.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220" +[[package]] +name = "pkg-config" +version = "0.3.32" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7edddbd0b52d732b21ad9a5fab5c704c14cd949e5e9a1ec5929a24fded1b904c" + [[package]] name = "plain" version = "0.2.3" @@ -1048,6 +1140,12 @@ dependencies = [ "weedle2", ] +[[package]] +name = "utf8parse" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821" + [[package]] name = "wasi" version = "0.14.3+wasi-0.2.4" diff --git a/core-modules-swift/healthcard/README.md b/core-modules-swift/healthcard/README.md index b5d6a190..8249ec4e 100644 --- a/core-modules-swift/healthcard/README.md +++ b/core-modules-swift/healthcard/README.md @@ -30,7 +30,7 @@ This module provides Swift bindings for the Rust `healthcard` crate via UniFFI, From the repository root: ```bash -just swift-healthcard-xcframework +just swift-xcframework ``` This generates: diff --git a/core-modules/healthcard/Cargo.toml b/core-modules/healthcard/Cargo.toml index 32f18587..39d42dd9 100644 --- a/core-modules/healthcard/Cargo.toml +++ b/core-modules/healthcard/Cargo.toml @@ -43,3 +43,11 @@ once_cell = "1.21.3" num-bigint = "0.4" zeroize = { version = "1.8.1", features = ["zeroize_derive"] } uniffi = { version = "0.30.0", optional = true } +clap = { version = "4.5.52", features = ["derive"], optional = true } +pcsc = { version = "2.9.0", optional = true } +serde = { version = "1.0.228", features = ["derive"], optional = true } +serde_json = { version = "1.0.145", optional = true } + +[dev-dependencies] +serde = { version = "1.0.228", features = ["derive"] } +serde_json = "1.0.145" diff --git a/core-modules/healthcard/src/exchange/apdu_tools.rs b/core-modules/healthcard/src/exchange/apdu_tools.rs index d490e235..49568125 100644 --- a/core-modules/healthcard/src/exchange/apdu_tools.rs +++ b/core-modules/healthcard/src/exchange/apdu_tools.rs @@ -26,12 +26,14 @@ use crypto::ec::ec_key::{EcCurve, EcPrivateKey, EcPublicKey}; use crypto::error::CryptoError; use num_bigint::{BigInt, Sign}; use serde::{Deserialize, Serialize}; -use std::ffi::CString; use std::fs::File; use std::io::{BufRead, BufReader, Write}; use std::path::Path; use thiserror::Error; +#[cfg(feature = "apdu-tools")] +use std::ffi::CString; + #[derive(Debug, Error)] pub enum TranscriptError { #[error("io error: {0}")] @@ -397,12 +399,14 @@ fn derive_keypair_from_scalar( Ok((public_key, private_key)) } +#[cfg(feature = "apdu-tools")] pub struct PcscChannel { card: pcsc::Card, supports_extended_length: bool, recv_buffer: Vec, } +#[cfg(feature = "apdu-tools")] impl PcscChannel { pub fn connect(reader: &str, supports_extended_length: bool) -> Result { let ctx = pcsc::Context::establish(pcsc::Scope::User).map_err(|err| ExchangeError::Transport { @@ -435,6 +439,7 @@ impl PcscChannel { } } +#[cfg(feature = "apdu-tools")] impl CardChannel for PcscChannel { type Error = ExchangeError; @@ -456,9 +461,6 @@ impl CardChannel for PcscChannel { mod tests { use super::*; use crate::command::apdu::CardCommandApdu; - use crate::command::health_card_command::HealthCardCommand; - use crate::command::select_command::SelectCommand; - use crate::exchange::channel::CardChannelExt; use crate::exchange::test_utils::MockSession; #[test] @@ -507,48 +509,55 @@ mod tests { assert_eq!(priv2.as_bytes(), key2.as_slice()); } - #[test] - fn pcsc_record_and_replay_select_mf() { - let reader = match std::env::var("HEALTHCARD_PCSC_READER") { - Ok(reader) => reader, - Err(_) => return, - }; - - let channel = PcscChannel::connect(&reader, true).expect("pcsc connect"); - let mut recorder = RecordingChannel::new(channel); - let response = recorder.execute_command(&HealthCardCommand::select(false, false)).expect("select MF"); - let response_bytes = response.apdu.to_bytes(); - - let transcript = recorder.into_transcript(); - let mut replay = ReplayChannel::from_transcript(transcript); - let replay_response = - replay.execute_command(&HealthCardCommand::select(false, false)).expect("replay select MF"); - assert_eq!(replay_response.apdu.to_bytes(), response_bytes); - } + #[cfg(feature = "apdu-tools")] + mod pcsc_tests { + use super::*; + use crate::command::health_card_command::HealthCardCommand; + use crate::exchange::channel::CardChannelExt; + + #[test] + fn pcsc_record_and_replay_select_mf() { + let reader = match std::env::var("HEALTHCARD_PCSC_READER") { + Ok(reader) => reader, + Err(_) => return, + }; + + let channel = PcscChannel::connect(&reader, true).expect("pcsc connect"); + let mut recorder = RecordingChannel::new(channel); + let response = recorder.execute_command(&HealthCardCommand::select(false, false)).expect("select MF"); + let response_bytes = response.apdu.to_bytes(); + + let transcript = recorder.into_transcript(); + let mut replay = ReplayChannel::from_transcript(transcript); + let replay_response = + replay.execute_command(&HealthCardCommand::select(false, false)).expect("replay select MF"); + assert_eq!(replay_response.apdu.to_bytes(), response_bytes); + } - #[test] - fn list_pcsc_readers() { - let ctx = match pcsc::Context::establish(pcsc::Scope::User) { - Ok(ctx) => ctx, - Err(err) => { - println!("pcsc context establish failed: {err}"); + #[test] + fn list_pcsc_readers() { + let ctx = match pcsc::Context::establish(pcsc::Scope::User) { + Ok(ctx) => ctx, + Err(err) => { + println!("pcsc context establish failed: {err}"); + return; + } + }; + let readers = match ctx.list_readers_owned() { + Ok(readers) => readers, + Err(err) => { + println!("pcsc list readers failed: {err}"); + return; + } + }; + if readers.is_empty() { + println!("no pcsc readers found"); return; } - }; - let readers = match ctx.list_readers_owned() { - Ok(readers) => readers, - Err(err) => { - println!("pcsc list readers failed: {err}"); - return; + println!("pcsc readers:"); + for reader in readers { + println!(" {}", reader.to_string_lossy()); } - }; - if readers.is_empty() { - println!("no pcsc readers found"); - return; - } - println!("pcsc readers:"); - for reader in readers { - println!(" {}", reader.to_string_lossy()); } } } From e94212695cdb942badb269010d2bce7aab1027af Mon Sep 17 00:00:00 2001 From: Tobias Schwerdtfeger Date: Thu, 8 Jan 2026 21:24:22 +0100 Subject: [PATCH 08/20] OPEN-94: Add documentation --- docs/README.md | 6 +++ docs/tooling/apdu-tools.md | 105 +++++++++++++++++++++++++++++++++++++ 2 files changed, 111 insertions(+) create mode 100644 docs/tooling/apdu-tools.md diff --git a/docs/README.md b/docs/README.md index 4879490d..38d20c04 100644 --- a/docs/README.md +++ b/docs/README.md @@ -37,4 +37,10 @@ Interoperability-related notes live under `interop/`: - [`JVM interoperability and debugging`](interop/jvm.md) – Debugging and interoperability notes for JVM targets (Java, Kotlin). +## Tooling + +Developer tooling documentation lives under `tooling/`: + +- [`APDU tools (recorder & replay)`](tooling/apdu-tools.md) – Record and replay APDU exchanges (PACE) for debugging and tests. + As additional documentation areas (e.g. architecture, APIs, deployment) are added under `docs/`, they should be organized into subdirectories and referenced from this overview. diff --git a/docs/tooling/apdu-tools.md b/docs/tooling/apdu-tools.md new file mode 100644 index 00000000..bf43c225 --- /dev/null +++ b/docs/tooling/apdu-tools.md @@ -0,0 +1,105 @@ + + +# APDU Tools (Recorder & Replay) + +The healthcard module contains small developer tools to record and replay APDU exchanges. This is useful for debugging +PACE establishment and for creating deterministic, offline test runs. + +Source locations: + +- Binary: `core-modules/healthcard/src/bin/apdu_record.rs` +- Library helpers: `core-modules/healthcard/src/exchange/apdu_tools.rs` + +## Feature flag + +Everything in `healthcard::exchange::apdu_tools` is gated behind the crate feature `apdu-tools`. + +- Build/run tools: add `--features apdu-tools` to your `cargo` command. +- Use in another crate: `healthcard = { path = "../core-modules/healthcard", features = ["apdu-tools"] }` + +## `apdu_record` (PC/SC recorder) + +Records APDU input/output while establishing a secure channel (PACE) and writes a transcript as JSON Lines (JSONL). + +Prerequisites: + +- A working PC/SC stack on your system and a connected reader/card. +- If `--list-readers` shows nothing or `pcsc context establish failed`, check that the PC/SC service/daemon is running. + +Show CLI help: + +```sh +cargo run -p healthcard --bin apdu_record --features apdu-tools -- --help +``` + +### List PC/SC readers + +```sh +cargo run -p healthcard --bin apdu_record --features apdu-tools -- --list-readers +``` + +### Record a transcript + +```sh +cargo run -p healthcard --bin apdu_record --features apdu-tools -- \ + --reader "" \ + --can 123456 \ + --out ./transcript.jsonl +``` + +APDU length options: + +- Default: uses extended-length APDUs when needed. +- `--no-extended`: forces short APDUs only. + +### Transcript contents (security note) + +The transcript file can include sensitive values (e.g., CAN and generated ephemeral private keys used during PACE). +Treat transcripts as secrets and do not commit them to source control. + +## Transcript format (JSONL) + +The output is JSON Lines: + +- First line: a `header` entry (`supports_extended_length`, optional `label`, optional `keys`, optional `can`) +- Following lines: `exchange` entries (`tx`/`rx` as uppercase hex) or `error` entries + +## Replay in Rust (offline) + +Use a recorded transcript to replay the same APDU sequence without a card/reader: + +```rust +use healthcard::exchange::apdu_tools::{ReplayChannel, Transcript}; +use healthcard::exchange::secure_channel::{establish_secure_channel_with, CardAccessNumber}; + +let transcript = Transcript::from_jsonl("transcript.jsonl")?; +let mut channel = ReplayChannel::from_transcript(transcript); +let can = CardAccessNumber::new("123456")?; +let key_generator = channel.fixed_key_generator()?.expect("transcript contains no keys"); + +let _secure = establish_secure_channel_with(&mut channel, &can, key_generator)?; +``` + +If the outgoing APDU does not match the transcript, replay fails with a mismatch error. This is intentional: it ensures +the code path and APDU sequence are identical to what was recorded. From c6c4ed63212efcb677fe3a3f472625ff1482ba4b Mon Sep 17 00:00:00 2001 From: Tobias Schwerdtfeger Date: Fri, 9 Jan 2026 09:53:05 +0100 Subject: [PATCH 09/20] OPEN-97: Add `cv_certificate` parser module for handling and decoding CV certificates --- core-modules/asn1/src/cv_certificate.rs | 705 ++++++++++++++++++++++++ core-modules/asn1/src/lib.rs | 1 + 2 files changed, 706 insertions(+) create mode 100644 core-modules/asn1/src/cv_certificate.rs diff --git a/core-modules/asn1/src/cv_certificate.rs b/core-modules/asn1/src/cv_certificate.rs new file mode 100644 index 00000000..b9ee74fd --- /dev/null +++ b/core-modules/asn1/src/cv_certificate.rs @@ -0,0 +1,705 @@ +// SPDX-FileCopyrightText: Copyright 2025 gematik GmbH +// +// SPDX-License-Identifier: Apache-2.0 +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// +// ******* +// +// For additional notes and disclaimer from gematik and in case of changes by gematik, +// find details in the "Readme" file. + +use crate::decoder::{Asn1Decoder, Asn1Length, ParserScope}; +use crate::error::{Asn1DecoderError, Asn1DecoderResult}; +use crate::oid::ObjectIdentifier; +use crate::tag::{Asn1Id, TagNumberExt}; + +const TAG_CV_CERTIFICATE: u32 = 33; +const TAG_CERTIFICATE_BODY: u32 = 78; +const TAG_PROFILE_IDENTIFIER: u32 = 41; +const TAG_CERTIFICATION_AUTHORITY_REFERENCE: u32 = 2; +const TAG_PUBLIC_KEY: u32 = 73; +const TAG_CERTIFICATE_HOLDER_REFERENCE: u32 = 32; +const TAG_CHAT: u32 = 76; +const TAG_CERTIFICATE_EFFECTIVE_DATE: u32 = 37; +const TAG_CERTIFICATE_EXPIRATION_DATE: u32 = 36; +const TAG_CERTIFICATE_EXTENSIONS: u32 = 5; +const TAG_DISCRETIONARY_DATA: u32 = 19; +const TAG_SIGNATURE: u32 = 55; + +const MAX_CERT_FIELD_LEN: usize = 65_535; + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct CVCertificate { + pub body: CertificateBody, + pub signature: Vec, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct CertificateBody { + pub profile_identifier: u8, + pub certification_authority_reference: Vec, + pub public_key: CVCertPublicKey, + pub certificate_holder_reference: Vec, + pub certificate_holder_authorization_template: Chat, + pub certificate_effective_date: CertificateDate, + pub certificate_expiration_date: CertificateDate, + pub certificate_extensions: Option, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct CVCertPublicKey { + /// Raw contents of the public key container (tag 7F49). + pub public_key_data: Vec, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Chat { + pub terminal_type: ObjectIdentifier, + pub relative_authorization: Vec, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct CertificateDate { + pub year: u8, + pub month: u8, + pub day: u8, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct CertificateExtensions { + pub templates: Vec, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct DiscretionaryDataTemplate { + pub extension_id: ObjectIdentifier, + pub extension_data: Vec, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ExtensionField { + pub tag: Asn1Id, + pub value: Vec, +} + +impl CVCertificate { + pub fn parse(data: &[u8]) -> Asn1DecoderResult { + let decoder = Asn1Decoder::new(data); + let certificate = decoder.read(|scope| parse_cv_certificate_scope(scope))?; + Ok(certificate) + } +} + +pub fn parse_cv_certificate(data: &[u8]) -> Asn1DecoderResult { + CVCertificate::parse(data) +} + +fn parse_cv_certificate_scope(scope: &mut ParserScope) -> Result { + scope.advance_with_tag(TAG_CV_CERTIFICATE.application_tag().constructed(), |scope| { + let body = parse_certificate_body(scope)?; + let signature = read_application_bytes(scope, TAG_SIGNATURE, 0, MAX_CERT_FIELD_LEN)?; + Ok(CVCertificate { body, signature }) + }) +} + +fn parse_certificate_body(scope: &mut ParserScope) -> Result { + scope.advance_with_tag(TAG_CERTIFICATE_BODY.application_tag().constructed(), |scope| { + let profile_identifier = read_profile_identifier(scope)?; + let certification_authority_reference = + read_application_bytes(scope, TAG_CERTIFICATION_AUTHORITY_REFERENCE, 1, 16)?; + let public_key = parse_public_key(scope)?; + let certificate_holder_reference = + read_application_bytes(scope, TAG_CERTIFICATE_HOLDER_REFERENCE, 1, 16)?; + let certificate_holder_authorization_template = parse_chat(scope)?; + let certificate_effective_date = parse_date(scope, TAG_CERTIFICATE_EFFECTIVE_DATE)?; + let certificate_expiration_date = parse_date(scope, TAG_CERTIFICATE_EXPIRATION_DATE)?; + let certificate_extensions = if scope.remaining_length() > 0 { + Some(parse_certificate_extensions(scope)?) + } else { + None + }; + + Ok(CertificateBody { + profile_identifier, + certification_authority_reference, + public_key, + certificate_holder_reference, + certificate_holder_authorization_template, + certificate_effective_date, + certificate_expiration_date, + certificate_extensions, + }) + }) +} + +fn read_profile_identifier(scope: &mut ParserScope) -> Result { + scope.advance_with_tag(TAG_PROFILE_IDENTIFIER.application_tag().primitive(), |scope| { + let bytes = scope.read_bytes(scope.remaining_length())?; + if bytes.is_empty() { + return Err(Asn1DecoderError::custom("CertificateProfileIdentifier must not be empty")); + } + if bytes.len() > 4 { + return Err(Asn1DecoderError::custom( + "CertificateProfileIdentifier must not exceed 4 bytes", + )); + } + if (bytes[0] & 0x80) != 0 { + return Err(Asn1DecoderError::custom( + "CertificateProfileIdentifier must be a non-negative INTEGER", + )); + } + let value = bytes.iter().fold(0u32, |acc, b| (acc << 8) | (*b as u32)); + if value > u8::MAX as u32 { + return Err(Asn1DecoderError::custom( + "CertificateProfileIdentifier must be within 0..=255", + )); + } + Ok(value as u8) + }) +} + +fn parse_public_key(scope: &mut ParserScope) -> Result { + scope.advance_with_tag(TAG_PUBLIC_KEY.application_tag().constructed(), |scope| { + let data = scope.read_bytes(scope.remaining_length())?; + if data.is_empty() { + return Err(Asn1DecoderError::custom("CVCertPublicKey must not be empty")); + } + Ok(CVCertPublicKey { public_key_data: data }) + }) +} + +fn parse_chat(scope: &mut ParserScope) -> Result { + scope.advance_with_tag(TAG_CHAT.application_tag().constructed(), |scope| { + let terminal_type = scope.read_object_identifier()?; + let relative_authorization = read_application_bytes(scope, TAG_DISCRETIONARY_DATA, 0, MAX_CERT_FIELD_LEN)?; + Ok(Chat { terminal_type, relative_authorization }) + }) +} + +fn parse_date(scope: &mut ParserScope, tag_number: u32) -> Result { + scope.advance_with_tag(tag_number.application_tag().primitive(), |scope| { + let bytes = scope.read_bytes(scope.remaining_length())?; + if bytes.len() != 6 { + return Err(Asn1DecoderError::custom("Certificate date must be 6 bytes")); + } + for (idx, byte) in bytes.iter().enumerate() { + if *byte > 9 { + return Err(Asn1DecoderError::custom(format!( + "Certificate date digit {idx} must be 0..9" + ))); + } + } + let year = bytes[0] * 10 + bytes[1]; + let month = bytes[2] * 10 + bytes[3]; + let day = bytes[4] * 10 + bytes[5]; + if !(1..=12).contains(&month) { + return Err(Asn1DecoderError::custom("Certificate month must be 1..=12")); + } + if !(1..=31).contains(&day) { + return Err(Asn1DecoderError::custom("Certificate day must be 1..=31")); + } + Ok(CertificateDate { year, month, day }) + }) +} + +fn parse_certificate_extensions(scope: &mut ParserScope) -> Result { + scope.advance_with_tag(TAG_CERTIFICATE_EXTENSIONS.application_tag().constructed(), |scope| { + let mut templates = Vec::new(); + while scope.remaining_length() > 0 { + templates.push(parse_discretionary_data_template(scope)?); + } + Ok(CertificateExtensions { templates }) + }) +} + +fn parse_discretionary_data_template(scope: &mut ParserScope) -> Result { + scope.advance_with_tag(TAG_DISCRETIONARY_DATA.application_tag().constructed(), |scope| { + let extension_id = scope.read_object_identifier()?; + let mut extension_data = Vec::new(); + while scope.remaining_length() > 0 { + extension_data.push(parse_extension_field(scope)?); + } + Ok(DiscretionaryDataTemplate { extension_id, extension_data }) + }) +} + +fn parse_extension_field(scope: &mut ParserScope) -> Result { + let tag = scope.read_tag()?; + let length = scope.read_length()?; + let value = match length { + Asn1Length::Definite(len) => scope.read_bytes(len)?, + Asn1Length::Indefinite => { + return Err(Asn1DecoderError::custom( + "Indefinite length is not supported for extension fields", + )) + } + }; + Ok(ExtensionField { tag, value }) +} + +fn read_application_bytes( + scope: &mut ParserScope, + tag_number: u32, + min_len: usize, + max_len: usize, +) -> Result, Asn1DecoderError> { + scope.advance_with_tag(tag_number.application_tag().primitive(), |scope| { + let len = scope.remaining_length(); + if len < min_len || len > max_len { + return Err(Asn1DecoderError::custom(format!( + "Invalid length {len} for application tag {tag_number}" + ))); + } + scope.read_bytes(len) + }) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::encoder::Asn1Encoder; + use crate::tag::TagNumberExt; + + type EncResult = Result<(), crate::error::Asn1EncoderError>; + + fn build_test_certificate(with_extensions: bool) -> Vec { + Asn1Encoder::write::(|w| { + w.write_tagged_object( + TAG_CV_CERTIFICATE.application_tag().constructed(), + |cert| -> EncResult { + cert.write_tagged_object( + TAG_CERTIFICATE_BODY.application_tag().constructed(), + |body| -> EncResult { + body.write_tagged_object(TAG_PROFILE_IDENTIFIER.application_tag(), |field| -> EncResult { + field.write_byte(0x00); + Ok(()) + })?; + body.write_tagged_object( + TAG_CERTIFICATION_AUTHORITY_REFERENCE.application_tag(), + |field| -> EncResult { + field.write_bytes(b"CAR"); + Ok(()) + })?; + body.write_tagged_object(TAG_PUBLIC_KEY.application_tag().constructed(), |field| -> EncResult { + field.write_bytes(&[0xA0, 0x01, 0x02]); + Ok(()) + })?; + body.write_tagged_object(TAG_CERTIFICATE_HOLDER_REFERENCE.application_tag(), |field| -> EncResult { + field.write_bytes(b"CH"); + Ok(()) + })?; + body.write_tagged_object(TAG_CHAT.application_tag().constructed(), |chat| -> EncResult { + let oid = ObjectIdentifier::parse("1.2.3").expect("valid OID"); + chat.write_object_identifier(&oid)?; + chat.write_tagged_object(TAG_DISCRETIONARY_DATA.application_tag(), |data| -> EncResult { + data.write_bytes(&[0xAA, 0xBB]); + Ok(()) + })?; + Ok(()) + })?; + body.write_tagged_object(TAG_CERTIFICATE_EFFECTIVE_DATE.application_tag(), |field| -> EncResult { + field.write_bytes(&[2, 5, 0, 1, 0, 1]); + Ok(()) + })?; + body.write_tagged_object(TAG_CERTIFICATE_EXPIRATION_DATE.application_tag(), |field| -> EncResult { + field.write_bytes(&[2, 6, 1, 2, 3, 1]); + Ok(()) + })?; + + if with_extensions { + body.write_tagged_object( + TAG_CERTIFICATE_EXTENSIONS.application_tag().constructed(), + |exts| -> EncResult { + exts.write_tagged_object( + TAG_DISCRETIONARY_DATA.application_tag().constructed(), + |tmpl| -> EncResult { + let oid = ObjectIdentifier::parse("1.2.3.4").expect("valid OID"); + tmpl.write_object_identifier(&oid)?; + tmpl.write_tagged_object(0u8.context_tag(), |field| -> EncResult { + field.write_bytes(&[0x10]); + Ok(()) + })?; + tmpl.write_tagged_object(1u8.context_tag(), |field| -> EncResult { + field.write_bytes(&[0x20, 0x30]); + Ok(()) + })?; + Ok(()) + }, + )?; + Ok(()) + }, + )?; + } + + Ok(()) + }, + )?; + cert.write_tagged_object(TAG_SIGNATURE.application_tag(), |sig| -> EncResult { + sig.write_bytes(&[0xDE, 0xAD]); + Ok(()) + })?; + Ok(()) + }, + ) + }) + .expect("encoding must succeed") + } + + fn build_certificate_with_fields( + profile_bytes: &[u8], + car: &[u8], + chr: &[u8], + effective: &[u8], + expiration: &[u8], + ) -> Vec { + build_certificate_with_fields_and_signature(profile_bytes, car, chr, effective, expiration, &[0x00]) + } + + fn build_certificate_with_fields_and_signature( + profile_bytes: &[u8], + car: &[u8], + chr: &[u8], + effective: &[u8], + expiration: &[u8], + signature: &[u8], + ) -> Vec { + Asn1Encoder::write::(|w| { + w.write_tagged_object(TAG_CV_CERTIFICATE.application_tag().constructed(), |cert| -> EncResult { + cert.write_tagged_object(TAG_CERTIFICATE_BODY.application_tag().constructed(), |body| -> EncResult { + body.write_tagged_object(TAG_PROFILE_IDENTIFIER.application_tag(), |field| -> EncResult { + field.write_bytes(profile_bytes); + Ok(()) + })?; + body.write_tagged_object( + TAG_CERTIFICATION_AUTHORITY_REFERENCE.application_tag(), + |field| -> EncResult { + field.write_bytes(car); + Ok(()) + }, + )?; + body.write_tagged_object(TAG_PUBLIC_KEY.application_tag().constructed(), |field| -> EncResult { + field.write_bytes(&[0xA0, 0x01, 0x02]); + Ok(()) + })?; + body.write_tagged_object(TAG_CERTIFICATE_HOLDER_REFERENCE.application_tag(), |field| -> EncResult { + field.write_bytes(chr); + Ok(()) + })?; + body.write_tagged_object(TAG_CHAT.application_tag().constructed(), |chat| -> EncResult { + let oid = ObjectIdentifier::parse("1.2.3").expect("valid OID"); + chat.write_object_identifier(&oid)?; + chat.write_tagged_object(TAG_DISCRETIONARY_DATA.application_tag(), |data| -> EncResult { + data.write_bytes(&[0x00]); + Ok(()) + })?; + Ok(()) + })?; + body.write_tagged_object(TAG_CERTIFICATE_EFFECTIVE_DATE.application_tag(), |field| -> EncResult { + field.write_bytes(effective); + Ok(()) + })?; + body.write_tagged_object(TAG_CERTIFICATE_EXPIRATION_DATE.application_tag(), |field| -> EncResult { + field.write_bytes(expiration); + Ok(()) + })?; + Ok(()) + })?; + cert.write_tagged_object(TAG_SIGNATURE.application_tag(), |sig| -> EncResult { + sig.write_bytes(signature); + Ok(()) + })?; + Ok(()) + }) + }) + .expect("encoding must succeed") + } + + fn build_certificate_with_chat_data(chat_data: &[u8]) -> Vec { + Asn1Encoder::write::(|w| { + w.write_tagged_object(TAG_CV_CERTIFICATE.application_tag().constructed(), |cert| -> EncResult { + cert.write_tagged_object(TAG_CERTIFICATE_BODY.application_tag().constructed(), |body| -> EncResult { + body.write_tagged_object(TAG_PROFILE_IDENTIFIER.application_tag(), |field| -> EncResult { + field.write_bytes(&[0x00]); + Ok(()) + })?; + body.write_tagged_object( + TAG_CERTIFICATION_AUTHORITY_REFERENCE.application_tag(), + |field| -> EncResult { + field.write_bytes(b"CAR"); + Ok(()) + }, + )?; + body.write_tagged_object(TAG_PUBLIC_KEY.application_tag().constructed(), |field| -> EncResult { + field.write_bytes(&[0xA0, 0x01, 0x02]); + Ok(()) + })?; + body.write_tagged_object(TAG_CERTIFICATE_HOLDER_REFERENCE.application_tag(), |field| -> EncResult { + field.write_bytes(b"CHR"); + Ok(()) + })?; + body.write_tagged_object(TAG_CHAT.application_tag().constructed(), |chat| -> EncResult { + let oid = ObjectIdentifier::parse("1.2.3").expect("valid OID"); + chat.write_object_identifier(&oid)?; + chat.write_tagged_object(TAG_DISCRETIONARY_DATA.application_tag(), |data| -> EncResult { + data.write_bytes(chat_data); + Ok(()) + })?; + Ok(()) + })?; + body.write_tagged_object(TAG_CERTIFICATE_EFFECTIVE_DATE.application_tag(), |field| -> EncResult { + field.write_bytes(&[2, 5, 0, 1, 0, 1]); + Ok(()) + })?; + body.write_tagged_object(TAG_CERTIFICATE_EXPIRATION_DATE.application_tag(), |field| -> EncResult { + field.write_bytes(&[2, 5, 0, 1, 0, 2]); + Ok(()) + })?; + Ok(()) + })?; + cert.write_tagged_object(TAG_SIGNATURE.application_tag(), |sig| -> EncResult { + sig.write_bytes(&[0x00]); + Ok(()) + })?; + Ok(()) + }) + }) + .expect("encoding must succeed") + } + + fn build_certificate_with_public_key(public_key: &[u8]) -> Vec { + Asn1Encoder::write::(|w| { + w.write_tagged_object(TAG_CV_CERTIFICATE.application_tag().constructed(), |cert| -> EncResult { + cert.write_tagged_object(TAG_CERTIFICATE_BODY.application_tag().constructed(), |body| -> EncResult { + body.write_tagged_object(TAG_PROFILE_IDENTIFIER.application_tag(), |field| -> EncResult { + field.write_bytes(&[0x00]); + Ok(()) + })?; + body.write_tagged_object( + TAG_CERTIFICATION_AUTHORITY_REFERENCE.application_tag(), + |field| -> EncResult { + field.write_bytes(b"CAR"); + Ok(()) + }, + )?; + body.write_tagged_object(TAG_PUBLIC_KEY.application_tag().constructed(), |field| -> EncResult { + field.write_bytes(public_key); + Ok(()) + })?; + body.write_tagged_object(TAG_CERTIFICATE_HOLDER_REFERENCE.application_tag(), |field| -> EncResult { + field.write_bytes(b"CHR"); + Ok(()) + })?; + body.write_tagged_object(TAG_CHAT.application_tag().constructed(), |chat| -> EncResult { + let oid = ObjectIdentifier::parse("1.2.3").expect("valid OID"); + chat.write_object_identifier(&oid)?; + chat.write_tagged_object(TAG_DISCRETIONARY_DATA.application_tag(), |data| -> EncResult { + data.write_bytes(&[0x00]); + Ok(()) + })?; + Ok(()) + })?; + body.write_tagged_object(TAG_CERTIFICATE_EFFECTIVE_DATE.application_tag(), |field| -> EncResult { + field.write_bytes(&[2, 5, 0, 1, 0, 1]); + Ok(()) + })?; + body.write_tagged_object(TAG_CERTIFICATE_EXPIRATION_DATE.application_tag(), |field| -> EncResult { + field.write_bytes(&[2, 5, 0, 1, 0, 2]); + Ok(()) + })?; + Ok(()) + })?; + cert.write_tagged_object(TAG_SIGNATURE.application_tag(), |sig| -> EncResult { + sig.write_bytes(&[0x00]); + Ok(()) + })?; + Ok(()) + }) + }) + .expect("encoding must succeed") + } + + fn hex_to_bytes(hex_str: &str) -> Vec { + let mut out = Vec::new(); + let mut chars = hex_str.chars().filter(|c| !c.is_whitespace()).peekable(); + while chars.peek().is_some() { + let hi = chars.next().expect("hex high nibble"); + let lo = chars.next().expect("hex low nibble"); + let byte = u8::from_str_radix(&format!("{hi}{lo}"), 16).expect("valid hex"); + out.push(byte); + } + out + } + + #[test] + fn parse_cv_certificate_without_extensions() { + let data = build_test_certificate(false); + let cert = CVCertificate::parse(&data).expect("parse should succeed"); + + assert_eq!(cert.body.profile_identifier, 0); + assert_eq!(cert.body.certification_authority_reference, b"CAR"); + assert_eq!(cert.body.public_key.public_key_data, vec![0xA0, 0x01, 0x02]); + assert_eq!(cert.body.certificate_holder_reference, b"CH"); + let chat = &cert.body.certificate_holder_authorization_template; + assert_eq!(chat.terminal_type.to_string(), "1.2.3"); + assert_eq!(chat.relative_authorization, vec![0xAA, 0xBB]); + assert_eq!(cert.body.certificate_effective_date, CertificateDate { year: 25, month: 1, day: 1 }); + assert_eq!(cert.body.certificate_expiration_date, CertificateDate { year: 26, month: 12, day: 31 }); + assert!(cert.body.certificate_extensions.is_none()); + assert_eq!(cert.signature, vec![0xDE, 0xAD]); + } + + #[test] + fn parse_cv_certificate_with_extensions() { + let data = build_test_certificate(true); + let cert = CVCertificate::parse(&data).expect("parse should succeed"); + let extensions = cert.body.certificate_extensions.expect("extensions should be present"); + + assert_eq!(extensions.templates.len(), 1); + let template = &extensions.templates[0]; + assert_eq!(template.extension_id.to_string(), "1.2.3.4"); + assert_eq!(template.extension_data.len(), 2); + assert_eq!(template.extension_data[0].tag, 0u8.context_tag()); + assert_eq!(template.extension_data[0].value, vec![0x10]); + assert_eq!(template.extension_data[1].tag, 1u8.context_tag()); + assert_eq!(template.extension_data[1].value, vec![0x20, 0x30]); + } + + #[test] + fn parse_cv_certificate_from_pycvc_fixture() { + let hex_data = "\ + 7f218202627f4e8201585f2901004207544553544341527f49820115060a04007f000702020201\ + 0281820100c1195824540bdeabbb33293c25d18eaf2afd8a3a546af0941105a9676e82046be6ea\ + 0e0be0a32832e9d0f55ea81de640f7097f8ec5ef8170a22469f0fa99f63e9aa35a2bcf73e837bbc\ + 13c9650f005dd9215a3046eb7db7e50e9b7a9d99d87736d08c0bbf7eae9f7a5c8e9b52e4de29be\ + 28682b3ed1443a30238132ea43d5ae69dcd450dcc09d4626102a1cbc2bbe3423169fbb6ca45cc52\ + d7930e28da53ab2eabf0f869471db512b614a7397a673b7228f11b851a8b0a3eb48ed762651a323\ + f4b907ef8d216f5cc028f6ead6b79b6229a6c075d266f4f726ae6a44ff1471f1066cd7ef1f17ecf\ + ed620ed3af4771085175eb85df2ba06ba437beb0a676380a4982030100015f200754455354434852\ + 7f4c12060904007f000703010202530500000003005f25060205000100015f24060205000103015f\ + 378201007ecf161d4146d0015edbebf7ec3a18a46ac0cfae67a488f893018ad7958774e8fc716ed\ + 349e0015d90f769d472492cbc7a010ccf81fa26ab59223047d38a2e02e6687f7b313386ac3e0ed3\ + ca4fa3c93434d86ab1fe4023fee002001b9c2aa45827e9614fb4503624a02b552d908cec1b55868\ + c68d2d646475f2b02d9db4fe9c250e64966a533b015c2faa995ea254ac08eccade344425991c122\ + 0fd08db2205b72b1aa70ba538924061292a93c6420cab3d9322882f0282b7ada9a097926f566e42\ + d54f39320e29a031641aa96e91508e3176a4d554c503d7ab4942b759ee304c99668cb9e34b1eb99\ + 5890aa75d7325cc9d7262d0b410b617184fad6bcc81fbd"; + let data = hex_to_bytes(hex_data); + let cert = CVCertificate::parse(&data).expect("parse should succeed"); + + assert_eq!(cert.body.profile_identifier, 0); + assert_eq!(cert.body.certification_authority_reference, b"TESTCAR"); + assert_eq!(cert.body.certificate_holder_reference, b"TESTCHR"); + assert_eq!(cert.body.certificate_effective_date, CertificateDate { year: 25, month: 1, day: 1 }); + assert_eq!(cert.body.certificate_expiration_date, CertificateDate { year: 25, month: 1, day: 31 }); + + let chat = &cert.body.certificate_holder_authorization_template; + assert_eq!(chat.terminal_type.to_string(), "0.4.0.127.0.7.3.1.2.2"); + assert_eq!(chat.relative_authorization, vec![0x00, 0x00, 0x00, 0x03, 0x00]); + } + + #[test] + fn reject_profile_identifier_out_of_range() { + let data = build_certificate_with_fields( + &[0x01, 0x00], + b"CAR", + b"CHR", + &[2, 5, 0, 1, 0, 1], + &[2, 5, 0, 1, 0, 2], + ); + assert!(CVCertificate::parse(&data).is_err()); + } + + #[test] + fn reject_negative_profile_identifier() { + let data = build_certificate_with_fields( + &[0xFF], + b"CAR", + b"CHR", + &[2, 5, 0, 1, 0, 1], + &[2, 5, 0, 1, 0, 2], + ); + assert!(CVCertificate::parse(&data).is_err()); + } + + #[test] + fn reject_empty_car() { + let data = build_certificate_with_fields( + &[0x00], + b"", + b"CHR", + &[2, 5, 0, 1, 0, 1], + &[2, 5, 0, 1, 0, 2], + ); + assert!(CVCertificate::parse(&data).is_err()); + } + + #[test] + fn reject_chr_too_long() { + let data = build_certificate_with_fields( + &[0x00], + b"CAR", + b"0123456789ABCDEFG", + &[2, 5, 0, 1, 0, 1], + &[2, 5, 0, 1, 0, 2], + ); + assert!(CVCertificate::parse(&data).is_err()); + } + + #[test] + fn reject_invalid_date_length() { + let data = build_certificate_with_fields(&[0x00], b"CAR", b"CHR", &[2, 5, 0, 1, 0], &[2, 5, 0, 1, 0, 2]); + assert!(CVCertificate::parse(&data).is_err()); + } + + #[test] + fn reject_invalid_date_digit() { + let data = + build_certificate_with_fields(&[0x00], b"CAR", b"CHR", &[2, 5, 10, 1, 0, 1], &[2, 5, 0, 1, 0, 2]); + assert!(CVCertificate::parse(&data).is_err()); + } + + #[test] + fn reject_invalid_month() { + let data = + build_certificate_with_fields(&[0x00], b"CAR", b"CHR", &[2, 5, 1, 3, 0, 1], &[2, 5, 0, 1, 0, 2]); + assert!(CVCertificate::parse(&data).is_err()); + } + + #[test] + fn reject_empty_public_key() { + let data = build_certificate_with_public_key(&[]); + assert!(CVCertificate::parse(&data).is_err()); + } + + #[test] + fn allow_empty_chat_data() { + let data = build_certificate_with_chat_data(&[]); + let cert = CVCertificate::parse(&data).expect("parse should succeed"); + assert!(cert.body.certificate_holder_authorization_template.relative_authorization.is_empty()); + } + + #[test] + fn allow_empty_signature() { + let data = build_certificate_with_fields_and_signature( + &[0x00], + b"CAR", + b"CHR", + &[2, 5, 0, 1, 0, 1], + &[2, 5, 0, 1, 0, 2], + &[], + ); + let cert = CVCertificate::parse(&data).expect("parse should succeed"); + assert!(cert.signature.is_empty()); + } +} diff --git a/core-modules/asn1/src/lib.rs b/core-modules/asn1/src/lib.rs index d050262c..d58b0634 100644 --- a/core-modules/asn1/src/lib.rs +++ b/core-modules/asn1/src/lib.rs @@ -24,3 +24,4 @@ pub mod encoder; pub mod error; pub mod oid; pub mod tag; +pub mod cv_certificate; From be3ef857668c07dd5354ee01d36467c926e4a97d Mon Sep 17 00:00:00 2001 From: Tobias Schwerdtfeger Date: Fri, 9 Jan 2026 15:29:01 +0100 Subject: [PATCH 10/20] Add spec --- .../spec/BSI_TR-03110_Part-3-V2_2_layout.txt | 4985 +++++++++++++++++ core-modules/asn1/src/spec/cvc_schema.txt | 191 + 2 files changed, 5176 insertions(+) create mode 100644 core-modules/asn1/src/spec/BSI_TR-03110_Part-3-V2_2_layout.txt create mode 100644 core-modules/asn1/src/spec/cvc_schema.txt diff --git a/core-modules/asn1/src/spec/BSI_TR-03110_Part-3-V2_2_layout.txt b/core-modules/asn1/src/spec/BSI_TR-03110_Part-3-V2_2_layout.txt new file mode 100644 index 00000000..8bfbf1ef --- /dev/null +++ b/core-modules/asn1/src/spec/BSI_TR-03110_Part-3-V2_2_layout.txt @@ -0,0 +1,4985 @@ +Technical Guideline TR-03110 + +Advanced Security Mechanisms for Machine +Readable Travel Documents and eIDAS Token – +Part 3: Common Specifications + +Version 2.21 +21. December 2016 + History +Version Date Comment +1.00 2006-02-08 Initial public version. +1.01 2006-11-02 Minor corrections and clarifications. +1.10 2007-08-20 Revised version. +1.11 2008-02-21 Minor corrections and clarifications. +2.00 2008-10-27 Enhanced version. +2.01 2009-05-05 Minor corrections and clarifications. Additional Mapping for PACE. +2.02 2009-11-09 Adjustments to PACE required due to international standardization. +2.03 2010-03-24 Clarification on the definition of a session. Standardization of domain + parameters. Introduction of a secondary security object. +2.04 2010-09-15 Clarifications on certificate extensions. Improved handling of chip-specific keys + for privileged terminals. +2.05 2010-10-14 Clarifications on RFU-bits, “Read access to eID” deprecated +2.10 2012-03-20 Split into three parts +2.11 2013-07-12 Minor clarifications, addition of Envelope/Get Response +2.20 2015-02-03 Enhanced version with additional mechanisms. Split into four parts. + +2.21 2016-12-21 Clarifications, minor corrections and optimizations. Simplification of + authorization handling. + + + + +Federal Office for Information Security +Post Box 20 03 63 +D-53133 Bonn + +Phone: +49 22899 9582-0 +E-Mail: ExtendedAccessControl@bsi.bund.de +Internet: https://www.bsi.bund.de +© Federal Office for Information Security 2016 + Contents + + + +Contents +1 Introduction.......................................................................................................................................................................................... 7 +1.1 Requirements for ICCs and Terminals............................................................................................................................... 7 +1.2 Cryptography requirements................................................................................................................................................... 7 +1.3 Terminology................................................................................................................................................................................... 8 +1.4 Abbreviations................................................................................................................................................................................. 8 +2 Public Key Infrastructure............................................................................................................................................................. 10 +2.1 Country Verifying CA.............................................................................................................................................................. 10 +2.2 Document Verifiers.................................................................................................................................................................. 11 +2.3 Card Verifiable Certificates.................................................................................................................................................... 11 +2.4 Certificate Scheduling............................................................................................................................................................. 11 +2.5 Certificate Validation............................................................................................................................................................... 12 +2.6 Initial State of the ICC's trust-point(s)............................................................................................................................. 14 +2.7 Effective Authorization.......................................................................................................................................................... 14 +2.8 Terminal Sector.......................................................................................................................................................................... 15 +3 Management of Attributes.......................................................................................................................................................... 19 +3.1 Specific Attributes..................................................................................................................................................................... 19 +3.2 Generic Attributes..................................................................................................................................................................... 20 +3.3 Attribute Requests.................................................................................................................................................................... 20 +A. ASN.1 Specifications (Normative)............................................................................................................................................. 22 +A.1. Information on Supported Security Protocols............................................................................................................ 22 +A.2. Key Agreement........................................................................................................................................................................... 41 +A.3. PACE................................................................................................................................................................................................ 46 +A.4. Chip Authentication................................................................................................................................................................ 48 +A.5. Restricted Identification........................................................................................................................................................ 50 +A.6. Pseudonymous Signatures.................................................................................................................................................... 51 +A.7. Terminal Authentication....................................................................................................................................................... 53 +A.8. Enhanced Role Authentication........................................................................................................................................... 60 +B. ISO 7816 Mapping (Normative)................................................................................................................................................. 61 +B.1. PACE................................................................................................................................................................................................ 61 +B.2. Chip Authentication................................................................................................................................................................ 62 +B.3. Terminal Authentication....................................................................................................................................................... 65 +B.4. Restricted Identification........................................................................................................................................................ 66 +B.5. Pseudonymous Signature of Messages or Credentials............................................................................................. 66 +B.6. Auxiliary Data Verification.................................................................................................................................................... 68 +B.7. PIN Management...................................................................................................................................................................... 68 +B.8. eSign Application...................................................................................................................................................................... 69 +B.9. Reading Data Groups............................................................................................................................................................... 69 +B.10. Enhanced Role Authentication........................................................................................................................................... 69 +B.11. Switching of Session Context.............................................................................................................................................. 71 +B.12. Extended Length....................................................................................................................................................................... 72 + +Bundesamt für Sicherheit in der Informationstechnik 3 + Inhaltsverzeichnis + + +B.13. Command Chaining................................................................................................................................................................ 72 +B.14. APDU Specification.................................................................................................................................................................. 73 +C. CV Certificates (normative).......................................................................................................................................................... 86 +C.1. Certificate Profile....................................................................................................................................................................... 86 +C.2. Certificate Requests.................................................................................................................................................................. 87 +C.3. Certificate Extensions for Terminal Authentication Version 2............................................................................89 +C.4. Certificate Policy........................................................................................................................................................................ 91 +D. DER Encoding (Normative)......................................................................................................................................................... 93 +D.1. ASN.1............................................................................................................................................................................................... 93 +D.2. Data Objects................................................................................................................................................................................. 93 +D.3. Public Key Data Objects......................................................................................................................................................... 96 +E. Envelope/Get Response (Normative)...................................................................................................................................... 98 +E.1. Envelope........................................................................................................................................................................................ 99 +E.2. Get Response............................................................................................................................................................................... 99 +F. Secure Messaging (Normative)................................................................................................................................................ 100 +F.1. Session.......................................................................................................................................................................................... 100 +F.2. Session Context....................................................................................................................................................................... 100 +F.3. Message Structure of Secure Messaging APDUs....................................................................................................... 100 +F.4. Cryptographic Algorithms................................................................................................................................................. 102 +F.5. Send Sequence Counter....................................................................................................................................................... 103 +F.6. Secure Messaging Termination........................................................................................................................................ 103 + + +List of Figures +Figure 1: Public Key Infrastructure....................................................................................................................................................... 10 +Figure 2: Certificate Scheduling.............................................................................................................................................................. 12 +Figure 3: Revocation..................................................................................................................................................................................... 17 +Figure 4: Transformation of a command APDU........................................................................................................................... 104 +Figure 5: Transformation of a command APDU if no data is available..............................................................................104 +Figure 6: Transformation of a response APDU.............................................................................................................................. 105 + + +List of Tables +Table 1: Key words........................................................................................................................................................................................... 8 +Table 2: Elementary Files CardAccess, CardSecurity and ChipSecurity...............................................................................37 +Table 3: Algorithms and Formats for Key Agreement.................................................................................................................. 41 +Table 4: Standardized Domain Parameters....................................................................................................................................... 42 +Table 5: Encoding of Passwords.............................................................................................................................................................. 45 +Table 6: Object Identifiers for PACE with DH................................................................................................................................... 46 +Table 7: Object Identifiers for PACE with ECDH............................................................................................................................. 46 +Table 8: Object Identifiers for Chip Authentication with DH................................................................................................... 48 +Table 9: Object Identifiers for Chip Authentication with ECDH.............................................................................................49 +Table 10: Object Identifiers for PSA based on ECSchnorr with ECDH..................................................................................50 +Table 11: Object Identifiers for Restricted Identification with DH.........................................................................................50 +Table 12: Object Identifiers for Restricted Identification with ECDH...................................................................................51 +Table 13: Object Identifiers for PSM and PSC based on ECSchnorr with ECDH..............................................................52 +Table 14: Credential data format for PSC........................................................................................................................................... 53 + + +4 Bundesamt für Sicherheit in der Informationstechnik + Contents + + +Table 15: Certificate Holder Reference................................................................................................................................................. 53 +Table 16: Elementary File EF.CVCA....................................................................................................................................................... 55 +Table 17: Object Identifiers for Terminal Authentication with RSA......................................................................................56 +Table 18: Object Identifiers for Terminal Authentication with ECDSA................................................................................57 +Table 19: Authenticated Auxiliary Data............................................................................................................................................... 58 +Table 20: Chip Authentication Version 3 - General Authenticate command for Key Agreement............................63 +Table 21: Chip Authentication Version 3 - General Authenticate command for PSA...................................................64 +Table 22: Pseudonymous Signature of Messages - PSO:Compute Digital Signature command..............................67 +Table 23: CV Certificate Profile................................................................................................................................................................ 86 +Table 24: CV Certificate Request Profile.............................................................................................................................................. 88 +Table 25: Certificate Extensions.............................................................................................................................................................. 89 +Table 26: Evolution of Authorization Extensions........................................................................................................................... 90 +Table 27: Overview on Data Objects (sorted by Tag)...................................................................................................................... 93 +Table 28: ISO/IEC 8859-1 Character Set.............................................................................................................................................. 95 +Table 29: RSA Public Key............................................................................................................................................................................ 96 +Table 30: DH Public Key.............................................................................................................................................................................. 97 +Table 31: EC Public Keys............................................................................................................................................................................. 97 +Table 32: Usage of Secure Messaging Data Objects...................................................................................................................... 101 + + + + +Bundesamt für Sicherheit in der Informationstechnik 5 + Introduction 1 + + + +1 Introduction +This Part of the Technical Guideline gives the common specifications, comprising the PKI used for +Access Control as well as a mapping of the protocols to ASN.1- and APDU-specifications, for the +protocols defined in Part 1 and Part 2: + • Part 1: + ◦ Terminal Authentication version 1 + ◦ Chip Authentication version 1 + • Part 2: + ◦ Password Authenticated Connection Establishment (PACE) + ◦ Chip Authentication version 2 + ◦ Chip Authentication version 3 + ◦ Terminal Authentication version 2 + ◦ Restricted Identification + ◦ Pseudonymous Signature +Although the specifications of PACEv2 in [8] are compatible to the specifications in this document, +please refer to [8] for an implementation of PACE according to Part 1. +In this Technical Guideline, documents which only implement the protocols described in Part 1 of this +Guideline are designated “MRTDs”, while documents implementing protocols from Part 2 or from both +Parts are designated “eIDAS token”. + + +1.1 Requirements for ICCs and Terminals +This Technical Guideline specifies requirements for implementations of ICCs and terminals. While ICCs +must comply with those requirements according to the terminology described in Section 1.3, +requirements for terminals are to be interpreted as guidance, i.e. interoperability of ICC and terminal +are only guaranteed if the terminal complies with those requirements, otherwise the interaction with +the ICC will either fail or the behavior of the ICC is undefined. In general, the ICC need not enforce +requirements related to terminals unless the security of the ICC is directly affected. + + +1.2 Cryptography requirements +This Technical Guideline specifies objects identifiers of the protocols for different cryptographic +parameters. Furthermore, this Technical Guideline defines IDs for different domain parameters that can +be used within the protocols. +It should be noted that the selection of suitable key lengths is up to the document issuer and not within +the scope of this Technical Guideline. Suitable standards and algorithm catalogues from IT security +authorities should be taken into account for selection of appropriate algorithms and key lengths. +Guidance on suitable cryptographic algorithms may also be found in [28]. + + + + +Bundesamt für Sicherheit in der Informationstechnik 7 + 1 Introduction + + + +1.3 Terminology +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD +NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described +in RFC 2119 [2]. The key word "CONDITIONAL" is to be interpreted as follows: +CONDITIONAL: The usage of an item is dependent on the usage of other items. It is therefore further + qualified under which conditions the item is REQUIRED or RECOMMENDED. +When used in tables (profiles), the key words are abbreviated as shown in Table 1. + + Key word Abbrev. + MUST / SHALL REQUIRED m + MUST NOT / SHALL NOT – x + SHOULD RECOMMENDED r + MAY OPTIONAL o + – CONDITIONAL c + Table 1: Key words + + + + +1.4 Abbreviations +The following abbreviations are commonly used throughout this specification. + Name Abbreviation + Binary Coded Digit BCD + Card Verifiable CV + Card/Chip Security Object SO C + + Certification Authority CA + Chip Identifier ID ICC + Chip Authentication Public Key PK ICC + Chip Authentication Private Key SK ICC + Country Signing CA CSCA + Country Verifying CA CVCA + Country Verifying CA Certificate C CVCA + Document Security Object SO D + Data Group DG + Document Verifier DV + Document Verifier Certificate C DV + Domain Parameters D + Ephemeral Private Key  + SK + Ephemeral Public Key  + PK + + + +8 Bundesamt für Sicherheit in der Informationstechnik + Introduction 1 + + + Name Abbreviation + Hash Function H + International Civil Aviation Organization ICAO + Key Agreement Function KA + Key Derivation Function KDF + Logical Data Structure LDS + Machine Readable Travel Document MRTD + Proximity Integrated Circuit Chip PICC + Proximity Coupling Device PCD + Restricted Identification Public Key PK ID + Restricted Identification Private Key SK ID + Sector Public Key PK Sector + Sector Private Key SK Sector + Sector + Sector-specific Identifier I ID + Terminal Authentication Public Key PK PCD + Terminal Authentication Private Key SK PCD + Terminal Certificate CT + Pseudonymous Signature Group Public Key PK ICC + Pseudonymous Signature Individual Public Keys PK ICC ,1, PK ICC ,2 + Pseudonymous Signature Sector-specific Identifier I Sector + ICC ,i + + Identifier of the Pseudonymous Signature variant ID DSI + + + + +Bundesamt für Sicherheit in der Informationstechnik 9 + 2 Public Key Infrastructure + + + +2 Public Key Infrastructure +Terminal Authentication requires the terminal to prove to the ICC that it is entitled to access sensitive +data. Such a terminal is equipped with at least one Terminal Certificate, encoding the terminal’s public +key and access rights, and the corresponding private key. After the terminal has proven knowledge of +this private key, the ICC grants the terminal access to sensitive data as indicated in the Terminal +Certificate. +The PKI required for issuing and validating Terminal Certificates consists of the following entities: + 1. Country Verifying CAs (CVCAs) + 2. Document Verifiers (DVs) + 3. Terminals +This PKI forms the basis of Extended Access Control and is also abbreviated by EAC-PKI. It is illustrated +in Figure 1. + + +2.1 Country Verifying CA +Every State is required to set up one trust-point that issues Document Verifier Certificates: the Country +Verifying CA (CVCA). + +Note: The Country Signing CA issuing certificates for Document Signers (cf. [8]) and the Country +Verifying CA MAY be integrated into a single entity, e.g. a Country CA. However, even in this case, +separate key pairs MUST be used for different roles. +A CVCA determines the access rights to national ICCs for all DVs (i.e. official domestic DVs as well as the +foreign/commercial DVs) by issuing certificates for DVs entitled to access some sensitive data. The +conditions under which a CVCA grants a DV access to sensitive data is out of the scope of this +document and SHOULD be stated in a certificate policy (cf. Appendix C.4). +Document Verifier Certificates MUST contain information, such as which data a certain DV is entitled +to access. To diminish the potential risk introduced by lost or stolen terminals Document Verifier + + Country A Country B + + DV-Cert. Assigns: + CVCA - Access Rights + - Validity Period + CVCA + + + + + Term.-Cert. restricts: + DV DV - Access Rights + - Validity Period + DV DV + + + Term. ... Term. Term. ... Term. Term. ... Term. Term. ... Term. + + Arrows denote certification + + Figure 1: Public Key Infrastructure + + +10 Bundesamt für Sicherheit in der Informationstechnik + Public Key Infrastructure 2 + + +Certificates MUST contain a short validity period. The validity period is assigned by the issuing CVCA at +its own choice and this validity period may differ depending on the Document Verifier the certificate is +issued to. + + +2.2 Document Verifiers +A Document Verifier (DV) is an organizational unit that manages a group of terminals (e.g. terminals +operated by a State’s border police) by – inter alia – issuing Terminal Certificates. A Document Verifier is +therefore a CA, authorized by at least the national CVCA to issue certificates for its terminals. The +Terminal Certificates issued by a DV usually inherit both the access rights and the validity period from +the Document Verifier Certificate, however, the Document Verifier MAY choose to further restrict the +access rights or the validity period depending on the terminal the certificate is issued for. +If a Document Verifier requires its terminals to access sensitive data stored on other States’ ICCs, it +MUST apply for a DV Certificate issued by the CVCA of the respective States. The Document Verifier +MUST also ensure that all received Document Verifier Certificates are forwarded to the terminals within +its domain. + + +2.3 Card Verifiable Certificates +CVCA Link Certificates, DV Certificates, and Terminal Certificates are to be validated by ICCs. Due to the +computational restrictions of those chips, the certificates MUST be in a card verifiable format: + • The certificate format and profile specified in Appendix C.1 SHALL be used. + • The signature algorithm, domain parameters, and key sizes to be used are determined by the + CVCA of the issuing State, i.e. the same signature algorithm, domain parameters and key sizes + MUST be used within a certificate chain.1 + • CVCA Link Certificates MAY include a public key that deviates from the current parameters, i.e. + the CVCA MAY switch to a new signature algorithm, new domain parameters, or key sizes. + + +2.4 Certificate Scheduling +Each certificate MUST contain a validity period. This validity period is identified by two dates, the +certificate effective date and the certificate expiration date. +Certificate Effective Date: The certificate effective date SHALL be the date of the certificate generation. +Certificate Expiration Date: The certificate expiration date SHALL be the date after which the +certificate expires. It may be arbitrarily chosen by the certificate issuer. +When generating certificates, the issuer MUST carefully plan the roll-over of certificates, as sufficient +time for propagation of certificates and set up of certificate chains MUST be provided. Obviously, a new +certificate must be generated before the current certificate expires. To realize the link of trust between +consecutive CVCA certificates, CVCA Link Certificates have to be produced. CVCA Link Certificates +MUST be signed with the previous CVCA key, i.e. the CVCA key with the most recent effective date. +In each case, the resulting maximum distribution time equals the certificate expiration date of the old +certificate minus the certificate effective date of the new certificate. For the application and + + +1 As a consequence Document Verifiers and terminals will have to be provided with several key pairs. + +Bundesamt für Sicherheit in der Informationstechnik 11 + 2 Public Key Infrastructure + + +distribution of certificates, the communication protocols specified in TR-03129 [3] are +RECOMMENDED. Certificate scheduling is illustrated in Figure 2. + + Certificate effective date + Certificate expiration date + + + CVCA + + + + Max. distribution time + + + + + DV + + + + + Terminal + + + + + Figure 2: Certificate Scheduling + + +2.5 Certificate Validation +To validate a Terminal Certificate, the ICC MUST be provided with a certificate chain starting at a +trust-point stored on the ICC. Those trust-points are more or less recent public keys of the ICC’s CVCA. +The initial trust-point(s) SHALL be stored securely in the ICC’s memory in the production or (pre-) +personalization phase. +As the key pair used by the CVCA changes over time, the ICC is REQUIRED to internally update its +trust-point(s) according to received valid link certificates. +The ICC MUST be able to store up to two trust-points per application. + +Note: Due to the scheduling of CVCA Link Certificates (cf. Figure 2), at most two trust-points per +application need to be stored on the ICC. +The ICC MUST accept expired CVCA Link Certificates but it MUST NOT accept expired DV and +Terminal Certificates. To determine whether a certificate is expired, the ICC SHALL use its current date. +Current Date: If the ICC has no internal clock, the current date of the ICC SHALL be approximated as +described in the following. The date is autonomously approximated by the ICC using the most recent +certificate effective date contained in a valid CVCA Link Certificate, a DV Certificate or an Accurate +Terminal Certificate. + +12 Bundesamt für Sicherheit in der Informationstechnik + Public Key Infrastructure 2 + + +Accurate Terminal Certificate: A Terminal Certificate is accurate, if the issuing Document Verifier is +trusted by the ICC to produce Terminal Certificates with the correct certificate effective date. A valid +Terminal Certificate MUST be accepted as accurate by the ICC if it was issued by an official domestic DV +and SHOULD NOT be accepted as accurate otherwise. +A terminal MAY send CVCA Link Certificates, DV Certificates, and Terminal Certificates to an ICC to +update the current date and the trust-point stored on the ICC even if the terminal does not intend to or +is not able to continue with Terminal Authentication. + +Note: The ICC only verifies that a certificate is apparently recent (i.e. with respect to the approximated +current date). + + +2.5.1 General Procedure +The certificate validation procedure consists of three steps: + 1. Certificate Verification: The signature MUST be valid and unless the certificate is a CVCA Link + Certificate, the certificate MUST NOT be expired. If the verification fails, the procedure SHALL + be aborted. + 2. Internal Status Update: The current date MUST be updated, the public key and the attributes + (including relevant certificate extensions) MUST be imported, new trust-points MUST be + enabled, expired trust-points MUST be disabled for the verification of DV Certificates. + 3. Cleanup: The chip SHALL provide at most two enabled trust-points per application. If more + than two trust-points for an application remain enabled after the internal status update, the + trust-point with the least recent effective date SHALL be disabled. +The operation of updating the current date and the operations of enabling and disabling a trust-point +MUST be implemented as an atomic operation. +Enabling a trust-point: The new trust-point SHALL be added to the list of trust-points. +Disabling a trust-point: Expired trust-points MUST NOT be used for the verification of DV Certificates. + In case of ICCs where the current date may be advanced beyond the expiry date of a trust-point, e.g. + ICCs with more than one application or ICCs using an internal clock, expired trust-points MUST + remain usable for the verification of CVCA Link Certificates. Disabled trust-points MAY be deleted + after the successful import of the successive Link Certificate. + +Note: In case of single-application ICCs with no internal clock, the above specification is equivalent to +the specification in version 1.11 of this Guideline. + + +2.5.2 Example Procedure +The following validation procedure, provided as an example, MAY be used to validate a certificate chain. +For each received certificate the ICC performs the following steps: + 1. The ICC verifies the signature on the certificate. If the signature is incorrect, the verification + fails. + 2. If the certificate is not a CVCA Link Certificate, the certificate expiration date is compared to the + ICC’s current date. If the expiration date is before the current date, the verification fails. + 3. The certificate is accepted as valid and the public key and the attributes (including relevant + certificate extensions) contained in the certificate are imported. + + +Bundesamt für Sicherheit in der Informationstechnik 13 + 2 Public Key Infrastructure + + + i For CVCA, DV, and Accurate Terminal Certificates: The certificate effective date is compared to + the ICC’s current date. If the current date is before the effective date, the current date is + updated to the effective date. + ii For CVCA Link Certificates: The new CVCA public key is added to the list of trust-points stored + securely in the ICC’s memory. The new trust-point is then enabled. + iii For DV and Terminal Certificates: The new DV or terminal public key is temporarily imported + for subsequent certificate verification or Terminal Authentication, respectively. + 4. Expired trust-points stored securely in the ICC’s memory are disabled for the verification of DV + Certificates and may be removed from the list of trust-points. + + +2.6 Initial State of the ICC's trust-point(s) +The (pre-)personalization agent SHALL + • set the current date of the ICC to the date of the (pre-)personalization, and + • personalize the CVCA key with the most recent effective date as trust-point. +The (pre-)personalization agent MAY additionally personalize the previous CVCA key as trust-point. + + +2.7 Effective Authorization +Each certificate SHALL contain a Certificate Holder Authorization Template (CHAT) (cf. Appendix C.1.5) +and MAY contain Authorization Extensions (cf. Appendix C.3.1). + • The Certificate Holder Authorization Template identifies the terminal type (cf. Parts 1 and 2 of + this Technical Guideline). + • The Certificate Holder Authorization Template and the Authorization Extensions determine the + relative authorization of the certificate holder assigned by the issuing certificate authority. +To determine the effective authorization of a certificate holder, the ICC MUST perform the following: + 1. If an Authorization Extension supported by the ICC is missing in a certificate of the certificate + chain, the corresponding relative authorization of the certificate holder SHALL be set all to '0' + for calculation of the effective authorization. + 2. For the CHAT and for each supported Authorization Extension, the ICC MUST calculate a + bitwise Boolean ’and’ of the relative authorization contained in the Terminal Certificate, the + referenced Document Verifier Certificate, and the referenced CVCA Certificate. + + +2.7.1 Confined Authorization (eIDAS token only) +The effective authorization may be further restricted by using the General Authentication Procedure +(cf. Part 2 of this Technical Guideline). In this case, the terminal performing the General Authentication +Procedure (cf. Part 2) MUST indicate the terminal type and the confined authorization (i.e. the effective +authorization required by the terminal) as part of PACE. If the ICC supports Authorization Extensions, +the confined authorization SHALL include the relevant Authorization Extensions of the Terminal +Certificate. Otherwise, the Authorization Extension SHALL be omitted by the terminal. +The confined authorization SHALL be used by the ICC to compute the effective authorization as part of +Terminal Authentication of the General Authentication Procedure phase (i.e. the first Terminal + +14 Bundesamt für Sicherheit in der Informationstechnik + Public Key Infrastructure 2 + + +Authentication of a session). For that purpose, the ICC SHALL include the confined authorization by +calculating a bitwise Boolean ’and’ in step 2. of Section 2.7 for the computation of the effective +authorization. +If switching of session contexts is supported and Terminal Authentication is performed as part of +Enhanced Role Authentication, the confined authorization SHALL be omitted by the ICC to compute +the effective authorization of an Attribute Provider. + +Note: The ICC MUST verify that the terminal type indicated in the confined authorization and the +terminal type in the relative authorization of each certificate of the certificate chain are equal. If a +mismatch is detected, the ICC SHALL reset the access rights and indicate an error (cf. Appendix B.14.7). + + +2.7.2 Interpretation (all document types) +The effective authorization SHALL be interpreted by the ICC as follows: + • The effective role is a CVCA: + ◦ This link certificate was issued by the national CVCA. + ◦ The ICC MUST update its internal trust-point, i.e. the public key and the relative + authorization. + ◦ The certificate issuer is a trusted source of time. If the ICC has no internal clock, the ICC + MUST update its current date using the Certificate Effective Date. + ◦ The ICC MUST NOT grant the CVCA access to sensitive data (i.e. the effective authorization + SHOULD be ignored). + • The effective role is a DV: + ◦ The certificate was issued by the national CVCA for an authorized DV. + ◦ The certificate issuer is a trusted source of time. If the ICC has no internal clock, the ICC + MUST update its current date using the Certificate Effective Date. + ◦ The ICC MUST NOT grant a DV access to sensitive data (i.e. the effective authorization + SHOULD be ignored). + • The effective role is a Terminal: + ◦ The certificate was issued by either an official domestic, a foreign, or a non-official DV. + ◦ If the certificate is an accurate terminal certificate (cf. Section 2.5), the issuer is a trusted + source of time. If the ICC has no internal clock, the ICC MUST update its current date using + the Certificate Effective Date. + ◦ The ICC MUST grant the authenticated terminal access to sensitive data according to the + effective authorization. + + +2.8 Terminal Sector +To support + • Restricted Identification + • Pseudonymous Signatures + • Enhanced Role Authentication + +Bundesamt für Sicherheit in der Informationstechnik 15 + 2 Public Key Infrastructure + + +terminals MUST be assigned a Terminal Sector. The Terminal Sector SHALL be contained in the +Terminal Certificate and thus, it is RECOMMENDED that the Terminal Sector is generated by the +certifying Document Verifier. In any case, the Terminal Sector MUST NOT be chosen by the terminal +itself. +The Terminal Sector is always a public key. It MAY be chosen either verifiably at random with an +unknown private key to disable tracing completely (in this case linking sector-specific identifiers across +sectors is computationally impossible) or as key pair to enable revocation based on sector-specific +identifiers. +The definition of a Sector is up to the policy of the Issuer of the ICC. + + +2.8.1 Sector Key Pair +Sector Key Pairs MUST be generated by all Document Verifiers that support sector-specific revocation +of ICCs. +Each Document Verifier SHALL perform the following steps for every subordinated sector: + 1. Generate a new Sector Key Pair based on the Revocation Sector Public Key. + 2. Store the Sector Private Key securely (at the Document Verifier). + 3. Include the Sector Public Key in every Terminal Certificate of all terminals belonging to the + corresponding sector. +The Revocation Sector Key Pair SHALL be generated by the CVCA. The CVCA MAY delegate the +revocation service to a service provider. + + +2.8.2 Sector-Specific Revocation of ICCs +At the (pre-) personalization of the ICC, a key pair for Restricted Identification SHALL be generated. For +Chip Authentication version 3, the ICC's private key is part of the ICC's private keys for Chip +Authentication Version 3 or Pseudonymous Signatures described in A.4.2.1. +The private key SHALL be stored in the ICC. If the public key is used to enable revocation of the ICC (i.e. +PK ID for Restricted Identification or PK ICC ,i for Pseudonymous Signatures), the public key SHALL be +stored in a database together with other data identifying the holder of the MRTD . + +Note: The generation of the key pair for Restricted Identification MAY be performed within the ICC or +externally. The key pair MUST be chosen to be unique and MAY be either chip-specific or +holder-specific (i.e. the same key pair will be used on subsequent ICCs). At least one key pair used for +Restricted Identification MUST be chip-specific. +To revoke the ICC, the chip-specific public key of the ICC is looked up in the database and transferred to +the CVCA. The CVCA then transforms the public key using its Revocation Sector Private Key. The +transformed public key is then transferred to all subordinated Document Verifiers. Each Document +Verifier calculates the sector-specific identifiers using the Sector Private Keys for all subordinated +Terminal Sectors. Finally, the sector-specific identifier is transferred to all terminals of the +corresponding sector. + + + + +16 Bundesamt für Sicherheit in der Informationstechnik + Public Key Infrastructure 2 + + + + + Figure 3: Revocation + + +2.8.3 Generation of Revocation Lists +The CVCA publishes the Revocation Sector Public Key PK Revocation and the domain parameters D . Each +Document Verifier randomly chooses a Sector Private Key SK Sector for every subordinated sector and +calculates the Sector Public Key as PK Sector =KA SK Sector , PK Revocation , D. +To revoke an ICC, a revocation request is sent to the CVCA containing the Restricted Identification + PK ID or Pseudonymous Signature Public Key PK ID := PK ICC , i . The sector-specific identities are +calculated as follows: + Revocation + 1. The CVCA calculates PK ID =KA  SK Revocation , PK ID , D using its private key SK Revocation and + the Restricted Identification Public Key PK ID received with the revocation request. The + Revocation + transformed public key PK ID is forwarded to all subordinated Document Verifiers. + 2. Each Document Verifier calculates the sector-specific identifier for all subordinated sectors. For each + Sector + sector the Document Verifier calculates I ID =F(KA (SK Sector , PK Revocation + ID , D)) using the + Revocation + corresponding Sector Private Key SK Sector , the received public key PK ID of the ICC to be + revoked and the hash function of the protocol object identifier as F for Restricted Identification + sector-specific identifiers or identity function as F for Pseudonymous Signature sector-specific + Sector + identifiers. The sector-specific identifier I ID is then forwarded to the terminals of the + corresponding sector. + + +Bundesamt für Sicherheit in der Informationstechnik 17 + 2 Public Key Infrastructure + + +2.8.4 Sector-specific Whitelisting of ICCs +The sector-specific identifiers generated with Chip Authentication version 3 or Pseudonymous +Signatures can also be used for the generation of Whitelists. In this case, the same procedure as for +revoking ICC's is performed with the generated ICCs. If an ICC is revoked, the corresponding +sector-specific identifier SHALL be deleted from the Whitelist. + + +2.8.5 Validity Period +In contrast to the Terminal Key Pair (for Terminal Authentication), the Sector Key Pair is valid for a long +time and MUST be chosen appropriately. + + +2.8.6 Migrating Terminals +To migrate a terminal from one Document Verifier to another Document Verifier, the sector key pair of +the terminal MUST be transferred securely to the new Document Verifier. + +Note: Migrating a terminal to a Document Verifier supervised by another CVCA is not possible. + + + + +18 Bundesamt für Sicherheit in der Informationstechnik + Management of Attributes 3 + + + +3 Management of Attributes +Enhanced Role Authentication (if supported by the ICC) enables Attribute Terminals manage additional +attributes on the ICC. +Management of attributes consists of the following functions: + • Requesting Attributes + • Reading Attribute Requests + • Writing Attributes + • Reading Attributes + • Deleting Attributes +The following classes of attributes are defined: + • Specific Attributes + • Generic Attributes + + +3.1 Specific Attributes +Specific Attributes are attributes that are stored in data containers, each bijectively linked to the hash of +a Sector Public Key contained in the Terminal Sector as defined in C.3.2.1 of requesting terminal's CV +Certificate. +The ASN.1 structure for Specific Attributes is specified in A.8.2. Commands for management of Specific +Attributes are specified in Appendix B. +Data containers nest data and their corresponding security attributes. However, the inherent structure +of data containers is out of scope of this document, i.e. containers can be files of self-controlled data +objects. +If the ICC supports Specific Attributes, it MUST also support Attribute Requests. + + +3.1.1 Reading and deleting Specific Attributes +The ICC SHALL restrict read and delete access to Specific Attribute containers to authenticated +terminals with the corresponding access right of the terminal. +If the terminal has effective authorization for reading/deleting Specific Attributes of all Terminal +Sectors, the ICC SHALL grant access to all Specific Attribute containers and MUST respond/delete all +Specific Attributes upon request of the terminal. +If the terminal's effective authorization is restricted to reading/deleting of Specific Attributes linked to +the hash of a Sector Public Key of the terminal's CV Certificate, the following steps MUST be performed +to read/delete Specific Attributes: + • The terminal MUST present the hash of its Sector Public Key to be used as user ID to the ICC. + • The ICC MUST verify that the hash of the Sector Public Key is contained in the Terminal Sector + of the terminal's CV Certificate sent during Terminal Authentication. + + + + +Bundesamt für Sicherheit in der Informationstechnik 19 + 3 Management of Attributes + + + • If the verification was successful, the ICC SHALL grant read/delete access to the Specific + Attribute container linked to the terminal's presented user ID and MUST respond/delete the + Specific Attributes upon request of the terminal. +If the terminal has no effective authorization for reading/deleting Specific Attributes, the ICC SHALL +NOT grant access to read/delete Specific Attributes. + + +3.1.2 Writing Specific Attributes +The ICC SHALL restrict read access to the Attribute Request container and write access to a Specific +Attribute container to authenticated terminals with the corresponding effective authorization +(Attribute Provider). +If no Attribute Request is present on the ICC, writing Specific Attribute MUST be denied by the ICC. If +the terminal writes a Specific Attribute to the ICC, the attribute MUST be added to the data container +that is linked to the user ID of the Attribute Request. + +Note: In order to avoid that single data containers take too much storage on the ICC, it can be advisable +to limit the maximum size of a data container taking into account the expected number and sizes of +relevant Specific Attributes. + + +3.2 Generic Attributes +Generic Attributes are attributes that are not linked to the Terminal Sector of the requesting terminal. +Each Generic Attribute is stored in a file, identified by a file identifier. +The ICC SHALL restrict read or write access or deletion of Generic Attributes to authenticated terminals +with the corresponding effective authorization. +If the ICC supports Generic Attributes, it MAY also support Attribute Requests. The ICC SHOULD allow +writing of Generic Attributes without Attribute Request stored on the ICC. +A Logical Data Structure and access rights for Generic Attributes are described in Part 4 of this Technical +Guideline. Commands for the management of Generic Attributes are specified in Appendix B. + + +3.3 Attribute Requests +If a terminal needs additional attributes not available on the ICC, it MAY write an Attribute Request to +the ICC. Attribute Requests are stored in a particular Attribute Request container. +Writing of Attribute Requests SHALL be restricted to authenticated terminals with the effective +authorization for writing Attribute Requests. +The following steps MUST be performed to write an Attributes Request on the ICC: + • The terminal SHALL present the hash of the Sector Public Key to be used as user ID to the ICC. + • The ICC MUST verify that the hash of the Sector Public Key Data is contained in the Terminal + Sector of the terminal's CV Certificate sent during Terminal Authentication. If the verification + was successful, the ICC SHALL grant write access to the Attribute Request container. + • The terminal MAY store an Attribute Request to the ICC's Attribute Request container. The ICC + SHALL make an internal link between the Attribute request and the user ID of the requesting + terminal. + +20 Bundesamt für Sicherheit in der Informationstechnik + Management of Attributes 3 + + +Reading of Attribute Requests SHALL be restricted to authenticated terminals with the effective +authorization for reading Attribute Requests. A terminal with effective authorization MAY read an +Attribute Request stored on the ICC (without presentation of its user ID). +The ICC SHALL provide only one data container for storage of Attribute Requests that must be shared +by all terminals. If a previous request is already stored on the ICC, the stored Attribute Request MUST be +replaced with the new one, i.e. the previous request is deleted. +The ASN.1 structure to be used for Attribute Requests is defined in Appendix A.8.1. + + + + +Bundesamt für Sicherheit in der Informationstechnik 21 + A. ASN.1 Specifications (Normative) + + + +A. ASN.1 Specifications (Normative) +The object identifiers used in this Technical Guideline are contained in the subtree of bsi-de: + bsi-de OBJECT IDENTIFIER ::= { + itu-t(0) identified-organization(4) etsi(0) + reserved(127) etsi-identified-organization(0) 7 + } + + +A.1. Information on Supported Security Protocols +The ASN.1 data structure SecurityInfos SHALL be provided by the ICC to indicate supported +security protocols. The data structure is specified as follows: + SecurityInfos ::= SET OF SecurityInfo + + SecurityInfo ::= SEQUENCE { + protocol OBJECT IDENTIFIER, + requiredData ANY DEFINED BY protocol, + optionalData ANY DEFINED BY protocol OPTIONAL + } + +The elements contained in a SecurityInfo data structure have the following meaning: + • The object identifier protocol identifies the supported protocol. + • The open type requiredData contains protocol specific mandatory data. + • The open type optionalData contains protocol specific optional data. + + +A.1.1. Supported Protocols +The ASN.1 specifications for the protocols provided in this specification are described in the following. + +Note: ICCs implemented according to Version 1.0.x of this specification will only provide a +ChipAuthenticationPublicKeyInfo. +In this case, the terminal SHOULD assume the following: + • The ICC supports Chip Authentication in version 1. + • The ICC may support Terminal Authentication in version 1. +To determine whether or not sensitive data protected by Terminal Authentication is stored on the +ICC, the terminal may consult the Document Security Object and the elementary file EF.CVCA. +A.1.1.1. PACE +To indicate support for PACE SecurityInfos may contain the following entries: + • At least one PACEInfo using a standardized domain parameter MUST be present. + • For each supported set of explicit domain parameters a PACEDomainParameterInfo MUST + be present. + • For each supported global user credential, a PasswordInfo MAY be present. +PACEInfo: This data structure provides detailed information on an implementation of PACE. + +22 Bundesamt für Sicherheit in der Informationstechnik + ASN.1 Specifications (Normative) A. + + + • The object identifier protocol SHALL identify the algorithms to be used (i.e. key agreement, + symmetric cipher and MAC). + • The integer version SHALL identify the version of the protocol. Version 1 is deprecated and it + is RECOMMENDED to only use version 2. + • The integer parameterId is used to indicate the domain parameter identifier. It MUST be + used if the ICC uses standardized domain parameters (cf. Table 4) or provides multiple explicit + domain parameters for PACE. + id-PACE OBJECT IDENTIFIER ::= { + bsi-de protocols(2) smartcard(2) 4 + } + + id-PACE-DH-GM OBJECT IDENTIFIER ::= {id-PACE 1} + id-PACE-DH-GM-3DES-CBC-CBC OBJECT IDENTIFIER ::= {id-PACE-DH-GM 1} + id-PACE-DH-GM-AES-CBC-CMAC-128 OBJECT IDENTIFIER ::= {id-PACE-DH-GM 2} + id-PACE-DH-GM-AES-CBC-CMAC-192 OBJECT IDENTIFIER ::= {id-PACE-DH-GM 3} + id-PACE-DH-GM-AES-CBC-CMAC-256 OBJECT IDENTIFIER ::= {id-PACE-DH-GM 4} + + id-PACE-ECDH-GM OBJECT IDENTIFIER ::= {id-PACE 2} + id-PACE-ECDH-GM-3DES-CBC-CBC OBJECT IDENTIFIER ::= {id-PACE-ECDH-GM 1} + id-PACE-ECDH-GM-AES-CBC-CMAC-128 OBJECT IDENTIFIER ::= {id-PACE-ECDH-GM 2} + id-PACE-ECDH-GM-AES-CBC-CMAC-192 OBJECT IDENTIFIER ::= {id-PACE-ECDH-GM 3} + id-PACE-ECDH-GM-AES-CBC-CMAC-256 OBJECT IDENTIFIER ::= {id-PACE-ECDH-GM 4} + + id-PACE-DH-IM OBJECT IDENTIFIER ::= {id-PACE 3} + id-PACE-DH-IM-3DES-CBC-CBC OBJECT IDENTIFIER ::= {id-PACE-DH-IM 1} + id-PACE-DH-IM-AES-CBC-CMAC-128 OBJECT IDENTIFIER ::= {id-PACE-DH-IM 2} + id-PACE-DH-IM-AES-CBC-CMAC-192 OBJECT IDENTIFIER ::= {id-PACE-DH-IM 3} + id-PACE-DH-IM-AES-CBC-CMAC-256 OBJECT IDENTIFIER ::= {id-PACE-DH-IM 4} + + id-PACE-ECDH-IM OBJECT IDENTIFIER ::= {id-PACE 4} + id-PACE-ECDH-IM-3DES-CBC-CBC OBJECT IDENTIFIER ::= {id-PACE-ECDH-IM 1} + id-PACE-ECDH-IM-AES-CBC-CMAC-128 OBJECT IDENTIFIER ::= {id-PACE-ECDH-IM 2} + id-PACE-ECDH-IM-AES-CBC-CMAC-192 OBJECT IDENTIFIER ::= {id-PACE-ECDH-IM 3} + id-PACE-ECDH-IM-AES-CBC-CMAC-256 OBJECT IDENTIFIER ::= {id-PACE-ECDH-IM 4} + + PACEInfo ::= SEQUENCE { + protocol OBJECT IDENTIFIER( + id-PACE-DH-GM-3DES-CBC-CBC | + id-PACE-DH-GM-AES-CBC-CMAC-128 | + id-PACE-DH-GM-AES-CBC-CMAC-192 | + id-PACE-DH-GM-AES-CBC-CMAC-256 | + id-PACE-ECDH-GM-3DES-CBC-CBC | + id-PACE-ECDH-GM-AES-CBC-CMAC-128 | + id-PACE-ECDH-GM-AES-CBC-CMAC-192 | + id-PACE-ECDH-GM-AES-CBC-CMAC-256 | + id-PACE-DH-IM-3DES-CBC-CBC | + id-PACE-DH-IM-AES-CBC-CMAC-128 | + id-PACE-DH-IM-AES-CBC-CMAC-192 | + id-PACE-DH-IM-AES-CBC-CMAC-256 | + id-PACE-ECDH-IM-3DES-CBC-CBC | + id-PACE-ECDH-IM-AES-CBC-CMAC-128 | + id-PACE-ECDH-IM-AES-CBC-CMAC-192 | + id-PACE-ECDH-IM-AES-CBC-CMAC-256), + version INTEGER, -- SHOULD be 2 + parameterId INTEGER OPTIONAL + } + + +Bundesamt für Sicherheit in der Informationstechnik 23 + A. ASN.1 Specifications (Normative) + + + +PACEDomainParameterInfo: This data structure provides one set of explicit domain parameters for +PACE of the ICC. + • The object identifier protocol SHALL identify the type of the domain parameters (i.e. DH or + ECDH). + • The sequence domainParameter SHALL contain the domain parameters. + • The integer parameterId MAY be used to indicate the local domain parameter identifier. It MUST + be used if the ICC provides multiple explicit domain parameters for PACE. + PACEDomainParameterInfo ::= SEQUENCE { + protocol OBJECT IDENTIFIER( + id-PACE-DH-GM | + id-PACE-ECDH-GM | + id-PACE-DH-IM | + id-PACE-ECDH-IM), + domainParameter AlgorithmIdentifier, + parameterId INTEGER OPTIONAL + } + +PasswordInfo: This data structure provides information about the passwords supported by the ICC 2. + • The object identifier protocol SHALL identify the password. + • The integer pwdId SHALL contain the identifier of the password. + • If optionalPwdData is present, the bit string pwdFlags SHALL be used to indicate whether + the password is + ◦ local, meaning that the password is a local password, i.e. a password specific to a + particular application, + ◦ unblocks-others, meaning that the password may be used to unblock other passwords, + ◦ is-blocking, meaning that the password has a retry counter and is blocked if the counter + has reached the value RC=0. + ◦ is-suspending, meaning that the password has to be resumed before usage if the retry + counter has reached the value RC=1, + ◦ limited-resetUT, meaning that the password is assigned with a reset counter for + unauthenticated terminals, + ◦ unblock-allowedUT, meaning that if the password is blocked and the reset counter is + non-zero, it may be unblocked by an unauthenticated terminal, + ◦ unblock-allowedAT, meaning that if the password is blocked and the reset counter is + non-zero, it may be unblocked by an authenticated terminal with effective authorization for + PIN management, + ◦ change-allowedUT, meaning that the password may be changed by an unauthenticated + terminal, + ◦ change-allowedAT, meaning that the password may be changed by an authenticated + terminal with effective authorization for PIN management,. + ◦ activation-allowedAT, meaning that the password may be activated (if deactive) by an + authenticated terminal with effective authorization for PIN management, + +2 The data structure is designed to allow the description of various passwords, not necessarily specified within + this Technical Guideline. + +24 Bundesamt für Sicherheit in der Informationstechnik + ASN.1 Specifications (Normative) A. + + + ◦ deactivation-allowedAT, meaning the the password may be deactivated (if active) by + an authenticated terminal with effective authorization for PIN management, + ◦ needs-padding, meaning that, depending on the length of the given password and the + stored length, the password may need to be padded before presentation to the ICC. + • The set of integers resuming-Pwds MAY be used to indicate the IDs of the passwords that can + be used to resume the password. + • The set of integers resetting-Pwds MAY be used to indicate the IDs of the passwords that + can be used by unauthenticated terminals to reset the password if the reset counter is non-zero. + • The set of integers change-Pwds MAY be used to indicate the IDs of the passwords that can be + used by unauthenticated terminals to change the password if the reset counter is non-zero. + • The field pwdType MAY be used to indicate type of the password (see [10] for details on + PasswordType). + • The integer minLength MAY be used to indicate the minimum length (in characters) of new + passwords (if allowed to change). + • The integer storedLength MAY be used to indicate the stored length on the ICC (in bytes). It + can be used to deduce the number of padding characters needed. + • The integer maxLength MAY be used to indicate the maximum password length (in characters) + allowed. + • The octet string padChar MAY be used to indicate the character to be used for padding. It + MUST be omitted if the password needs no padding. If present and the password is of type bcd, + then padChar should consist of two nibbles of the same value, any nibble could be used as the + “padding nibble” (e.g. ‘55’ is allowed, meaning padding with ‘0101’, but ‘34’ is illegal). + id-PasswordType OBJECT IDENTIFIER ::= { + bsi-de protocols(2) smartcards(2) 12 + } + + id-MRZ OBJECT IDENTIFIER ::= { id-PasswordType 1 } + id-CAN OBJECT IDENTIFIER ::= { id-PasswordType 2 } + id-PIN OBJECT IDENTIFIER ::= { id-PasswordType 3 } + id-PUK OBJECT IDENTIFIER ::= { id-PasswordType 4 } + + PasswordInfo ::= SEQUENCE { + protocol OBJECT IDENTIFIER, + requiredPwdData RequiredPwdData, + optionalPwdData OptionalPwdData + } + + RequiredPwdData ::= SEQUENCE { + pwdId PwdId + } + + PwdId ::= INTEGER + + OptionalPwdData ::= SEQUENCE { + pwdFlags PwdFlags, + resuming-Pwds [0] IMPLICIT SET OF PwdId OPTIONAL, + resetting-Pwds [1] IMPLICIT SET OF PwdId OPTIONAL, + changing-PwdsUT [2] IMPLICIT SET OF PwdId OPTIONAL, + pwdType [3] IMPLICIT PasswordType OPTIONAL, + minLength [4] IMPLICIT INTEGER OPTIONAL, + +Bundesamt für Sicherheit in der Informationstechnik 25 + A. ASN.1 Specifications (Normative) + + + storedLength [5] IMPLICIT INTEGER OPTIONAL, + maxLength [6] IMPLICIT INTEGER OPTIONAL, + padChar [7] IMPLICIT OCTET STRING (SIZE(1)) OPTIONAL, + ... –- For future extensions + } + + PwdFlags ::= BIT STRING { + local (0) + unblocks-others (1), + is-blocking (2), + is-suspending (3), + limited-resetUT (4), + unblock-allowedUT (5), + unblock-allowedAT (6), + change-allowedUT (7), + change-allowedAT (8), + activation-allowedAT (9), + deactivation-allowedAT (10), + needs-padding (11) + } + + PasswordType ::= ENUMERATED {bcd, ascii-numeric, utf8, half-nibble-bcd, + iso9564-1, ...} + +If the PasswordInfo structure is absent for a password, the following options of the description in +Part 2 SHOULD be implemented: + • The PIN is assigned with a reset counter. + • The PUK is non-blocking. + • For unauthenticated terminals, the function Change PIN after PACE with PUK is not allowed. + +Note: Usage of the algorithm 3DES is deprecated, hence the object identifiers +id-PACE-DH-GM-3DES-CBC-CBC, id-PACE-ECDH-GM-3DES-CBC-CBC, +id-PACE-DH-IM-3DES-CBC-CBC and id-PACE-DH-IM-3DES-CBC-CBC SHOUL NOT be used + + +A.1.1.2. Chip Authentication +To indicate support for Chip Authentication Version 1 or Version 2 SecurityInfos may contain the +following entries: + • At least one ChipAuthenticationPublicKeyInfo MUST be present. + • At least one ChipAuthenticationInfo MUST be present. + • At least one ChipAuthenticationDomainParameterInfo MUST be present for Chip + Authentication in version 2. +To indicate support for Chip Authentication Version 3 SecurityInfos may contain the following +entries: + • At least one ChipAuthenticationInfo MUST be present. + • At least one ChipAuthenticationDomainParameterInfo MUST be present. + • At least one PSAInfo MUST be present. + • At least one PSPublicKeyInfo MUST be present. + + +26 Bundesamt für Sicherheit in der Informationstechnik + ASN.1 Specifications (Normative) A. + + +The usage of the keyId within the SecurityInfos is CONDITIONAL. In case Chip Authentication +version 3 is supported by the ICC or more than one Chip Authentication Public Key is present on the +ICC, the optional keyId MUST be used in all data structures to indicate the local key identifier and +domain parameters. + +Note: For Chip Authentication Version 3, the domain parameters for the ephemeral key agreement are +contained in ChipAuthenticationDomainParameterInfo, while the domain parameters to be +used for the Pseudonymous Signature are contained in PSPublicKeyInfo. Hence, the keyId does +not only indicate the local key identifier for Pseudonymous Signature Authentication, but also the +domain parameters to be used within the ephemeral key agreement for secure messaging. +ChipAuthenticationInfo: This data structure provides detailed information on an implementation of +Chip Authentication. + • The object identifier protocol SHALL identify the algorithms to be used (i.e. key agreement, + symmetric cipher and MAC). + • The integer version SHALL identify the version of the protocol. Currently, versions 1, 2 and 3 + are supported. + • The integer keyId MAY be used to indicate the local key identifier (and domain parameters for + key agreement). It MUST be used if the condition listed above is satisfied. + id-CA OBJECT IDENTIFIER ::= { + bsi-de protocols(2) smartcard(2) 3 + } + + id-CA-DH OBJECT IDENTIFIER ::= {id-CA 1} + id-CA-DH-3DES-CBC-CBC OBJECT IDENTIFIER ::= {id-CA-DH 1} + id-CA-DH-AES-CBC-CMAC-128 OBJECT IDENTIFIER ::= {id-CA-DH 2} + id-CA-DH-AES-CBC-CMAC-192 OBJECT IDENTIFIER ::= {id-CA-DH 3} + id-CA-DH-AES-CBC-CMAC-256 OBJECT IDENTIFIER ::= {id-CA-DH 4} + + id-CA-ECDH OBJECT IDENTIFIER ::= {id-CA 2} + id-CA-ECDH-3DES-CBC-CBC OBJECT IDENTIFIER ::= {id-CA-ECDH 1} + id-CA-ECDH-AES-CBC-CMAC-128 OBJECT IDENTIFIER ::= {id-CA-ECDH 2} + id-CA-ECDH-AES-CBC-CMAC-192 OBJECT IDENTIFIER ::= {id-CA-ECDH 3} + id-CA-ECDH-AES-CBC-CMAC-256 OBJECT IDENTIFIER ::= {id-CA-ECDH 4} + + ChipAuthenticationInfo ::= SEQUENCE { + protocol OBJECT IDENTIFIER( + id-CA-DH-3DES-CBC-CBC | + id-CA-DH-AES-CBC-CMAC-128 | + id-CA-DH-AES-CBC-CMAC-192 | + id-CA-DH-AES-CBC-CMAC-256 | + id-CA-ECDH-3DES-CBC-CBC | + id-CA-ECDH-AES-CBC-CMAC-128 | + id-CA-ECDH-AES-CBC-CMAC-192 | + id-CA-ECDH-AES-CBC-CMAC-256), + version INTEGER, -- MUST be 1 for CAv1 or 2 for CAv2 or 3 for CAv3 + keyId INTEGER OPTIONAL + } + +ChipAuthenticationDomainParameterInfo: This data structure provides one set of domain parameters +for Chip Authentication version 2 and version 3 of the ICC. + • The object identifier protocol SHALL identify the type of the domain parameters (i.e. DH or + ECDH). + + +Bundesamt für Sicherheit in der Informationstechnik 27 + A. ASN.1 Specifications (Normative) + + + • The sequence domainParameter SHALL contain the domain parameters. + • The integer keyId MAY be used to indicate the local key identifier (and domain parameters for + key agreement). It MUST be used if the condition listed above is satisfied. + ChipAuthenticationDomainParameterInfo ::= SEQUENCE { + protocol OBJECT IDENTIFIER(id-CA-DH | id-CA-ECDH), + domainParameter AlgorithmIdentifier, + keyId INTEGER OPTIONAL + } + +ChipAuthenticationPublicKeyInfo: This data structure provides a public key for Chip Authentication of +the ICC. + • The object identifier protocol SHALL identify the type of the public key (i.e. DH or ECDH). + • The sequence chipAuthenticationPublicKey SHALL contain the public key in encoded + form. + • The integer keyId MAY be used to indicate the local key identifier. It MUST be used if the + condition listed above is satisfied. + id-PK OBJECT IDENTIFIER ::= { + bsi-de protocols(2) smartcard(2) 1 + } + + id-PK-DH OBJECT IDENTIFIER ::= {id-PK 1} + id-PK-ECDH OBJECT IDENTIFIER ::= {id-PK 2} + + ChipAuthenticationPublicKeyInfo ::= SEQUENCE { + protocol OBJECT IDENTIFIER(id-PK-DH | id-PK-ECDH), + chipAuthenticationPublicKey SubjectPublicKeyInfo, + keyId INTEGER OPTIONAL + } + +PSAInfo: This data structure provides detailed information on an implementation of Pseudonymous +Signature Authentication and is of the following form: + PSAInfo ::= SEQUENCE { + protocol OBJECT IDENTIFIER ( + id-PSA-ECDH-ECSchnorr-SHA-256 | + id-PSA-ECDH-ECSchnorr-SHA-384 | + id-PSA-ECDH-ECSchnorr-SHA-512), + requiredData PSARequiredData, + keyId INTEGER OPTIONAL + } + + PSARequiredData ::= SEQUENCE { + version INTEGER, –- MUST be 1 + ps1-authInfo INTEGER (0 | 1 | 2), + ps2-authInfo INTEGER (0 | 1 | 2) + } + + id-PS OBJECT IDENTIFIER ::= { bsi-de protocols(2) smartcards(2) 11 } + id-PSA OBJECT IDENTIFIER ::= { id-PS 1 } + + id-PSA-ECDH-ECSchnorr OBJECT IDENTIFIER ::= { id-PSA 2 } + id-PSA-ECDH-ECSchnorr-SHA-256 OBJECT IDENTIFIER ::= { PSA-ECDH-ECSchnorr 3 } + id-PSA-ECDH-ECSchnorr-SHA-384 OBJECT IDENTIFIER ::= { PSA-ECDH-ECSchnorr 4 } + id-PSA-ECDH-ECSchnorr-SHA-512 OBJECT IDENTIFIER ::= { PSA-ECDH-ECSchnorr 5 } + + +28 Bundesamt für Sicherheit in der Informationstechnik + ASN.1 Specifications (Normative) A. + + + + +The fields in the data structure contain the following information: + • The object identifier protocol SHALL identify the Pseudonymous Signature Authentication + Protocol. + • The integer version SHALL identify the version of the supported protocol. Currently, version + 1 is supported. + • The integer ps1-authInfo SHALL indicate the terminal's effective authorization required to + Sector + get the Pseudonym I ICC , 1 during Pseudonymous Signature Authentication. The value + ◦ '0' indicates that no explicit authorization is required, + ◦ '1' indicates that explicit authorization is required and + Sector + ◦ '2' indicates that a terminal is not authorized to obtain I ICC , 1 . + • The integer ps2-authInfo SHALL indicate the required terminal's effective authorization to + Sector + obtain the Pseudonym I ICC , 2 during Pseudonymous Signature Authentication. The value + ◦ '0' indicates that no explicit authorization is required, + ◦ '1' indicates that explicit authorization is required and + Sector + ◦ '2' indicates that a terminal is not authorized to obtain I ICC , 2 . + • The integer keyId MUST be used to indicate the local key identifier and domain parameters + for key agreement. +PSPublicKeyInfo: This data structure provides detailed information on a public key for the +Pseudonymous Signature and is of the following form: + PSPublicKeyInfo ::= SEQUENCE { + protocol OBJECT IDENTIFIER (id-PS-PK-ECDH-ECSchnorr), + requiredData PSPKRequiredData, + optionalData PSPKOptionalData OPTIONAL + } + + PSPKRequiredData ::= SEQUENCE { + pSPublicKey SubjectPublicKeyInfo, + } + + PSPKOptionalData ::= SEQUENCE { + pSParameterID [1] IMPLICIT INTEGER OPTIONAL, + keyId [2] IMPLICIT INTEGER OPTIONAL + + id-PS-PK OBJECT IDENTIFIER ::= { bsi-de protocols(2) smartcards(2) PK(1) 3 } + id-PS-PK-ECDH-ECSchnorr OBJECT IDENTIFIER ::= { id-PS-PK 2 } + +The fields in the data structures contain the following information: + • The object identifier protocol SHALL identify the public key type, + • The sequence pSPublicKey SHALL contain the ICC's public key and the underlying extended + domain parameters in encoded form. The algorithm identifiers of section A.6.1 SHALL be used. + • The integer pSParameterID MAY be used to indicate the (local) ID of the domain parameters + (excluding the domain parameters). It MUST be present if explicit domain parameters are used. + Otherwise, the field SHOULD be omitted. + + +Bundesamt für Sicherheit in der Informationstechnik 29 + A. ASN.1 Specifications (Normative) + + + • The integer keyId MUST be used to indicate the local key identifier and domain parameters + for key agreement. + +Note: Usage of the algorithm 3DES is deprecated, hence, the object identifiers +id-CA-DH-3DES-CBC-CBC and id-CA-ECDH-GM-3DES-CBC-CBC SHOULD NOT be used. + + +A.1.1.3. Terminal Authentication +To indicate support for Terminal Authentication SecurityInfos may contain the following entry: + • At least one TerminalAuthenticationInfo SHOULD be present. +TerminalAuthenticationInfo: This data structure provides detailed information on an implementation +of Terminal Authentication. + • The object identifier protocol SHALL identify the general Terminal Authentication Protocol + as the specific protocol may change over time. + • The integer version SHALL identify the version of the protocol. Currently, versions 1 and 2 + are supported. + • The sequence efCVCA MAY be used in version 1 to indicate a (short) file identifier of the file + EF.CVCA. It MUST be used, if the default (short) file identifier is not used. In version 2, the field + MUST be absent. + id-TA OBJECT IDENTIFIER ::= { + bsi-de protocols(2) smartcard(2) 2 + } + + id-TA-RSA OBJECT IDENTIFIER ::= {id-TA 1} + id-TA-RSA-v1-5-SHA-1 OBJECT IDENTIFIER ::= {id-TA-RSA 1} + id-TA-RSA-v1-5-SHA-256 OBJECT IDENTIFIER ::= {id-TA-RSA 2} + id-TA-RSA-PSS-SHA-1 OBJECT IDENTIFIER ::= {id-TA-RSA 3} + id-TA-RSA-PSS-SHA-256 OBJECT IDENTIFIER ::= {id-TA-RSA 4} + id-TA-RSA-v1-5-SHA-512 OBJECT IDENTIFIER ::= {id-TA-RSA 5} + id-TA-RSA-PSS-SHA-512 OBJECT IDENTIFIER ::= {id-TA-RSA 6} + + id-TA-ECDSA OBJECT IDENTIFIER ::= {id-TA 2} + id-TA-ECDSA-SHA-1 OBJECT IDENTIFIER ::= {id-TA-ECDSA 1} + id-TA-ECDSA-SHA-224 OBJECT IDENTIFIER ::= {id-TA-ECDSA 2} + id-TA-ECDSA-SHA-256 OBJECT IDENTIFIER ::= {id-TA-ECDSA 3} + id-TA-ECDSA-SHA-384 OBJECT IDENTIFIER ::= {id-TA-ECDSA 4} + id-TA-ECDSA-SHA-512 OBJECT IDENTIFIER ::= {id-TA-ECDSA 5} + + TerminalAuthenticationInfo ::= SEQUENCE { + protocol OBJECT IDENTIFIER(id-TA), + version INTEGER, -- MUST be 1 for TAv1 or 2 for TAv2 + efCVCA FileID OPTIONAL -- MUST NOT be used for version 2 + } + + FileID ::= SEQUENCE { + fid OCTET STRING (SIZE(2)), + sfid OCTET STRING (SIZE(1)) OPTIONAL + } + + + + +30 Bundesamt für Sicherheit in der Informationstechnik + ASN.1 Specifications (Normative) A. + + +Note: Usage of the hash function SHA-1 is deprecated, hence the object identifiers +id-TA-RSA-v1-5-SHA-1, id-TA-RSA-PSS-SHA-1 and id-TA-ECDSA-SHA-1 SHOULD NOT be +used. + + +A.1.1.4. Restricted Identification +To indicate support for Restricted Identification SecurityInfos may contain the following entry: + • At least one RestrictedIdentificationInfo MUST be present. + • At most one RestrictedIdentificationDomainParameterInfo MAY be present. +RestrictedIdentificationInfo: This data structure provides detailed information on an implementation +of Restricted Identification. + • The object identifier protocol SHALL identify the algorithms to be used (i.e. key agreement). + • The integer version SHALL identify the version of the protocol. Currently, only version 1 is + supported. + • The integer keyId SHALL identify the private key to be used. + • The boolean authorizedOnly SHALL indicate whether explicit authorization is REQUIRED + to use the corresponding secret key. + • The integer maxKeyLen MAY be used to indicate the maximum length of the supported sector + specific public keys. + id-RI OBJECT IDENTIFIER ::= { + bsi-de protocols(2) smartcard(2) 5 + } + + id-RI-DH OBJECT IDENTIFIER ::= {id-RI 1} + id-RI-DH-SHA-1 OBJECT IDENTIFIER ::= {id-RI-DH 1} + id-RI-DH-SHA-224 OBJECT IDENTIFIER ::= {id-RI-DH 2} + id-RI-DH-SHA-256 OBJECT IDENTIFIER ::= {id-RI-DH 3} + id-RI-DH-SHA-384 OBJECT IDENTIFIER ::= {id-RI-DH 4} + id-RI-DH-SHA-512 OBJECT IDENTIFIER ::= {id-RI-DH 5} + + id-RI-ECDH OBJECT IDENTIFIER ::= {id-RI 2} + id-RI-ECDH-SHA-1 OBJECT IDENTIFIER ::= {id-RI-ECDH 1} + id-RI-ECDH-SHA-224 OBJECT IDENTIFIER ::= {id-RI-ECDH 2} + id-RI-ECDH-SHA-256 OBJECT IDENTIFIER ::= {id-RI-ECDH 3} + id-RI-ECDH-SHA-384 OBJECT IDENTIFIER ::= {id-RI-ECDH 4} + id-RI-ECDH-SHA-512 OBJECT IDENTIFIER ::= {id-RI-ECDH 5} + + RestrictedIdentificationInfo ::= SEQUENCE { + protocol OBJECT IDENTIFIER( + id-RI-DH-SHA-1 | + id-RI-DH-SHA-224 | + id-RI-DH-SHA-256 | + id-RI-DH-SHA-384 | + id-RI-DH-SHA-512 | + id-RI-ECDH-SHA-1 | + id-RI-ECDH-SHA-224 | + id-RI-ECDH-SHA-256 | + id-RI-ECDH-SHA-384 | + id-RI-ECDH-SHA-512), + params ProtocolParams, + + +Bundesamt für Sicherheit in der Informationstechnik 31 + A. ASN.1 Specifications (Normative) + + + maxKeyLen INTEGER OPTIONAL + } + + ProtocolParams ::= SEQUENCE { + version INTEGER, -- MUST be 1 + keyId INTEGER, + authorizedOnly BOOLEAN + } + +RestrictedIdentificationDomainParameterInfo: This data structure provides the set of domain +parameters that have been used for the generation of the public key PK ID for revocation of the ICC. + • The object identifier protocol SHALL identify the type of the domain parameters (i.e. DH or + ECDH). + • The sequence domainParameter SHALL contain the domain parameters. + RestrictedIdentificationDomainParameterInfo ::= SEQUENCE { + protocol OBJECT IDENTIFIER(id-RI-DH | id-RI-ECDH), + domainParameter AlgorithmIdentifier + } + + +Note: Usage of the hash function SHA-1 is deprecated, hence the object identifiers id-RI-DH-SHA-1 +and id-RI-ECDH-SHA-1 SHOULD NOT be used. + + +A.1.1.5. Pseudonymous Signatures of Messages (PSM) +To indicate support for Pseudonymous Signature of Messages, SecurityInfos may contain the +following entries: + • At least one PSMInfo MUST be present. + • At least one PSPublicKeyInfo MUST be present. +PSMInfo: This data structure provides detailed information on an implementation of PSM and is of the +following form: + PSMInfo ::= SEQUENCE { + protocol OBJECT IDENTIFIER ( + id-PSM-ECDH-ECSchnorr-SHA-256 | + id-PSM-ECDH-ECSchnorr-SHA-384 | + id-PSM-ECDH-ECSchnorr-SHA-512), + requiredData PSMRequiredData, + keyId INTEGER OPTIONAL + } + + PSMRequiredData ::= SEQUENCE { + version INTEGER, –- MUST be 1 + ps1-authInfo INTEGER (0 | 1 | 2), + ps2-authInfo INTEGER (0 | 1 | 2) + } + + id-PSM OBJECT IDENTIFIER ::= { id-PS 2 } + + id-PSM-ECDH-ECSchnorr OBJECT IDENTIFIER ::= { id-PSM 2 } + id-PSM-ECDH-ECSchnorr-SHA-256 OBJECT IDENTIFIER ::= { PSM-ECDH-ECSchnorr 3 } + id-PSM-ECDH-ECSchnorr-SHA-384 OBJECT IDENTIFIER ::= { PSM-ECDH-ECSchnorr 4 } + id-PSM-ECDH-ECSchnorr-SHA-512 OBJECT IDENTIFIER ::= { PSM-ECDH-ECSchnorr 5 } + + +32 Bundesamt für Sicherheit in der Informationstechnik + ASN.1 Specifications (Normative) A. + + + +The fields in the data structure contain the following information: + • The object identifier protocol SHALL identify the PSM Protocol. + • The integer version SHALL identify the version of the supported protocol. Currently, version + 1 is supported. + • The integer ps1-authInfo SHALL indicate the required terminal's effective authorization to + Sector + get the Pseudonym I ICC , 1 during Pseudonymous Signature of a Message. The value + ◦ '0' indicates that no explicit authorization is required, + ◦ '1' indicates that explicit authorization is required and + Sector + ◦ '2' indicates that a terminal is not authorized to obtain I ICC , 1 . + • The integer ps2-authInfo SHALL indicate the required terminal's effective authorization to + Sector + get the Pseudonym I ICC , 2 during Pseudonymous Signature of a Message. The value + ◦ '0' indicates that no explicit authorization is required, + ◦ '1' indicates that explicit authorization is required and + Sector + ◦ '2' indicates that a terminal is not authorized to obtain I ICC , 2 . + • The integer keyId MUST be used to indicate the local key identifier. + + +A.1.1.6. Pseudonymous Signatures of Credentials (PSC) +To indicate support for Pseudonymous Signature of Credentials, SecurityInfos may contain the +following entries: + • At least one PSCInfo MUST be present. + • At least one PSPublicKeyInfo MUST be present. +PSCInfo: This data structure provides detailed information on an implementation of PSC and is of the +following form: + PSCInfo ::= SEQUENCE { + protocol OBJECT IDENTIFIER ( + id-PSC-ECDH-ECSchnorr-SHA-256 | + id-PSC-ECDH-ECSchnorr-SHA-384 | + id-PSC-ECDH-ECSchnorr-SHA-512), + requiredData PSCRequiredData, + keyId INTEGER OPTIONAL + } + + PSCRequiredData ::= SEQUENCE { + version INTEGER, –- MUST be 1 + ps1-authInfo INTEGER (0 | 1 | 2), + ps2-authInfo INTEGER (0 | 1 | 2) + } + + id-PSC OBJECT IDENTIFIER ::= { id-PS 3 } + + id-PSC-ECDH-ECSchnorr OBJECT IDENTIFIER ::= { id-PSC 2 } + id-PSC-ECDH-ECSchnorr-SHA-256 OBJECT IDENTIFIER ::= { PSC-ECDH-ECSchnorr 3 } + id-PSC-ECDH-ECSchnorr-SHA-384 OBJECT IDENTIFIER ::= { PSC-ECDH-ECSchnorr 4 } + + +Bundesamt für Sicherheit in der Informationstechnik 33 + A. ASN.1 Specifications (Normative) + + + id-PSC-ECDH-ECSchnorr-SHA-512 OBJECT IDENTIFIER ::= { PSC-ECDH-ECSchnorr 5 } + +The fields in the data structure contain the following information: + • The object identifier protocol SHALL identify the PSC Protocol. + • The integer version SHALL identify the version of the supported protocol. Currently, version + 1 is supported. + • The integer ps1-authInfo SHALL indicate the required terminal's effective authorization to + Sector + get the Pseudonym I ICC , 1 during Pseudonymous Signature of Credentials. The value + ◦ '0' indicates that no explicit authorization is required, + ◦ '1' indicates that explicit authorization is required and + Sector + ◦ '2' indicates that a terminal is not authorized to obtain I ICC , 1 . + • The integer ps2-authInfo SHALL indicate the required terminal's effective authorization to + Sector + get the Pseudonym I ICC , 2 during Pseudonymous Signature of Credentials. The value + ◦ '0' indicates that no explicit authorization is required, + ◦ '1' indicates that explicit authorization is required and + Sector + ◦ '2' indicates that a terminal is not authorized to obtain I ICC , 2 . + • The integer keyId MUST be used to indicate the local key identifier. + + +A.1.1.7. CardInfo (eIDAS token only) +To provide information about card capabilities and the structure of the card SecurityInfos may +contain the following entry: + • Exactly one CardInfo SHOULD be present. It MUST be present if the ICC supports + authorization extensions or storing/restoring of the session context. +CardInfo: This data structure provides detailed information about the applications supported by the +ICC. + • The object identifier protocol SHALL identify the CardInfo structure. + • The string urlCardInfo SHALL define the location that provides the most recent CardInfo + file [5] for the respective ICC type and version. + • The choice optionalCardInfoData MAY contain optional CardInfo data. If the ICC + supports Authorization Extensions or storing/restoring of Session Contexts or the compare + command for auxilliary data verification, the choice ExtCardInfoData MUST be present. + ◦ The sequence efCardInfo MAY be used to indicate a (short) file identifier of the file + EF.CardInfo containing a CardInfo file [5]. + ◦ If present, supportedTRVersion SHALL contain the version of this Technical Guideline. + Compliance to this version SHALL be indicated by 'Version 2.21'. + ◦ If the ICC supports Authorization Extensions, the set of suppTerminalTypes MUST be + present. + ▪ If present, the object identifier supportedTerminalType SHALL contain a terminal + type supported by the ICC a terminal type supported by the ICC indicated by the + +34 Bundesamt für Sicherheit in der Informationstechnik + ASN.1 Specifications (Normative) A. + + + corresponding OBJECT IDENTIFIER. See Part 4 for the Terminal Types defined in this + Technical Guideline. + ▪ If the ICC supports Authorization Extensions for the terminal type, these extensions + SHALL be indicated by the corresponding object identifier in the set of + supportedAuthorizationExtensions. + ◦ The integer maxSCNo MAY indicate the maximum number of Session Contexts that can be + handled by the ICC in addition to the default session context. It MUST be present if the ICC + supports switching of session contexts. The value MUST NOT exceed 127. The value of 0x00 + indicates that the ICC supports the default session context only. + ◦ The boolean envInfo MAY be used to indicate if the ICC supports Envelope/GetResponse + TPDUs. + id-CI OBJECT IDENTIFIER ::= { + bsi-de protocols(2) smartcard(2) 6 + } + + CardInfo ::= SEQUENCE { + protocol OBJECT IDENTIFIER(id-CI), + urlCardInfo IA5String, + optionalCardInfoData OptionalCardInfoData OPTIONAL, + } + + FileID ::= SEQUENCE { + fid OCTET STRING (SIZE(2)), + sfid OCTET STRING (SIZE(1)) OPTIONAL + } + + OptionalCardInfoData ::= CHOICE { + efCardInfo EfCardInfo, + extCardInfoData [0] IMPLICIT ExtCardInfoData + } + + EfCardInfo ::= FileID + + ExtCardInfoData ::= SEQUENCE { + efCardInfo [0] IMPLICIT FileID OPTIONAL, + supportedTRVersion [1] IMPLICIT UTF8String OPTIONAL, + suppTerminalTypes [2] IMPLICIT SET OF SupportedTerminalTypes + OPTIONAL, + maxSCNo [3] IMPLICIT INTEGER OPTIONAL, + envInfo [4] IMPLICIT BOOLEAN OPTIONAL + } + + SupportedTerminalTypes ::=SEQUENCE { + supportedTerminalType OBJECT IDENTIFIER, + supportedAuthorizations SET OF OBJECT IDENTIFIER OPTIONAL + } + + +A.1.1.8. EIDSecurityInfo (eIDAS token only) +To protect data stored in the eID application SecurityInfos may contain the following entry: + • Exactly one EIDSecurityInfo SHOULD be present. +EIDSecurityInfo: This data structure provides hash values of selected data groups of the eID +application. + +Bundesamt für Sicherheit in der Informationstechnik 35 + A. ASN.1 Specifications (Normative) + + + • The sequence eIDSecurityObject SHALL define the hash values of selected data groups. + • The sequence eIDVersionInfo MAY be used to identify the version of the eID Application. + id-eIDSecurity OBJECT IDENTIFIER ::= { + bsi-de protocols(2) smartcard(2) 7 + } + + EIDSecurityInfo ::= SEQUENCE { + protocol OBJECT IDENTIFIER(id-eIDSecurity), + eIDSecurityObject EIDSecurityObject, + eIDVersionInfo EIDVersionInfo OPTIONAL + } + + EIDSecurityObject ::= SEQUENCE { + hashAlgorithm AlgorithmIdentifier, + dataGroupHashValues SEQUENCE OF DataGroupHash + } + + DataGroupHash ::= SEQUENCE { + dataGroupNumber INTEGER, + dataGroupHashValue OCTET STRING + } + + EIDVersionInfo ::= SEQUENCE { + eIDVersion PrintableString, + unicodeVersion PrintableString + } + +A.1.1.9. PrivilegedTerminalInfo (eIDAS token only) +To provide additional information about Chip Authentication keys restricted to privileged terminals +SecurityInfos may contain the following entry: + • Exactly one PrivilegedTerminalInfo MUST be present, if some Chip Authentication keys + are only available to privileged terminals. +PrivilegedTerminalInfo: This data structure provides SecurityInfos related to Chip Authentication +using chip-individual keys that are only available to privileged terminals. + • The set privilegedTerminalInfos SHALL encapsulate SecurityInfos corresponding + to Chip Authentication keys that are only available to privileged terminals. + id-PT OBJECT IDENTIFIER ::= { + bsi-de protocols(2) smartcard(2) 8 + } + + PrivilegedTerminalInfo ::= SEQUENCE { + protocol OBJECT IDENTIFIER(id-PT), + privilegedTerminalInfos SecurityInfos + } + + + + +36 Bundesamt für Sicherheit in der Informationstechnik + ASN.1 Specifications (Normative) A. + + + +File Name EF.CardAccess EF.CardSecurity EF.ChipSecurity +File ID 0x011C 0x011D 0x011B +Short File ID 0x1C 0x1D 0x1B +Read Access ALWAYS PACE (m) PACE + + TA (o) + TA[authenticated privileged + terminals] +Write Access NEVER NEVER NEVER +Size variable variable variable +Content DER encoded DER encoded ContentInfo DER encoded ContentInfo + SecurityInfos structure of type id-SignedData structure of type id-SignedData + Table 2: Elementary Files CardAccess, CardSecurity and ChipSecurity + + +A.1.1.10. Other Protocols +SecurityInfos MAY contain references to protocols that are not contained in this specification +(including Active Authentication and Basic Access Control). + + +A.1.2. Storage on the Chip +The ICC SHALL provide SecurityInfos in the following transparent elementary files contained in +the master file (cf. Table 2): + • CardAccess (CONDITIONAL) + SHALL be present if PACE, Chip Authentication version 2 and/or Terminal Authentication + version 2 are implemented by the chip. SHALL be readable by all terminals. + • CardSecurity (CONDITIONAL) + SHALL be present if Chip Authentication version 2 or 3, Terminal Authentication version 2, + Restricted Identification or PSM are implemented by the chip. Read access to CardSecurity + SHALL be restricted to terminals having successfully performed PACE and MAY be further + restricted to authenticated terminals. + • ChipSecurity (OPTIONAL) + Read access to ChipSecurity SHALL be restricted to authenticated privileged terminals. If this + optional file is available, all privacy-relevant SecurityInfos SHOULD be stored in + ChipSecurity and SHOULD NOT be included in CardSecurity. +If PACE according [8], Terminal Authentication version 1 or Chip Authentication version 1 are +implemented, the ICC SHALL provide SecurityInfos in the elementary file DG14 contained in the +ePassport application. + + + + +Bundesamt für Sicherheit in der Informationstechnik 37 + A. ASN.1 Specifications (Normative) + + +A.1.2.1. CardAccess (CONDITIONAL) +If present, the file CardAccess shall contain the relevant SecurityInfos that are required to access +applications: + • PACEInfo (REQUIRED) + • PACEDomainParameterInfo (CONDITIONAL) + ◦ This structure(s) MUST be present if explicit domain parameters are used. + • PasswordInfo (OPTIONAL) + ◦ This structure MAY be present to provide information about supported passwords. + • ChipAuthenticationInfo (CONDITIONAL) + ◦ This structure(s) MUST be present if Chip Authentication in version 2 or 3 is supported and + read access to CardSecurity is restricted to authenticated terminals. + • ChipAuthenticationDomainParameterInfo (CONDITIONAL) + ◦ This structure(s) MUST be present if Chip Authentication in version 2 or 3 is supported and + read access to CardSecurity is restricted to authenticated terminals. + • PSAInfo (CONDITIONAL) + ◦ This structure MUST be present if Chip Authentication in version 3 is supported and read + access to CardSecurity is restricted to authenticated terminals. + • TerminalAuthenticationInfo (CONDITIONAL) + ◦ This structure MUST be present if Terminal Authentication in version 2 is supported. + • PSMInfo (CONDITIONAL) + ◦ This structure MUST be present if Pseudonymous Signature of Messages is supported and + read access to CardSecurity is restricted to authenticated terminals. + • CardInfo (RECOMMENDED) + • PrivilegedTerminalInfo (CONDITIONAL) + ◦ This structure MUST be present if some Chip Authentication version 2 keys are only + available to privileged terminals and read access to CardSecurity is restricted to + authenticated terminals. + ◦ It SHALL encapsulate the corresponding SecurityInfos, i.e. for each Chip + Authentication key that is restricted to privileged terminals a + ChipAuthenticationInfo and ChipAuthenticationDomainParameterInfo + MUST be included referencing the key identifier. + + +A.1.2.2. CardSecurity (CONDITIONAL) +If present, the file CardSecurity + • SHALL contain all SecurityInfos supported by the ICC (except for + PrivilegedTerminalInfo and EIDSecurityInfo for which the conditions as described + below apply) + + + +38 Bundesamt für Sicherheit in der Informationstechnik + ASN.1 Specifications (Normative) A. + + + • SHALL contain all SecurityInfos contained in CardAccess except + PrivilegedTerminalInfo, + • if some Chip Authentication version 2 keys are only available to privileged terminals and no + PrivilegedTerminalInfo is contained in CardAccess, SHALL contain a + PrivilegedTerminalInfo, which encapsulates the corresponding SecurityInfos, + • SHALL contain the corresponding ChipAuthenticationPublicKeyInfo for each key + referenced by a ChipAuthenticationInfo of version 1 or 2 (excluding keys encapsulated + in PrivilegedTerminalInfo). Generation-specific keys SHOULD be used instead of + chip-individual keys, and + • SHOULD NOT contain EIDSecurityInfo. +The SecurityInfos contained in CardSecurity MUST be signed using the data structure specified in +A.1.2.5. + + +A.1.2.3. ChipSecurity (OPTIONAL) +If present, the file ChipSecurity + • SHALL contain all SecurityInfos supported by the ICC. In particular, the file + ◦ SHALL contain all SecurityInfos contained in CardAccess, and + ◦ SHALL contain the corresponding ChipAuthenticationPublicKeyInfo for each key + referenced by a ChipAuthenticationInfo. For each ChipAuthenticationInfo + encapsulated in PrivilegedTerminalInfo, the corresponding + ChipAuthenticationPublicKeyInfo MUST also be included in + PrivilegedTerminalInfo. All keys encapsulated in PrivilegedTerminalInfo + SHOULD be chip-individual keys. + • It is RECOMMENDED that EIDSecurityInfo is used to provide hashes of (static) data groups + related to personal data of the holder. +The SecurityInfos contained in ChipSecurity MUST be signed using the data structure specified in +A.1.2.5. + + +A.1.2.4. ePassport DG14 (CONDITIONAL) +If PACE according to [8], Terminal Authentication version 1 or Chip Authentication version 1 are +implemented by the chip, the ICC SHALL also provide SecurityInfos in data group DG14 of the +ePassport application. It is RECOMMENDED that DG14 and ChipSecurity (if present) contain the same +keys. + + +A.1.2.5. Signature Format for CardSecurity and ChipSecurity +The files CardSecurity and ChipSecurity SHALL be implemented as SignedData according to [7]3 with +content type id-SecurityObject within the field encapContentInfo. The Security Objects +SHALL be signed by the Document Signer. The Document Signer Certificate MUST be included in +SignedData. The following Object Identifier SHALL be used to identify the content type: + id-SecurityObject OBJECT IDENTIFIER ::= { + +3 i.e. a ContentInfo structure with content type id-signed-data and content of type SignedData. + +Bundesamt für Sicherheit in der Informationstechnik 39 + A. ASN.1 Specifications (Normative) + + + bsi-de applications(3) eID(2) 1 + } + +The data structure SignedData is defined as follows; more details can be found in [7]: + SignedData ::= SEQUENCE{ + version CMSVersion, + digestAlgorithms DigestAlgorithmIdentifiers, + encapContentInfo EncapsulatedContentInfo, + certificates [0] IMPLICIT CertificateSet OPTIONAL, + crls [1] IMPLICIT RevocationInfoChoices OPTIONAL, + signerInfos SignerInfos + } + + DigestAlgorithmIdentifiers ::= SET OF DigestAlgorithmIdentifier + + EncapsulatedContentInfo ::= SEQUENCE { + eContentType ContentType, + eContent [0] EXPLICIT OCTET STRING OPTIONAL + } + + ContentType ::= OBJECT IDENTIFIER + + SignerInfos ::= SET OF SignerInfo + + SignerInfo ::= SEQUENCE { + version CMSVersion, + sid SignerIdentifier, + digestAlgorithm DigestAlgorithmIdentifier, + signedAttrs [0] IMPLICIT SignedAttributes OPTIONAL, + signatureAlgoritm SignatureAlgorithmIdentifier, + signature SignatureValue, + unsignedAttrs [1] IMPLICIT UnsignedAttributes OPTIONAL + } + + SignerIdentifier ::= CHOICE { + issuerAndSerialNumber IssuerAndSerialNumber, + subjectKeyIdentifier [0] SubjectKeyIdentifier + } + + SignatureValue ::= OCTET STRING + +Within SignerInfos, the field signedAttrs SHALL consist of the content-type attribute and the field +unsignedAttrs SHALL NOT be present. + + + + +40 Bundesamt für Sicherheit in der Informationstechnik + ASN.1 Specifications (Normative) A. + + + Algorithm / Format DH ECDH + Key Agreement Algorithm PKCS#3 [26] ECKA [4] + X.509 Public Key Format X9.42 [1] ECC [4] + TLV Public Key Format TLV, cf. Appendix D.3.2 TLV, cf. Appendix D.3.3 + Public Key Compression SHA-1 [24] X-Coordinate + Ephemeral Public Key RFC 2631 [25] ECC [4] + Validation + Table 3: Algorithms and Formats for Key Agreement + + +A.2. Key Agreement +PACE, Chip Authentication, Restricted Identification and the pseudonym generation within +Pseudonymous Signatures are based on key agreement protocols. This appendix specifies the general +algorithms, formats and protocols. An overview can be found in table 3. + + +A.2.1. Domain Parameters +With the exception of domain parameters contained in PACEInfo, all domain parameters SHALL be +provided as AlgorithmIdentifier, the data structure is defined as follows; more details can be +found in [6]: + AlgorithmIdentifier ::= SEQUENCE { + algorithm OBJECT IDENTIFIER, + parameters ANY DEFINED BY algorithm OPTIONAL + } + +Within PACEInfo, the ID of standardized domain parameters described in Table 4 SHALL be +referenced directly. Explicit domain parameters provided in the field parameterID by +PACEDomainParameterInfo or in pSParameterID by PSPublicKeyInfo MUST NOT use those +IDs reserved for standardized domain parameters. + + +A.2.1.1. Standardized Domain Parameters +Standardized domain parameters described in Table 4 SHOULD be used4. The following object identifier +SHOULD be used to reference standardized domain parameters in an AlgorithmIdentifier: + standardizedDomainParameters OBJECT IDENTIFIER ::= { + bsi-de algorithms(1) 2 + } + + + + +4 The selection of suitable key lengths is not within the scope of this Technical Guideline. + +Bundesamt für Sicherheit in der Informationstechnik 41 + A. ASN.1 Specifications (Normative) + + + + + ID Name Size Type Reference + 0 1024-bit MODP Group with 160-bit Prime Order Subgroup 1024/160 GFP [18] + 1 2048-bit MODP Group with 224-bit Prime Order Subgroup 2048/224 GFP [18] + 2 2048-bit MODP Group with 256-bit Prime Order Subgroup 2048/256 GFP [18] + 3 - 7 RFU + 8 NIST P-192 (secp192r1) 192 ECP [23], [18] + 9 BrainpoolP192r1 192 ECP [19] + 10 NIST P-224 (secp224r1)* 224 ECP [23], [18] + 11 BrainpoolP224r1 224 ECP [19] + 12 NIST P-256 (secp256r1) 256 ECP [23], [18] + 13 BrainpoolP256r1 256 ECP [19] + 14 BrainpoolP320r1 320 ECP [19] + 15 NIST P-384 (secp384r1) 384 ECP [23], [18] + 16 BrainpoolP384r1 384 ECP [19] + 17 BrainpoolP512r1 512 ECP [19] + 18 NIST P-521 (secp521r1) 521 ECP [23], [18] + 19-31 RFU +* This curve cannot be used with the integrated mapping. + + Table 4: Standardized Domain Parameters + + +Within an AlgorithmIdentifier this object identifier SHALL reference the ID of the standardized +domain parameter as contained in Table 4 as INTEGER. + +Note: Usage of the standardized domain parameter IDs 0, 8 and 9 is deprecated. + + +A.2.1.2. Explicit Domain Parameters +Explicit domain parameters may be contained in the following structures: + • PACEDomainParameterInfo, + • ChipAuthenticationPublicKeyInfo, + • ChipAuthenticationDomainParameterInfo, + • PSPublicKeyInfo, and + • RestrictedIdentificationDomainParameterInfo +The object identifier dhpublicnumber or id-ecPublicKey for DH or ECDH, respectively, SHALL +be used to reference explicit domain parameters in an AlgorithmIdentifier: + dhpublicnumber OBJECT IDENTIFIER ::= { + iso(1) member-body(2) us(840) ansi-x942(10046) number-type(2) 1 + } + + + +42 Bundesamt für Sicherheit in der Informationstechnik + ASN.1 Specifications (Normative) A. + + + id-ecPublicKey OBJECT IDENTIFIER ::= { + iso(1) member-body(2) us(840) ansi-x962(10045) keyType(2) 1 + } +In the case of elliptic curves domain parameters MUST be described explicitly in the ECParameters +structure, i.e. named curves and implicit domain parameters MUST NOT be used. + + +A.2.1.3. PACE, Chip Authentication and Pseudonymous Signatures +The ICC MAY support more than one set of domain parameters (i.e. the chip may support different +algorithms and/or key lengths) for PACE, Chip Authentication version 1, 2 and 3, PSM and PSC. + • Domain parameters contained in EF.CardAccess, i.e. PACEDomainParameterInfo, + ChipAuthenticationDomainParameterInfo (for Chip Authentication version 2 or 3), + are unprotected and may be insecure. Using insecure domain parameters may lead to attacks, + e.g. using insecure domain parameters for PACE will leak the used password. + ◦ ICCs MUST support at least one set of standardized domain parameters for PACE and Chip + Authentication version 2 and 3, if the respective protocols are implemented, as specified in + table 4. + ◦ Terminals MUST NOT use unverified domain parameters for PACE or Chip Authentication + version 2 and 3, i.e. only standardized domain parameters or domain parameters explicitly + known by the terminal to be secure are to be used. + • Domain parameters contained in ChipAuthenticationDomainParameterInfo and + ChipAuthenticationPublicKeyInfo and PSPublicKeyInfo are protected by the + Security Object. + ◦ Chip Authentication in version 1 MUST provide at least one set of explicit domain + parameters. + + +A.2.1.4. Restricted Identification +The domain parameters for Restricted Identification are defined by the Document Verifier and MUST +be provided together with the Sector Public Key in a public key data object as part of Restricted +Identification (cf. Appendix D.3 and Appendix B.4.1). The hash of this public key data object MUST be +contained in the Terminal Certificate as Terminal Sector extension (cf. Appendix C.3.2). The ICC MUST +verify the Sector Public Key using the Terminal Sector extension. + + +A.2.2. Ephemeral Public Keys + +A.2.2.1. PACE and Chip Authentication +The domain parameters contained in PACEInfo or PACEDomainParameterInfo and +ChipAuthenticationDomainParameterInfo or ChipAuthenticationPublicKeyInfo +MUST be used by the terminal for the generation of an ephemeral public key for PACE and Chip +Authentication, respectively. Ephemeral public keys MUST be exchanged as plain public key values. +More information on the encoding can be found in Appendix D.3.4. + + + + +Bundesamt für Sicherheit in der Informationstechnik 43 + A. ASN.1 Specifications (Normative) + + + +Note: The validation of ephemeral public keys is REQUIRED. For DH, the validation algorithm requires +the ICC to have a more detailed knowledge of the domain parameters (i.e. the order of the used +subgroup) than usually provided by PKCS#3. + + +A.2.2.2. Restricted Identification +For Restricted Identification ephemeral public keys are not used. + + +A.2.2.3. Public Key Compression + ~ +The terminal's compressed ephemeral public key Comp( PK PCD ) as required for Terminal +Authentication is defined as follows: + • For DH the compressed ephemeral public key is the SHA-1 hash of the DH public value, i.e. an + octet string of fixed length 20. + • For ECDH the compressed ephemeral public key is the x-coordinate of the ECDH public point, + i.e. an octet string of fixed length ⌈log256 p⌉ . + + +A.2.3. Key Derivation Function +Let KDF Enc (K ,[r ])=KDF( K ,[ r ],1), KDF MAC (K ,[r ])=KDF( K ,[r ],2), be key derivation functions to +derive encryption and authentication keys, respectively, from a shared secret K and an optional nonce + r . Let KDF π (π)=KDF( f (π),3), be a key derivation function to derive encryption keys from a +password  . The encoding of passwords, i.e. K = f ( π) is specified in Table 5. +The key derivation function KDF( K ,[r ] ,c ), is defined as follows: +Input: The following inputs are required: + • The shared secret value K (REQUIRED) + • A nonce r (OPTIONAL) + • A 32-bit, big-endian integer counter c (REQUIRED) +Output: An octet string keydata. +Actions: The following actions are performed: + 1. keydata=H ( K∥r∥c ) + 2. Output octet string keydata +The key derivation function KDF( K ,[r ] ,c ) requires a suitable hash function denoted by H (), i.e the +bit-length of the hash function SHALL be greater or equal to the bit-length of the derived key. The hash +value SHALL be interpreted as big-endian byte output. +The nonce r is used for Chip Authentication version 2 only. + +Note: The shared secret K is defined as an octet string. If the shared secret is generated with ECKA [4], +the x-coordinate of the generated point SHALL be used. + + + + +44 Bundesamt für Sicherheit in der Informationstechnik + ASN.1 Specifications (Normative) A. + + + + Password Encoding + MRZ SHA-1(Serial Number || Date of Birth || Date of Expiry) + CAN Character String (cf. Appendix D.2.1.4) + PIN Character String (cf. Appendix D.2.1.4) + PUK Character String (cf. Appendix D.2.1.4) + Table 5: Encoding of Passwords + + + +A.2.3.1. 3DES +To derive 112-bit 3DES [20] keys the hash function SHA-1 [24] SHALL be used and the following +additional steps MUST be performed: + • Use octets 1 to 8 of keydata to form keydataA and octets 9 to 16 of keydata to form keydataB; + additional octets are not used. + • Adjust the parity bits of keydataA and keydataB to form correct DES keys (OPTIONAL). + + +A.2.3.2. AES +To derive 128-bit AES [21] keys the hash function SHA-1 [24] SHALL be used and the following +additional step MUST be performed: + • Use octets 1 to 16 of keydata; additional octets are not used. +To derive 192-bit and 256-bit AES [21] keys SHA-256 [24] SHALL be used. For 192-bit AES keys the +following additional step MUST be performed: + • Use octets 1 to 24 of keydata; additional octets are not used. + + +A.2.4. Authentication Token +The authentication token used in PACE and Chip Authentication in version 2 SHALL be computed over +a public key data object (cf. Appendix D.3) containing the object identifier of the protocol used, i.e. PACE +or Chip Authentication (as indicated in MSE:Set AT, cf. Appendix B.14.1), and the received ephemeral +public key using an authentication code and the key K MAC derived from the key agreement. + + +A.2.4.1. 3DES +3DES [20] SHALL be used in Retail-mode according to ISO/IEC 9797-1 [15] MAC algorithm 3 / padding +method 2 with block cipher DES and IV =0. + + +A.2.4.2. AES +AES [21] SHALL be used in CMAC-mode [22] with a MAC length of 8 bytes. + + + + +Bundesamt für Sicherheit in der Informationstechnik 45 + A. ASN.1 Specifications (Normative) + + + +A.3. PACE + +A.3.1. PACE with DH +For PACE with DH the respective algorithms and formats from Table 3 and Table 6 MUST be used. + +OID Mapping Sym. Key Secure Auth. + Cipher Len Messaging Token +id-PACE-DH-GM-3DES-CBC-CBC Generic 3DES 112 CBC / CBC CBC +id-PACE-DH-GM-AES-CBC-CMAC-128 Generic AES 128 CBC / CMAC CMAC +id-PACE-DH-GM-AES-CBC-CMAC-192 Generic AES 192 CBC / CMAC CMAC +id-PACE-DH-GM-AES-CBC-CMAC-256 Generic AES 256 CBC / CMAC CMAC +id-PACE-DH-IM-3DES-CBC-CBC Integrated 3DES 112 CBC / CBC CBC +id-PACE-DH-IM-AES-CBC-CMAC-128 Integrated AES 128 CBC / CMAC CMAC +id-PACE-DH-IM-AES-CBC-CMAC-192 Integrated AES 192 CBC / CMAC CMAC +id-PACE-DH-IM-AES-CBC-CMAC-256 Integrated AES 256 CBC / CMAC CMAC + Table 6: Object Identifiers for PACE with DH + + +A.3.2. PACE with ECDH +For PACE with ECDH the respective algorithms and formats from Table 3 and Table 7 MUST be used. + +OID Mapping Sym. Key Secure Auth. + Cipher Len Messaging Token +id-PACE-ECDH-GM-3DES-CBC-CBC Generic 3DES 112 CBC / CBC CBC +id-PACE-ECDH-GM-AES-CBC-CMAC-128 Generic AES 128 CBC / CMAC CMAC +id-PACE-ECDH-GM-AES-CBC-CMAC-192 Generic AES 192 CBC / CMAC CMAC +id-PACE-ECDH-GM-AES-CBC-CMAC-256 Generic AES 256 CBC / CMAC CMAC +id-PACE-ECDH-IM-3DES-CBC-CBC Integrated 3DES 112 CBC / CBC CBC +id-PACE-ECDH-IM-AES-CBC-CMAC-128 Integrated AES 128 CBC / CMAC CMAC +id-PACE-ECDH-IM-AES-CBC-CMAC-192 Integrated AES 192 CBC / CMAC CMAC +id-PACE-ECDH-IM-AES-CBC-CMAC-256 Integrated AES 256 CBC / CMAC CMAC + Table 7: Object Identifiers for PACE with ECDH + + +A.3.3. Encrypted Nonce +The ICC SHALL randomly and uniformly select the nonce s∈ R {0 2 l −1} as a binary bit string of +length l, where l is a positive multiple of the block size in bits of the respective block cipher E chosen +by the ICC. + + + +46 Bundesamt für Sicherheit in der Informationstechnik + ASN.1 Specifications (Normative) A. + + + • The nonce s SHALL be encrypted in CBC mode according to ISO 10116 [9] using the key + K  =KDF    derived from the password  and IV =0. + • The nonce s SHALL be converted to a random generator using an algorithm-specific mapping + function Map. + +Note: Several different algorithms exist for implementing the mapping of the nonce to ephemeral +domain parameters. Currently, all specified mappings implementing  D =Map D PICC , s  map the +nonce to an ephemeral generator. It is RECOMMENDED to implement the mapping as a randomized +function. + + +A.3.4. ECDH Mapping + ~ +Let G and G Mapped be the static and an ephemeral base point on the elliptic curve. + + +A.3.4.1. Generic Mapping + ~ ~ +The function Map : G ↦ G Mapped is defined as G Mapped =s⋅G+ H , where H ∈〈G 〉 is chosen s.t. +log G H is unknown. The point H SHALL be calculated by an anonymous Diffie-Hellman Key +Agreement [4]. + +Note: The key agreement algorithm ECKA prevents small subgroup attacks by using compatible +cofactor multiplication. + + +A.3.4.2. Integrated Mapping +The Integrated ECDH Mapping is specified by ICAO [8]. + + +A.3.5. DH Mapping +Let g and ~ + g Mapped be the static and an ephemeral generator. + + +A.3.5.1. Generic Mapping +The function Map : g ↦~ + g Mapped is defined as ~ s + g Mapped =g ⋅h , where h∈⟨ g ⟩ is chosen s.t. log g h is +unknown. The group element h SHALL be calculated by an anonymous Diffie-Hellman Key +Agreement. + +Note: The public key validation method described in RFC 2631 [25] MUST be used to prevent small +subgroup attacks. + + +A.3.5.2. Integrated Mapping +The Integrated DH Mapping is specified by ICAO [8]. + + + + +Bundesamt für Sicherheit in der Informationstechnik 47 + A. ASN.1 Specifications (Normative) + + + +A.4. Chip Authentication + +A.4.1. Chip Authentication version 1 and 2 + +A.4.1.1. Chip Authentication Key Pair +The Key Pair(s) for Chip Authentication version 1 and 2 MUST be stored on the ICC. + • The private key SHALL be stored securely in the ICC’s memory. + • The public key SHALL be provided as SubjectPublicKeyInfo in the + ChipAuthenticationPublicKeyInfo structure. + • The domain parameters MAY be additionally provided as AlgorithmIdentifier in the + ChipAuthenticationDomainParameterInfo structure. +The data structures SubjectPublicKeyInfo and AlgorithmIdentifier are defined as follows; +more details can be found in [6]: + SubjectPublicKeyInfo ::= SEQUENCE { + algorithm AlgorithmIdentifier, + subjectPublicKey BIT STRING + } + + AlgorithmIdentifier ::= SEQUENCE { + algorithm OBJECT IDENTIFIER, + parameters ANY DEFINED BY algorithm OPTIONAL + } + +The ICC MAY support more than one Chip Authentication Key Pair (i.e. the chip may support different +algorithms and/or key lengths). In this case the local key identifier MUST be disclosed in the +corresponding ChipAuthenticationInfo, ChipAuthenticationPublicKeyInfo, and +ChipAuthenticationDomainParameterInfo (cf. A.1.1.2 for further details on the keyId). + + +A.4.1.2. Chip Authentication version 1 and 2 with DH +For Chip Authentication version 1 and 2 with DH the respective algorithms and formats from Table 3 +and Table 8 MUST be used. For Chip Authentication in version 1 PKCS#3 [26] MUST be used instead of +X9.42 [1]. + + OID Sym. Key Secure Auth. + Cipher Length Messaging Token + id-CA-DH-3DES-CBC-CBC 3DES 112 CBC / CBC CBC + id-CA-DH-AES-CBC-CMAC-128 AES 128 CBC / CMAC CMAC + id-CA-DH-AES-CBC-CMAC-192 AES 192 CBC / CMAC CMAC + id-CA-DH-AES-CBC-CMAC-256 AES 256 CBC / CMAC CMAC + Table 8: Object Identifiers for Chip Authentication with DH + + + + +48 Bundesamt für Sicherheit in der Informationstechnik + ASN.1 Specifications (Normative) A. + + +A.4.1.3. Chip Authentication version 1 and 2 with ECDH +For Chip Authentication version 1 and 2 with ECDH the respective algorithms and formats from Table 3 +and Table 9 MUST be used. + + + OID Sym. Key Secure Auth. + Cipher Length Messaging Token + id-CA-ECDH-3DES-CBC-CBC 3DES 112 CBC / CBC CBC + id-CA-ECDH-AES-CBC-CMAC-128 AES 128 CBC / CMAC CMAC + id-CA-ECDH-AES-CBC-CMAC-192 AES 192 CBC / CMAC CMAC + id-CA-ECDH-AES-CBC-CMAC-256 AES 256 CBC / CMAC CMAC + Table 9: Object Identifiers for Chip Authentication with ECDH + + +A.4.2. Chip Authentication Version 3 + +A.4.2.1. Static keys for Chip Authentication version 3 +Chip Authentication version 3 requires static keys on the ICC for Pseudonymous Signature +Authentication. See A.6 for the requirements. +The ICC MAY support more than one set of static keys for Pseudonymous Signature Authentication or +domain parameters for key agreement during Chip Authentication version 3 (i.e. the chip may support +different algorithms and/or key lengths). In this case, the local key identifier MUST be disclosed in the +corresponding ChipAuthenticationInfo, ChipAuthenticationDomainParameterInfo, +PSAInfo, and PSPublicKeyInfo (cf. A.1.1.2 for further details on the keyId). +For each supported set of static keys for Pseudonymous Signature Authentication, the ICC SHALL grant +access to at least one pseudonym without explicit authorization of the terminal (i.e. ps1-authInfo or +ps2-authInfo SHALL have value '0' in PSAInfo). + + +A.4.2.2. Sector Public Keys +The Sector Public Keys for Chip Authentication version 3 are used within Pseudonymous Signature +Authentication. See A.6.2 for the requirements. + + +A.4.2.3. Chip Authentication version 3 based on ECDH and ECSchnorr +For the Diffie Hellman Key Agreement during Chip Authentication version 3, the respective algorithms +of Table 3 and Table 9 MUST be used. +For Pseudonymous Signature Authentication the algorithms and formats of Table 3 and Table 10 +SHALL be used. The Pseudonymous Signature MUST be of plain signature format as defined in +Appendix A.6.5. + + + + +Bundesamt für Sicherheit in der Informationstechnik 49 + A. ASN.1 Specifications (Normative) + + + + + OID Hash + id-PSA-ECDH-ECSchnorr-SHA-256 SHA-256 + id-PSA-ECDH-ECSchnorr-SHA-384 SHA-384 + id-PSA-ECDH-ECSchnorr-SHA-512 SHA-512 + Table 10: Object Identifiers for PSA based on ECSchnorr with ECDH + + +A.5. Restricted Identification + +A.5.1. ICC Private Key +The generation of the private key SK ID is out of the scope of this specification. If SK ID is generated as +encrypted sequential counter or as encrypted document number, the secret encryption key SHALL be +generated and stored securely by a third party. + + +A.5.2. Sector Public Keys +The Sector Public Keys MUST be generated by a (trusted) third party. + • If the third party MUST be able to link sector-specific identifier across sectors, then the third + party SHALL generate Sector Key Pairs and store the Sector Private Keys securely. + • If the third party MUST NOT be able to link sector-specific identifier across sectors, then the + third party SHALL generate Sector Public Keys in a way that the corresponding private keys are + unknown. + + +A.5.3. Restricted Identification with DH +For Restricted Identification with DH the respective algorithms and formats from Table 3 and Table 11 +MUST be used. + + OID Hash + id-RI-DH-SHA-1 SHA-1 + id-RI-DH-SHA-224 SHA-224 + id-RI-DH-SHA-256 SHA-256 + id-RI-DH-SHA-384 SHA-384 + id-RI-DH-SHA-512 SHA-512 + Table 11: Object Identifiers for Restricted Identification with DH + + + + +50 Bundesamt für Sicherheit in der Informationstechnik + ASN.1 Specifications (Normative) A. + + +A.5.4. Restricted Identification with ECDH +For Restricted Identification with ECDH the respective algorithms and formats from Table 3 and Table +12 MUST be used. Input to the hash function SHALL be the x-coordinate of the point generated by +ECKA [4]. + + OID Hash + id-RI-ECDH-SHA-1 SHA-1 + id-RI-ECDH-SHA-224 SHA-224 + id-RI-ECDH-SHA-256 SHA-256 + id-RI-ECDH-SHA-384 SHA-384 + id-RI-ECDH-SHA-512 SHA-512 + Table 12: Object Identifiers for Restricted Identification with ECDH + + + +A.6. Pseudonymous Signatures + +A.6.1. Static keys for Pseudonymous Signatures +The static keys for Pseudonymous signatures MUST be stored on the ICC. + • The private keys SHALL be stored securely in the ICC’s memory. + • The ICC's public key including the domain parameters and the group manager's public key + SHALL be provided as SubjectPublicKeyInfo in the PSPublicKeyInfo structure. +To indicate public keys for Pseudonymous Signatures, the following algorithm identifier SHALL be used +within the SubjectPublicKeyInfo: + • The algorithm SHALL be of type ecPSPublicKey. + • The parameters SHALL indicate the associated cryptographic parameters and MUST consist of a + sequence containing + ◦ the domain parameters encoded as algorithm identifier according appendix A.2.1. + ◦ the group manager public key encoded as ECPoint. + ecPSPublicKey OBJECT IDENTIFIER ::= { bsi-de algorithms(1) ecc(1) keytype(2) + 3 } + +The ICC MAY support more than one set of static keys for Pseudonymous Signatures (i.e. the chip may +support different algorithms and/or key lengths). In this case, the local key identifier MUST be disclosed +in the corresponding PSAInfo, PSMInfo, PSCInfo and PSPublicKeyInfo (cf. also A.1.1.2 for +further details on the keyId for PSA). + + +A.6.2. Sector Public Keys +The Sector Public Keys for Chip Authentication version 3 and Pseudonymous Signatures MUST be +generated by a (trusted) third party. + + +Bundesamt für Sicherheit in der Informationstechnik 51 + A. ASN.1 Specifications (Normative) + + +If the third party must be able to link sector-specific identifier across sectors, then the third party +SHALL generate Sector Key Pairs and store the Sector Private Keys securely. +If the third party must not be able to link sector-specific identifier across sectors, then the third party +SHALL generate Sector Public Keys in a way that the corresponding private keys are unknown. + + +A.6.3. Digital Signature Information +As part of the pseudonymous signature protocol, the ICC SHALL include the object identifier (including tag +0x06 and length) of the protocol that is used as signature information ID DSI into signature computation. + +A.6.4. Projected representation of a public key +For computation and verification of Pseudonymous Signatures, projected representations of public keys are +used as described in the following: + • For ECSchnorr, the projected representation Π(PK ) of a public key is the x-coordinate of the + public point, i.e. an octet string of fixed length ⌈log 256 p⌉ . + +A.6.5. Pseudonymous Signatures of Messages or Credentials based on +ECSchnorr +The algorithms and formats of Table 3 and Table 13 SHALL be used for Pseudonymous Signature of +Messages and Credentials, respectively. + + + OID Hash + id-PSM-ECDH-ECSchnorr-SHA-256 SHA-256 + id-PSM-ECDH-ECSchnorr-SHA-384 SHA-384 + id-PSM-ECDH-ECSchnorr-SHA-512 SHA-512 + id-PSC-ECDH-ECSchnorr-SHA-256 SHA-256 + id-PSC-ECDH-ECSchnorr-SHA-384 SHA-384 + id-PSC-ECDH-ECSchnorr-SHA-512 SHA-512 + Table 13: Object Identifiers for PSM and PSC based on ECSchnorr with ECDH + + + +For the Pseudonymous Signature based on EC-Schnorr, the plain signature format SHALL be used, i.e. +the signature (e , s 1, s 2 ) SHALL be encoded as an octet string as octet string e||S 1||S 2 format, where + e is of hash length and S 1 and S 2 are the integers s1 and s 2 encoded as octet string with length +equal to the length of the order of the base point, respectively. + + +A.6.5.1. Credentials for PSC +The data that is signed by the ICC during Pseudonymous Signature of Credentials MUST have the +following structure + + + + +52 Bundesamt für Sicherheit in der Informationstechnik + ASN.1 Specifications (Normative) A. + + + • A discretionary data template containing a sequence of discretionary data objects with order as + given by the file IDs or data object tags as specified in the command data field of the + corresponding command APDU. + • Each discretionary data object contains the logical content of the corresponding data group or + Specific Attribute, respectively. + + + Data Object + Discretionary Data Template + Discretionary Data + ... + Table 14: Credential data format for PSC + + + + +A.7. Terminal Authentication + +A.7.1. Public Key References +Public keys to be used for Terminal Authentication MUST be contained in CV Certificates according to +the certificate profile defined in Appendix C.1. Each CV Certificate MUST contain two public key +references, a Certificate Holder Reference and a Certification Authority Reference: +Certificate Holder Reference: The Certificate Holder Reference is an identifier for the public key +provided in the certificate that SHALL be used to reference this public key. +Certification Authority Reference: The Certification Authority Reference is a reference to the (external) +public key of the certification authority that SHALL be used to verify the signature of the certificate. + +Note: As a consequence, the Certification Authority Reference contained in a certificate MUST be equal +to the Certificate Holder Reference in the corresponding certificate of the issuing certification +authority. + + + Encoding Length + Country Code ISO 3166-1 ALPHA-2 2F + Holder Mnemonic ISO/IEC 8859-1 9V + Sequence Number ISO/IEC 8859-1 5F + F: fixed length (exact number of octets) + V: variable length (up to number of octets) + Table 15: Certificate Holder Reference + +The Certificate Holder Reference SHALL consist of the following concatenated elements: Country Code, +Holder Mnemonic, and Sequence Number. Those elements MUST be chosen according to Table 15 and +the following rules: + 1. Country Code + The Country Code SHALL be the ISO 3166-1 ALPHA-2 code of the certificate holder’s country. + +Bundesamt für Sicherheit in der Informationstechnik 53 + A. ASN.1 Specifications (Normative) + + + 2. Holder Mnemonic + The Holder Mnemonic SHALL be assigned as unique identifier as follows: + • The Holder Mnemonic of a CVCA SHALL be assigned by the CVCA itself. + • The Holder Mnemonic of a DV SHALL be assigned by the domestic CVCA. + • The Holder Mnemonic of an IS SHALL be assigned by the supervising DV. + 3. Sequence Number + The Sequence Number SHALL be assigned by the certificate holder. + • The Sequence Number MUST be numeric or alphanumeric: + – A numeric Sequence Number SHALL consist of the characters “0”...”9”. + – An alphanumeric Sequence Number SHALL consist of the characters “0”...”9” and “A”...”Z”. + • The Sequence Number MAY start with the ISO 3166-1 ALPHA-2 country code of the certifying + certification authority, the remaining three characters SHALL be assigned as alphanumeric + Sequence Number. + • The Sequence Number MAY be reset if all available Sequence Numbers are exhausted. + + +A.7.2. Public Key Import +Public keys imported by the certificate validation procedure (cf. Section 2.5) are either permanently or +temporarily stored on the ICC. + +Note: The ICC SHOULD reject to import a public key, if the Certificate Holder Reference is already +known to the ICC. + + +A.7.2.1. Permanent Import +Public keys contained in CVCA Link Certificates SHALL be permanently imported by the ICC and +MUST be stored securely in the ICC's memory. A permanently imported public key and its metadata +SHALL fulfill the following conditions: + • It MAY be overwritten after expiration by a subsequent permanently imported public key. + • It MUST + ◦ either be overwritten by a subsequent permanently imported public key with the same + Certificate Holder Reference + ◦ or the import MUST be rejected. + • It MUST NOT be overwritten by a temporarily imported public key. +Enabling and disabling a permanently imported public key MUST be an atomic operation. + + +A.7.2.2. Temporary Import +Public keys contained in DV and Terminal Certificates SHALL be temporarily imported by the ICC. A +temporarily imported public key and its metadata SHALL fulfill the following conditions: + • It SHALL NOT be selectable or usable after a power down of the ICC. + +54 Bundesamt für Sicherheit in der Informationstechnik + ASN.1 Specifications (Normative) A. + + + • It MUST remain usable until the subsequent cryptographic operation is successfully completed + (i.e. PSO:Verify Certificate or External Authenticate). + • It MAY be overwritten by a subsequent temporarily imported public key. +A terminal MUST NOT make use of any temporarily imported public key but the most recently +imported. + + +A.7.2.3. Imported Metadata +For each permanently or temporarily imported public key the following additional data contained in +the certificate (cf. Appendix C.1) MUST be stored: + • Certificate Holder Reference + • Certificate Holder Authorization (effective role and effective authorization) + • Certificate Effective Date + • Certificate Expiration Date + • Certificate Extensions (where applicable) +The calculation of the effective role (CVCA, DV, or Terminal) and the effective authorization of the +certificate holder is described in Section 2.7. + +Note: The format of the stored data is operating system dependent and out of the scope of this +specification. + + +A.7.2.4. EF.CVCA +Support for the elementary file EF.CVCA is CONDITIONAL. If the ICC supports Terminal +Authentication in version 1 it MUST make the references of CVCA public keys suitable for inspection +systems available in a transparent elementary file EF.CVCA contained in the ePassport application as +specified in Table 16. + + File Name EF.CVCA + File ID 0x011C (default) + Short File ID 0x1C (default) + Read Access BAC or PACE (conditional to protocol support) + Write Access NEVER (internally updated only) + Size 36 bytes (fixed) padded with octets of value 0x00 + Content [CARi ][||CARi-1][||0x00..00] + Table 16: Elementary File EF.CVCA + + +This file SHALL contain a sequence of Certification Authority Reference (CAR) data objects (cf. +Appendix D.2) suitable for Terminal Authentication. + • It SHALL contain at most two Certification Authority Reference data objects. + • The most recent Certification Authority Reference SHALL be the first data object in this list. + + + +Bundesamt für Sicherheit in der Informationstechnik 55 + A. ASN.1 Specifications (Normative) + + + • The file MUST be padded by appending octets of value 0x00. +The file EF.CVCA has a default file identifier and short file identifier. If the default values cannot be used, +the (short) file identifier SHALL be specified in the OPTIONAL parameter efCVCA of the +TerminalAuthenticationInfo. If efCVCA is used to indicate the file identifier to be used, the +default file identifier is overridden. If no short file identifier is given in efCVCA, the file EF.CVCA MUST +be explicitly selected using the given file identifier. + + +A.7.3. Terminal Authentication with RSA +For Terminal Authentication with RSA the following algorithms and formats MUST be used. + + +A.7.3.1. Signature Algorithm +RSA [17], [27] as specified in Table 17 SHALL be used. The default parameters to be used with RSA-PSS +are defined as follows: + • Hash Algorithm: The hash algorithm is selected according to Table 17. + • Mask Generation Algorithm: MGF1 [17], [27] using the selected hash algorithm. + • Salt Length: Octet length of the output of the selected hash algorithm. + • Trailer Field: 0xBC + +A.7.3.2. Public Key Format +The TLV-Format [14] as described in Appendix D.3.1 SHALL be used. + • The object identifier SHALL be taken from Table 17. + • The bit length of the modulus SHALL be 1024, 1280, 1536, 2048, or 3072. + • The bit length of the exponent SHALL be at most 32. + + OID Signature Hash Parameters + id-TA-RSA-v1-5-SHA-1 RSASSA-PKCS1-v1_5 SHA-1 N/A + id-TA-RSA-v1-5-SHA-256 RSASSA-PKCS1-v1_5 SHA-256 N/A + id-TA-RSA-v1-5-SHA-512 RSASSA-PKCS1-v1_5 SHA-512 N/A + id-TA-RSA-PSS-SHA-1 RSASSA-PSS SHA-1 default + id-TA-RSA-PSS-SHA-256 RSASSA-PSS SHA-256 default + id-TA-RSA-PSS-SHA-512 RSASSA-PSS SHA-512 default + Table 17: Object Identifiers for Terminal Authentication with RSA + + +A.7.4. Terminal Authentication with ECDSA +For Terminal Authentication with ECDSA the following algorithms and formats MUST be used. + + + + +56 Bundesamt für Sicherheit in der Informationstechnik + ASN.1 Specifications (Normative) A. + + +A.7.4.1. Signature Algorithm + + + OID Signature Hash + id-TA-ECDSA-SHA-1 ECDSA SHA-1 + id-TA-ECDSA-SHA-224 ECDSA SHA-224 + id-TA-ECDSA-SHA-256 ECDSA SHA-256 + id-TA-ECDSA-SHA-384 ECDSA SHA-384 + id-TA-ECDSA-SHA-512 ECDSA SHA-512 + Table 18: Object Identifiers for Terminal Authentication with ECDSA + +ECDSA with plain signature format [4] as specified in Table 18 SHALL be used. + + +A.7.4.2. Public Key Format +The TLV-Format [14] as described in Appendix D.3.3 SHALL be used. + • The object identifier SHALL be taken from Table 18. + • The bit length of the curve SHALL be 160, 192, 224, 256, 320, 384 or 512. + • Domain Parameters SHALL be compliant to [4]. + + +A.7.5. Authenticated Auxiliary Data for Terminal Authentication Version 2 +Usage of auxiliary data A PCD in Terminal Authentication is CONDITIONAL. It MUST be used if further +operations performed by the terminal require authenticated auxiliary data (details can be found in the +following sections): + • For age verification, the terminal MUST commit to the required date of birth. + • For document validity verification, the terminal MUST commit to the current date. + • For municipality ID verification, the terminal MUST commit to (parts of) the municipality ID. + • For PSM, the terminal MUST commit to the messages to be signed. + • For Data Group Content verification, the terminal MUST commit to the required data to be + verified. +Authenticated auxiliary data MUST be structured as specified in Table 19: + • An authentication data object that contains a sequence of discretionary data templates. + • Each discretionary data template contains an object identifier and a discretionary data object. + The content of the discretionary data object is defined by the object identifier. + + + + +Bundesamt für Sicherheit in der Informationstechnik 57 + A. ASN.1 Specifications (Normative) + + + + + Data Object + Authentication + Discretionary Data Template + Object Identifier + Discretionary Data + Discretionary Data Template + Object Identifier + Discretionary Data + ... + Table 19: Authenticated Auxiliary Data + + + +This structure SHALL be used as input for the signature computation during Terminal Authentication. +Only after a successful authentication of the terminal, the ICC SHALL interpret and make the data +contained in the discretionary data object available for further operations. Depending of the +application, the terminal MAY transmit additional discretionary data templates than listed in the +following. Discretionary data templates with unknown object identifier SHOULD be ignored by the +ICC. + +Note: If the authentication data object contains more than one discretionary data template with the +same object identifier, the data of the last discretionary data template SHALL be made available for +further operations. + + +A.7.5.1. Object Identifier +The following object identifier SHALL be used to identify authenticated auxiliary data: + id-AuxiliaryData OBJECT IDENTIFIER ::= { + bsi-de applications(3) mrtd(1) 4 + } + +A.7.5.2. Age Verification +The following object identifier SHALL be used for age verification: + id-DateOfBirth OBJECT IDENTIFIER ::= {id-AuxiliaryData 1} + +The discretionary data object SHALL contain the date of birth encoded as Date (cf. Part 2) that is +required by the terminal. The ICC SHALL compare the stored date of birth to the required date of birth. +Age Verification is successful if the stored date of birth is not after the required date of birth. + + +A.7.5.3. Document Validity Verification +The following object identifier SHALL be used for document validity verification: + id-DateOfExpiry OBJECT IDENTIFIER ::= {id-AuxiliaryData 2} + + +58 Bundesamt für Sicherheit in der Informationstechnik + ASN.1 Specifications (Normative) A. + + + +The discretionary data object SHALL contain the current date of the terminal encoded as Date (cf. Part +2). The ICC SHALL compare the stored date of expiry to the current date. Document Validity +Verification is successful if the stored date of expiry is not before the given current date. + + +A.7.5.4. Municipality ID Verification +The following object identifier SHALL be used for municipality ID verification: + id-MunicipalityID OBJECT IDENTIFIER ::= {id-AuxiliaryData 3} + +The discretionary data object SHALL contain (parts of) the municipality ID encoded as OctetString +(cf. Part 2). The ICC SHALL compare the leftmost octets of the stored municipality ID to the transmitted +(part of the) requested municipality ID. Municipality ID Verification is successful if the leftmost octets +of the stored data are identical to the transmitted data. + + +A.7.5.5. Pseudonymous Signature of Messages +The following object identifier SHALL be used to authenticate a message to be signed by the ICC via +PSM: + id-PSM-Message OBJECT IDENTIFIER ::= {id-AuxiliaryData 4} + +The discretionary data object SHALL contain the hash value of the input to be signed encoded as +Octet String. When a Pseudonymous Signature is requested by the Terminal after authentication, +the ICC SHALL verify that the hash of the transmitted input was contained in the authenticated +auxiliary data using the hash function defined by Terminal Authentication. If this verification fails, the +ICC MUST deny to sign the input via PSM. + + +A.7.5.6. Data Group Content Verification +The following object identifiers SHALL be used for Data Group Content verification + id-DGContent OBJECT IDENTIFIER ::= {id-AuxiliaryData 5} + + id-DGContent-DG1 OBJECT IDENTIFIER ::= {id-DGContent 1} + id-DGContent-DG2 OBJECT IDENTIFIER ::= {id-DGContent 2} + id-DGContent-DG3 OBJECT IDENTIFIER ::= {id-DGContent 3} + id-DGContent-DG4 OBJECT IDENTIFIER ::= {id-DGContent 4} + id-DGContent-DG5 OBJECT IDENTIFIER ::= {id-DGContent 5} + id-DGContent-DG6 OBJECT IDENTIFIER ::= {id-DGContent 6} + id-DGContent-DG7 OBJECT IDENTIFIER ::= {id-DGContent 7} + id-DGContent-DG8 OBJECT IDENTIFIER ::= {id-DGContent 8} + id-DGContent-DG9 OBJECT IDENTIFIER ::= {id-DGContent 9} + id-DGContent-DG10 OBJECT IDENTIFIER ::= {id-DGContent 10} + id-DGContent-DG11 OBJECT IDENTIFIER ::= {id-DGContent 11} + id-DGContent-DG12 OBJECT IDENTIFIER ::= {id-DGContent 12} + id-DGContent-DG13 OBJECT IDENTIFIER ::= {id-DGContent 13} + id-DGContent-DG14 OBJECT IDENTIFIER ::= {id-DGContent 14} + id-DGContent-DG15 OBJECT IDENTIFIER ::= {id-DGContent 15} + id-DGContent-DG16 OBJECT IDENTIFIER ::= {id-DGContent 16} + id-DGContent-DG17 OBJECT IDENTIFIER ::= {id-DGContent 17} + id-DGContent-DG18 OBJECT IDENTIFIER ::= {id-DGContent 18} + id-DGContent-DG19 OBJECT IDENTIFIER ::= {id-DGContent 19} + + +Bundesamt für Sicherheit in der Informationstechnik 59 + A. ASN.1 Specifications (Normative) + + + id-DGContent-DG20 OBJECT IDENTIFIER ::= {id-DGContent 20} + id-DGContent-DG21 OBJECT IDENTIFIER ::= {id-DGContent 21} + id-DGContent-DG22 OBJECT IDENTIFIER ::= {id-DGContent 22} + +The discretionary data object SHALL contain the data encoded as BIT STRING. The ICC SHALL +compare the data with the binary logical content of the corresponding data group. Data Group +Verification is successful if the transmitted data is identical with the logical content of the +corresponding data group. + +Note: To support Data Group Content Verification for further data groups in future, the list of object +identifiers will be continued accordingly. + + +A.8. Enhanced Role Authentication + +A.8.1. Data format of Attribute Request +For Enhanced Role Authentication, Attribute Requests stored on the ICC SHALL be of the following type. + RequestInfos ::= SET OF RequestInfo + + RequestInfo ::= SEQUENCE { + requestType OBJECT IDENTIFIER, + requiredData ANY DEFINED BY requestType, + optionalData ANY DEFINED BY requestType OPTIONAL + } + +A.8.2. Data format of Specific Attributes +The following ASN.1 structure SHALL be used to store Attributes for Enhanced Role Authentication on the +ICC. + Attribute ::= SEQUENCE { + attributeType OBJECT IDENTIFIER, + requiredData ANY DEFINED BY attributeType + optionalData ANY DEFINED BY attributeType +} + + + + +60 Bundesamt für Sicherheit in der Informationstechnik + ISO 7816 Mapping (Normative) B. + + + +B. ISO 7816 Mapping (Normative) +In this Appendix the protocols for PACE, Chip Authentication and Terminal Authentication are mapped +to ISO 7816 APDUs (Application Protocol Data Units). + + +B.1. PACE +The following sequence of commands SHALL be used to implement PACE. Secure messaging is +CONDITIONAL. It MUST be used for the second execution of PACE if the protocol is executed twice: + 1. MSE:Set AT + 2. General Authenticate +The command MSE:Set AT contains the following data objects (see B.14.1 for details). + Tag Comment +0x80 Cryptographic mechanism reference REQUIRED +0x83 Password reference REQUIRED +0x84 Reference for computing a session key CONDITIONAL +0x7F4C Certificate Holder Authorization Template CONDITIONAL +0x65 Certificate Extensions CONDITIONAL + + +The protocol specific data objects SHALL be exchanged in a chain of General Authenticate commands +as shown below: + Step Description Protocol Command Data Protocol Response Data + 1. Encrypted Nonce - Absent5 0x80 Encrypted Nonce + 2. Map Nonce 0x81 Mapping Data 0x82 Mapping Data + 3. Perform Key Agreement 0x83 Ephemeral Public Key 0x84 Ephemeral Public Key + 4. Mutual Authentication 0x85 Authentication Token 0x86 Authentication Token + 0x87 Certification Authority + Reference + (CONDITIONAL) + 0x88 Certification Authority + Reference + (CONDITIONAL) + +The Certificate Authority Reference(s) are REQUIRED if PACE is used with a Certificate Holder +Authorization Template, i.e. if PACE is to be followed by Terminal Authentication version 2. In this case +the data object 0x87 SHALL contain the most recent Certificate Authority Reference with respect to the +terminal type indicated in the Certificate Holder Authorization Template. The data object 0x88 MAY +contain the previous Certificate Authority Reference. + + + + +5 This implies an empty Dynamic Authentication Data Object. + +Bundesamt für Sicherheit in der Informationstechnik 61 + B. ISO 7816 Mapping (Normative) + + +Note: The domain parameters for PACE supported by the chip are made available in EF.CardAccess (cf. +Appendix A.1.2). If more than one set of domain parameters is supported, the terminal MUST select the +domain parameters to be used within MSE:Set AT. + + +B.1.1. Encrypted Nonce +The encrypted nonce (cf. Appendix A.3.3) SHALL be encoded as octet string. + + +B.1.2. Mapping Data +The exchanged data is specific to the used mapping. + +B.1.2.1. Generic Mapping +The ephemeral public keys (cf. Appendix A.2.2 and Appendix D.3.4) SHALL be encoded as elliptic curve +point (ECDH) or unsigned integer (DH). + + +B.1.2.2. Integrated Mapping +The Integrated Mapping is specified by ICAO [8]. + +B.1.3. Authentication Token +The authentication token (cf. Appendix A.2.4) SHALL be encoded as octet string. + + +B.1.4. Certification Authority Reference +The ICC SHALL return the Certificate Authority References of appropriate CVCA public keys stored on +the ICC: + • The references MUST be dynamically chosen to suit the terminal type indicated by PACE. + • It SHALL return at most two Certification Authority Reference data objects. + • The most recent Certification Authority Reference SHALL be contained in data object 0x87. + + +B.2. Chip Authentication +The following command SHALL be used with secure messaging to implement Chip Authentication in +version 1 with 3DES Secure Messaging: + 1. MSE:Set KAT + +Note: MSE:Set KAT MUST NOT be used for any other algorithms than id-CA-DH-3DES-CBC-CBC +and id-CA-ECDH-3DES-CBC-CBC, i.e. Secure Messaging is restricted to 3DES. +The following sequence of commands SHALL be used with secure messaging + • to implement Chip Authentication in version 1 with AES and + • to implement Chip Authentication in version 2. + + +62 Bundesamt für Sicherheit in der Informationstechnik + ISO 7816 Mapping (Normative) B. + + +Additionally, this sequence MAY be used to implement Chip Authentication version 1 with 3DES. + 1. MSE:Set AT + 2. General Authenticate +The command MSE:Set AT contains the following data objects (see B.14.1 for details). + Tag Comment +0x80 Cryptographic mechanism reference REQUIRED +0x84 Reference of a private key CONDITIONAL +0xE0 Template for Session Context Identifier CONDITIONAL + + +The protocol specific data objects SHALL be exchanged with a General Authenticate command as +shown below: + Step Description Protocol Command Data Protocol Response Data + 1. Chip Authentication 0x80 Ephemeral Public Key 0x81 Nonce + 0x82 Authentication Token + +Note: Support of Protocol Response Data is CONDITIONAL: It MUST be provided for version 2 but +MUST NOT be provided for version 1. + +Note: The public keys for Chip Authentication supported by the chip are made available in the Security +Objects (cf. Appendix A.1.2). If more than one public key is supported, the terminal MUST select the +corresponding private key of the chip to be used within MSE:Set AT. +The following sequence of commands SHALL be used with secure messaging to implement Chip +Authentication Version 3: + 1. MSE:Set AT + 2. General Authenticate + 3. MSE:Set AT + 4. General Authenticate +The first MSE:Set AT command of step 1 contains the following data objects (see B.14.1 for details). + Tag Comment +0x80 Cryptographic mechanism reference REQUIRED +0x84 Reference of a private key REQUIRED +0xE0 Template for Session Context Identifier CONDITIONAL + + +The protocol specific data objects for the key agreement during Chip Authentication Version 3 SHALL +be exchanged in command number 2 by means of a General Authenticate command as shown below. + Step Description Protocol Command Data Protocol Response Data + 1. Perform Key Agreement 0x80 Ephemeral Public Key 0x81 Ephemeral Public Key + + Table 20: Chip Authentication Version 3 - General Authenticate command for Key Agreement + + + +Bundesamt für Sicherheit in der Informationstechnik 63 + B. ISO 7816 Mapping (Normative) + + +The MSE:Set AT command of step 3 contains the following data objects (see B.14.1 for details). + Tag Comment +0x80 Cryptographic mechanism reference REQUIRED +0x84 Reference of a private key REQUIRED + + +The protocol specific data objects for PSA during Chip Authentication Version 3 SHALL be exchanged in +command number 4 with a General Authenticate command as shown below. + Step Description Protocol Command Data Protocol Response Data + 1. Compute Pseudonymous 0x80 Sector Public Key 0x82 1st Pseudonym Public + Signature Key (CONDITIONAL) + 0x83 2nd Pseudonym Public + Key (CONDITIONAL) + 0x84 Pseudonymous + Signature + + Table 21: Chip Authentication Version 3 - General Authenticate command for PSA + +The ICC MUST compute the Pseudonymous Signature over the context-specific data object 0x81 of step +2 (including tag 0x81 and length) encapsulating the ICC's ephemeral public key. +If applicable, the steps 3. and 4. MAY be repeated with a different ICC's private key and/or different +Terminal Sector Public keys. + +Note: The ICC's private key pair for Chip Authentication Version 3 supported by the chip are indicated +in the relevant Security Objects. If more than one private key is supported, the Terminal MUST select +the private key to be used within MSE:Set AT. +Note: If Chip Authentication Version 3 is supported by the ICC, this protocol SHALL be available in the +Master File. Availability on application level is application-specific. + + +B.2.1. Ephemeral Public Key +The ephemeral public keys (cf. Appendix A.2.2 and Appendix D.3.4) SHALL be encoded as elliptic curve +point (ECDH) or unsigned integer (DH). + + +B.2.2. Nonce +The nonce SHALL be encoded as octet string of size 8 octets. + + +B.2.3. Authentication Token +The authentication token (cf. Appendix A.2.4) SHALL be encoded as octet string. + + + + +64 Bundesamt für Sicherheit in der Informationstechnik + ISO 7816 Mapping (Normative) B. + + +B.2.4. Sector Public Key +The Sector Public Key PK Sector for Chip Authentication Version 3 SHALL be encoded as elliptic curve +point (cf. D.2.1.2). The domain parameters SHALL NOT be included. + + +B.2.5. Pseudonym Public Key +The Pseudonym Public Key SHALL be encoded as an elliptic curve point (cf. A.2.2 and D.3.4). The +domain parameters SHALL NOT be included. + + +B.2.6. Pseudonymous signature +The pseudonymous signature SHALL be encoded as an octet string according to A.6.5. + + +B.3. Terminal Authentication +The following sequence of commands SHALL be used with secure messaging to implement Terminal +Authentication: + 1. MSE:Set DST + 2. PSO:Verify Certificate + 3. MSE:Set AT + 4. Get Challenge + 5. External Authenticate +Steps 1 and 2 are repeated for every CV certificate to be verified (CVCA Link Certificates, DV Certificate, +Terminal Certificate). +The command MSE:Set DST contains the following data objects (see B.14.4 for details). + Tag Comment +0x83 Reference of a public key REQUIRED + + +The Command MSE:Set AT contains the following data objects (see B.14.1 for details). + Tag Comment +0x80 Cryptographic mechanism reference REQUIRED +0x83 Reference of a public key REQUIRED +0x67 Auxiliary authenticated data CONDITIONAL +0x91 Ephemeral Public Key REQUIRED + + +For Terminal Authentication in version 2 the ICC MUST in addition support the usage of Get Challenge +before step 1, i.e. the ICC MUST keep a generated challenge upon usage by External Authenticate. + + + + +Bundesamt für Sicherheit in der Informationstechnik 65 + B. ISO 7816 Mapping (Normative) + + + +B.4. Restricted Identification +The following sequence of commands SHALL be used with secure messaging to implement Restricted +Identification: + 1. MSE:Set AT + 2. General Authenticate +The command MSE:Set AT contains the following data objects (see B.14.1 for details). + Tag Comment +0x80 Cryptographic mechanism reference REQUIRED + + +The protocol specific data objects SHALL be exchanged with General Authenticate commands as shown +below, command chaining MUST NOT be used. At least one of the steps MUST be executed: + Step Description Protocol Command Data Protocol Response Data + 1. Restricted Identification 0xA0 1st Sector Public Key 0x81 1st Sector-specific + (CONDITIONAL) Identifier + 2. Restricted Identification 0xA2 2nd Sector Public Key 0x83 2nd Sector-specific + (CONDITIONAL) Identifier + +Note: The private keys for Restricted Identification supported by the chip are indicated in the relevant +Security Objects (cf. Appendix A.1.2). If more than one private key is supported, the terminal MUST +select the private key to be used within MSE:Set AT. + +Note: If Restricted Identification is supported by the ICC, availability of the protocol is +application-specific. + + +B.4.1. Public Key +The Sector Public Key PK Sector SHALL be encoded as public key data object without tag 0x7F49 (i.e. +0x7F49 is replaced by 0xA0/0xA2, respectively) (cf. Appendix D.3), the domain parameters MUST be +included. + + +B.4.2. Sector-specific Identifier +The sector-specific identifier I Sector + ID SHALL be encoded as octet string. + + +B.5. Pseudonymous Signature of Messages or Credentials +The following sequence of commands SHALL be used to implement the Pseudonymous Signature of a +Message: + 1. MSE:Set DST + 2. PSO: Compute Digital Signature +The Command MSE:Set DST contains the following data objects (see B.14.4 for details). + + +66 Bundesamt für Sicherheit in der Informationstechnik + ISO 7816 Mapping (Normative) B. + + + Tag Comment +0x80 Cryptographic mechanism reference REQUIRED +0xE1 File Reference CONDITONAL +x84 Reference of a private key REQUIRED + + +The protocol specific data objects SHALL be exchanged in a PSO:Compute Digital Signature +command as shown below. + Step Description Protocol Command Data Protocol Response Data + 1. Compute Pseudonymous 0x80 Sector Public Key 0x82 Pseudonym Public Key + Signature of a Message (CONDITIONAL) + 0x81 Input to be signed 0x83 Pseudonym Public Key + (CONDITIONAL) (CONDITIONAL) + 0x84 Pseudonymous + Signature + + Table 22: Pseudonymous Signature of Messages - PSO:Compute Digital Signature command + +The input to be signed MUST be present if PSM is performed. In this case, the hash value of the input +using the hash function of Terminal Authentication MUST have been sent to the ICC by the terminal in +authenticated auxiliary data as part of Terminal Authentication. The ICC MUST compute the +Pseudonymous Signature over plain value of tag 0x81. +For PSC, the input MUST be absent. In this case, the ICC MUST compute the Pseudonymous Signature +over the data template defined in A.6.5.1 encapsulating the content of the files and Attributes as +indicated in the MSE:Set DST command. + +Note: If the terminal requests a Specific Attribute to be included into the Pseudonymous Signature of +Credentials computation and the terminal is not authorized to get access to all Terminal Sectors, the +ICC MUST require the terminal to present its user ID before execution of the protocol. + +Note: If the terminal requests Specific Attributes to be included into the Pseudonymous Signature of +Credentials computation and the terminal is authorized to get access to all Terminal Sectors, the ICC +MUST include the Specific Attributes in the same order into the data template of case, the ICC MUST +compute the Pseudonymous Signature over the data template defined in A.6.5.1 as in the Get Data +response according to B.10.5. + +Note: The private keys for Pseudonymous Signature supported by the chip are indicated in the relevant +Security Objects. If more than one private key is supported, the Terminal MUST select the private key to +be used within MSE:Set DST. + +Note: If Pseudonymous Signatures of Messages and/or Pseudonymous Signatures of Credentials are +supported by the ICC, availability of PSM and/or PSC is application-specific. + + +B.5.1. Sector Public Key +The Sector Public Key PK Sector SHALL be encoded as elliptic curve point (ECDH) (cf. A.2.2 and D.3.4). +The domain parameters SHALL NOT be included. + + +Bundesamt für Sicherheit in der Informationstechnik 67 + B. ISO 7816 Mapping (Normative) + + +B.5.2. Pseudonym Public Key +The Pseudonym Public Key SHALL be encoded as an elliptic curve point (cf. A.2.2 and D.3.4). The +domain parameters SHALL NOT be included. + + +B.5.3. Pseudonymous signature +The pseudonymous signature SHALL be encoded as an octet string according to Appendix A.6.5 +(ECDH). + + +B.6. Auxiliary Data Verification +One or both of the following commands SHALL be used with secure messaging to implement Age +Verification, Document Validity Verification and Municipality ID Verification: + • Verify + • Compare +For the remaining verification functions, the following command MUST be used with secure messaging +for implementation: + • Compare +The following authenticated auxiliary data MUST have been sent to the ICC as part of Terminal +Authentication: + • For Age Verification the terminal MUST have sent the required date of birth. + • For Document Validity Verification, the terminal MUST have sent the current date. + • For Municipality ID Verification, the terminal MUST have sent the (part of the) municipality ID. + • For Data Group Content Verification, the terminal MUST have sent the required data to be + compared with a data group. + + +B.7. PIN Management + +B.7.1. Unblock or Change PIN +The following command SHALL be used with secure messaging to implement unblocking and/or +changing of the PIN: + 1. Reset Retry Counter + • To set a new PIN and reset the retry counter the terminal SHALL use Reset Retry Counter + with the new PIN as data. + • To reset the retry counter the terminal SHALL use Reset Retry Counter with no data. +Usage of the command SHALL be restricted to authorized terminals: Before using this command the +terminal must either authenticate as Authentication Terminal with effective authorization for PIN +Management or by using PACE with the PUK/PIN. + + + +68 Bundesamt für Sicherheit in der Informationstechnik + ISO 7816 Mapping (Normative) B. + + +B.7.2. Activate or Deactivate PIN +The following command SHALL be used with secure messaging to activate the PIN: + 1. Activate +The following command SHALL be used with secure messaging to deactivate the PIN: + 1. Deactivate +Usage of the command SHALL be restricted to authorized terminals: Before using this command the +terminal must authenticate as Authentication Terminal with effective authorization for PIN +Management. + + +B.8. eSign Application +Commands for installing, updating, and using the eSign Application are out of scope of this +specification. + + +B.9. Reading Data Groups +The APDUs for selecting and reading EAC-protected data groups already specified by ICAO [8] SHALL +be used (i.e. Select File and Read Binary). In accordance with ICAO specifications any unauthorized +access to EAC-protected data groups SHALL be denied and the ICC MUST respond with status bytes +0x6982 (“Security status not satisfied”). + + +B.10. Enhanced Role Authentication +Usage of the commands of this section SHALL be restricted to authenticated terminals. + +Note: Within this section, the commands Put Data/Get Data/Delete Data are specified only as +interfaces for Enhanced Role Authentication. It is not required to support the whole functionalities of +data objects (e.g. access control management). + + +B.10.1. User Presentation +The following commands SHALL be used with secure messaging to implement the presentation of the +user for writing Attribute Requests or reading/deleting Specific Attributes. + 1. Perform User Operation:Present User + • The terminal SHALL present the hash of its Sector Public key as user ID in the data field of + the command APDU + • The ICC MUST verify that the received hash is contained in the Terminal Sector extension + as defined in C.3.2.1 of the terminal's CV Certificate. +If the user ID is unknown to the ICC, the ICC MUST return a warning 0x62XX to the terminal. In this +case, the ICC SHALL create the respective user by assigning an accessible data container to the user ID +and personalizing the access conditions of the data container. + + + + +Bundesamt für Sicherheit in der Informationstechnik 69 + B. ISO 7816 Mapping (Normative) + + +Note: The moment when a data container is created is implementation specific and out of scope of this +document. + +Note: The presentation of the user ID MUST only be valid within the corresponding session context. + + +B.10.2. Writing Attribute Requests +The following commands SHALL be used with secure messaging to implement writing of an Attribute +Request into the ICC's Attribute Request Container: + 1. Put Data + • The terminal SHALL send the RequestInfos in the data field of the command APDU + +Note: The ICC MUST require the terminal to present its user ID before writing an Attribute Request. +Writing Attribute Requests SHALL be restricted to authorized terminals. + + +B.10.3. Reading Attribute Requests +The following command SHALL be used with secure messaging to implement reading of an Attribute +Request from the ICC + 1. Get Data + • The ICC's response APDU MUST contain the RequestInfos in the data field. +Reading Attribute Requests SHALL be restricted to authorized terminals (Attribute Providers). + + +B.10.4. Writing Specific Attributes +The following command SHALL be used with secure messaging to implement writing of Attributes on +the ICC + 1. Put Data + • The terminal SHALL use the tag P1/P2=0x00FF with a list of discretionary data tags 0x53 + each containing a Specific Attribute in the command data field. +Writing Attribute SHALL be restricted to authorized terminals (Attribute Providers). + + +B.10.5. Reading Specific Attributes +The following command SHALL be used with secure messaging to implement reading of an Attribute +from the ICC + 1. Get Data + • If the terminal has effective authorization to access to Specific Attributes for all Terminal + Sectors, the response data field MUST contain the Specific Attributes for each Terminal + Sector contained in a discretionary data template 0x73. Otherwise, the response MUST + contain the Specific Attributes linked to the presented terminal's Sector Public Key. + + + + +70 Bundesamt für Sicherheit in der Informationstechnik + ISO 7816 Mapping (Normative) B. + + +Note: If the terminal's effective authorization is restricted to read Specific Attributes linked to the +Terminal Sector, the ICC MUST require the terminal to present its user ID before execution of the +command. +Usage of this command SHALL be restricted to authenticated terminals with effective authorization for +reading Specific Attributes. + + +B.10.6. Deleting Specific Attributes +The following command SHALL be used with secure messaging to implement deleting of an Attribute +from the ICC + 1. Delete Data + • If the terminal has effective authorization to delete to Specific Attributes for all Terminal + Sectors, the ICC MUST delete the Specific Attributes for each Terminal Sector. Otherwise, + the ICC MUST delete only the Specific Attributes linked to the presented terminal's Sector + Public Key. + +Note: If the terminal's effective authorization is restricted to delete Specific Attributes linked to the +Terminal Sector, the ICC MUST require the terminal to present its user ID before execution of the +command. +Usage of this command SHALL be restricted to authenticated terminals with effective authorization for +deleting Specific Attributes. + + +B.10.7. Writing and Reading and Erasing Generic Attributes +For reading and writing Generic Attributes the commands Read Binary, Update Binary and Erase Binary are +specified in [12]. + + +B.11. Switching of Session Context +If switching of Session Context is supported by the ICC, the PACE Session Context MUST be stored +immediately before restarting secure messaging or switching from PACE session context to another +session context. +The storage of the Chip Authentication Session Context is indicated within the command MSE: Set AT +of Chip Authentication Version 2 or Version 3. +To restore a stored Session Context, the following command SHALL be used with Secure Messaging: + 1. MSE:Set AT +The command MSE:Set AT contains the following data objects. + Tag Comment +0xE1 Template for Session Context Identifier REQUIRED + +Note: The current DF and current EF (and for Chip Authentication Session Context also a presented +user ID) are part of the session context and MUST be updated by the ICC as part of restoring the session +context accordingly. + + + + +Bundesamt für Sicherheit in der Informationstechnik 71 + B. ISO 7816 Mapping (Normative) + + +B.11.1. Session Context Identifier +The Session Context identifier is an integer encoded as single octet(see D.2.1.1) that MAY have values +between 0 and maxSCNo. The identifier 0 is reserved for the default Session Context and MUST NOT be +used for storing a Chip Authentication Session Context. + + +B.12. Extended Length +Depending on the size of the cryptographic objects (e.g. public keys, signatures), APDUs with extended +length fields MUST be used to send this data to the ICC. For details on extended length see [12]. + + +B.12.1. ICCs +For ICCs support of extended length is CONDITIONAL. If the cryptographic algorithms and key sizes +selected by the issuing state require the use of extended length, the ICCs SHALL support extended +length. In this case, to support terminals without extended length transport capability, ICCs of eIDAS +token SHOULD additionally support receiving extended length APDUs using Envelope/Get Response +TPDUs as specified in Appendix E. +If the ICC supports extended length, this MUST be indicated in the ATR/ATS or in EF.ATR/INFO as +specified in [12]. + + +B.12.2. Terminals +For terminals support of extended length is REQUIRED. A terminal SHOULD examine whether or not +support for extended length is indicated in the ICC’s ATR/ATS or in EF.ATR/INFO before using this +option. The terminal MUST NOT use extended length for APDUs other than the following commands +unless the exact input and output buffer sizes of the ICC are explicitly stated in the ATR/ATS or in +EF.ATR/INFO. + • PSO:Verify Certificate + • PSO:Compute Digital Signature + • MSE:Set KAT + • General Authenticate + • External Authenticate + + +B.12.3. Errors +The ICC SHALL indicate extended length errors with status bytes 0x6700. + + +B.13. Command Chaining +Command chaining is only used for the General Authenticate command. For details on command +chaining see [12]. + + + + +72 Bundesamt für Sicherheit in der Informationstechnik + ISO 7816 Mapping (Normative) B. + + +B.13.1. ICCs +For ICCs support of command chaining is REQUIRED and support for command chaining MUST be +indicated in the historical bytes of the ATR/ATS or in the EF.ATR/INFO as specified in [12]. + + +B.13.2. Terminals +For terminals support of command chaining is REQUIRED. A terminal SHOULD test whether or not +the ICC supports command chaining before using this option. + + +B.13.3. Errors +If the ICC expects the end of the chain, but receives a command that is not marked as the last +command, the ICC SHALL indicate that the last command in a chain was expected with status bytes +0x6883. + + +B.14. APDU Specification +In the following, the APDUs required to implement the protocols are described. The ICC SHALL +implement the APDUs as described but MAY deviate from the description if the APDUs are used in +other contexts. +The omitted CLA byte SHALL be set to indicate secure messaging with authenticated header, command +chaining and application specific encoding as required by the protocols (cf. Appendix F.3). +The sender of a command or response APDU MUST transmit the data objects in the data field in the +order as defined in the following. The receiver SHOULD be capable to process APDUs with data objects +given in any order. + + +B.14.1. MSE:Set AT +The command MSE:Set AT is used to select and initialize the following protocols: PACE, Chip +Authentication, Terminal Authentication, and Restricted Identification. +Command +INS 0x22 Manage Security Environment +P1/P2 0xC1A4 PACE: + Set Authentication Template for mutual authentication. + 0x41A4 Chip Authentication / Restricted Identification: + Set Authentication Template for internal authentication. + 0x81A4 Terminal Authentication: + Set Authentication Template for external authentication. + 0x01A4 Restoring Session Context: + Used to indicate restoring of a stored Session Context +Data 0x80 Cryptographic mechanism reference CONDITIONAL + Object Identifier of the protocol to select (value only, Tag + 0x06 is omitted). This data object is REQUIRED for all + + +Bundesamt für Sicherheit in der Informationstechnik 73 + B. ISO 7816 Mapping (Normative) + + + protocols except Terminal Authentication in version 1. + 0x83 Reference of a public key / secret key CONDITIONAL + This data object is REQUIRED for the following protocols: + – For PACE to indicate the password to be used: + 0x01: MRZ + 0x02: CAN + 0x03: PIN + 0x04: PUK + – For Terminal Authentication to select the public key of + the terminal by its ISO 8859-1 encoded name. + 0x84 Reference of a private key / Reference for computing a session CONDITIONAL + key + This data object is REQUIRED for the following protocols + (cf. Appendix A.2): + – For PACE to indicate the identifier of the domain + parameters to be used if the domain parameters are + ambiguous, i.e. more than one set of domain parameters + is available for PACE. + – For Chip Authentication to indicate the identifier of the + private key (including protocol version) to be used if + Chip Authentication Version 3 is supported or the + private key is ambiguous (cf. A.1.1.2). + – For Restricted Identification to indicate the private key + to be used i.e. more than one private key is available for + Restricted Identification. + 0x67 Auxiliary authenticated data CONDITIONAL + This data object is REQUIRED for Terminal Authentication + (version 2) if auxiliary data verification or PSM shall be + used. + 0x91 Ephemeral Public Key CONDITIONAL + This data object is REQUIRED for Terminal Authentication + if the terminal's ephemeral public key  PK PCD is unknown + or ambiguous to the ICC when Terminal Authentication is + performed (i.e. version 2). In this case the terminal's + compressed ephemeral public key Comp  PK PCD  MUST + be sent to the ICC. + 0x7F4C Certificate Holder Authorization Template CONDITIONAL + This data object (defined in C.1.5) is REQUIRED for PACE if + Terminal Authentication version 2 shall be used after + PACE. + 0x65 Certificate Extensions CONDITIONAL + This data object is REQUIRED for PACE if Terminal + Authentication version 2 shall be used after PACE and the + ICC supports Authorization Extensions. + In this case, it MUST encapsulate a sequence of + Authorization Extensions. + + If the ICC does not support Authorization Extensions, this + data object SHOULD be omitted. + + +74 Bundesamt für Sicherheit in der Informationstechnik + ISO 7816 Mapping (Normative) B. + + + 0xE0 If the ICC supports switching of Session Contexts, this CONDITIONAL + template MUST be present for Chip Authentication Version + 2 and the Key Agreement phase of Chip Authentication + Version 3 in case the corresponding Session Context shall + be stored immediately before switching to another Session + Context. + In this case, the template MUST encapsulate a tag 0x81 + containing the identifier of the Session Context. + + If the ICC does not support switching of Session Contexts, + this template SHOULD be omitted. + 0xE1 This REQUIRED for Restoring Session Context to indicate CONDITIONAL + that a stored Session Context shall be restored. + In this case, the template SHALL encapsulate a data object + 0x81 containing the identifier of the Session Context to be + restored. + + Otherwise, this template MUST be omitted. +Response +Data – Absent +Status 0x9000 Normal operation +Bytes The protocol has been selected and initialized. + 0x6A80 Incorrect parameters in the command data field + – Algorithm not supported or initialization failed. + – Terminal Type indicated by Certificate Holder Authorization Template is not + authorized to use referenced password. (PACE) + 0x6A88 Referenced data not found + The referenced data (i.e. password, private key, public key, domain parameter) is not + available. +PACE 0x63CX Warning + The password has been selected. X indicates the number of remaining verification + tries, if not equal to the initial value: + X=1: The password is suspended. The password MUST be resumed. + X=0: The password is blocked. The password MUST be unblocked. +PACE 0x6283 Warning + The password is deactivated. + other Operating system dependent error + The initialization of the protocol failed. + +Note: + • Some operating systems accept the selection of an unavailable public key and return an error + only when the public key is used for the selected purpose. + • Resuming and unblocking a password requires explicitly setting the CAN or the PUK using + MSE:Set AT. + + + + +Bundesamt für Sicherheit in der Informationstechnik 75 + B. ISO 7816 Mapping (Normative) + + +B.14.2. General Authenticate +The command General Authenticate is used to perform the following protocols: PACE, Chip +Authentication, and Restricted Identification. +Command +INS 0x86 General Authenticate +P1/P2 0x0000 Keys and protocol implicitly known. +Data 0x7C Dynamic Authentication Data REQUIRED + Protocol specific data objects. +Response +Data 0x7C Dynamic Authentication Data CONDITIONAL, see + Protocol specific data objects. below +Status 0x9000 Normal operation +Bytes The protocol (step) was successful. + 0x6300 Authentication failed + The protocol (step) failed. + 0x63CX Authentication failed + The protocol (step) failed. X indicates the number of remaining verification tries: + X=1: The password is suspended. The password MUST be resumed. + X=0: The password is blocked. The password MUST be unblocked. + 0x6982 Security status not satisfied + The terminal is not authorized to perform the protocol (e.g. the password is blocked, + deactivated, or suspended). + 0x6983 Authentication method blocked + The password is blocked. + 0x6984 Reference data not usable + The password is deactivated. + 0x6985 Conditions of use not satisfied + The password is suspended. + 0x6A80 Incorrect parameters in data field + Provided data is invalid. + other Operating system dependent error + The protocol (step) failed. + +Note: The ICC MAY indicate a blocked, deactivated, or suspended password by responding with status +bytes 0x6982 instead of using status bytes 0x6983, 0x6984, or 0x6985, respectively. +The response Dynamic Authentication Data object 0x7C + • MUST be present if the operation is successful, i.e. the Status Bytes are 0x9000, + • MUST be absent in case of an execution error or checking error, i.e. if the Status Bytes are in the + range 0x6400 - 0x6FFF, and + • MAY be absent in case of a warning, i.e. if the Status Bytes are in the range 0x6200 – 0x63FF. + +Note: The General Authenticate command with TPDU chaining is not supported for communication +protocol T=0 according to [11]. + +76 Bundesamt für Sicherheit in der Informationstechnik + ISO 7816 Mapping (Normative) B. + + +B.14.3. MSE:Set KAT +The command MSE:Set KAT is used to perform Chip Authentication version 1 with 3DES. +Command +INS 0x22 Manage Security Environment +P1/P2 0x41A6 Set Key Agreement Template for computation. +Data 0x91 Ephemeral Public Key REQUIRED + Ephemeral public key  PK PCD (cf. Appendix A.2) encoded + as plain public key value. + 0x84 Reference of a private key CONDITIONAL + This data object is REQUIRED if the private key is + ambiguous, i.e. more than one key pair is available for Chip + Authentication (cf. Appendix A.1.1.2, Appendix A.4.1.1 and + Appendix A.4.2.1). +Response +Data – Absent +Status 0x9000 Normal operation +Bytes The key agreement operation was successfully performed. New session keys have + been derived. + 0x6A80 Incorrect Parameters in the command data field + The validation of the ephemeral public key failed. The previously established session + keys remain valid. + other Operating system dependent error + The previously established session keys remain valid. + + +B.14.4. MSE:Set DST +The command MSE:Set DST is used to setup certificate verification for Terminal Authentication and to +setup signature computation for PSM or PSC . + + + + +Bundesamt für Sicherheit in der Informationstechnik 77 + B. ISO 7816 Mapping (Normative) + + +Command +INS 0x22 Manage Security Environment +P1/P2 0x81B6 Set Digital Signature Template for verification. + 0x41B6 Set Digital Signature Template for computation +Data 0x80 Cryptographic mechanism reference CONDITIONAL + This data object is REQUIRED for PSM or PSC to indicate + the object identifier of the protocol to select (value only, + Tag 0x06 is omitted). + 0xE1 File reference CONDITIONAL + The data object is REQUIRED for PSC and MUST contain + the following content: + • 0x80: MAY be present and encapsulate the + concatenation of two byte file IDs for data group + content to be integrated into the signature + computation. + • 0x81: MAY be present and contain the content + 0x00FF encoded as plain octet string (without tag + and length) if the Specific Attribute of the terminal + is to be integrated into signature computation. + 0x83 Reference of a public key CONDITIONAL + This data object is REQUIRED for Terminal Authentication + and contains the ISO 8859-1 encoded name of the public + key to be set + 0x84 Reference of a private key CONDITIONAL + This data object is REQUIRED for PSM or PSC +Response +Data – Absent +Status 0x9000 Normal Operation +Bytes The key has been selected for the given purpose. + 0x6A88 Referenced data not found + The selection failed as the public key is not available. + other Operating system dependent error + The key has not been selected. + +Note: Some operating systems accept the selection of an unavailable public key and return an error +only when the public key is used for the selected purpose. + + +B.14.5. PSO:Verify Certificate +The command PSO:Verify Certificate is used to verify and import certificates for Terminal +Authentication. + + + + +78 Bundesamt für Sicherheit in der Informationstechnik + ISO 7816 Mapping (Normative) B. + + +Command +INS 0x2A Perform Security Operation +P1/P2 0x00BE Verify self-descriptive certificate. +Data 0x7F4E Certificate body REQUIRED + The body of the certificate to be verified. + 0x5F37 Signature REQUIRED + The signature of the certificate to be verified. +Response +Data – Absent +Status 0x9000 Normal operation +Bytes The certificate was successfully validated and the public key has been imported. + other Operating system dependent error + The public key could not be imported (e.g. the certificate was not accepted). + + +B.14.6. Get Challenge +The command Get Challenge is used to perform Terminal Authentication. +Command +INS 0x84 Get Challenge +P1/P2 0x0000 +Data – Absent +Le 0x08 REQUIRED +Response +Data r PICC 8 bytes of randomness. +Status 0x9000 Normal operation +Bytes other Operating system dependent error + + +B.14.7. External Authenticate +The command External Authenticate is used to perform Terminal Authentication. +Command +INS 0x82 External Authenticate +P1/P2 0x0000 Keys and Algorithms implicitly known. +Data Signature generated by the terminal. REQUIRED +Response +Data – Absent +Status 0x9000 Normal operation +Bytes The authentication was successful. Access to data groups will be granted according to + the effective authorization of the corresponding verified certificate. + + + +Bundesamt für Sicherheit in der Informationstechnik 79 + B. ISO 7816 Mapping (Normative) + + +Response + 0x6300 Warning + Signature verification failed. + 0x6982 Security status not satisfied + The authentication failed as the current authentication level of the terminal does not + allow to use Terminal Authentication (e.g. Terminal Authentication was already + performed, etc.). + 0x6985 Conditions of use not satisfied + Terminal type set by PACE does not match terminal type contained in certificate + chain. + other Operating system dependent error + The authentication failed. + + +B.14.8. PSO: Compute Digital Signature +The command PSO:Compute Digital Signature is used to perform PSM or PSC. +Command +INS 0x2B Perform Security Operation +P1/P2 0x0200 Compute Digital Signature +Data 0x73 Discretionary Data Template REQUIRED + Protocol specific data objects. +Response +Data 0x73 Discretionary Data Template CONDITIONAL, see + Protocol specific data objects. below +Status 0x9000 Normal operation +Bytes The protocol (step) was successful. + 0x6982 Security status not satisfied + The terminal is not authorized to perform the protocol + 0x6A80 Incorrect parameters in data field + Provided data is invalid. + other Operating system dependent error + The protocol (step) failed. +The response Discretionary Data Template 0x73 + • MUST be present if the operation is successful, i.e. the Status Bytes are 0x9000, + • MUST be absent in case of an execution error or checking error, i.e. if the Status Bytes are in the + range 0x6400 - 0x6FFF, and + • MAY be absent in case of a warning, i.e. if the Status Bytes are in the range 0x6200 – 0x63FF. + + +B.14.9. Compare +The command Compare is used to verify authenticated auxiliary data, i.e. to perform age verification, +document validity verification, Municipality ID verification, phone number verification, email address +verification, or data group content verification. + +80 Bundesamt für Sicherheit in der Informationstechnik + ISO 7816 Mapping (Normative) B. + + +Command +INS 0x33 Compare +P1 0x00 Compare Binary +P2 0x00 Comparison defined by OID +Data Object Identifier of the auxiliary data to be compared REQUIRED +Response +Data – Absent +Status 0x9000 Normal operation +Bytes Comparison successful. + 0x6340 Comparison failed + Comparison failed. + 0x6A88 Referenced data not found + The referenced data was not found. + 0x6982 Security status not satisfied + The terminal is not authorized to perform verification. + other Operating system dependent error + The protocol (step) failed. + + +B.14.10. Verify +The command Verify is used to verify authenticated auxiliary data, i.e. to perform age verification, +document validity verification, or Municipality ID verification. + +Note: Due to the application specific coding the proprietary class (with secure messaging and no +chaining) MUST be used, i.e. CLA=0x8C. +Command +INS 0x20 Verify +P1/P2 0x8000 Verify authenticated auxiliary data. +Data Object Identifier of the auxiliary data to be verified. REQUIRED +Response +Data – Absent +Status 0x9000 Normal operation +Bytes Verification successful. + 0x6300 Verification failed + Verification failed. + 0x6A88 Referenced data not found + The referenced data was not found. + 0x6982 Security status not satisfied + The terminal is not authorized to perform verification. + other Operating system dependent error + The protocol (step) failed. + + + +Bundesamt für Sicherheit in der Informationstechnik 81 + B. ISO 7816 Mapping (Normative) + + +B.14.11. Reset Retry Counter +The command Reset Retry Counter is used to unblock or change the PIN. +Command +INS 0x2C Reset Retry Counter +P1 0x02-0x03 see below +P2 0x03: PIN + +Data Context specific reset data depending on P1: REQUIRED + P1=0x02: new PIN + P1=0x03: Absent +Response +Data – Absent +Status 0x9000 Normal operation +Bytes Unblocking or changing of the PIN was successful. + 0x6982 Security status not satisfied + The terminal is not authorized to unblock or change the PIN. + other Operating system dependent error + Unblocking or changing of the PIN failed. + + +B.14.12. Activate +The command Activate is used to set the PIN to the state activated. +Command +INS 0x44 Activate +P1 0x10 Activate PIN referenced by parameter P2. +P2 0x03: PIN +Data Absent +Response +Data – Absent +Status 0x9000 Normal operation +Bytes PIN state has been set to activated. + 0x6982 Security status not satisfied + The terminal is not authorized to change the PIN state. + other Operating system dependent error + Changing of the PIN state failed. + + +B.14.13. Deactivate +The command Deactivate is used to set the PIN to the state deactivated. + + + + +82 Bundesamt für Sicherheit in der Informationstechnik + ISO 7816 Mapping (Normative) B. + + +Command +INS 0x04 Deactivate +P1 0x10 Deactivate PIN referenced by parameter P2. +P2 0x03: PIN +Data Absent +Response +Data – Absent +Status 0x9000 Normal operation +Bytes PIN state has been set to deactivated. + 0x6982 Security status not satisfied + The terminal is not authorized to change the PIN state. + other Operating system dependent error + Changing of the PIN state failed. + + +B.14.14. Perform User Operation:Present User +The command Perform User Operation:Present User is used to present the user for writing Attribute +Requests and reading Attributes. +Command +INS 0x14 Perform User Operation +P1/P2 0x0080 Present User +Data 0x7F21 The data object MUST contain a Discretionary Data Template 0x73 encapsulating the + following content: + • 0x80: Hash of Sector Public key +Response +Data – Absent +Status 0x9000 Normal operation +Bytes Operation successful + 0x62XX Warning: Unknown user ID + + other Operating system dependent error + + +B.14.15. Put Data +The command Put Data is used for Enhanced Role Authentication to store attribute requests and +specific attributes on the ICC. +Command +INS 0xDA Put Data +P1/P2 0xFF01 Store attribute request + 0x00FF Store specific attribute +Data Context-specific data depending on P1/P2 and the effective authorization of the + + +Bundesamt für Sicherheit in der Informationstechnik 83 + B. ISO 7816 Mapping (Normative) + + + terminal + P1/P2=0xFF01: Tag 0x53 containing the ASN.1 structure Attribute Request. + P1/P2=0x00FF: Concatenation of tags 0x53 each containing a specific attribute to be + stored on the ICC. +Response +Data – Absent +Status 0x9000 Normal operation +Bytes Operation successful + 0x6982 Security status not satisfied + The terminal is not authorized to perform the operation + other Operating system dependent error + +Note: The Coding of P1/P2=0x00FF appends the content of the currently selected EF supporting DOs or +currently selected DO, respectively. + + +B.14.16. Get Data +The command Get Data is used for Enhanced Role Authentication to read attribute requests and +specific attributes from the ICC. +Command +INS 0xCA Get Data +P1/P2 0xFF01 Get attribute request + 0x00FF Read Specific Attributes: Get Current Template +Data Absent + +Response +Data Context-specific data depending on P1/P2 and the effective authorization of the + terminal + P1/P2=0xFF01: ASN.1 structure RequestInfos + P1/P2=0x00FF: Concatenation of Discretionary Data Templates 0x73 encapsulating + • 0x80: Terminal Sector (CONDITIONAL) + MUST be present if and only if the terminal is authorized to access all + Specific Attributes + • Concatenation of tags 0x53: Specific Attribute (REQUIRED) +Status 0x9000 Normal operation +Bytes Operation successful + 0x6982 Security status not satisfied + The terminal is not authorized to perform the operation + other Operating system dependent error + +Note: The Coding of P1/P2=0x00FF retrieves the content of the currently selected EF supporting DOs +or currently selected DO, respectively. + + + + +84 Bundesamt für Sicherheit in der Informationstechnik + ISO 7816 Mapping (Normative) B. + + +B.14.17. Delete Data +The command Delete Data is used for Enhanced Role Authentication to delete Specific Attributes from +the ICC. +Command +INS 0xEE Delete Data +P1/P2 0x0000 +Data Absent + +Response +Data – Absent +Status 0x9000 Normal operation +Bytes Operation successful + 0x6982 Security status not satisfied + The terminal is not authorized to perform the operation + other Operating system dependent error + + + + +Bundesamt für Sicherheit in der Informationstechnik 85 + C. CV Certificates (normative) + + + +C. CV Certificates (normative) + +C.1. Certificate Profile +Self-descriptive card verifiable (CV) certificates according to ISO 7816 (cf. [12], [13], [14]) and the +certificate profile specified in Table 23 SHALL be used. Details on the encoding of the data objects used +in the certificate profile can be found in Appendix D.2. + + +C.1.1. Certificate Profile Identifier +The version of the profile is indicated by the Certificate Profile Identifier. Version 1 as specified in Table +23 is identified by a value of 0. + + + Data Object Cert + CV Certificate m + Certificate Body m + Certificate Profile Identifier m + Certification Authority Reference m + Public Key m + Certificate Holder Reference m + Certificate Holder Authorization Template m + Certificate Effective Date m + Certificate Expiration Date m + Certificate Extensions o + Signature m + Table 23: CV Certificate Profile + +C.1.2. Certification Authority Reference +The Certification Authority Reference is used to identify the public key to be used to verify the +signature of the certification authority (CVCA or DV). The Certification Authority Reference MUST be +equal to the Certificate Holder Reference in the corresponding certificate of the certification authority +(CVCA Link Certificate or DV Certificate). Details on the Certification Authority Reference can be found +in Appendix A.7.1. + + +C.1.3. Public Key +Details on the encoding of public keys can be found in Appendix D.3. + + + + +86 Bundesamt für Sicherheit in der Informationstechnik + CV Certificates (normative) C. + + +C.1.4. Certificate Holder Reference +The Certificate Holder Reference is used to identify the public key contained in the certificate. Details +on the Certificate Holder Reference can be found in Appendix A.7.1. + + +C.1.5. Certificate Holder Authorization Template +The role and authorization of the certificate holder SHALL be encoded in the Certificate Holder +Authorization Template. This template is a sequence that consists of the following data objects: + 1. An object identifier that specifies the terminal type and the format of the template. + 2. A discretionary data object that encodes the relative authorization, i.e. the role and + authorization of the certificate holder relative to the certification authority. +The content and evaluation of the Certificate Holder Authorization Template is described in Appendix +Part 4 of this Technical Guideline. + + +C.1.6. Certificate Effective/Expiration Date +Indicates the validity period of the certificate. The Certificate Effective Date MUST be the date of the +certificate generation. + + +C.1.7. Certificate Extensions for Terminal Authentication Version 2 +Certificates MAY contain extensions as defined in Appendix C.3. + + +C.1.8. Signature +The signature on the certificate SHALL be created over the encoded certificate body (i.e. including tag +and length). The Certification Authority Reference SHALL identify the public key to be used to verify +the signature. + + +C.2. Certificate Requests +Certificate requests are reduced CV certificates that may carry an additional signature. The certificate +request profile specified in Table 24 SHALL be used. Details on the encoding of the data objects used in +the certificate request profile can be found in Appendix D.2. + + +C.2.1. Certificate Profile Identifier +The version of the profile is identified by the Certificate Profile Identifier. Version 1 as specified in Table +24 is identified by a value of 0. + + + + +Bundesamt für Sicherheit in der Informationstechnik 87 + C. CV Certificates (normative) + + + + Data Object Req + Authentication c + CV Certificate m + Certificate Body m + Certificate Profile Identifier m + Certification Authority Reference r + Public Key m + Certificate Holder Reference m + Certificate Extensions o + Signature m + Certification Authority Reference c + Signature c + Table 24: CV Certificate Request Profile + + + +C.2.2. Certification Authority Reference +The Certification Authority Reference SHOULD be used to inform the certification authority about the +private key that is expected by the applicant to be used to sign the certificate. If the Certification +Authority Reference contained in the request deviates from the Certification Authority Reference +contained in the issued certificate (i.e. the issued certificate is signed by a private key that is not +expected by the applicant), the corresponding certificate of the certification authority SHOULD also be +provided to the applicant in response. +Details on the Certification Authority Reference can be found in Appendix A.7.1. + + +C.2.3. Public Key +Details on the encoding of public keys can be found in Appendix D.3. + + +C.2.4. Certificate Holder Reference +The Certificate Holder Reference is used to identify the public key contained in the request and the +resulting certificate. Details on the Certificate Holder Reference can be found in Appendix A.7.1. + + +C.2.5. Certificate Extensions for Terminal Authentication Version 2 +Requests for certificates MAY contain extensions as defined in Appendix C.3. + + +C.2.6. Signature(s) +A certificate request may have two signatures, an inner signature and an outer signature: + + +88 Bundesamt für Sicherheit in der Informationstechnik + CV Certificates (normative) C. + + +Inner Signature (REQUIRED) + The certificate body is self-signed, i.e. the inner signature SHALL be verifiable with the public key + contained in the certificate request. The signature SHALL be created over the encoded certificate + body (i.e. including tag and length). +Outer Signature (CONDITIONAL) + – The signature is OPTIONAL if an entity applies for the initial certificate. In this case the request + MAY be additionally signed by another entity trusted by the receiving certification authority (e.g. + the national CVCA may authenticate the request of a DV sent to a foreign CVCA). + – The signature is REQUIRED if an entity applies for a successive certificate. In this case the request + MUST be additionally signed by the applicant using a recent key pair previously registered with + the receiving certification authority. +If the outer signature is used, an authentication data object SHALL be used to nest the CV Certificate +(Request), the Certification Authority Reference and the additional signature. The Certification +Authority Reference SHALL identify the public key to be used to verify the additional signature. The +signature SHALL be created over the concatenation of the encoded CV Certificate and the encoded +Certification Authority Reference (i.e. both including tag and length). + + + + Data Object + Certificate Extensions + Discretionary Data Template + Object Identifier + Context Specific Data Object 1 + ... + Context Specific Data Object n + Discretionary Data Template + Object Identifier + Context Specific Data Object 1 + ... + Context Specific Data Object m + ... + Table 25: Certificate Extensions + + +C.3. Certificate Extensions for Terminal Authentication Version 2 +The certificate extension is a sequence of discretionary data templates, where every discretionary data +template SHALL contain a sequence of the following data objects also shown in Table 25: + 1. An object identifier that specifies the content and the format of the extension. + 2. One or more context specific data objects that contain the encoded extension. +The following base object identifier is used to identify the certificate extensions: + + +Bundesamt für Sicherheit in der Informationstechnik 89 + C. CV Certificates (normative) + + + id-extensions OBJECT IDENTIFIER ::= { + bsi-de applictions(3) mrtd(1) 3 + } + +This Part of the Technical Guideline defines application independent extensions. Additional application +specific extensions are defined in Part 4. + +Note: The certificate validation procedure described in Section 2.5.1 does not take certificate extensions +into account. Thus, extensions are uncritical attributes and the ICC MUST NOT reject certificates due to +unknown extensions. Unknown extensions and extensions irrelevant for the ICC SHOULD NOT be +imported. + + +C.3.1. Authorization Extensions +A special type of certificate extension are Authorization Extensions. These extensions convey +authorizations additional to those in the Certificate Holder Authorization Template contained in the +certificate. Authorization Extensions contain exactly one discretionary data object that encodes the +relative authorization. +Authorization Extensions SHALL be evolving, i.e. new authorization bits MAY be appended to the +leftmost authorization bit in future versions of this Technical Guideline (cf. Table 26). Appended +authorization bits that are not supported by the ICC SHALL be ignored by the ICC. + + + Authorization Extension + (before evolution) + Discretionary Data Template + Object Identifier + Authorization Bit Mask + b8s+ b8s+ b8s+ ... b2 b1 b0 + 7 6 5 + + + + + Bits to be appended + ↓ + c8t+7 c8t+6 c8t+5 ... c2 c1 c0 + + + Authorization Extension + (after evolution) + Discretionary Data Template + Object Identifier + Authorization Bit Mask + c8t+7 ... c2 c1 b8s+ b8s+ ... b1 b0 + 7 6 + + + Table 26: Evolution of Authorization Extensions + + + + +90 Bundesamt für Sicherheit in der Informationstechnik + CV Certificates (normative) C. + + +C.3.2. Terminal Sector + +C.3.2.1. Terminal Sector for Restricted Identification +The following object identifier SHALL be used for this extension: + id-sector OBJECT IDENTIFIER ::= {id-extensions 2} + +This extension MUST be supported for Restricted Identification and Enhanced Role Authentication. +The following context specific data objects are used to encode the terminal sector: + • 0x80: Hash of 1st sector public key data object (cf. Appendix D.3). + • 0x81: Hash of 2nd sector public key data object (cf. Appendix D.3). +The hash function to be used SHALL be defined by the hash function used to sign the certificate. The +public key itself is not contained in the certificate and MUST be provided by the terminal as part of +Restricted Identification. The ICC SHALL compute the hash over the received public key and compare it +to the received hash. + +Note: Context-specific tagging is used for the sector public key in Restricted Identification (cf. Appendix +B.4.1). The ICC MUST replace the context-specific tag 0xA0 by the application-specific tag 0x7F49 before +computing the hash value. + + +C.3.2.2. Terminal Sector for Pseudonymous Signatures +The following object identifier SHALL be used to identify the terminal sector extension for the +Pseudonymous Signature (PS terminal sector): + id-PS-Sector OBJECT IDENTIFIER ::= { id-extensions 3 } + +A concatenation of the following context-specific data object is used to encode the PS terminal sector. +The data object MAY occur more than once. + • 0xA0: Discretionary Data Template consisting of + ◦ 0x80: ID of the domain parameters for Pseudonymous Signature + ◦ 0x81: Hash of Sector Public Key encoded as elliptic curve point, i.e. (without domain + parameters). +The hash function to be used SHALL be defined by the hash function used to sign the certificate. The +public key itself is not contained in the certificate and MUST be provided by the terminal as part of the +Pseudonymous Signature. +The ICC SHALL compute the hash of the received Sector Public Key and SHALL verify that the hash value +matches with the hash value encoded in one of the corresponding data templates of the certificate extension. + + +C.4. Certificate Policy +It is RECOMMENDED that each CVCA and every DV publishes a certificate policy and/or a certification +practice statement. + + + + +Bundesamt für Sicherheit in der Informationstechnik 91 + C. CV Certificates (normative) + + +C.4.1. Procedures +The certificate policy SHOULD specify the following procedures: + • Entity identification, authentication, and registration; + • Certificate application, issuance, and distribution; + • Compromise and disaster recovery; + • Auditing. + + +C.4.2. Usage Restrictions +The certificate policy SHOULD imply restrictions on the devices used to store/process corresponding +private keys and other sensitive (personal) data: + • Physical and operational security; + • Access control mechanisms; + • Evaluation and certification (e.g. Common Criteria Protection Profiles); + • Data Protection. + + + + +92 Bundesamt für Sicherheit in der Informationstechnik + DER Encoding (Normative) D. + + + +D. DER Encoding (Normative) +The Distinguished Encoding Rules (DER) according to X.690 [16] SHALL be used to encode both ASN.1 +data structures and (application specific) data objects. The encoding results in a Tag-Length-Value (TLV) +structure as follows: +Tag: The tag is encoded in one or two octets and indicates the content. +Length: The length is encoded as unsigned integer in one, two, or three octets resulting in a maximum + length of 65535 octets. The minimum number of octets SHALL be used. +Value: The value is encoded in zero or more octets. + + +D.1. ASN.1 +The encoding of data structures defined in ASN.1 syntax is described in X.690 [16]. + + +D.2. Data Objects +Table 27 gives an overview on the tags, lengths, and values of the data objects used in this specification. + +Name Tag Len Value Comment + +Object Identifier 0x06 V Object Identifier – +Certification Authority 0x42 16V Character String Identifies the public key of the issuing certification authority +Reference in a certificate. +Discretionary Data 0x53 V Octet String Contains arbitrary data. +Certificate Holder Reference 0x5F20 16V Character String Associates the public key contained in a certificate with an + identifier. +Certificate Expiration Date 0x5F24 6F Date The date after which the certificate expires. +Certificate Effective Date 0x5F25 6F Date The date of the certificate generation. +Certificate Profile Identifier 0x5F29 1F Unsigned Integer Version of the certificate and certificate request format. +Signature 0x5F37 V Octet String Digital signature produced by an asymmetric cryptographic + algorithm. +Certificate Extensions 0x65 V Sequence Nests certificate extensions. +Authentication 0x67 V Sequence Contains authentication related data objects. +Discretionary Data Template 0x73 V Sequence Nests arbitrary data objects. +CV Certificate 0x7F21 V Sequence Nests certificate body and signature. +Public Key 0x7F49 V Sequence Nests the public key value and the domain parameters. +Certificate Holder 0x7F4C V Sequence Encodes the role of the certificate holder (i.e. CVCA, DV, +Authorization Template Terminal) and assigns read/write access rights. +Certificate Body 0x7F4E V Sequence Nests data objects of the certificate body. + F: fixed length (exact number of octets), V: variable length (up to number of octets) + + Table 27: Overview on Data Objects (sorted by Tag) + + + + +Bundesamt für Sicherheit in der Informationstechnik 93 + D. DER Encoding (Normative) + + +D.2.1. Encoding of Values +The basic value types used in this specification are the following: (unsigned) integers, elliptic curve +points, dates, character strings, octet strings, object identifiers, and sequences. + + +D.2.1.1. Unsigned Integers +All integers used in this specification are unsigned integers. An unsigned integer SHALL be converted to +an octet string using the binary representation of the integer in big-endian format. The minimum +number of octets SHALL be used, i.e. leading octets of value 0x00 MUST NOT be used. + +Note: In contrast the ASN.1 type INTEGER is always a signed integer. + + +D.2.1.2. Elliptic Curve Points +The conversion of Elliptic Curve Points to octet strings is specified in [4]. The uncompressed format +SHALL be used. + + +D.2.1.3. Dates +A date is encoded in 6 digits d 1 ⋯d 6 in the format YYMMDD using timezone GMT. It is converted to +an octet string o1 ⋯o 6 by encoding each digit d j to an octet o j as unpacked BCDs 1≤ j≤6 . +The year YY is encoded in two digits and to be interpreted as 20YY, i.e. the year is in the range of 2000 to +2099. + + + + +94 Bundesamt für Sicherheit in der Informationstechnik + DER Encoding (Normative) D. + + +D.2.1.4. Character Strings +A character string c 1 ⋯c n is a concatenation of n characters c j with 1≤ j≤n . It SHALL be +converted to an octet string o1 ⋯o n by converting each character c j to an octet o j using the ISO/IEC +8859-1 character set. For informational purposes the character set can be found in Table 28. +The character codes 0x00-0x1F and 0x7F-0x9F are unassigned and MUST NOT be used. The conversion +of an octet to an unassigned character SHALL result in an error. + + Code 0 1 2 3 4 5 6 7 8 9 A B C D E F + 0 + 1 + 2 SP ! " # $ % & ’ ( ) * + , - . / + 3 0 1 2 3 4 5 6 7 8 9 : ; < = > ? + 4 @ A B C D E F G H I J K L M N O + 5 P Q R S T U V W X Y Z [ \ ] ^ _ + 6 ‘ a b c d e f g h i j k l m n o + 7 p q r s t u v w x y z { | } ~ + 8 + 9 + A NBSP ¡ ¢ £ ¤ ¥ ¦ § ¨ © ª « ¬ SHY ® ¯ + ° + B ± ² ³ ´ µ ¶ · ¹ º » ¼ ½ ¾ ¿ + C À Á Â Ã Ä Å Æ Ç È É Ê Ë Ì Í Î Ï + D Ð Ñ Ò Ó Ô Õ Ö × Ø Ù Ú Û Ü Ý Þ ß + E à á â ã ä å æ ç è é ê ë ì í î ï + F ð ñ ò ó ô õ ö ÷ ø ù ú û ü ý þ ÿ + SP: Space, NBSP: Non-breaking Space, SHY: Soft Hyphen + Table 28: ISO/IEC 8859-1 Character Set + +D.2.1.5. Octet Strings +An octet string o1 ⋯o n is a concatenation of n octets o j with 1≤ j≤n . Every octet o j consists of 8 +bits. + + +D.2.1.6. Object Identifiers +An object identifier i 1 .i 2 .⋯. i n is encoded as an ordered list of n unsigned integers i j with 1≤ j≤n . +It SHALL be converted to an octet string o1 ⋯o n−1 using the following procedure: + 1. The first two integers i 1 and i 2 are packed into a single integer i that is then converted to the + octet string o1 . The value i is calculated as follows: + + + + +Bundesamt für Sicherheit in der Informationstechnik 95 + D. DER Encoding (Normative) + + + i=i 1⋅4 0i 2 + 2. The remaining integers i j are directly converted to octet strings o j−1 with 3≤ j≤n . +More details on the encoding can be found in [16]. + +Note: The unsigned integers are encoded as octet strings using the big-endian format as described in +Appendix D.2.1.1, however only bits 1-7 of each octet are used. Bit 8 (the leftmost bit) set to one is used +to indicate that this octet is not the last octet in the string. + + +D.2.1.7. Sequences +A sequence D1 ⋯ D n is an ordered list of n data objects D j with 1≤ j≤n . The sequence SHALL be +converted to a concatenated list of octet strings O 1 ⋯O n by DER encoding each data object D j to an +octet string O j . + + +D.3. Public Key Data Objects +A public key data object contains a sequence of an object identifier and several context specific data +objects: + • The object identifier is application specific and refers not only to the public key format (i.e. the + context specific data objects) but also to its usage. + • The context specific data objects are defined by the object identifier and contain the public key + value and the domain parameters. +The format of public keys data objects used in this specification is described below. + + +D.3.1. RSA Public Keys +The data objects contained in an RSA public key are shown in Table 29. The order of the data objects is +fixed. + + Data Object Abbrev. Tag Type CV Certificate + Object Identifier 0x06 Object Identifier m + Composite modulus n 0x81 Unsigned Integer m + Public exponent e 0x82 Unsigned Integer m + Table 29: RSA Public Key + + + +D.3.2. Diffie Hellman Public Keys +The data objects contained in a DH public key are shown in Table 30. The order of the data objects is +fixed. + + + + +96 Bundesamt für Sicherheit in der Informationstechnik + DER Encoding (Normative) D. + + +Note: The encoding of key components as unsigned integer implies that each of them is encoded over +the least number of bytes possible, i.e. without preceding bytes set to 0x00. In particular, a DH public +key may be encoded over a number of bytes smaller than the number of bytes of the prime. + + + + Data Object Abbrev. Tag Type + Object Identifier 0x06 Object Identifier + Prime modulus p 0x81 Unsigned Integer + Order of the subgroup q 0x82 Unsigned Integer + Generator g 0x83 Unsigned Integer + Public value y 0x84 Unsigned Integer + Table 30: DH Public Key + + +D.3.3. Elliptic Curve Public Keys +The data objects contained in an EC public key are shown in Table 31. The order of the data objects is +fixed, CONDITIONAL domain parameters MUST be either all present, except the cofactor, or all absent +as follows: + • Self-signed CVCA Certificates SHALL contain domain parameters. + • CVCA Link Certificates MAY contain domain parameters. + • DV and Terminal Certificates MUST NOT contain domain parameters. The domain parameters + of DV and terminal public keys SHALL be inherited from the respective CVCA public key. + • Certificate Requests MUST always contain domain parameters. + + Data Object Abbrev. Tag Type CV Certificate + Object Identifier 0x06 Object Identifier m + Prime modulus p 0x81 Unsigned Integer c + First coefficient a 0x82 Unsigned Integer c + Second coefficient b 0x83 Unsigned Integer c + Base point G 0x84 Elliptic Curve Point c + Order of the base point r 0x85 Unsigned Integer c + Public point Y 0x86 Elliptic Curve Point m + Cofactor f 0x87 Unsigned Integer c + Table 31: EC Public Keys + + + +D.3.4. Ephemeral Public Keys +For ephemeral public keys the format and the domain parameters are already known. Therefore, only +the plain public key value, i.e. the public value y for Diffie-Hellman public keys and the public point Y +for Elliptic Curve public keys, is used to convey the ephemeral public key in a context specific data +object. + + + + +Bundesamt für Sicherheit in der Informationstechnik 97 + E. Envelope/Get Response (Normative) + + + +E. Envelope/Get Response (Normative) +To support terminals without extended length transport capability, chips of part-2 documents +SHOULD support receiving extended length command APDUs/transmitting extended length response +APDUs via Envelope/Get Response as a transport mechanism. The mechanism is designed to separate +the construction of (secured) APDUs from the transport of the APDUs between chip and (local) +terminal, allowing a (remote) terminal to construct APDUs without knowledge about the transport +capabilities of the (local) terminal. +A terminal MAY support this mechanism. +To convey an extended length command APDU via Envelope, the following steps are performed: + 1. The terminal constructs the APDU, including applying Secure Messaging, if applicable. The + terminal SHALL split the APDU in chunks, such that each chunk fits into the data field of a + standard length command TPDU. + 2. The chunks SHALL be transmitted as data fields of a chain of Envelope TPDUs to the chip. The + terminal SHALL NOT apply Secure Messaging to the Envelope TPDUs and SHALL set the + Chaining Bit of CLA for all but the last Envelope of the chain. + 3. The chip receives the chain of the Envelope TPDUs and SHALL reconstruct the extended length + APDU from the data fields. The resulting APDU SHALL be processed by the chip. This includes + processing Secure Messaging, if applicable. +If a command APDU is received via Envelope as described above, the chip SHALL transmit the response +APDU via Get Response as specified below. + 1. The response APDU SHALL be transformed into a Secure Messaging response, if applicable. + 2. The (transformed) APDU SHALL be transmitted in chunks as data fields of response TPDUs to + Get Response command TPDUs. The status words of these Get Response response TPDUs + SHALL be set to 0x9000 for the last chunk and to 0x61XX for all other chunks, respectively. +The terminal MUST send appropriate Get Response TPDUs immediately after the last Envelope TPDU. +The chip MAY dispose the response data if the terminal sends any other command. + +Note: If the terminal is not capable of transporting extended length APDUs and the response to a +command APDU is to be expected to exceed the length of a standard length APDU, the terminal +SHOULD transmit the command APDU via Envelope TPDUs, in order to trigger the chip to use the Get +Response TPDU mechanism for transporting the response APDU. + +Note: The security status is not affected by the usage of Envelope/Get Response, e.g. Secure Messaging +is not affected by using plain Envelope/Get Response TPDUs. + + + + +98 Bundesamt für Sicherheit in der Informationstechnik + Envelope/Get Response (Normative) E. + + + +E.1. Envelope +Command +CLA 0x00 Last command TPDU of a chain + 0x10 Any other command TPDU of a chain +INS 0xC2 Envelope +P1/P2 0x0000 +Lc Length of Data field REQUIRED +Data Part of a command APDU, such that the resulting REQUIRED + Envelope TPDU is a standard length TPDU. +Le MUST be absent +Response +Data MUST be absent +Status 0x9000 Normal operation +Bytes + 0x61XX More response data available + SW2 MUST be equal to '00' or optionally encode the number of response data bytes + available + other Operating system dependent error + + +E.2. Get Response +Command +CLA 0x00 +INS 0xC0 Get Response +P1/P2 0x0000 +Lc MUST be absent +Data MUST be absent +Le Maximum length of response data field expected REQUIRED +Response +Data Part of Response APDU REQUIRED +Status 0x9000 Normal operation +Bytes The complete response APDU has been transmitted, no more data available + 0x61XX More response data available + SW2 MUST be equal to '00' or optionally encode the number of data bytes still + available + other Operating system dependent error + + + + +Bundesamt für Sicherheit in der Informationstechnik 99 + F. Secure Messaging (Normative) + + + +F. Secure Messaging (Normative) +Secure Messaging provides a secure channel (i.e. encrypted and authenticated) between ICC and +terminal. Secure Messaging can be set up by Chip Authentication, PACE, or Basic Access Control. The +provided security level however depends on the mechanism used to set up Secure Messaging. + + +F.1. Session +A session is started when secure messaging is established. The session only ends with the release of +secure messaging, e.g. by sending a command APDU without secure messaging. The state of a session is +not changed by using Envelope/Get Response TPDUs. +Within a session the secure messaging keys (i.e. established by Chip Authentication, PACE, or Basic +Access Control) may be changed. + +Note: The ICC MAY implicitly select the Master File when a session is terminated. + + +F.2. Session Context +The ICC MAY support switching of Session Contexts. Support is REQUIRED if the ICC supports +multiple Extended Access Control executions in one session. +The PACE Session Context SHALL comprise at least: + • the verification state of passwords + • the Secure Messaging state, i.e. Secure Messaging keys and Send Sequence Counter + • the confined authorization + • the Terminal Certificates of the session for which Terminal Authentication was already performed. + • The current DF and the current EF. +The CA Session Context SHALL comprise at least: + • the verification state of passwords + • the Secure Messaging state, i.e. Secure Messaging keys and Send Sequence Counter + • effective access rights + • Authenticated Auxiliary Data + • the Terminal Sector. + • The current DF and the current EF. + • A presented user ID. + + +F.3. Message Structure of Secure Messaging APDUs +As this guideline only considers command APDUs with even instruction byte, this Appendix solely +takes into account Secure Messaging for command/response pairs where the command APDU has an +even INS byte. +Secure Messaging Data Objects SHALL be used according to Table 32 in the following order: + + +100 Bundesamt für Sicherheit in der Informationstechnik + Secure Messaging (Normative) F. + + + • Command APDU: [DO‘87’] [DO‘97’] DO‘8E’ + • Response APDU: [DO‘87’] DO‘99’ DO‘8E’ +All secure messaging data objects SHALL be encoded in DER (cf. Appendix D.2). The actual value of Lc +will be modified to Lc’ after application of secure messaging. If required, an appropriate data object may +optionally be included into the APDU data part in order to convey the original value of Le. In the +protected command APDU the new Le byte SHALL be set to ‘00’. + +Note: Secure messaging MUST be indicated by using class byte CLA = ‘XC’, with a bit mask X, where bit 8 +(set to 0) indicates the interindustry class and bit 5 (set to 1) indicates command chaining. + + +F.3.1. Command APDU +The command with applied Secure Messaging therefore SHALL have the following structure, +depending on the case of the respective unsecured command: +Case 1: CH || Lc’ || DO’8E’ || new Le +Case 2: CH || Lc’ || DO’97’ || DO’8E’ || new Le +Case 3: CH || Lc’ || DO’87’ || DO’8E’ || new Le +Case 4: CH || Lc’ || DO’87’ || DO’97’ || DO’8E’ || new Le +with CH: Command Header (CLA INS P1 P2) + + +F.3.2. Response APDU +The response with applied Secure Messaging SHALL have the following structure, depending on the +case of the respective unsecured command: +Case 1: DO’99’ || DO’8E’ || SW1SW2 +Case 2: DO’87’ || DO’99’ || DO’8E’ || SW1SW2 +Case 3: DO’99’ || DO’8E’ || SW1SW2 +Case 4: DO’87’ || DO’99’ || DO’8E’ || SW1SW2 + + + Name Tag Len Command Response + Padding-content indicator followed by cryptogram 0x87 V c c + Protected Le 0x97 2V c x + Processing Status 0x99 2F x m + Cryptographic Checksum 0x8E 8F m m + F: fixed length (exact number of octets), V: variable length (up to number of octets) + Table 32: Usage of Secure Messaging Data Objects +F.3.3. Padding +The data to be encrypted SHALL be padded according to ISO 7816-4 [12] using padding-content +indicator 0x01. For the calculation of the cryptographic checksum the APDU SHALL be padded +according to ISO 7816-4 [12]. + + + + +Bundesamt für Sicherheit in der Informationstechnik 101 + F. Secure Messaging (Normative) + + +Note: Padding is always performed by the secure messaging layer not by the underlying cryptographic +algorithm. + + +F.3.4. Examples +Three Examples are provided at the end of this section: + • Figure 4 shows the transformation of an unprotected command APDU to a protected command + APDU in the case Data and/or Le are available. If no Data is available, leave building DO ’87’ out. + If Le is not available, leave building DO ’97’ out. + • Figure 5 shows the transformation of an unprotected command APDU to a protected command + APDU in the case Data and Le are not available. + • Figure 6 shows the transformation of an unprotected response APDU to a protected response + APDU in the case Data are available. If no Data is available, leave building DO ’87’ out. + + +F.4. Cryptographic Algorithms +Secure Messaging is based on either 3DES [20] or AES [21] in encrypt-then-authenticate mode, i.e. data +is encrypted first and afterwards the formatted encrypted data is input to the authentication +calculation. The session keys SHALL be derived from PACE or Chip Authentication using the key +derivation function described in Appendix A.2.3. + +Note: If a command does not contain command data, no encryption applies for the command. If a +response does not contain response data, no encryption applies for the response. + + +F.4.1. 3DES +3DES is specified in [20]. + +F.4.1.1. 3DES Encryption +For message encryption two key 3DES SHALL be used in CBC-mode according to ISO 10116 [9] with key +K Enc and IV =0. + +F.4.1.2. 3DES Authentication +For message authentication 3DES SHALL be used in Retail-mode according to ISO/IEC 9797-1 [15] MAC +algorithm 3 with block cipher DES, key K MAC and IV =0. The datagram to be authenticated SHALL be +prepended by the Send Sequence Counter. + + +F.4.2. AES +AES is specified in [21]. + + + + +102 Bundesamt für Sicherheit in der Informationstechnik + Secure Messaging (Normative) F. + + +F.4.2.1. AES Encryption +For message encryption AES SHALL be used in CBC-mode according to ISO 10116 [9] with key K Enc and +IV =E  K Enc , SSC . + +F.4.2.2. AES Authentication +For message authentication AES SHALL be used in CMAC-mode [22] with K MAC with a MAC length of +8 bytes. The datagram to be authenticated SHALL be prepended by the Send Sequence Counter. + + +F.5. Send Sequence Counter +An unsigned integer SHALL be used as Send Sequence Counter (SSC). The bitsize of the SSC SHALL be +equal to the blocksize of the block cipher used for Secure Messaging, i.e. 64 bit for 3DES and 128 bit for +AES. +The SSC SHALL be increased every time before a command or response APDU is generated, i.e. if the +starting value is x, in the next command the value of the SSC is x1. The value of SSC for the first +response is x2. +If Secure Messaging is restarted, the SSC is used as follows: + • The commands used for key agreement are protected with the old session keys and old SSC. + This applies in particular for the response of the last command used for session key agreement. + • The Send Sequence Counter is set to its new start value, i.e. within this specification the SSC is + set to 0. + • The new session keys and the new SSC are used to protect subsequent commands/responses. + + +F.6. Secure Messaging Termination +The ICC MUST abort Secure Messaging if and only if a plain APDU is received or a Secure Messaging +error occurs: + • If expected Secure Messaging data objects are missing, the ICC SHALL respond with status bytes + 0x6987 + • If Secure Messaging data objects are incorrect, the ICC SHALL respond with status bytes 0x6988 +If Secure Messaging is aborted, the ICC SHALL delete the stored session keys and reset the terminal’s +access rights. + + + + +Bundesamt für Sicherheit in der Informationstechnik 103 + F. Secure Messaging (Normative) + + + + Header Lc Data Le + CLA, INS, P1, P2 Lc Data Le + + + + + Data padded to multiple of block size + Header + k bytes k bytes x bytes '80' ['00' .. '00'] Le + + + + Data encryption + + + + '87' L '01' Encrypted Data + + + + + Header '80 00 00 00' ['00' .. '00'] Formatted Encrypted Data '97' L Le '80' ['00' .. '00'] + + + + + MAC calculation + + + + + Header Lc' '87' L '01' Encrypted Data '97' L Le '8E 08' MAC '00' + + Figure 4: Transformation of a command APDU + + + + + Header + CLA, INS, P1, P2 + + + + + Header + + + + + Header '80' ['00' .. '00'] + + + + + MAC calculation + + + + + Header Lc' '8E 08' MAC '00' + + + + + Figure 5: Transformation of a command APDU if no data is available + + + + +104 Bundesamt für Sicherheit in der Informationstechnik + Secure Messaging (Normative) F. + + + + + Data Status + Data SW1-SW2 + + + + + Data padded to multiple of block size + k bytes k bytes x bytes '80' ['00' .. '00'] SW1-SW2 + + + + Data encryption + + + + '87' L '01' Encrypted Data + + + + + Formatted Encrypted Data '99 02' SW1-SW2 '80' ['00' .. '00'] + + + + + MAC calculation + + + + + '87' L '01' Encrypted Data '99 02' SW1-SW2 '8E 08' MAC SW1-SW2 + + + + + Figure 6: Transformation of a response APDU + + + + +Bundesamt für Sicherheit in der Informationstechnik 105 + F. Secure Messaging (Normative) + + + + +Bibliography +[1] ANSI. Public Key Cryptography for the Financial Services Industry: Agreement of + Symmetric Keys Using Discrete Logarithm Cryptography, ANSI X9.42-2003, 2003 +[2] Bradner, Scott. Key words for use in RFCs to indicate requirement levels, RFC 2119, 1997 +[3] BSI. PKIs for Machine Readable Travel Documents – Protocols for the Management of + Certificates and CRLs, TR-03129, 2009 +[4] BSI. Elliptic Curve Cryptography (ECC), TR-03111, +[5] BSI. eCard-API-Framework - ISO24727-3 Interface, TR-03112-4, +[6] Cooper, David; Santesson, Stefan; Farrell, Stephen; Boeyen, Sharon; Housley, Russell and + Polk, Tim. Internet X.509 public key infrastructure - certificate and certificate revocation + list (CRL) profile, RFC 5280, 2008 +[7] Housley, Russel. Cryptographic message syntax (CMS), RFC 5652, 2009 +[8] ICAO. Machine Readable Travel Documents, ICAO Doc 9303, 2015 +[9] ISO/IEC 10116:2006. Information technology − Security techniques − Modes of operation + for an n-bit block cipher, 2006 +[10] ISO/IEC 7816-15. Identification cards – Integrated circuit cards – Part 15: Cryptographic + Information Application, 2004 +[11] ISO/IEC 7816-3:2006. Identification cards – Integrated circuit cards – Part 3: Cards with + contacts — Electrical interface and transmission protocols, 2006 +[12] ISO/IEC 7816-4:2013. Identification cards – Integrated circuit cards – Part 4: + Organization, security and commands for interchange, 2013 +[13] ISO/IEC 7816-6:2004. Identification cards – Integrated circuit cards – Part 6: Interindustry + data elements for interchange, 2004 +[14] ISO/IEC 7816-8:2004. Identification cards – Integrated circuit cards – Part 8: Commands + for security operations, 2004 +[15] ISO/IEC 9797-1:1999. Information technology − Security techniques − Message + Authentication Codes (MACs) − Part 1: Mechanisms using a block cipher, 1999 +[16] ITU-T. Information Technology – ASN.1 encoding rules: Specification of Basic Encoding + Rules(BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER), + X.690, 2002 +[17] Jonsson, Jakob and Kaliski, Burt. Public-key cryptography standards (PKCS)#1: RSA + cryptography specifications version 2.1, RFC 3447, 2003 +[18] Lepinski, Matt; Kent, Stephen. Additional Diffie-Hellman Groups for Use with IETF + Standards, RFC 5114, 2008 +[19] Lochter, Manfred; Merkle, Johannes. Elliptic Curve Cryptography (ECC) Brainpool + Standard Curves and Curve Generation, RFC 5639, 2010 +[20] NIST. Data Encryption Standard (DES), FIPS PUB 46-3, 1999 +[21] NIST. Specification for the Advanced Encryption Standard (AES), FIPS PUB 197, 2001 +[22] NIST. Recommendation for Block Cipher Modes of Operation: The CMAC Mode for + Authentication, Special Publication 800-38B, 2005 +[23] NIST. Digital Signature Standard (DSS), FIPS 186-4, 2013 +[24] NIST. Secure hash standard, FIPS PUB 180-4, 2015 +[25] Rescorla, Eric. Diffie-Hellman key agreement method, RFC 2631, 1999 +[26] RSA Laboratories. PKCS#3: Diffie-Hellman key-agreement standard, RSA Laboratories + Technical Note, 1993 +[27] RSA Laboratories. PKCS#1 v2.2: RSA cryptography standard, RSA Laboratories Technical + Note, 2012 +[28] SOG-IS. Crypto Evaluation Scheme - Agreed Cryptographic Mechanisms, Crypto + Working Group, + + + + +106 Bundesamt für Sicherheit in der Informationstechnik + \ No newline at end of file diff --git a/core-modules/asn1/src/spec/cvc_schema.txt b/core-modules/asn1/src/spec/cvc_schema.txt new file mode 100644 index 00000000..653377fa --- /dev/null +++ b/core-modules/asn1/src/spec/cvc_schema.txt @@ -0,0 +1,191 @@ +BSI-TR03110-CVCert DEFINITIONS IMPLICIT TAGS ::= +BEGIN + +-- ============================================================ +-- CV Certificate (TR-03110 Part 3) +-- Tag mapping / data objects are defined by TR-03110 Appendix D.2 +-- Profile requirements are defined by TR-03110 Appendix C.1 (Table 23). +-- ============================================================ + +-- ----------------------------- +-- Top-level certificate object +-- ----------------------------- +CVCertificate ::= [APPLICATION 33] -- tag '7F21' (CV Certificate) + SEQUENCE { + body CertificateBody, -- tag '7F4E' + signature Signature -- tag '5F37' + } + +-- ----------------------------- +-- Certificate body +-- ----------------------------- +CertificateBody ::= [APPLICATION 78] -- tag '7F4E' (Certificate Body) + SEQUENCE { + profileIdentifier CertificateProfileIdentifier, -- tag '5F29' (version of profile) + certificationAuthorityReference CertificationAuthorityReference, -- tag '42' + publicKey CVCertPublicKey, -- tag '7F49' + certificateHolderReference CertificateHolderReference, -- tag '5F20' + certificateHolderAuthorizationTemplate CHAT, -- tag '7F4C' + certificateEffectiveDate CertificateEffectiveDate, -- tag '5F25' + certificateExpirationDate CertificateExpirationDate,-- tag '5F24' + certificateExtensions CertificateExtensions OPTIONAL -- tag '65' + } + +-- ============================================================ +-- Primitive fields (data objects) +-- ============================================================ + +-- Certificate Profile Identifier (TR says profile version 1 is value 0) +-- Tag '5F29' value encoding is an unsigned integer (Appendix D.2.1.1), i.e. raw octets (not ASN.1 INTEGER). +CertificateProfileIdentifier ::= [APPLICATION 41] -- tag '5F29' + OCTET STRING (SIZE(1)) + +-- Certification Authority Reference (CAR): identifies issuer key reference. +-- TR encodes this as a "Character String" with up to 16 octets. +-- Appendix D.2.1.4 constrains the octets to ISO/IEC 8859-1 and excludes control code ranges. +CharacterString ::= OCTET STRING (SIZE(1..16)) + +CertificationAuthorityReference ::= [APPLICATION 2] -- tag '42' + CharacterString + +-- Certificate Holder Reference (CHR): identifies holder key reference. +-- TR encodes this as a "Character String" with up to 16 octets. +CertificateHolderReference ::= [APPLICATION 32] -- tag '5F20' + CharacterString + +-- Dates are encoded as YYMMDD (6 digits) in unpacked BCD => 6 octets. +CertificateEffectiveDate ::= [APPLICATION 37] -- tag '5F25' + OCTET STRING (SIZE(6)) + +CertificateExpirationDate ::= [APPLICATION 36] -- tag '5F24' + OCTET STRING (SIZE(6)) + +-- Signature: created over the encoded CertificateBody (incl. tag and length). +Signature ::= [APPLICATION 55] -- tag '5F37' + OCTET STRING (SIZE(0..65535)) + +-- ============================================================ +-- Public key container (data object '7F49') +-- TR-03110 Appendix D.3 defines the exact content, tags and order: +-- - First: an OBJECT IDENTIFIER (tag 0x06) specifying algorithm/usage. +-- - Then: context-specific data objects (tags 0x81..0x87) in fixed order, +-- depending on the algorithm (Tables 29-31). +-- +-- Note: Tags 0x81..0x87 are context-specific tags [1]..[7] (not APPLICATION tags). +-- All values are transported as raw octets (unsigned integer / EC point encodings). +-- ============================================================ + +UnsignedInteger ::= OCTET STRING (SIZE(1..65535)) +EllipticCurvePoint ::= OCTET STRING (SIZE(1..65535)) + +CVCertPublicKey ::= [APPLICATION 73] -- tag '7F49' (Public Key) + SEQUENCE { + keyOid OBJECT IDENTIFIER, + + -- Tag 0x81 (context [1]): + -- RSA: n (modulus), DH: p, EC: p + cs1 [1] IMPLICIT UnsignedInteger OPTIONAL, + + -- Tag 0x82 (context [2]): + -- RSA: e (exponent), DH: q, EC: a + cs2 [2] IMPLICIT UnsignedInteger OPTIONAL, + + -- Tag 0x83 (context [3]): + -- DH: g, EC: b + cs3 [3] IMPLICIT UnsignedInteger OPTIONAL, + + -- Tag 0x84 (context [4]): + -- DH: y (public value, as unsigned integer), + -- EC: G (base point, as EC point) + cs4 [4] IMPLICIT OCTET STRING OPTIONAL, + + -- Tag 0x85 (context [5]): + -- EC: r (order of base point) + cs5 [5] IMPLICIT UnsignedInteger OPTIONAL, + + -- Tag 0x86 (context [6]): + -- EC: Y (public point) [MANDATORY for EC keys] + cs6 [6] IMPLICIT EllipticCurvePoint OPTIONAL, + + -- Tag 0x87 (context [7]): + -- EC: f (cofactor) + cs7 [7] IMPLICIT UnsignedInteger OPTIONAL + } + +-- ============================================================ +-- Certificate Holder Authorization Template (CHAT) (data object '7F4C') +-- TR defines: (1) OID for terminal type/template format, (2) discretionary data +-- encoding relative authorization. (Semantics described in TR Part 4.) +-- ============================================================ +CHAT ::= [APPLICATION 76] -- tag '7F4C' + SEQUENCE { + terminalType OBJECT IDENTIFIER, + relativeAuthorization DiscretionaryData + } + +DiscretionaryData ::= [APPLICATION 19] -- tag '53' + OCTET STRING (SIZE(0..65535)) + +-- ============================================================ +-- Certificate Extensions (optional) (data object '65') +-- TR: sequence of Discretionary Data Templates (tag '73'), each with: +-- 1) OID (extension identifier) +-- 2) one or more context-specific data objects carrying the extension payload +-- ============================================================ +CertificateExtensions ::= [APPLICATION 5] -- tag '65' + SEQUENCE OF DiscretionaryDataTemplate + +DiscretionaryDataTemplate ::= [APPLICATION 19] -- tag '73' + SEQUENCE { + extensionId OBJECT IDENTIFIER, + extensionField1 ExtensionField, + extensionField2 ExtensionField OPTIONAL, + extensionField3 ExtensionField OPTIONAL, + extensionField4 ExtensionField OPTIONAL, + extensionField5 ExtensionField OPTIONAL, + extensionField6 ExtensionField OPTIONAL, + extensionField7 ExtensionField OPTIONAL, + extensionField8 ExtensionField OPTIONAL + } + +-- Context-specific fields (e.g., 'A0', '80', '81', etc.) vary per extension. +-- Model them as open ANY; the concrete tags/contents are defined per extension. +ExtensionField ::= ANY + +-- ============================================================ +-- Known extension payloads (Appendix C.3) +-- +-- Note: Extensions are defined as "OID + one or more context-specific data objects" +-- inside the Discretionary Data Template (tag 0x73). The concrete payload depends on +-- the extension OID (and may be repeatable), which is not directly expressible as +-- conditional typing in plain ASN.1 here. The following types document the +-- application-independent structures defined in Part 3. +-- ============================================================ + +HashValue ::= OCTET STRING (SIZE(1..65535)) +DomainParametersId ::= OCTET STRING (SIZE(1..65535)) + +-- C.3.2.1 Terminal Sector for Restricted Identification: +-- extension OID: id-sector (id-extensions 2) +-- payload tags: +-- - 0x80 ([0]) hash of 1st sector public key data object +-- - 0x81 ([1]) hash of 2nd sector public key data object +TerminalSectorExtension ::= [APPLICATION 19] -- tag '73' + SEQUENCE { + extensionId OBJECT IDENTIFIER, + hash1 [0] IMPLICIT HashValue OPTIONAL, + hash2 [1] IMPLICIT HashValue OPTIONAL + } + +-- C.3.2.2 Terminal Sector for Pseudonymous Signatures: +-- extension OID: id-PS-Sector (id-extensions 3) +-- payload is one or more templates with tag 0xA0 ([0], constructed) containing: +-- - 0x80 ([0]) ID of domain parameters +-- - 0x81 ([1]) hash of sector public key (EC point without domain parameters) +PSSectorTemplate ::= [0] IMPLICIT + SEQUENCE { + domainParametersId [0] IMPLICIT DomainParametersId, + sectorPublicKeyHash [1] IMPLICIT HashValue + } + +END From 196c840c40d12b4b9e1407f9de34a281f32e1da6 Mon Sep 17 00:00:00 2001 From: Tobias Schwerdtfeger Date: Fri, 9 Jan 2026 16:37:21 +0100 Subject: [PATCH 11/20] Add spec --- core-modules/asn1/src/spec/cvc_schema.txt | 33 +++++++++++------------ 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/core-modules/asn1/src/spec/cvc_schema.txt b/core-modules/asn1/src/spec/cvc_schema.txt index 653377fa..609e0269 100644 --- a/core-modules/asn1/src/spec/cvc_schema.txt +++ b/core-modules/asn1/src/spec/cvc_schema.txt @@ -135,18 +135,19 @@ DiscretionaryData ::= [APPLICATION 19] -- tag '53' CertificateExtensions ::= [APPLICATION 5] -- tag '65' SEQUENCE OF DiscretionaryDataTemplate +-- Discretionary Data Template (tag '73') is a SEQUENCE whose content is: +-- 1) OBJECT IDENTIFIER (extension identifier) +-- 2) one or more context-specific data objects (extension payload) +-- (Appendix C.3 / Table 25). ASN.1 cannot express "an arbitrary number of +-- context-specific fields with arbitrary tags" as direct SEQUENCE components +-- without either bounding the count (which becomes ambiguous with ANY) or +-- adding an extra wrapper. We therefore model the template as a tagged +-- SEQUENCE OF items and keep the payload items open via ANY. +-- +-- Constraint (to be validated by the caller): the first item MUST be an OID, +-- remaining items MUST be the context-specific data objects of the extension. DiscretionaryDataTemplate ::= [APPLICATION 19] -- tag '73' - SEQUENCE { - extensionId OBJECT IDENTIFIER, - extensionField1 ExtensionField, - extensionField2 ExtensionField OPTIONAL, - extensionField3 ExtensionField OPTIONAL, - extensionField4 ExtensionField OPTIONAL, - extensionField5 ExtensionField OPTIONAL, - extensionField6 ExtensionField OPTIONAL, - extensionField7 ExtensionField OPTIONAL, - extensionField8 ExtensionField OPTIONAL - } + SEQUENCE OF ExtensionField -- Context-specific fields (e.g., 'A0', '80', '81', etc.) vary per extension. -- Model them as open ANY; the concrete tags/contents are defined per extension. @@ -170,12 +171,10 @@ DomainParametersId ::= OCTET STRING (SIZE(1..65535)) -- payload tags: -- - 0x80 ([0]) hash of 1st sector public key data object -- - 0x81 ([1]) hash of 2nd sector public key data object -TerminalSectorExtension ::= [APPLICATION 19] -- tag '73' - SEQUENCE { - extensionId OBJECT IDENTIFIER, - hash1 [0] IMPLICIT HashValue OPTIONAL, - hash2 [1] IMPLICIT HashValue OPTIONAL - } +TerminalSectorExtensionContent ::= SEQUENCE { + hash1 [0] IMPLICIT HashValue OPTIONAL, + hash2 [1] IMPLICIT HashValue OPTIONAL +} -- C.3.2.2 Terminal Sector for Pseudonymous Signatures: -- extension OID: id-PS-Sector (id-extensions 3) From a5b879c768383397900ecc389fe3eadb11eef415 Mon Sep 17 00:00:00 2001 From: "sandra.bieseke" Date: Mon, 12 Jan 2026 10:42:21 +0100 Subject: [PATCH 12/20] OPEN-99: Add support for selecting and retrieving multiple certificate types from health card --- .../healthcard/src/exchange/certificate.rs | 87 +++++++++++++++++-- core-modules/healthcard/src/exchange/ids.rs | 12 +++ 2 files changed, 92 insertions(+), 7 deletions(-) diff --git a/core-modules/healthcard/src/exchange/certificate.rs b/core-modules/healthcard/src/exchange/certificate.rs index 8c54e649..61146bfd 100644 --- a/core-modules/healthcard/src/exchange/certificate.rs +++ b/core-modules/healthcard/src/exchange/certificate.rs @@ -29,6 +29,43 @@ use super::channel::CardChannelExt; use super::error::ExchangeError; use super::ids; +/// Defines which certificate file to read from the card. +#[derive(Clone, Copy, Debug)] +pub enum CertificateFile { + /// X.509 certificate stored in `DF.ESIGN/EF.C.CH.AUT.E256`. + ChAutE256, + /// CV certificate stored in `MF/EF.C.eGK.AUT_CVC.E256`. + EgkAutCvcE256, +} + +fn select_certificate_file(session: &mut S, certificate: CertificateFile) -> Result<(), ExchangeError> +where + S: CardChannelExt, +{ + match certificate { + CertificateFile::ChAutE256 => { + session.execute_command_success(&HealthCardCommand::select_aid(&ids::df_esign_aid()))?; + session.execute_command_success(&HealthCardCommand::select_fid_with_options( + &ids::ef_cch_aut_e256_fid(), + false, + true, + EXPECTED_LENGTH_WILDCARD_EXTENDED as i32, + ))?; + } + CertificateFile::EgkAutCvcE256 => { + session.execute_command_success(&HealthCardCommand::select(false, false))?; + session.execute_command_success(&HealthCardCommand::select_fid_with_options( + &ids::ef_c_egk_aut_cvc_e256_fid(), + false, + true, + EXPECTED_LENGTH_WILDCARD_EXTENDED as i32, + ))?; + } + } + + Ok(()) +} + /// Retrieve the X.509 certificate stored in `DF.ESIGN/EF.C.CH.AUT.E256`. /// /// The certificate is read in chunks using the READ BINARY command until the @@ -37,13 +74,21 @@ pub fn retrieve_certificate(session: &mut S) -> Result, ExchangeError where S: CardChannelExt, { - session.execute_command_success(&HealthCardCommand::select_aid(&ids::df_esign_aid()))?; - session.execute_command_success(&HealthCardCommand::select_fid_with_options( - &ids::ef_cch_aut_e256_fid(), - false, - true, - EXPECTED_LENGTH_WILDCARD_EXTENDED as i32, - ))?; + retrieve_certificate_from(session, CertificateFile::ChAutE256) +} + +/// Retrieve a certificate file from the card. +/// +/// The certificate is read in chunks using the READ BINARY command until the +/// card indicates the end of the file. +pub fn retrieve_certificate_from( + session: &mut S, + certificate: CertificateFile, +) -> Result, ExchangeError> +where + S: CardChannelExt, +{ + select_certificate_file(session, certificate)?; let mut certificate = Vec::new(); let mut offset: i32 = 0; @@ -71,6 +116,7 @@ where mod tests { use super::*; use crate::command::health_card_status::HealthCardResponseStatus; + use crate::command::select_command::SelectCommand; use crate::exchange::test_utils::MockSession; #[test] @@ -95,4 +141,31 @@ mod tests { other => panic!("unexpected error {other:?}"), } } + + #[test] + fn cv_certificate_selects_master_file() { + let mut session = MockSession::with_extended_support( + vec![vec![0x90, 0x00], vec![0x90, 0x00], vec![0xDE, 0xAD, 0x90, 0x00], vec![0xBE, 0xEF, 0x62, 0x82]], + true, + ); + + let cert = retrieve_certificate_from(&mut session, CertificateFile::EgkAutCvcE256).unwrap(); + assert_eq!(cert, vec![0xDE, 0xAD, 0xBE, 0xEF]); + assert_eq!( + session.recorded[0], + HealthCardCommand::select(false, false).command_apdu(false).unwrap().to_bytes() + ); + assert_eq!( + session.recorded[1], + HealthCardCommand::select_fid_with_options( + &ids::ef_c_egk_aut_cvc_e256_fid(), + false, + true, + EXPECTED_LENGTH_WILDCARD_EXTENDED as i32, + ) + .command_apdu(false) + .unwrap() + .to_bytes() + ); + } } diff --git a/core-modules/healthcard/src/exchange/ids.rs b/core-modules/healthcard/src/exchange/ids.rs index 89e9bc0b..61e4fe9e 100644 --- a/core-modules/healthcard/src/exchange/ids.rs +++ b/core-modules/healthcard/src/exchange/ids.rs @@ -102,6 +102,16 @@ pub fn ef_cch_aut_e256_sfid() -> ShortFileIdentifier { short_file_identifier(0x04) } +/// File identifier for `MF/EF.C.eGK.AUT_CVC.E256` (gemSpec_ObjSys Section 5.3.4). +pub fn ef_c_egk_aut_cvc_e256_fid() -> FileIdentifier { + file_identifier(0x2F06) +} + +/// Short file identifier for `MF/EF.C.eGK.AUT_CVC.E256` (gemSpec_ObjSys Section 5.3.4). +pub fn ef_c_egk_aut_cvc_e256_sfid() -> ShortFileIdentifier { + short_file_identifier(0x06) +} + /// Key identifier for the `PrK.CH.AUT.E256` private key in `DF.ESIGN`. pub fn prk_ch_aut_e256() -> CardKey { CardKey::new(0x04).expect("constant key id must be valid") @@ -135,6 +145,8 @@ mod tests { assert_eq!(ef_status_vd_sfid().value(), 0x0C); assert_eq!(ef_cch_aut_e256_fid().to_bytes(), [0xC5, 0x04]); assert_eq!(ef_cch_aut_e256_sfid().value(), 0x04); + assert_eq!(ef_c_egk_aut_cvc_e256_fid().to_bytes(), [0x2F, 0x06]); + assert_eq!(ef_c_egk_aut_cvc_e256_sfid().value(), 0x06); assert_eq!(prk_ch_aut_e256().key_id(), 0x04); assert_eq!(mr_pin_home_reference().pwd_id(), 0x02); From dfa43ad964eaa212fe9eab774863c09aa560bbb9 Mon Sep 17 00:00:00 2001 From: Tobias Schwerdtfeger Date: Mon, 12 Jan 2026 11:47:14 +0100 Subject: [PATCH 13/20] OPEN-97: Add real world egk cvc test --- CONTRIBUTING.md | 4 +- core-modules/asn1/src/cv_certificate.rs | 325 +- core-modules/asn1/src/lib.rs | 2 +- .../spec/BSI_TR-03110_Part-3-V2_2_layout.txt | 4985 ----------------- 4 files changed, 175 insertions(+), 5141 deletions(-) delete mode 100644 core-modules/asn1/src/spec/BSI_TR-03110_Part-3-V2_2_layout.txt diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f2e6d01c..f60b7f27 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -54,12 +54,12 @@ Ensure all the following pre-requirements are done: Formatting: ```shell -cargo +nightly fmt +cargo +nightly fmt --all ``` Linting: ```shell -cargo clippy +cargo clippy --workspace --all-targets --all-features ``` ## Handling TODOs diff --git a/core-modules/asn1/src/cv_certificate.rs b/core-modules/asn1/src/cv_certificate.rs index b9ee74fd..8355536a 100644 --- a/core-modules/asn1/src/cv_certificate.rs +++ b/core-modules/asn1/src/cv_certificate.rs @@ -59,8 +59,9 @@ pub struct CertificateBody { #[derive(Debug, Clone, PartialEq, Eq)] pub struct CVCertPublicKey { - /// Raw contents of the public key container (tag 7F49). - pub public_key_data: Vec, + pub key_oid: ObjectIdentifier, + /// Raw contents after the key OID (context-specific key data objects). + pub key_data: Vec, } #[derive(Debug, Clone, PartialEq, Eq)] @@ -119,16 +120,12 @@ fn parse_certificate_body(scope: &mut ParserScope) -> Result 0 { - Some(parse_certificate_extensions(scope)?) - } else { - None - }; + let certificate_extensions = + if scope.remaining_length() > 0 { Some(parse_certificate_extensions(scope)?) } else { None }; Ok(CertificateBody { profile_identifier, @@ -144,38 +141,25 @@ fn parse_certificate_body(scope: &mut ParserScope) -> Result Result { - scope.advance_with_tag(TAG_PROFILE_IDENTIFIER.application_tag().primitive(), |scope| { - let bytes = scope.read_bytes(scope.remaining_length())?; - if bytes.is_empty() { - return Err(Asn1DecoderError::custom("CertificateProfileIdentifier must not be empty")); - } - if bytes.len() > 4 { - return Err(Asn1DecoderError::custom( - "CertificateProfileIdentifier must not exceed 4 bytes", - )); - } - if (bytes[0] & 0x80) != 0 { - return Err(Asn1DecoderError::custom( - "CertificateProfileIdentifier must be a non-negative INTEGER", - )); - } - let value = bytes.iter().fold(0u32, |acc, b| (acc << 8) | (*b as u32)); - if value > u8::MAX as u32 { - return Err(Asn1DecoderError::custom( - "CertificateProfileIdentifier must be within 0..=255", - )); - } - Ok(value as u8) - }) + let bytes = read_application_bytes(scope, TAG_PROFILE_IDENTIFIER, 1, 4)?; + if (bytes[0] & 0x80) != 0 { + return Err(Asn1DecoderError::custom("CertificateProfileIdentifier must be a non-negative INTEGER")); + } + let value = bytes.iter().fold(0u32, |acc, b| (acc << 8) | (*b as u32)); + if value > u8::MAX as u32 { + return Err(Asn1DecoderError::custom("CertificateProfileIdentifier must be within 0..=255")); + } + Ok(value as u8) } fn parse_public_key(scope: &mut ParserScope) -> Result { scope.advance_with_tag(TAG_PUBLIC_KEY.application_tag().constructed(), |scope| { - let data = scope.read_bytes(scope.remaining_length())?; - if data.is_empty() { - return Err(Asn1DecoderError::custom("CVCertPublicKey must not be empty")); + let key_oid = scope.read_object_identifier()?; + let key_data = scope.read_bytes(scope.remaining_length())?; + if key_data.is_empty() { + return Err(Asn1DecoderError::custom("CVCertPublicKey data must not be empty")); } - Ok(CVCertPublicKey { public_key_data: data }) + Ok(CVCertPublicKey { key_oid, key_data }) }) } @@ -188,29 +172,8 @@ fn parse_chat(scope: &mut ParserScope) -> Result { } fn parse_date(scope: &mut ParserScope, tag_number: u32) -> Result { - scope.advance_with_tag(tag_number.application_tag().primitive(), |scope| { - let bytes = scope.read_bytes(scope.remaining_length())?; - if bytes.len() != 6 { - return Err(Asn1DecoderError::custom("Certificate date must be 6 bytes")); - } - for (idx, byte) in bytes.iter().enumerate() { - if *byte > 9 { - return Err(Asn1DecoderError::custom(format!( - "Certificate date digit {idx} must be 0..9" - ))); - } - } - let year = bytes[0] * 10 + bytes[1]; - let month = bytes[2] * 10 + bytes[3]; - let day = bytes[4] * 10 + bytes[5]; - if !(1..=12).contains(&month) { - return Err(Asn1DecoderError::custom("Certificate month must be 1..=12")); - } - if !(1..=31).contains(&day) { - return Err(Asn1DecoderError::custom("Certificate day must be 1..=31")); - } - Ok(CertificateDate { year, month, day }) - }) + let bytes = read_application_bytes(scope, tag_number, 6, 6)?; + parse_date_bytes(&bytes) } fn parse_certificate_extensions(scope: &mut ParserScope) -> Result { @@ -240,9 +203,7 @@ fn parse_extension_field(scope: &mut ParserScope) -> Result scope.read_bytes(len)?, Asn1Length::Indefinite => { - return Err(Asn1DecoderError::custom( - "Indefinite length is not supported for extension fields", - )) + return Err(Asn1DecoderError::custom("Indefinite length is not supported for extension fields")) } }; Ok(ExtensionField { tag, value }) @@ -257,14 +218,30 @@ fn read_application_bytes( scope.advance_with_tag(tag_number.application_tag().primitive(), |scope| { let len = scope.remaining_length(); if len < min_len || len > max_len { - return Err(Asn1DecoderError::custom(format!( - "Invalid length {len} for application tag {tag_number}" - ))); + return Err(Asn1DecoderError::custom(format!("Invalid length {len} for application tag {tag_number}"))); } scope.read_bytes(len) }) } +fn parse_date_bytes(bytes: &[u8]) -> Result { + for (idx, byte) in bytes.iter().enumerate() { + if *byte > 9 { + return Err(Asn1DecoderError::custom(format!("Certificate date digit {idx} must be 0..9"))); + } + } + let year = bytes[0] * 10 + bytes[1]; + let month = bytes[2] * 10 + bytes[3]; + let day = bytes[4] * 10 + bytes[5]; + if !(1..=12).contains(&month) { + return Err(Asn1DecoderError::custom("Certificate month must be 1..=12")); + } + if !(1..=31).contains(&day) { + return Err(Asn1DecoderError::custom("Certificate day must be 1..=31")); + } + Ok(CertificateDate { year, month, day }) +} + #[cfg(test)] mod tests { use super::*; @@ -275,12 +252,8 @@ mod tests { fn build_test_certificate(with_extensions: bool) -> Vec { Asn1Encoder::write::(|w| { - w.write_tagged_object( - TAG_CV_CERTIFICATE.application_tag().constructed(), - |cert| -> EncResult { - cert.write_tagged_object( - TAG_CERTIFICATE_BODY.application_tag().constructed(), - |body| -> EncResult { + w.write_tagged_object(TAG_CV_CERTIFICATE.application_tag().constructed(), |cert| -> EncResult { + cert.write_tagged_object(TAG_CERTIFICATE_BODY.application_tag().constructed(), |body| -> EncResult { body.write_tagged_object(TAG_PROFILE_IDENTIFIER.application_tag(), |field| -> EncResult { field.write_byte(0x00); Ok(()) @@ -288,17 +261,23 @@ mod tests { body.write_tagged_object( TAG_CERTIFICATION_AUTHORITY_REFERENCE.application_tag(), |field| -> EncResult { - field.write_bytes(b"CAR"); - Ok(()) - })?; + field.write_bytes(b"CAR"); + Ok(()) + }, + )?; body.write_tagged_object(TAG_PUBLIC_KEY.application_tag().constructed(), |field| -> EncResult { + let oid = ObjectIdentifier::parse("1.2.3.4").expect("valid OID"); + field.write_object_identifier(&oid)?; field.write_bytes(&[0xA0, 0x01, 0x02]); Ok(()) })?; - body.write_tagged_object(TAG_CERTIFICATE_HOLDER_REFERENCE.application_tag(), |field| -> EncResult { - field.write_bytes(b"CH"); - Ok(()) - })?; + body.write_tagged_object( + TAG_CERTIFICATE_HOLDER_REFERENCE.application_tag(), + |field| -> EncResult { + field.write_bytes(b"CH"); + Ok(()) + }, + )?; body.write_tagged_object(TAG_CHAT.application_tag().constructed(), |chat| -> EncResult { let oid = ObjectIdentifier::parse("1.2.3").expect("valid OID"); chat.write_object_identifier(&oid)?; @@ -312,10 +291,13 @@ mod tests { field.write_bytes(&[2, 5, 0, 1, 0, 1]); Ok(()) })?; - body.write_tagged_object(TAG_CERTIFICATE_EXPIRATION_DATE.application_tag(), |field| -> EncResult { - field.write_bytes(&[2, 6, 1, 2, 3, 1]); - Ok(()) - })?; + body.write_tagged_object( + TAG_CERTIFICATE_EXPIRATION_DATE.application_tag(), + |field| -> EncResult { + field.write_bytes(&[2, 6, 1, 2, 3, 1]); + Ok(()) + }, + )?; if with_extensions { body.write_tagged_object( @@ -324,34 +306,32 @@ mod tests { exts.write_tagged_object( TAG_DISCRETIONARY_DATA.application_tag().constructed(), |tmpl| -> EncResult { - let oid = ObjectIdentifier::parse("1.2.3.4").expect("valid OID"); - tmpl.write_object_identifier(&oid)?; - tmpl.write_tagged_object(0u8.context_tag(), |field| -> EncResult { - field.write_bytes(&[0x10]); - Ok(()) - })?; - tmpl.write_tagged_object(1u8.context_tag(), |field| -> EncResult { - field.write_bytes(&[0x20, 0x30]); - Ok(()) - })?; + let oid = ObjectIdentifier::parse("1.2.3.4").expect("valid OID"); + tmpl.write_object_identifier(&oid)?; + tmpl.write_tagged_object(0u8.context_tag(), |field| -> EncResult { + field.write_bytes(&[0x10]); + Ok(()) + })?; + tmpl.write_tagged_object(1u8.context_tag(), |field| -> EncResult { + field.write_bytes(&[0x20, 0x30]); + Ok(()) + })?; + Ok(()) + }, + )?; Ok(()) }, - )?; - Ok(()) - }, )?; } Ok(()) - }, - )?; - cert.write_tagged_object(TAG_SIGNATURE.application_tag(), |sig| -> EncResult { - sig.write_bytes(&[0xDE, 0xAD]); - Ok(()) - })?; + })?; + cert.write_tagged_object(TAG_SIGNATURE.application_tag(), |sig| -> EncResult { + sig.write_bytes(&[0xDE, 0xAD]); Ok(()) - }, - ) + })?; + Ok(()) + }) }) .expect("encoding must succeed") } @@ -389,13 +369,18 @@ mod tests { }, )?; body.write_tagged_object(TAG_PUBLIC_KEY.application_tag().constructed(), |field| -> EncResult { + let oid = ObjectIdentifier::parse("1.2.3.4").expect("valid OID"); + field.write_object_identifier(&oid)?; field.write_bytes(&[0xA0, 0x01, 0x02]); Ok(()) })?; - body.write_tagged_object(TAG_CERTIFICATE_HOLDER_REFERENCE.application_tag(), |field| -> EncResult { - field.write_bytes(chr); - Ok(()) - })?; + body.write_tagged_object( + TAG_CERTIFICATE_HOLDER_REFERENCE.application_tag(), + |field| -> EncResult { + field.write_bytes(chr); + Ok(()) + }, + )?; body.write_tagged_object(TAG_CHAT.application_tag().constructed(), |chat| -> EncResult { let oid = ObjectIdentifier::parse("1.2.3").expect("valid OID"); chat.write_object_identifier(&oid)?; @@ -409,10 +394,13 @@ mod tests { field.write_bytes(effective); Ok(()) })?; - body.write_tagged_object(TAG_CERTIFICATE_EXPIRATION_DATE.application_tag(), |field| -> EncResult { - field.write_bytes(expiration); - Ok(()) - })?; + body.write_tagged_object( + TAG_CERTIFICATE_EXPIRATION_DATE.application_tag(), + |field| -> EncResult { + field.write_bytes(expiration); + Ok(()) + }, + )?; Ok(()) })?; cert.write_tagged_object(TAG_SIGNATURE.application_tag(), |sig| -> EncResult { @@ -441,13 +429,18 @@ mod tests { }, )?; body.write_tagged_object(TAG_PUBLIC_KEY.application_tag().constructed(), |field| -> EncResult { + let oid = ObjectIdentifier::parse("1.2.3.4").expect("valid OID"); + field.write_object_identifier(&oid)?; field.write_bytes(&[0xA0, 0x01, 0x02]); Ok(()) })?; - body.write_tagged_object(TAG_CERTIFICATE_HOLDER_REFERENCE.application_tag(), |field| -> EncResult { - field.write_bytes(b"CHR"); - Ok(()) - })?; + body.write_tagged_object( + TAG_CERTIFICATE_HOLDER_REFERENCE.application_tag(), + |field| -> EncResult { + field.write_bytes(b"CHR"); + Ok(()) + }, + )?; body.write_tagged_object(TAG_CHAT.application_tag().constructed(), |chat| -> EncResult { let oid = ObjectIdentifier::parse("1.2.3").expect("valid OID"); chat.write_object_identifier(&oid)?; @@ -461,10 +454,13 @@ mod tests { field.write_bytes(&[2, 5, 0, 1, 0, 1]); Ok(()) })?; - body.write_tagged_object(TAG_CERTIFICATE_EXPIRATION_DATE.application_tag(), |field| -> EncResult { - field.write_bytes(&[2, 5, 0, 1, 0, 2]); - Ok(()) - })?; + body.write_tagged_object( + TAG_CERTIFICATE_EXPIRATION_DATE.application_tag(), + |field| -> EncResult { + field.write_bytes(&[2, 5, 0, 1, 0, 2]); + Ok(()) + }, + )?; Ok(()) })?; cert.write_tagged_object(TAG_SIGNATURE.application_tag(), |sig| -> EncResult { @@ -493,13 +489,18 @@ mod tests { }, )?; body.write_tagged_object(TAG_PUBLIC_KEY.application_tag().constructed(), |field| -> EncResult { + let oid = ObjectIdentifier::parse("1.2.3.4").expect("valid OID"); + field.write_object_identifier(&oid)?; field.write_bytes(public_key); Ok(()) })?; - body.write_tagged_object(TAG_CERTIFICATE_HOLDER_REFERENCE.application_tag(), |field| -> EncResult { - field.write_bytes(b"CHR"); - Ok(()) - })?; + body.write_tagged_object( + TAG_CERTIFICATE_HOLDER_REFERENCE.application_tag(), + |field| -> EncResult { + field.write_bytes(b"CHR"); + Ok(()) + }, + )?; body.write_tagged_object(TAG_CHAT.application_tag().constructed(), |chat| -> EncResult { let oid = ObjectIdentifier::parse("1.2.3").expect("valid OID"); chat.write_object_identifier(&oid)?; @@ -513,10 +514,13 @@ mod tests { field.write_bytes(&[2, 5, 0, 1, 0, 1]); Ok(()) })?; - body.write_tagged_object(TAG_CERTIFICATE_EXPIRATION_DATE.application_tag(), |field| -> EncResult { - field.write_bytes(&[2, 5, 0, 1, 0, 2]); - Ok(()) - })?; + body.write_tagged_object( + TAG_CERTIFICATE_EXPIRATION_DATE.application_tag(), + |field| -> EncResult { + field.write_bytes(&[2, 5, 0, 1, 0, 2]); + Ok(()) + }, + )?; Ok(()) })?; cert.write_tagged_object(TAG_SIGNATURE.application_tag(), |sig| -> EncResult { @@ -548,7 +552,8 @@ mod tests { assert_eq!(cert.body.profile_identifier, 0); assert_eq!(cert.body.certification_authority_reference, b"CAR"); - assert_eq!(cert.body.public_key.public_key_data, vec![0xA0, 0x01, 0x02]); + assert_eq!(cert.body.public_key.key_oid.to_string(), "1.2.3.4"); + assert_eq!(cert.body.public_key.key_data, vec![0xA0, 0x01, 0x02]); assert_eq!(cert.body.certificate_holder_reference, b"CH"); let chat = &cert.body.certificate_holder_authorization_template; assert_eq!(chat.terminal_type.to_string(), "1.2.3"); @@ -599,6 +604,8 @@ mod tests { assert_eq!(cert.body.profile_identifier, 0); assert_eq!(cert.body.certification_authority_reference, b"TESTCAR"); + assert_eq!(cert.body.public_key.key_oid.to_string(), "0.4.0.127.0.7.2.2.2.1.2"); + assert_eq!(cert.body.public_key.key_data.len(), 0x109); assert_eq!(cert.body.certificate_holder_reference, b"TESTCHR"); assert_eq!(cert.body.certificate_effective_date, CertificateDate { year: 25, month: 1, day: 1 }); assert_eq!(cert.body.certificate_expiration_date, CertificateDate { year: 25, month: 1, day: 31 }); @@ -609,38 +616,52 @@ mod tests { } #[test] - fn reject_profile_identifier_out_of_range() { - let data = build_certificate_with_fields( - &[0x01, 0x00], - b"CAR", - b"CHR", - &[2, 5, 0, 1, 0, 1], - &[2, 5, 0, 1, 0, 2], + fn parse_cv_certificate_from_egk_aut_cvc_e256() { + let hex_data = "\ + 7f2181da7f4e81935f290170420844454758581102237f494b06062b24030503\ + 018641045e7ae614740e7012e350de71c10021ec668f21d6859591b4f709c4c7\ + 3cce91c5a7fb0be1327e59ff1d0cb402b9c2bb0dc0432fa566bd4ff5f532258c\ + 7364aecd5f200c0009802768831100001565497f4c1306082a8214004c048118\ + 5307000000000000005f25060204000400025f24060209000400015f37409d24\ + 4d497832172304f298bd49f91f45bf346cb306adeb44b0742017a074902146cc\ + cbdbb35426c2eb602d38253d92ebe1ac6905f388407398a474c4ea612d84"; + let data = hex_to_bytes(hex_data); + let cert = CVCertificate::parse(&data).expect("parse should succeed"); + + assert_eq!(cert.body.profile_identifier, 0x70); + assert_eq!(cert.body.certification_authority_reference, vec![0x44, 0x45, 0x47, 0x58, 0x58, 0x11, 0x02, 0x23]); + assert_eq!( + cert.body.certificate_holder_reference, + vec![0x00, 0x09, 0x80, 0x27, 0x68, 0x83, 0x11, 0x00, 0x00, 0x15, 0x65, 0x49] + ); + assert_eq!(cert.body.certificate_holder_authorization_template.terminal_type.to_string(), "1.2.276.0.76.4.152"); + assert_eq!( + cert.body.certificate_holder_authorization_template.relative_authorization, + vec![0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00] ); + assert_eq!(cert.body.certificate_effective_date, CertificateDate { year: 24, month: 4, day: 2 }); + assert_eq!(cert.body.certificate_expiration_date, CertificateDate { year: 29, month: 4, day: 1 }); + assert_eq!(cert.body.public_key.key_oid.to_string(), "1.3.36.3.5.3.1"); + assert_eq!(cert.body.public_key.key_data.len(), 0x43); + assert_eq!(cert.signature.len(), 0x40); + } + + #[test] + fn reject_profile_identifier_out_of_range() { + let data = + build_certificate_with_fields(&[0x01, 0x00], b"CAR", b"CHR", &[2, 5, 0, 1, 0, 1], &[2, 5, 0, 1, 0, 2]); assert!(CVCertificate::parse(&data).is_err()); } #[test] fn reject_negative_profile_identifier() { - let data = build_certificate_with_fields( - &[0xFF], - b"CAR", - b"CHR", - &[2, 5, 0, 1, 0, 1], - &[2, 5, 0, 1, 0, 2], - ); + let data = build_certificate_with_fields(&[0xFF], b"CAR", b"CHR", &[2, 5, 0, 1, 0, 1], &[2, 5, 0, 1, 0, 2]); assert!(CVCertificate::parse(&data).is_err()); } #[test] fn reject_empty_car() { - let data = build_certificate_with_fields( - &[0x00], - b"", - b"CHR", - &[2, 5, 0, 1, 0, 1], - &[2, 5, 0, 1, 0, 2], - ); + let data = build_certificate_with_fields(&[0x00], b"", b"CHR", &[2, 5, 0, 1, 0, 1], &[2, 5, 0, 1, 0, 2]); assert!(CVCertificate::parse(&data).is_err()); } @@ -664,15 +685,13 @@ mod tests { #[test] fn reject_invalid_date_digit() { - let data = - build_certificate_with_fields(&[0x00], b"CAR", b"CHR", &[2, 5, 10, 1, 0, 1], &[2, 5, 0, 1, 0, 2]); + let data = build_certificate_with_fields(&[0x00], b"CAR", b"CHR", &[2, 5, 10, 1, 0, 1], &[2, 5, 0, 1, 0, 2]); assert!(CVCertificate::parse(&data).is_err()); } #[test] fn reject_invalid_month() { - let data = - build_certificate_with_fields(&[0x00], b"CAR", b"CHR", &[2, 5, 1, 3, 0, 1], &[2, 5, 0, 1, 0, 2]); + let data = build_certificate_with_fields(&[0x00], b"CAR", b"CHR", &[2, 5, 1, 3, 0, 1], &[2, 5, 0, 1, 0, 2]); assert!(CVCertificate::parse(&data).is_err()); } diff --git a/core-modules/asn1/src/lib.rs b/core-modules/asn1/src/lib.rs index d58b0634..4d0bb7b4 100644 --- a/core-modules/asn1/src/lib.rs +++ b/core-modules/asn1/src/lib.rs @@ -18,10 +18,10 @@ // // For additional notes and disclaimer from gematik and in case of changes by gematik, // find details in the "Readme" file. +pub mod cv_certificate; pub mod date_time; pub mod decoder; pub mod encoder; pub mod error; pub mod oid; pub mod tag; -pub mod cv_certificate; diff --git a/core-modules/asn1/src/spec/BSI_TR-03110_Part-3-V2_2_layout.txt b/core-modules/asn1/src/spec/BSI_TR-03110_Part-3-V2_2_layout.txt deleted file mode 100644 index 8bfbf1ef..00000000 --- a/core-modules/asn1/src/spec/BSI_TR-03110_Part-3-V2_2_layout.txt +++ /dev/null @@ -1,4985 +0,0 @@ -Technical Guideline TR-03110 - -Advanced Security Mechanisms for Machine -Readable Travel Documents and eIDAS Token – -Part 3: Common Specifications - -Version 2.21 -21. December 2016 - History -Version Date Comment -1.00 2006-02-08 Initial public version. -1.01 2006-11-02 Minor corrections and clarifications. -1.10 2007-08-20 Revised version. -1.11 2008-02-21 Minor corrections and clarifications. -2.00 2008-10-27 Enhanced version. -2.01 2009-05-05 Minor corrections and clarifications. Additional Mapping for PACE. -2.02 2009-11-09 Adjustments to PACE required due to international standardization. -2.03 2010-03-24 Clarification on the definition of a session. Standardization of domain - parameters. Introduction of a secondary security object. -2.04 2010-09-15 Clarifications on certificate extensions. Improved handling of chip-specific keys - for privileged terminals. -2.05 2010-10-14 Clarifications on RFU-bits, “Read access to eID” deprecated -2.10 2012-03-20 Split into three parts -2.11 2013-07-12 Minor clarifications, addition of Envelope/Get Response -2.20 2015-02-03 Enhanced version with additional mechanisms. Split into four parts. - -2.21 2016-12-21 Clarifications, minor corrections and optimizations. Simplification of - authorization handling. - - - - -Federal Office for Information Security -Post Box 20 03 63 -D-53133 Bonn - -Phone: +49 22899 9582-0 -E-Mail: ExtendedAccessControl@bsi.bund.de -Internet: https://www.bsi.bund.de -© Federal Office for Information Security 2016 - Contents - - - -Contents -1 Introduction.......................................................................................................................................................................................... 7 -1.1 Requirements for ICCs and Terminals............................................................................................................................... 7 -1.2 Cryptography requirements................................................................................................................................................... 7 -1.3 Terminology................................................................................................................................................................................... 8 -1.4 Abbreviations................................................................................................................................................................................. 8 -2 Public Key Infrastructure............................................................................................................................................................. 10 -2.1 Country Verifying CA.............................................................................................................................................................. 10 -2.2 Document Verifiers.................................................................................................................................................................. 11 -2.3 Card Verifiable Certificates.................................................................................................................................................... 11 -2.4 Certificate Scheduling............................................................................................................................................................. 11 -2.5 Certificate Validation............................................................................................................................................................... 12 -2.6 Initial State of the ICC's trust-point(s)............................................................................................................................. 14 -2.7 Effective Authorization.......................................................................................................................................................... 14 -2.8 Terminal Sector.......................................................................................................................................................................... 15 -3 Management of Attributes.......................................................................................................................................................... 19 -3.1 Specific Attributes..................................................................................................................................................................... 19 -3.2 Generic Attributes..................................................................................................................................................................... 20 -3.3 Attribute Requests.................................................................................................................................................................... 20 -A. ASN.1 Specifications (Normative)............................................................................................................................................. 22 -A.1. Information on Supported Security Protocols............................................................................................................ 22 -A.2. Key Agreement........................................................................................................................................................................... 41 -A.3. PACE................................................................................................................................................................................................ 46 -A.4. Chip Authentication................................................................................................................................................................ 48 -A.5. Restricted Identification........................................................................................................................................................ 50 -A.6. Pseudonymous Signatures.................................................................................................................................................... 51 -A.7. Terminal Authentication....................................................................................................................................................... 53 -A.8. Enhanced Role Authentication........................................................................................................................................... 60 -B. ISO 7816 Mapping (Normative)................................................................................................................................................. 61 -B.1. PACE................................................................................................................................................................................................ 61 -B.2. Chip Authentication................................................................................................................................................................ 62 -B.3. Terminal Authentication....................................................................................................................................................... 65 -B.4. Restricted Identification........................................................................................................................................................ 66 -B.5. Pseudonymous Signature of Messages or Credentials............................................................................................. 66 -B.6. Auxiliary Data Verification.................................................................................................................................................... 68 -B.7. PIN Management...................................................................................................................................................................... 68 -B.8. eSign Application...................................................................................................................................................................... 69 -B.9. Reading Data Groups............................................................................................................................................................... 69 -B.10. Enhanced Role Authentication........................................................................................................................................... 69 -B.11. Switching of Session Context.............................................................................................................................................. 71 -B.12. Extended Length....................................................................................................................................................................... 72 - -Bundesamt für Sicherheit in der Informationstechnik 3 - Inhaltsverzeichnis - - -B.13. Command Chaining................................................................................................................................................................ 72 -B.14. APDU Specification.................................................................................................................................................................. 73 -C. CV Certificates (normative).......................................................................................................................................................... 86 -C.1. Certificate Profile....................................................................................................................................................................... 86 -C.2. Certificate Requests.................................................................................................................................................................. 87 -C.3. Certificate Extensions for Terminal Authentication Version 2............................................................................89 -C.4. Certificate Policy........................................................................................................................................................................ 91 -D. DER Encoding (Normative)......................................................................................................................................................... 93 -D.1. ASN.1............................................................................................................................................................................................... 93 -D.2. Data Objects................................................................................................................................................................................. 93 -D.3. Public Key Data Objects......................................................................................................................................................... 96 -E. Envelope/Get Response (Normative)...................................................................................................................................... 98 -E.1. Envelope........................................................................................................................................................................................ 99 -E.2. Get Response............................................................................................................................................................................... 99 -F. Secure Messaging (Normative)................................................................................................................................................ 100 -F.1. Session.......................................................................................................................................................................................... 100 -F.2. Session Context....................................................................................................................................................................... 100 -F.3. Message Structure of Secure Messaging APDUs....................................................................................................... 100 -F.4. Cryptographic Algorithms................................................................................................................................................. 102 -F.5. Send Sequence Counter....................................................................................................................................................... 103 -F.6. Secure Messaging Termination........................................................................................................................................ 103 - - -List of Figures -Figure 1: Public Key Infrastructure....................................................................................................................................................... 10 -Figure 2: Certificate Scheduling.............................................................................................................................................................. 12 -Figure 3: Revocation..................................................................................................................................................................................... 17 -Figure 4: Transformation of a command APDU........................................................................................................................... 104 -Figure 5: Transformation of a command APDU if no data is available..............................................................................104 -Figure 6: Transformation of a response APDU.............................................................................................................................. 105 - - -List of Tables -Table 1: Key words........................................................................................................................................................................................... 8 -Table 2: Elementary Files CardAccess, CardSecurity and ChipSecurity...............................................................................37 -Table 3: Algorithms and Formats for Key Agreement.................................................................................................................. 41 -Table 4: Standardized Domain Parameters....................................................................................................................................... 42 -Table 5: Encoding of Passwords.............................................................................................................................................................. 45 -Table 6: Object Identifiers for PACE with DH................................................................................................................................... 46 -Table 7: Object Identifiers for PACE with ECDH............................................................................................................................. 46 -Table 8: Object Identifiers for Chip Authentication with DH................................................................................................... 48 -Table 9: Object Identifiers for Chip Authentication with ECDH.............................................................................................49 -Table 10: Object Identifiers for PSA based on ECSchnorr with ECDH..................................................................................50 -Table 11: Object Identifiers for Restricted Identification with DH.........................................................................................50 -Table 12: Object Identifiers for Restricted Identification with ECDH...................................................................................51 -Table 13: Object Identifiers for PSM and PSC based on ECSchnorr with ECDH..............................................................52 -Table 14: Credential data format for PSC........................................................................................................................................... 53 - - -4 Bundesamt für Sicherheit in der Informationstechnik - Contents - - -Table 15: Certificate Holder Reference................................................................................................................................................. 53 -Table 16: Elementary File EF.CVCA....................................................................................................................................................... 55 -Table 17: Object Identifiers for Terminal Authentication with RSA......................................................................................56 -Table 18: Object Identifiers for Terminal Authentication with ECDSA................................................................................57 -Table 19: Authenticated Auxiliary Data............................................................................................................................................... 58 -Table 20: Chip Authentication Version 3 - General Authenticate command for Key Agreement............................63 -Table 21: Chip Authentication Version 3 - General Authenticate command for PSA...................................................64 -Table 22: Pseudonymous Signature of Messages - PSO:Compute Digital Signature command..............................67 -Table 23: CV Certificate Profile................................................................................................................................................................ 86 -Table 24: CV Certificate Request Profile.............................................................................................................................................. 88 -Table 25: Certificate Extensions.............................................................................................................................................................. 89 -Table 26: Evolution of Authorization Extensions........................................................................................................................... 90 -Table 27: Overview on Data Objects (sorted by Tag)...................................................................................................................... 93 -Table 28: ISO/IEC 8859-1 Character Set.............................................................................................................................................. 95 -Table 29: RSA Public Key............................................................................................................................................................................ 96 -Table 30: DH Public Key.............................................................................................................................................................................. 97 -Table 31: EC Public Keys............................................................................................................................................................................. 97 -Table 32: Usage of Secure Messaging Data Objects...................................................................................................................... 101 - - - - -Bundesamt für Sicherheit in der Informationstechnik 5 - Introduction 1 - - - -1 Introduction -This Part of the Technical Guideline gives the common specifications, comprising the PKI used for -Access Control as well as a mapping of the protocols to ASN.1- and APDU-specifications, for the -protocols defined in Part 1 and Part 2: - • Part 1: - ◦ Terminal Authentication version 1 - ◦ Chip Authentication version 1 - • Part 2: - ◦ Password Authenticated Connection Establishment (PACE) - ◦ Chip Authentication version 2 - ◦ Chip Authentication version 3 - ◦ Terminal Authentication version 2 - ◦ Restricted Identification - ◦ Pseudonymous Signature -Although the specifications of PACEv2 in [8] are compatible to the specifications in this document, -please refer to [8] for an implementation of PACE according to Part 1. -In this Technical Guideline, documents which only implement the protocols described in Part 1 of this -Guideline are designated “MRTDs”, while documents implementing protocols from Part 2 or from both -Parts are designated “eIDAS token”. - - -1.1 Requirements for ICCs and Terminals -This Technical Guideline specifies requirements for implementations of ICCs and terminals. While ICCs -must comply with those requirements according to the terminology described in Section 1.3, -requirements for terminals are to be interpreted as guidance, i.e. interoperability of ICC and terminal -are only guaranteed if the terminal complies with those requirements, otherwise the interaction with -the ICC will either fail or the behavior of the ICC is undefined. In general, the ICC need not enforce -requirements related to terminals unless the security of the ICC is directly affected. - - -1.2 Cryptography requirements -This Technical Guideline specifies objects identifiers of the protocols for different cryptographic -parameters. Furthermore, this Technical Guideline defines IDs for different domain parameters that can -be used within the protocols. -It should be noted that the selection of suitable key lengths is up to the document issuer and not within -the scope of this Technical Guideline. Suitable standards and algorithm catalogues from IT security -authorities should be taken into account for selection of appropriate algorithms and key lengths. -Guidance on suitable cryptographic algorithms may also be found in [28]. - - - - -Bundesamt für Sicherheit in der Informationstechnik 7 - 1 Introduction - - - -1.3 Terminology -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD -NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described -in RFC 2119 [2]. The key word "CONDITIONAL" is to be interpreted as follows: -CONDITIONAL: The usage of an item is dependent on the usage of other items. It is therefore further - qualified under which conditions the item is REQUIRED or RECOMMENDED. -When used in tables (profiles), the key words are abbreviated as shown in Table 1. - - Key word Abbrev. - MUST / SHALL REQUIRED m - MUST NOT / SHALL NOT – x - SHOULD RECOMMENDED r - MAY OPTIONAL o - – CONDITIONAL c - Table 1: Key words - - - - -1.4 Abbreviations -The following abbreviations are commonly used throughout this specification. - Name Abbreviation - Binary Coded Digit BCD - Card Verifiable CV - Card/Chip Security Object SO C - - Certification Authority CA - Chip Identifier ID ICC - Chip Authentication Public Key PK ICC - Chip Authentication Private Key SK ICC - Country Signing CA CSCA - Country Verifying CA CVCA - Country Verifying CA Certificate C CVCA - Document Security Object SO D - Data Group DG - Document Verifier DV - Document Verifier Certificate C DV - Domain Parameters D - Ephemeral Private Key  - SK - Ephemeral Public Key  - PK - - - -8 Bundesamt für Sicherheit in der Informationstechnik - Introduction 1 - - - Name Abbreviation - Hash Function H - International Civil Aviation Organization ICAO - Key Agreement Function KA - Key Derivation Function KDF - Logical Data Structure LDS - Machine Readable Travel Document MRTD - Proximity Integrated Circuit Chip PICC - Proximity Coupling Device PCD - Restricted Identification Public Key PK ID - Restricted Identification Private Key SK ID - Sector Public Key PK Sector - Sector Private Key SK Sector - Sector - Sector-specific Identifier I ID - Terminal Authentication Public Key PK PCD - Terminal Authentication Private Key SK PCD - Terminal Certificate CT - Pseudonymous Signature Group Public Key PK ICC - Pseudonymous Signature Individual Public Keys PK ICC ,1, PK ICC ,2 - Pseudonymous Signature Sector-specific Identifier I Sector - ICC ,i - - Identifier of the Pseudonymous Signature variant ID DSI - - - - -Bundesamt für Sicherheit in der Informationstechnik 9 - 2 Public Key Infrastructure - - - -2 Public Key Infrastructure -Terminal Authentication requires the terminal to prove to the ICC that it is entitled to access sensitive -data. Such a terminal is equipped with at least one Terminal Certificate, encoding the terminal’s public -key and access rights, and the corresponding private key. After the terminal has proven knowledge of -this private key, the ICC grants the terminal access to sensitive data as indicated in the Terminal -Certificate. -The PKI required for issuing and validating Terminal Certificates consists of the following entities: - 1. Country Verifying CAs (CVCAs) - 2. Document Verifiers (DVs) - 3. Terminals -This PKI forms the basis of Extended Access Control and is also abbreviated by EAC-PKI. It is illustrated -in Figure 1. - - -2.1 Country Verifying CA -Every State is required to set up one trust-point that issues Document Verifier Certificates: the Country -Verifying CA (CVCA). - -Note: The Country Signing CA issuing certificates for Document Signers (cf. [8]) and the Country -Verifying CA MAY be integrated into a single entity, e.g. a Country CA. However, even in this case, -separate key pairs MUST be used for different roles. -A CVCA determines the access rights to national ICCs for all DVs (i.e. official domestic DVs as well as the -foreign/commercial DVs) by issuing certificates for DVs entitled to access some sensitive data. The -conditions under which a CVCA grants a DV access to sensitive data is out of the scope of this -document and SHOULD be stated in a certificate policy (cf. Appendix C.4). -Document Verifier Certificates MUST contain information, such as which data a certain DV is entitled -to access. To diminish the potential risk introduced by lost or stolen terminals Document Verifier - - Country A Country B - - DV-Cert. Assigns: - CVCA - Access Rights - - Validity Period - CVCA - - - - - Term.-Cert. restricts: - DV DV - Access Rights - - Validity Period - DV DV - - - Term. ... Term. Term. ... Term. Term. ... Term. Term. ... Term. - - Arrows denote certification - - Figure 1: Public Key Infrastructure - - -10 Bundesamt für Sicherheit in der Informationstechnik - Public Key Infrastructure 2 - - -Certificates MUST contain a short validity period. The validity period is assigned by the issuing CVCA at -its own choice and this validity period may differ depending on the Document Verifier the certificate is -issued to. - - -2.2 Document Verifiers -A Document Verifier (DV) is an organizational unit that manages a group of terminals (e.g. terminals -operated by a State’s border police) by – inter alia – issuing Terminal Certificates. A Document Verifier is -therefore a CA, authorized by at least the national CVCA to issue certificates for its terminals. The -Terminal Certificates issued by a DV usually inherit both the access rights and the validity period from -the Document Verifier Certificate, however, the Document Verifier MAY choose to further restrict the -access rights or the validity period depending on the terminal the certificate is issued for. -If a Document Verifier requires its terminals to access sensitive data stored on other States’ ICCs, it -MUST apply for a DV Certificate issued by the CVCA of the respective States. The Document Verifier -MUST also ensure that all received Document Verifier Certificates are forwarded to the terminals within -its domain. - - -2.3 Card Verifiable Certificates -CVCA Link Certificates, DV Certificates, and Terminal Certificates are to be validated by ICCs. Due to the -computational restrictions of those chips, the certificates MUST be in a card verifiable format: - • The certificate format and profile specified in Appendix C.1 SHALL be used. - • The signature algorithm, domain parameters, and key sizes to be used are determined by the - CVCA of the issuing State, i.e. the same signature algorithm, domain parameters and key sizes - MUST be used within a certificate chain.1 - • CVCA Link Certificates MAY include a public key that deviates from the current parameters, i.e. - the CVCA MAY switch to a new signature algorithm, new domain parameters, or key sizes. - - -2.4 Certificate Scheduling -Each certificate MUST contain a validity period. This validity period is identified by two dates, the -certificate effective date and the certificate expiration date. -Certificate Effective Date: The certificate effective date SHALL be the date of the certificate generation. -Certificate Expiration Date: The certificate expiration date SHALL be the date after which the -certificate expires. It may be arbitrarily chosen by the certificate issuer. -When generating certificates, the issuer MUST carefully plan the roll-over of certificates, as sufficient -time for propagation of certificates and set up of certificate chains MUST be provided. Obviously, a new -certificate must be generated before the current certificate expires. To realize the link of trust between -consecutive CVCA certificates, CVCA Link Certificates have to be produced. CVCA Link Certificates -MUST be signed with the previous CVCA key, i.e. the CVCA key with the most recent effective date. -In each case, the resulting maximum distribution time equals the certificate expiration date of the old -certificate minus the certificate effective date of the new certificate. For the application and - - -1 As a consequence Document Verifiers and terminals will have to be provided with several key pairs. - -Bundesamt für Sicherheit in der Informationstechnik 11 - 2 Public Key Infrastructure - - -distribution of certificates, the communication protocols specified in TR-03129 [3] are -RECOMMENDED. Certificate scheduling is illustrated in Figure 2. - - Certificate effective date - Certificate expiration date - - - CVCA - - - - Max. distribution time - - - - - DV - - - - - Terminal - - - - - Figure 2: Certificate Scheduling - - -2.5 Certificate Validation -To validate a Terminal Certificate, the ICC MUST be provided with a certificate chain starting at a -trust-point stored on the ICC. Those trust-points are more or less recent public keys of the ICC’s CVCA. -The initial trust-point(s) SHALL be stored securely in the ICC’s memory in the production or (pre-) -personalization phase. -As the key pair used by the CVCA changes over time, the ICC is REQUIRED to internally update its -trust-point(s) according to received valid link certificates. -The ICC MUST be able to store up to two trust-points per application. - -Note: Due to the scheduling of CVCA Link Certificates (cf. Figure 2), at most two trust-points per -application need to be stored on the ICC. -The ICC MUST accept expired CVCA Link Certificates but it MUST NOT accept expired DV and -Terminal Certificates. To determine whether a certificate is expired, the ICC SHALL use its current date. -Current Date: If the ICC has no internal clock, the current date of the ICC SHALL be approximated as -described in the following. The date is autonomously approximated by the ICC using the most recent -certificate effective date contained in a valid CVCA Link Certificate, a DV Certificate or an Accurate -Terminal Certificate. - -12 Bundesamt für Sicherheit in der Informationstechnik - Public Key Infrastructure 2 - - -Accurate Terminal Certificate: A Terminal Certificate is accurate, if the issuing Document Verifier is -trusted by the ICC to produce Terminal Certificates with the correct certificate effective date. A valid -Terminal Certificate MUST be accepted as accurate by the ICC if it was issued by an official domestic DV -and SHOULD NOT be accepted as accurate otherwise. -A terminal MAY send CVCA Link Certificates, DV Certificates, and Terminal Certificates to an ICC to -update the current date and the trust-point stored on the ICC even if the terminal does not intend to or -is not able to continue with Terminal Authentication. - -Note: The ICC only verifies that a certificate is apparently recent (i.e. with respect to the approximated -current date). - - -2.5.1 General Procedure -The certificate validation procedure consists of three steps: - 1. Certificate Verification: The signature MUST be valid and unless the certificate is a CVCA Link - Certificate, the certificate MUST NOT be expired. If the verification fails, the procedure SHALL - be aborted. - 2. Internal Status Update: The current date MUST be updated, the public key and the attributes - (including relevant certificate extensions) MUST be imported, new trust-points MUST be - enabled, expired trust-points MUST be disabled for the verification of DV Certificates. - 3. Cleanup: The chip SHALL provide at most two enabled trust-points per application. If more - than two trust-points for an application remain enabled after the internal status update, the - trust-point with the least recent effective date SHALL be disabled. -The operation of updating the current date and the operations of enabling and disabling a trust-point -MUST be implemented as an atomic operation. -Enabling a trust-point: The new trust-point SHALL be added to the list of trust-points. -Disabling a trust-point: Expired trust-points MUST NOT be used for the verification of DV Certificates. - In case of ICCs where the current date may be advanced beyond the expiry date of a trust-point, e.g. - ICCs with more than one application or ICCs using an internal clock, expired trust-points MUST - remain usable for the verification of CVCA Link Certificates. Disabled trust-points MAY be deleted - after the successful import of the successive Link Certificate. - -Note: In case of single-application ICCs with no internal clock, the above specification is equivalent to -the specification in version 1.11 of this Guideline. - - -2.5.2 Example Procedure -The following validation procedure, provided as an example, MAY be used to validate a certificate chain. -For each received certificate the ICC performs the following steps: - 1. The ICC verifies the signature on the certificate. If the signature is incorrect, the verification - fails. - 2. If the certificate is not a CVCA Link Certificate, the certificate expiration date is compared to the - ICC’s current date. If the expiration date is before the current date, the verification fails. - 3. The certificate is accepted as valid and the public key and the attributes (including relevant - certificate extensions) contained in the certificate are imported. - - -Bundesamt für Sicherheit in der Informationstechnik 13 - 2 Public Key Infrastructure - - - i For CVCA, DV, and Accurate Terminal Certificates: The certificate effective date is compared to - the ICC’s current date. If the current date is before the effective date, the current date is - updated to the effective date. - ii For CVCA Link Certificates: The new CVCA public key is added to the list of trust-points stored - securely in the ICC’s memory. The new trust-point is then enabled. - iii For DV and Terminal Certificates: The new DV or terminal public key is temporarily imported - for subsequent certificate verification or Terminal Authentication, respectively. - 4. Expired trust-points stored securely in the ICC’s memory are disabled for the verification of DV - Certificates and may be removed from the list of trust-points. - - -2.6 Initial State of the ICC's trust-point(s) -The (pre-)personalization agent SHALL - • set the current date of the ICC to the date of the (pre-)personalization, and - • personalize the CVCA key with the most recent effective date as trust-point. -The (pre-)personalization agent MAY additionally personalize the previous CVCA key as trust-point. - - -2.7 Effective Authorization -Each certificate SHALL contain a Certificate Holder Authorization Template (CHAT) (cf. Appendix C.1.5) -and MAY contain Authorization Extensions (cf. Appendix C.3.1). - • The Certificate Holder Authorization Template identifies the terminal type (cf. Parts 1 and 2 of - this Technical Guideline). - • The Certificate Holder Authorization Template and the Authorization Extensions determine the - relative authorization of the certificate holder assigned by the issuing certificate authority. -To determine the effective authorization of a certificate holder, the ICC MUST perform the following: - 1. If an Authorization Extension supported by the ICC is missing in a certificate of the certificate - chain, the corresponding relative authorization of the certificate holder SHALL be set all to '0' - for calculation of the effective authorization. - 2. For the CHAT and for each supported Authorization Extension, the ICC MUST calculate a - bitwise Boolean ’and’ of the relative authorization contained in the Terminal Certificate, the - referenced Document Verifier Certificate, and the referenced CVCA Certificate. - - -2.7.1 Confined Authorization (eIDAS token only) -The effective authorization may be further restricted by using the General Authentication Procedure -(cf. Part 2 of this Technical Guideline). In this case, the terminal performing the General Authentication -Procedure (cf. Part 2) MUST indicate the terminal type and the confined authorization (i.e. the effective -authorization required by the terminal) as part of PACE. If the ICC supports Authorization Extensions, -the confined authorization SHALL include the relevant Authorization Extensions of the Terminal -Certificate. Otherwise, the Authorization Extension SHALL be omitted by the terminal. -The confined authorization SHALL be used by the ICC to compute the effective authorization as part of -Terminal Authentication of the General Authentication Procedure phase (i.e. the first Terminal - -14 Bundesamt für Sicherheit in der Informationstechnik - Public Key Infrastructure 2 - - -Authentication of a session). For that purpose, the ICC SHALL include the confined authorization by -calculating a bitwise Boolean ’and’ in step 2. of Section 2.7 for the computation of the effective -authorization. -If switching of session contexts is supported and Terminal Authentication is performed as part of -Enhanced Role Authentication, the confined authorization SHALL be omitted by the ICC to compute -the effective authorization of an Attribute Provider. - -Note: The ICC MUST verify that the terminal type indicated in the confined authorization and the -terminal type in the relative authorization of each certificate of the certificate chain are equal. If a -mismatch is detected, the ICC SHALL reset the access rights and indicate an error (cf. Appendix B.14.7). - - -2.7.2 Interpretation (all document types) -The effective authorization SHALL be interpreted by the ICC as follows: - • The effective role is a CVCA: - ◦ This link certificate was issued by the national CVCA. - ◦ The ICC MUST update its internal trust-point, i.e. the public key and the relative - authorization. - ◦ The certificate issuer is a trusted source of time. If the ICC has no internal clock, the ICC - MUST update its current date using the Certificate Effective Date. - ◦ The ICC MUST NOT grant the CVCA access to sensitive data (i.e. the effective authorization - SHOULD be ignored). - • The effective role is a DV: - ◦ The certificate was issued by the national CVCA for an authorized DV. - ◦ The certificate issuer is a trusted source of time. If the ICC has no internal clock, the ICC - MUST update its current date using the Certificate Effective Date. - ◦ The ICC MUST NOT grant a DV access to sensitive data (i.e. the effective authorization - SHOULD be ignored). - • The effective role is a Terminal: - ◦ The certificate was issued by either an official domestic, a foreign, or a non-official DV. - ◦ If the certificate is an accurate terminal certificate (cf. Section 2.5), the issuer is a trusted - source of time. If the ICC has no internal clock, the ICC MUST update its current date using - the Certificate Effective Date. - ◦ The ICC MUST grant the authenticated terminal access to sensitive data according to the - effective authorization. - - -2.8 Terminal Sector -To support - • Restricted Identification - • Pseudonymous Signatures - • Enhanced Role Authentication - -Bundesamt für Sicherheit in der Informationstechnik 15 - 2 Public Key Infrastructure - - -terminals MUST be assigned a Terminal Sector. The Terminal Sector SHALL be contained in the -Terminal Certificate and thus, it is RECOMMENDED that the Terminal Sector is generated by the -certifying Document Verifier. In any case, the Terminal Sector MUST NOT be chosen by the terminal -itself. -The Terminal Sector is always a public key. It MAY be chosen either verifiably at random with an -unknown private key to disable tracing completely (in this case linking sector-specific identifiers across -sectors is computationally impossible) or as key pair to enable revocation based on sector-specific -identifiers. -The definition of a Sector is up to the policy of the Issuer of the ICC. - - -2.8.1 Sector Key Pair -Sector Key Pairs MUST be generated by all Document Verifiers that support sector-specific revocation -of ICCs. -Each Document Verifier SHALL perform the following steps for every subordinated sector: - 1. Generate a new Sector Key Pair based on the Revocation Sector Public Key. - 2. Store the Sector Private Key securely (at the Document Verifier). - 3. Include the Sector Public Key in every Terminal Certificate of all terminals belonging to the - corresponding sector. -The Revocation Sector Key Pair SHALL be generated by the CVCA. The CVCA MAY delegate the -revocation service to a service provider. - - -2.8.2 Sector-Specific Revocation of ICCs -At the (pre-) personalization of the ICC, a key pair for Restricted Identification SHALL be generated. For -Chip Authentication version 3, the ICC's private key is part of the ICC's private keys for Chip -Authentication Version 3 or Pseudonymous Signatures described in A.4.2.1. -The private key SHALL be stored in the ICC. If the public key is used to enable revocation of the ICC (i.e. -PK ID for Restricted Identification or PK ICC ,i for Pseudonymous Signatures), the public key SHALL be -stored in a database together with other data identifying the holder of the MRTD . - -Note: The generation of the key pair for Restricted Identification MAY be performed within the ICC or -externally. The key pair MUST be chosen to be unique and MAY be either chip-specific or -holder-specific (i.e. the same key pair will be used on subsequent ICCs). At least one key pair used for -Restricted Identification MUST be chip-specific. -To revoke the ICC, the chip-specific public key of the ICC is looked up in the database and transferred to -the CVCA. The CVCA then transforms the public key using its Revocation Sector Private Key. The -transformed public key is then transferred to all subordinated Document Verifiers. Each Document -Verifier calculates the sector-specific identifiers using the Sector Private Keys for all subordinated -Terminal Sectors. Finally, the sector-specific identifier is transferred to all terminals of the -corresponding sector. - - - - -16 Bundesamt für Sicherheit in der Informationstechnik - Public Key Infrastructure 2 - - - - - Figure 3: Revocation - - -2.8.3 Generation of Revocation Lists -The CVCA publishes the Revocation Sector Public Key PK Revocation and the domain parameters D . Each -Document Verifier randomly chooses a Sector Private Key SK Sector for every subordinated sector and -calculates the Sector Public Key as PK Sector =KA SK Sector , PK Revocation , D. -To revoke an ICC, a revocation request is sent to the CVCA containing the Restricted Identification - PK ID or Pseudonymous Signature Public Key PK ID := PK ICC , i . The sector-specific identities are -calculated as follows: - Revocation - 1. The CVCA calculates PK ID =KA  SK Revocation , PK ID , D using its private key SK Revocation and - the Restricted Identification Public Key PK ID received with the revocation request. The - Revocation - transformed public key PK ID is forwarded to all subordinated Document Verifiers. - 2. Each Document Verifier calculates the sector-specific identifier for all subordinated sectors. For each - Sector - sector the Document Verifier calculates I ID =F(KA (SK Sector , PK Revocation - ID , D)) using the - Revocation - corresponding Sector Private Key SK Sector , the received public key PK ID of the ICC to be - revoked and the hash function of the protocol object identifier as F for Restricted Identification - sector-specific identifiers or identity function as F for Pseudonymous Signature sector-specific - Sector - identifiers. The sector-specific identifier I ID is then forwarded to the terminals of the - corresponding sector. - - -Bundesamt für Sicherheit in der Informationstechnik 17 - 2 Public Key Infrastructure - - -2.8.4 Sector-specific Whitelisting of ICCs -The sector-specific identifiers generated with Chip Authentication version 3 or Pseudonymous -Signatures can also be used for the generation of Whitelists. In this case, the same procedure as for -revoking ICC's is performed with the generated ICCs. If an ICC is revoked, the corresponding -sector-specific identifier SHALL be deleted from the Whitelist. - - -2.8.5 Validity Period -In contrast to the Terminal Key Pair (for Terminal Authentication), the Sector Key Pair is valid for a long -time and MUST be chosen appropriately. - - -2.8.6 Migrating Terminals -To migrate a terminal from one Document Verifier to another Document Verifier, the sector key pair of -the terminal MUST be transferred securely to the new Document Verifier. - -Note: Migrating a terminal to a Document Verifier supervised by another CVCA is not possible. - - - - -18 Bundesamt für Sicherheit in der Informationstechnik - Management of Attributes 3 - - - -3 Management of Attributes -Enhanced Role Authentication (if supported by the ICC) enables Attribute Terminals manage additional -attributes on the ICC. -Management of attributes consists of the following functions: - • Requesting Attributes - • Reading Attribute Requests - • Writing Attributes - • Reading Attributes - • Deleting Attributes -The following classes of attributes are defined: - • Specific Attributes - • Generic Attributes - - -3.1 Specific Attributes -Specific Attributes are attributes that are stored in data containers, each bijectively linked to the hash of -a Sector Public Key contained in the Terminal Sector as defined in C.3.2.1 of requesting terminal's CV -Certificate. -The ASN.1 structure for Specific Attributes is specified in A.8.2. Commands for management of Specific -Attributes are specified in Appendix B. -Data containers nest data and their corresponding security attributes. However, the inherent structure -of data containers is out of scope of this document, i.e. containers can be files of self-controlled data -objects. -If the ICC supports Specific Attributes, it MUST also support Attribute Requests. - - -3.1.1 Reading and deleting Specific Attributes -The ICC SHALL restrict read and delete access to Specific Attribute containers to authenticated -terminals with the corresponding access right of the terminal. -If the terminal has effective authorization for reading/deleting Specific Attributes of all Terminal -Sectors, the ICC SHALL grant access to all Specific Attribute containers and MUST respond/delete all -Specific Attributes upon request of the terminal. -If the terminal's effective authorization is restricted to reading/deleting of Specific Attributes linked to -the hash of a Sector Public Key of the terminal's CV Certificate, the following steps MUST be performed -to read/delete Specific Attributes: - • The terminal MUST present the hash of its Sector Public Key to be used as user ID to the ICC. - • The ICC MUST verify that the hash of the Sector Public Key is contained in the Terminal Sector - of the terminal's CV Certificate sent during Terminal Authentication. - - - - -Bundesamt für Sicherheit in der Informationstechnik 19 - 3 Management of Attributes - - - • If the verification was successful, the ICC SHALL grant read/delete access to the Specific - Attribute container linked to the terminal's presented user ID and MUST respond/delete the - Specific Attributes upon request of the terminal. -If the terminal has no effective authorization for reading/deleting Specific Attributes, the ICC SHALL -NOT grant access to read/delete Specific Attributes. - - -3.1.2 Writing Specific Attributes -The ICC SHALL restrict read access to the Attribute Request container and write access to a Specific -Attribute container to authenticated terminals with the corresponding effective authorization -(Attribute Provider). -If no Attribute Request is present on the ICC, writing Specific Attribute MUST be denied by the ICC. If -the terminal writes a Specific Attribute to the ICC, the attribute MUST be added to the data container -that is linked to the user ID of the Attribute Request. - -Note: In order to avoid that single data containers take too much storage on the ICC, it can be advisable -to limit the maximum size of a data container taking into account the expected number and sizes of -relevant Specific Attributes. - - -3.2 Generic Attributes -Generic Attributes are attributes that are not linked to the Terminal Sector of the requesting terminal. -Each Generic Attribute is stored in a file, identified by a file identifier. -The ICC SHALL restrict read or write access or deletion of Generic Attributes to authenticated terminals -with the corresponding effective authorization. -If the ICC supports Generic Attributes, it MAY also support Attribute Requests. The ICC SHOULD allow -writing of Generic Attributes without Attribute Request stored on the ICC. -A Logical Data Structure and access rights for Generic Attributes are described in Part 4 of this Technical -Guideline. Commands for the management of Generic Attributes are specified in Appendix B. - - -3.3 Attribute Requests -If a terminal needs additional attributes not available on the ICC, it MAY write an Attribute Request to -the ICC. Attribute Requests are stored in a particular Attribute Request container. -Writing of Attribute Requests SHALL be restricted to authenticated terminals with the effective -authorization for writing Attribute Requests. -The following steps MUST be performed to write an Attributes Request on the ICC: - • The terminal SHALL present the hash of the Sector Public Key to be used as user ID to the ICC. - • The ICC MUST verify that the hash of the Sector Public Key Data is contained in the Terminal - Sector of the terminal's CV Certificate sent during Terminal Authentication. If the verification - was successful, the ICC SHALL grant write access to the Attribute Request container. - • The terminal MAY store an Attribute Request to the ICC's Attribute Request container. The ICC - SHALL make an internal link between the Attribute request and the user ID of the requesting - terminal. - -20 Bundesamt für Sicherheit in der Informationstechnik - Management of Attributes 3 - - -Reading of Attribute Requests SHALL be restricted to authenticated terminals with the effective -authorization for reading Attribute Requests. A terminal with effective authorization MAY read an -Attribute Request stored on the ICC (without presentation of its user ID). -The ICC SHALL provide only one data container for storage of Attribute Requests that must be shared -by all terminals. If a previous request is already stored on the ICC, the stored Attribute Request MUST be -replaced with the new one, i.e. the previous request is deleted. -The ASN.1 structure to be used for Attribute Requests is defined in Appendix A.8.1. - - - - -Bundesamt für Sicherheit in der Informationstechnik 21 - A. ASN.1 Specifications (Normative) - - - -A. ASN.1 Specifications (Normative) -The object identifiers used in this Technical Guideline are contained in the subtree of bsi-de: - bsi-de OBJECT IDENTIFIER ::= { - itu-t(0) identified-organization(4) etsi(0) - reserved(127) etsi-identified-organization(0) 7 - } - - -A.1. Information on Supported Security Protocols -The ASN.1 data structure SecurityInfos SHALL be provided by the ICC to indicate supported -security protocols. The data structure is specified as follows: - SecurityInfos ::= SET OF SecurityInfo - - SecurityInfo ::= SEQUENCE { - protocol OBJECT IDENTIFIER, - requiredData ANY DEFINED BY protocol, - optionalData ANY DEFINED BY protocol OPTIONAL - } - -The elements contained in a SecurityInfo data structure have the following meaning: - • The object identifier protocol identifies the supported protocol. - • The open type requiredData contains protocol specific mandatory data. - • The open type optionalData contains protocol specific optional data. - - -A.1.1. Supported Protocols -The ASN.1 specifications for the protocols provided in this specification are described in the following. - -Note: ICCs implemented according to Version 1.0.x of this specification will only provide a -ChipAuthenticationPublicKeyInfo. -In this case, the terminal SHOULD assume the following: - • The ICC supports Chip Authentication in version 1. - • The ICC may support Terminal Authentication in version 1. -To determine whether or not sensitive data protected by Terminal Authentication is stored on the -ICC, the terminal may consult the Document Security Object and the elementary file EF.CVCA. -A.1.1.1. PACE -To indicate support for PACE SecurityInfos may contain the following entries: - • At least one PACEInfo using a standardized domain parameter MUST be present. - • For each supported set of explicit domain parameters a PACEDomainParameterInfo MUST - be present. - • For each supported global user credential, a PasswordInfo MAY be present. -PACEInfo: This data structure provides detailed information on an implementation of PACE. - -22 Bundesamt für Sicherheit in der Informationstechnik - ASN.1 Specifications (Normative) A. - - - • The object identifier protocol SHALL identify the algorithms to be used (i.e. key agreement, - symmetric cipher and MAC). - • The integer version SHALL identify the version of the protocol. Version 1 is deprecated and it - is RECOMMENDED to only use version 2. - • The integer parameterId is used to indicate the domain parameter identifier. It MUST be - used if the ICC uses standardized domain parameters (cf. Table 4) or provides multiple explicit - domain parameters for PACE. - id-PACE OBJECT IDENTIFIER ::= { - bsi-de protocols(2) smartcard(2) 4 - } - - id-PACE-DH-GM OBJECT IDENTIFIER ::= {id-PACE 1} - id-PACE-DH-GM-3DES-CBC-CBC OBJECT IDENTIFIER ::= {id-PACE-DH-GM 1} - id-PACE-DH-GM-AES-CBC-CMAC-128 OBJECT IDENTIFIER ::= {id-PACE-DH-GM 2} - id-PACE-DH-GM-AES-CBC-CMAC-192 OBJECT IDENTIFIER ::= {id-PACE-DH-GM 3} - id-PACE-DH-GM-AES-CBC-CMAC-256 OBJECT IDENTIFIER ::= {id-PACE-DH-GM 4} - - id-PACE-ECDH-GM OBJECT IDENTIFIER ::= {id-PACE 2} - id-PACE-ECDH-GM-3DES-CBC-CBC OBJECT IDENTIFIER ::= {id-PACE-ECDH-GM 1} - id-PACE-ECDH-GM-AES-CBC-CMAC-128 OBJECT IDENTIFIER ::= {id-PACE-ECDH-GM 2} - id-PACE-ECDH-GM-AES-CBC-CMAC-192 OBJECT IDENTIFIER ::= {id-PACE-ECDH-GM 3} - id-PACE-ECDH-GM-AES-CBC-CMAC-256 OBJECT IDENTIFIER ::= {id-PACE-ECDH-GM 4} - - id-PACE-DH-IM OBJECT IDENTIFIER ::= {id-PACE 3} - id-PACE-DH-IM-3DES-CBC-CBC OBJECT IDENTIFIER ::= {id-PACE-DH-IM 1} - id-PACE-DH-IM-AES-CBC-CMAC-128 OBJECT IDENTIFIER ::= {id-PACE-DH-IM 2} - id-PACE-DH-IM-AES-CBC-CMAC-192 OBJECT IDENTIFIER ::= {id-PACE-DH-IM 3} - id-PACE-DH-IM-AES-CBC-CMAC-256 OBJECT IDENTIFIER ::= {id-PACE-DH-IM 4} - - id-PACE-ECDH-IM OBJECT IDENTIFIER ::= {id-PACE 4} - id-PACE-ECDH-IM-3DES-CBC-CBC OBJECT IDENTIFIER ::= {id-PACE-ECDH-IM 1} - id-PACE-ECDH-IM-AES-CBC-CMAC-128 OBJECT IDENTIFIER ::= {id-PACE-ECDH-IM 2} - id-PACE-ECDH-IM-AES-CBC-CMAC-192 OBJECT IDENTIFIER ::= {id-PACE-ECDH-IM 3} - id-PACE-ECDH-IM-AES-CBC-CMAC-256 OBJECT IDENTIFIER ::= {id-PACE-ECDH-IM 4} - - PACEInfo ::= SEQUENCE { - protocol OBJECT IDENTIFIER( - id-PACE-DH-GM-3DES-CBC-CBC | - id-PACE-DH-GM-AES-CBC-CMAC-128 | - id-PACE-DH-GM-AES-CBC-CMAC-192 | - id-PACE-DH-GM-AES-CBC-CMAC-256 | - id-PACE-ECDH-GM-3DES-CBC-CBC | - id-PACE-ECDH-GM-AES-CBC-CMAC-128 | - id-PACE-ECDH-GM-AES-CBC-CMAC-192 | - id-PACE-ECDH-GM-AES-CBC-CMAC-256 | - id-PACE-DH-IM-3DES-CBC-CBC | - id-PACE-DH-IM-AES-CBC-CMAC-128 | - id-PACE-DH-IM-AES-CBC-CMAC-192 | - id-PACE-DH-IM-AES-CBC-CMAC-256 | - id-PACE-ECDH-IM-3DES-CBC-CBC | - id-PACE-ECDH-IM-AES-CBC-CMAC-128 | - id-PACE-ECDH-IM-AES-CBC-CMAC-192 | - id-PACE-ECDH-IM-AES-CBC-CMAC-256), - version INTEGER, -- SHOULD be 2 - parameterId INTEGER OPTIONAL - } - - -Bundesamt für Sicherheit in der Informationstechnik 23 - A. ASN.1 Specifications (Normative) - - - -PACEDomainParameterInfo: This data structure provides one set of explicit domain parameters for -PACE of the ICC. - • The object identifier protocol SHALL identify the type of the domain parameters (i.e. DH or - ECDH). - • The sequence domainParameter SHALL contain the domain parameters. - • The integer parameterId MAY be used to indicate the local domain parameter identifier. It MUST - be used if the ICC provides multiple explicit domain parameters for PACE. - PACEDomainParameterInfo ::= SEQUENCE { - protocol OBJECT IDENTIFIER( - id-PACE-DH-GM | - id-PACE-ECDH-GM | - id-PACE-DH-IM | - id-PACE-ECDH-IM), - domainParameter AlgorithmIdentifier, - parameterId INTEGER OPTIONAL - } - -PasswordInfo: This data structure provides information about the passwords supported by the ICC 2. - • The object identifier protocol SHALL identify the password. - • The integer pwdId SHALL contain the identifier of the password. - • If optionalPwdData is present, the bit string pwdFlags SHALL be used to indicate whether - the password is - ◦ local, meaning that the password is a local password, i.e. a password specific to a - particular application, - ◦ unblocks-others, meaning that the password may be used to unblock other passwords, - ◦ is-blocking, meaning that the password has a retry counter and is blocked if the counter - has reached the value RC=0. - ◦ is-suspending, meaning that the password has to be resumed before usage if the retry - counter has reached the value RC=1, - ◦ limited-resetUT, meaning that the password is assigned with a reset counter for - unauthenticated terminals, - ◦ unblock-allowedUT, meaning that if the password is blocked and the reset counter is - non-zero, it may be unblocked by an unauthenticated terminal, - ◦ unblock-allowedAT, meaning that if the password is blocked and the reset counter is - non-zero, it may be unblocked by an authenticated terminal with effective authorization for - PIN management, - ◦ change-allowedUT, meaning that the password may be changed by an unauthenticated - terminal, - ◦ change-allowedAT, meaning that the password may be changed by an authenticated - terminal with effective authorization for PIN management,. - ◦ activation-allowedAT, meaning that the password may be activated (if deactive) by an - authenticated terminal with effective authorization for PIN management, - -2 The data structure is designed to allow the description of various passwords, not necessarily specified within - this Technical Guideline. - -24 Bundesamt für Sicherheit in der Informationstechnik - ASN.1 Specifications (Normative) A. - - - ◦ deactivation-allowedAT, meaning the the password may be deactivated (if active) by - an authenticated terminal with effective authorization for PIN management, - ◦ needs-padding, meaning that, depending on the length of the given password and the - stored length, the password may need to be padded before presentation to the ICC. - • The set of integers resuming-Pwds MAY be used to indicate the IDs of the passwords that can - be used to resume the password. - • The set of integers resetting-Pwds MAY be used to indicate the IDs of the passwords that - can be used by unauthenticated terminals to reset the password if the reset counter is non-zero. - • The set of integers change-Pwds MAY be used to indicate the IDs of the passwords that can be - used by unauthenticated terminals to change the password if the reset counter is non-zero. - • The field pwdType MAY be used to indicate type of the password (see [10] for details on - PasswordType). - • The integer minLength MAY be used to indicate the minimum length (in characters) of new - passwords (if allowed to change). - • The integer storedLength MAY be used to indicate the stored length on the ICC (in bytes). It - can be used to deduce the number of padding characters needed. - • The integer maxLength MAY be used to indicate the maximum password length (in characters) - allowed. - • The octet string padChar MAY be used to indicate the character to be used for padding. It - MUST be omitted if the password needs no padding. If present and the password is of type bcd, - then padChar should consist of two nibbles of the same value, any nibble could be used as the - “padding nibble” (e.g. ‘55’ is allowed, meaning padding with ‘0101’, but ‘34’ is illegal). - id-PasswordType OBJECT IDENTIFIER ::= { - bsi-de protocols(2) smartcards(2) 12 - } - - id-MRZ OBJECT IDENTIFIER ::= { id-PasswordType 1 } - id-CAN OBJECT IDENTIFIER ::= { id-PasswordType 2 } - id-PIN OBJECT IDENTIFIER ::= { id-PasswordType 3 } - id-PUK OBJECT IDENTIFIER ::= { id-PasswordType 4 } - - PasswordInfo ::= SEQUENCE { - protocol OBJECT IDENTIFIER, - requiredPwdData RequiredPwdData, - optionalPwdData OptionalPwdData - } - - RequiredPwdData ::= SEQUENCE { - pwdId PwdId - } - - PwdId ::= INTEGER - - OptionalPwdData ::= SEQUENCE { - pwdFlags PwdFlags, - resuming-Pwds [0] IMPLICIT SET OF PwdId OPTIONAL, - resetting-Pwds [1] IMPLICIT SET OF PwdId OPTIONAL, - changing-PwdsUT [2] IMPLICIT SET OF PwdId OPTIONAL, - pwdType [3] IMPLICIT PasswordType OPTIONAL, - minLength [4] IMPLICIT INTEGER OPTIONAL, - -Bundesamt für Sicherheit in der Informationstechnik 25 - A. ASN.1 Specifications (Normative) - - - storedLength [5] IMPLICIT INTEGER OPTIONAL, - maxLength [6] IMPLICIT INTEGER OPTIONAL, - padChar [7] IMPLICIT OCTET STRING (SIZE(1)) OPTIONAL, - ... –- For future extensions - } - - PwdFlags ::= BIT STRING { - local (0) - unblocks-others (1), - is-blocking (2), - is-suspending (3), - limited-resetUT (4), - unblock-allowedUT (5), - unblock-allowedAT (6), - change-allowedUT (7), - change-allowedAT (8), - activation-allowedAT (9), - deactivation-allowedAT (10), - needs-padding (11) - } - - PasswordType ::= ENUMERATED {bcd, ascii-numeric, utf8, half-nibble-bcd, - iso9564-1, ...} - -If the PasswordInfo structure is absent for a password, the following options of the description in -Part 2 SHOULD be implemented: - • The PIN is assigned with a reset counter. - • The PUK is non-blocking. - • For unauthenticated terminals, the function Change PIN after PACE with PUK is not allowed. - -Note: Usage of the algorithm 3DES is deprecated, hence the object identifiers -id-PACE-DH-GM-3DES-CBC-CBC, id-PACE-ECDH-GM-3DES-CBC-CBC, -id-PACE-DH-IM-3DES-CBC-CBC and id-PACE-DH-IM-3DES-CBC-CBC SHOUL NOT be used - - -A.1.1.2. Chip Authentication -To indicate support for Chip Authentication Version 1 or Version 2 SecurityInfos may contain the -following entries: - • At least one ChipAuthenticationPublicKeyInfo MUST be present. - • At least one ChipAuthenticationInfo MUST be present. - • At least one ChipAuthenticationDomainParameterInfo MUST be present for Chip - Authentication in version 2. -To indicate support for Chip Authentication Version 3 SecurityInfos may contain the following -entries: - • At least one ChipAuthenticationInfo MUST be present. - • At least one ChipAuthenticationDomainParameterInfo MUST be present. - • At least one PSAInfo MUST be present. - • At least one PSPublicKeyInfo MUST be present. - - -26 Bundesamt für Sicherheit in der Informationstechnik - ASN.1 Specifications (Normative) A. - - -The usage of the keyId within the SecurityInfos is CONDITIONAL. In case Chip Authentication -version 3 is supported by the ICC or more than one Chip Authentication Public Key is present on the -ICC, the optional keyId MUST be used in all data structures to indicate the local key identifier and -domain parameters. - -Note: For Chip Authentication Version 3, the domain parameters for the ephemeral key agreement are -contained in ChipAuthenticationDomainParameterInfo, while the domain parameters to be -used for the Pseudonymous Signature are contained in PSPublicKeyInfo. Hence, the keyId does -not only indicate the local key identifier for Pseudonymous Signature Authentication, but also the -domain parameters to be used within the ephemeral key agreement for secure messaging. -ChipAuthenticationInfo: This data structure provides detailed information on an implementation of -Chip Authentication. - • The object identifier protocol SHALL identify the algorithms to be used (i.e. key agreement, - symmetric cipher and MAC). - • The integer version SHALL identify the version of the protocol. Currently, versions 1, 2 and 3 - are supported. - • The integer keyId MAY be used to indicate the local key identifier (and domain parameters for - key agreement). It MUST be used if the condition listed above is satisfied. - id-CA OBJECT IDENTIFIER ::= { - bsi-de protocols(2) smartcard(2) 3 - } - - id-CA-DH OBJECT IDENTIFIER ::= {id-CA 1} - id-CA-DH-3DES-CBC-CBC OBJECT IDENTIFIER ::= {id-CA-DH 1} - id-CA-DH-AES-CBC-CMAC-128 OBJECT IDENTIFIER ::= {id-CA-DH 2} - id-CA-DH-AES-CBC-CMAC-192 OBJECT IDENTIFIER ::= {id-CA-DH 3} - id-CA-DH-AES-CBC-CMAC-256 OBJECT IDENTIFIER ::= {id-CA-DH 4} - - id-CA-ECDH OBJECT IDENTIFIER ::= {id-CA 2} - id-CA-ECDH-3DES-CBC-CBC OBJECT IDENTIFIER ::= {id-CA-ECDH 1} - id-CA-ECDH-AES-CBC-CMAC-128 OBJECT IDENTIFIER ::= {id-CA-ECDH 2} - id-CA-ECDH-AES-CBC-CMAC-192 OBJECT IDENTIFIER ::= {id-CA-ECDH 3} - id-CA-ECDH-AES-CBC-CMAC-256 OBJECT IDENTIFIER ::= {id-CA-ECDH 4} - - ChipAuthenticationInfo ::= SEQUENCE { - protocol OBJECT IDENTIFIER( - id-CA-DH-3DES-CBC-CBC | - id-CA-DH-AES-CBC-CMAC-128 | - id-CA-DH-AES-CBC-CMAC-192 | - id-CA-DH-AES-CBC-CMAC-256 | - id-CA-ECDH-3DES-CBC-CBC | - id-CA-ECDH-AES-CBC-CMAC-128 | - id-CA-ECDH-AES-CBC-CMAC-192 | - id-CA-ECDH-AES-CBC-CMAC-256), - version INTEGER, -- MUST be 1 for CAv1 or 2 for CAv2 or 3 for CAv3 - keyId INTEGER OPTIONAL - } - -ChipAuthenticationDomainParameterInfo: This data structure provides one set of domain parameters -for Chip Authentication version 2 and version 3 of the ICC. - • The object identifier protocol SHALL identify the type of the domain parameters (i.e. DH or - ECDH). - - -Bundesamt für Sicherheit in der Informationstechnik 27 - A. ASN.1 Specifications (Normative) - - - • The sequence domainParameter SHALL contain the domain parameters. - • The integer keyId MAY be used to indicate the local key identifier (and domain parameters for - key agreement). It MUST be used if the condition listed above is satisfied. - ChipAuthenticationDomainParameterInfo ::= SEQUENCE { - protocol OBJECT IDENTIFIER(id-CA-DH | id-CA-ECDH), - domainParameter AlgorithmIdentifier, - keyId INTEGER OPTIONAL - } - -ChipAuthenticationPublicKeyInfo: This data structure provides a public key for Chip Authentication of -the ICC. - • The object identifier protocol SHALL identify the type of the public key (i.e. DH or ECDH). - • The sequence chipAuthenticationPublicKey SHALL contain the public key in encoded - form. - • The integer keyId MAY be used to indicate the local key identifier. It MUST be used if the - condition listed above is satisfied. - id-PK OBJECT IDENTIFIER ::= { - bsi-de protocols(2) smartcard(2) 1 - } - - id-PK-DH OBJECT IDENTIFIER ::= {id-PK 1} - id-PK-ECDH OBJECT IDENTIFIER ::= {id-PK 2} - - ChipAuthenticationPublicKeyInfo ::= SEQUENCE { - protocol OBJECT IDENTIFIER(id-PK-DH | id-PK-ECDH), - chipAuthenticationPublicKey SubjectPublicKeyInfo, - keyId INTEGER OPTIONAL - } - -PSAInfo: This data structure provides detailed information on an implementation of Pseudonymous -Signature Authentication and is of the following form: - PSAInfo ::= SEQUENCE { - protocol OBJECT IDENTIFIER ( - id-PSA-ECDH-ECSchnorr-SHA-256 | - id-PSA-ECDH-ECSchnorr-SHA-384 | - id-PSA-ECDH-ECSchnorr-SHA-512), - requiredData PSARequiredData, - keyId INTEGER OPTIONAL - } - - PSARequiredData ::= SEQUENCE { - version INTEGER, –- MUST be 1 - ps1-authInfo INTEGER (0 | 1 | 2), - ps2-authInfo INTEGER (0 | 1 | 2) - } - - id-PS OBJECT IDENTIFIER ::= { bsi-de protocols(2) smartcards(2) 11 } - id-PSA OBJECT IDENTIFIER ::= { id-PS 1 } - - id-PSA-ECDH-ECSchnorr OBJECT IDENTIFIER ::= { id-PSA 2 } - id-PSA-ECDH-ECSchnorr-SHA-256 OBJECT IDENTIFIER ::= { PSA-ECDH-ECSchnorr 3 } - id-PSA-ECDH-ECSchnorr-SHA-384 OBJECT IDENTIFIER ::= { PSA-ECDH-ECSchnorr 4 } - id-PSA-ECDH-ECSchnorr-SHA-512 OBJECT IDENTIFIER ::= { PSA-ECDH-ECSchnorr 5 } - - -28 Bundesamt für Sicherheit in der Informationstechnik - ASN.1 Specifications (Normative) A. - - - - -The fields in the data structure contain the following information: - • The object identifier protocol SHALL identify the Pseudonymous Signature Authentication - Protocol. - • The integer version SHALL identify the version of the supported protocol. Currently, version - 1 is supported. - • The integer ps1-authInfo SHALL indicate the terminal's effective authorization required to - Sector - get the Pseudonym I ICC , 1 during Pseudonymous Signature Authentication. The value - ◦ '0' indicates that no explicit authorization is required, - ◦ '1' indicates that explicit authorization is required and - Sector - ◦ '2' indicates that a terminal is not authorized to obtain I ICC , 1 . - • The integer ps2-authInfo SHALL indicate the required terminal's effective authorization to - Sector - obtain the Pseudonym I ICC , 2 during Pseudonymous Signature Authentication. The value - ◦ '0' indicates that no explicit authorization is required, - ◦ '1' indicates that explicit authorization is required and - Sector - ◦ '2' indicates that a terminal is not authorized to obtain I ICC , 2 . - • The integer keyId MUST be used to indicate the local key identifier and domain parameters - for key agreement. -PSPublicKeyInfo: This data structure provides detailed information on a public key for the -Pseudonymous Signature and is of the following form: - PSPublicKeyInfo ::= SEQUENCE { - protocol OBJECT IDENTIFIER (id-PS-PK-ECDH-ECSchnorr), - requiredData PSPKRequiredData, - optionalData PSPKOptionalData OPTIONAL - } - - PSPKRequiredData ::= SEQUENCE { - pSPublicKey SubjectPublicKeyInfo, - } - - PSPKOptionalData ::= SEQUENCE { - pSParameterID [1] IMPLICIT INTEGER OPTIONAL, - keyId [2] IMPLICIT INTEGER OPTIONAL - - id-PS-PK OBJECT IDENTIFIER ::= { bsi-de protocols(2) smartcards(2) PK(1) 3 } - id-PS-PK-ECDH-ECSchnorr OBJECT IDENTIFIER ::= { id-PS-PK 2 } - -The fields in the data structures contain the following information: - • The object identifier protocol SHALL identify the public key type, - • The sequence pSPublicKey SHALL contain the ICC's public key and the underlying extended - domain parameters in encoded form. The algorithm identifiers of section A.6.1 SHALL be used. - • The integer pSParameterID MAY be used to indicate the (local) ID of the domain parameters - (excluding the domain parameters). It MUST be present if explicit domain parameters are used. - Otherwise, the field SHOULD be omitted. - - -Bundesamt für Sicherheit in der Informationstechnik 29 - A. ASN.1 Specifications (Normative) - - - • The integer keyId MUST be used to indicate the local key identifier and domain parameters - for key agreement. - -Note: Usage of the algorithm 3DES is deprecated, hence, the object identifiers -id-CA-DH-3DES-CBC-CBC and id-CA-ECDH-GM-3DES-CBC-CBC SHOULD NOT be used. - - -A.1.1.3. Terminal Authentication -To indicate support for Terminal Authentication SecurityInfos may contain the following entry: - • At least one TerminalAuthenticationInfo SHOULD be present. -TerminalAuthenticationInfo: This data structure provides detailed information on an implementation -of Terminal Authentication. - • The object identifier protocol SHALL identify the general Terminal Authentication Protocol - as the specific protocol may change over time. - • The integer version SHALL identify the version of the protocol. Currently, versions 1 and 2 - are supported. - • The sequence efCVCA MAY be used in version 1 to indicate a (short) file identifier of the file - EF.CVCA. It MUST be used, if the default (short) file identifier is not used. In version 2, the field - MUST be absent. - id-TA OBJECT IDENTIFIER ::= { - bsi-de protocols(2) smartcard(2) 2 - } - - id-TA-RSA OBJECT IDENTIFIER ::= {id-TA 1} - id-TA-RSA-v1-5-SHA-1 OBJECT IDENTIFIER ::= {id-TA-RSA 1} - id-TA-RSA-v1-5-SHA-256 OBJECT IDENTIFIER ::= {id-TA-RSA 2} - id-TA-RSA-PSS-SHA-1 OBJECT IDENTIFIER ::= {id-TA-RSA 3} - id-TA-RSA-PSS-SHA-256 OBJECT IDENTIFIER ::= {id-TA-RSA 4} - id-TA-RSA-v1-5-SHA-512 OBJECT IDENTIFIER ::= {id-TA-RSA 5} - id-TA-RSA-PSS-SHA-512 OBJECT IDENTIFIER ::= {id-TA-RSA 6} - - id-TA-ECDSA OBJECT IDENTIFIER ::= {id-TA 2} - id-TA-ECDSA-SHA-1 OBJECT IDENTIFIER ::= {id-TA-ECDSA 1} - id-TA-ECDSA-SHA-224 OBJECT IDENTIFIER ::= {id-TA-ECDSA 2} - id-TA-ECDSA-SHA-256 OBJECT IDENTIFIER ::= {id-TA-ECDSA 3} - id-TA-ECDSA-SHA-384 OBJECT IDENTIFIER ::= {id-TA-ECDSA 4} - id-TA-ECDSA-SHA-512 OBJECT IDENTIFIER ::= {id-TA-ECDSA 5} - - TerminalAuthenticationInfo ::= SEQUENCE { - protocol OBJECT IDENTIFIER(id-TA), - version INTEGER, -- MUST be 1 for TAv1 or 2 for TAv2 - efCVCA FileID OPTIONAL -- MUST NOT be used for version 2 - } - - FileID ::= SEQUENCE { - fid OCTET STRING (SIZE(2)), - sfid OCTET STRING (SIZE(1)) OPTIONAL - } - - - - -30 Bundesamt für Sicherheit in der Informationstechnik - ASN.1 Specifications (Normative) A. - - -Note: Usage of the hash function SHA-1 is deprecated, hence the object identifiers -id-TA-RSA-v1-5-SHA-1, id-TA-RSA-PSS-SHA-1 and id-TA-ECDSA-SHA-1 SHOULD NOT be -used. - - -A.1.1.4. Restricted Identification -To indicate support for Restricted Identification SecurityInfos may contain the following entry: - • At least one RestrictedIdentificationInfo MUST be present. - • At most one RestrictedIdentificationDomainParameterInfo MAY be present. -RestrictedIdentificationInfo: This data structure provides detailed information on an implementation -of Restricted Identification. - • The object identifier protocol SHALL identify the algorithms to be used (i.e. key agreement). - • The integer version SHALL identify the version of the protocol. Currently, only version 1 is - supported. - • The integer keyId SHALL identify the private key to be used. - • The boolean authorizedOnly SHALL indicate whether explicit authorization is REQUIRED - to use the corresponding secret key. - • The integer maxKeyLen MAY be used to indicate the maximum length of the supported sector - specific public keys. - id-RI OBJECT IDENTIFIER ::= { - bsi-de protocols(2) smartcard(2) 5 - } - - id-RI-DH OBJECT IDENTIFIER ::= {id-RI 1} - id-RI-DH-SHA-1 OBJECT IDENTIFIER ::= {id-RI-DH 1} - id-RI-DH-SHA-224 OBJECT IDENTIFIER ::= {id-RI-DH 2} - id-RI-DH-SHA-256 OBJECT IDENTIFIER ::= {id-RI-DH 3} - id-RI-DH-SHA-384 OBJECT IDENTIFIER ::= {id-RI-DH 4} - id-RI-DH-SHA-512 OBJECT IDENTIFIER ::= {id-RI-DH 5} - - id-RI-ECDH OBJECT IDENTIFIER ::= {id-RI 2} - id-RI-ECDH-SHA-1 OBJECT IDENTIFIER ::= {id-RI-ECDH 1} - id-RI-ECDH-SHA-224 OBJECT IDENTIFIER ::= {id-RI-ECDH 2} - id-RI-ECDH-SHA-256 OBJECT IDENTIFIER ::= {id-RI-ECDH 3} - id-RI-ECDH-SHA-384 OBJECT IDENTIFIER ::= {id-RI-ECDH 4} - id-RI-ECDH-SHA-512 OBJECT IDENTIFIER ::= {id-RI-ECDH 5} - - RestrictedIdentificationInfo ::= SEQUENCE { - protocol OBJECT IDENTIFIER( - id-RI-DH-SHA-1 | - id-RI-DH-SHA-224 | - id-RI-DH-SHA-256 | - id-RI-DH-SHA-384 | - id-RI-DH-SHA-512 | - id-RI-ECDH-SHA-1 | - id-RI-ECDH-SHA-224 | - id-RI-ECDH-SHA-256 | - id-RI-ECDH-SHA-384 | - id-RI-ECDH-SHA-512), - params ProtocolParams, - - -Bundesamt für Sicherheit in der Informationstechnik 31 - A. ASN.1 Specifications (Normative) - - - maxKeyLen INTEGER OPTIONAL - } - - ProtocolParams ::= SEQUENCE { - version INTEGER, -- MUST be 1 - keyId INTEGER, - authorizedOnly BOOLEAN - } - -RestrictedIdentificationDomainParameterInfo: This data structure provides the set of domain -parameters that have been used for the generation of the public key PK ID for revocation of the ICC. - • The object identifier protocol SHALL identify the type of the domain parameters (i.e. DH or - ECDH). - • The sequence domainParameter SHALL contain the domain parameters. - RestrictedIdentificationDomainParameterInfo ::= SEQUENCE { - protocol OBJECT IDENTIFIER(id-RI-DH | id-RI-ECDH), - domainParameter AlgorithmIdentifier - } - - -Note: Usage of the hash function SHA-1 is deprecated, hence the object identifiers id-RI-DH-SHA-1 -and id-RI-ECDH-SHA-1 SHOULD NOT be used. - - -A.1.1.5. Pseudonymous Signatures of Messages (PSM) -To indicate support for Pseudonymous Signature of Messages, SecurityInfos may contain the -following entries: - • At least one PSMInfo MUST be present. - • At least one PSPublicKeyInfo MUST be present. -PSMInfo: This data structure provides detailed information on an implementation of PSM and is of the -following form: - PSMInfo ::= SEQUENCE { - protocol OBJECT IDENTIFIER ( - id-PSM-ECDH-ECSchnorr-SHA-256 | - id-PSM-ECDH-ECSchnorr-SHA-384 | - id-PSM-ECDH-ECSchnorr-SHA-512), - requiredData PSMRequiredData, - keyId INTEGER OPTIONAL - } - - PSMRequiredData ::= SEQUENCE { - version INTEGER, –- MUST be 1 - ps1-authInfo INTEGER (0 | 1 | 2), - ps2-authInfo INTEGER (0 | 1 | 2) - } - - id-PSM OBJECT IDENTIFIER ::= { id-PS 2 } - - id-PSM-ECDH-ECSchnorr OBJECT IDENTIFIER ::= { id-PSM 2 } - id-PSM-ECDH-ECSchnorr-SHA-256 OBJECT IDENTIFIER ::= { PSM-ECDH-ECSchnorr 3 } - id-PSM-ECDH-ECSchnorr-SHA-384 OBJECT IDENTIFIER ::= { PSM-ECDH-ECSchnorr 4 } - id-PSM-ECDH-ECSchnorr-SHA-512 OBJECT IDENTIFIER ::= { PSM-ECDH-ECSchnorr 5 } - - -32 Bundesamt für Sicherheit in der Informationstechnik - ASN.1 Specifications (Normative) A. - - - -The fields in the data structure contain the following information: - • The object identifier protocol SHALL identify the PSM Protocol. - • The integer version SHALL identify the version of the supported protocol. Currently, version - 1 is supported. - • The integer ps1-authInfo SHALL indicate the required terminal's effective authorization to - Sector - get the Pseudonym I ICC , 1 during Pseudonymous Signature of a Message. The value - ◦ '0' indicates that no explicit authorization is required, - ◦ '1' indicates that explicit authorization is required and - Sector - ◦ '2' indicates that a terminal is not authorized to obtain I ICC , 1 . - • The integer ps2-authInfo SHALL indicate the required terminal's effective authorization to - Sector - get the Pseudonym I ICC , 2 during Pseudonymous Signature of a Message. The value - ◦ '0' indicates that no explicit authorization is required, - ◦ '1' indicates that explicit authorization is required and - Sector - ◦ '2' indicates that a terminal is not authorized to obtain I ICC , 2 . - • The integer keyId MUST be used to indicate the local key identifier. - - -A.1.1.6. Pseudonymous Signatures of Credentials (PSC) -To indicate support for Pseudonymous Signature of Credentials, SecurityInfos may contain the -following entries: - • At least one PSCInfo MUST be present. - • At least one PSPublicKeyInfo MUST be present. -PSCInfo: This data structure provides detailed information on an implementation of PSC and is of the -following form: - PSCInfo ::= SEQUENCE { - protocol OBJECT IDENTIFIER ( - id-PSC-ECDH-ECSchnorr-SHA-256 | - id-PSC-ECDH-ECSchnorr-SHA-384 | - id-PSC-ECDH-ECSchnorr-SHA-512), - requiredData PSCRequiredData, - keyId INTEGER OPTIONAL - } - - PSCRequiredData ::= SEQUENCE { - version INTEGER, –- MUST be 1 - ps1-authInfo INTEGER (0 | 1 | 2), - ps2-authInfo INTEGER (0 | 1 | 2) - } - - id-PSC OBJECT IDENTIFIER ::= { id-PS 3 } - - id-PSC-ECDH-ECSchnorr OBJECT IDENTIFIER ::= { id-PSC 2 } - id-PSC-ECDH-ECSchnorr-SHA-256 OBJECT IDENTIFIER ::= { PSC-ECDH-ECSchnorr 3 } - id-PSC-ECDH-ECSchnorr-SHA-384 OBJECT IDENTIFIER ::= { PSC-ECDH-ECSchnorr 4 } - - -Bundesamt für Sicherheit in der Informationstechnik 33 - A. ASN.1 Specifications (Normative) - - - id-PSC-ECDH-ECSchnorr-SHA-512 OBJECT IDENTIFIER ::= { PSC-ECDH-ECSchnorr 5 } - -The fields in the data structure contain the following information: - • The object identifier protocol SHALL identify the PSC Protocol. - • The integer version SHALL identify the version of the supported protocol. Currently, version - 1 is supported. - • The integer ps1-authInfo SHALL indicate the required terminal's effective authorization to - Sector - get the Pseudonym I ICC , 1 during Pseudonymous Signature of Credentials. The value - ◦ '0' indicates that no explicit authorization is required, - ◦ '1' indicates that explicit authorization is required and - Sector - ◦ '2' indicates that a terminal is not authorized to obtain I ICC , 1 . - • The integer ps2-authInfo SHALL indicate the required terminal's effective authorization to - Sector - get the Pseudonym I ICC , 2 during Pseudonymous Signature of Credentials. The value - ◦ '0' indicates that no explicit authorization is required, - ◦ '1' indicates that explicit authorization is required and - Sector - ◦ '2' indicates that a terminal is not authorized to obtain I ICC , 2 . - • The integer keyId MUST be used to indicate the local key identifier. - - -A.1.1.7. CardInfo (eIDAS token only) -To provide information about card capabilities and the structure of the card SecurityInfos may -contain the following entry: - • Exactly one CardInfo SHOULD be present. It MUST be present if the ICC supports - authorization extensions or storing/restoring of the session context. -CardInfo: This data structure provides detailed information about the applications supported by the -ICC. - • The object identifier protocol SHALL identify the CardInfo structure. - • The string urlCardInfo SHALL define the location that provides the most recent CardInfo - file [5] for the respective ICC type and version. - • The choice optionalCardInfoData MAY contain optional CardInfo data. If the ICC - supports Authorization Extensions or storing/restoring of Session Contexts or the compare - command for auxilliary data verification, the choice ExtCardInfoData MUST be present. - ◦ The sequence efCardInfo MAY be used to indicate a (short) file identifier of the file - EF.CardInfo containing a CardInfo file [5]. - ◦ If present, supportedTRVersion SHALL contain the version of this Technical Guideline. - Compliance to this version SHALL be indicated by 'Version 2.21'. - ◦ If the ICC supports Authorization Extensions, the set of suppTerminalTypes MUST be - present. - ▪ If present, the object identifier supportedTerminalType SHALL contain a terminal - type supported by the ICC a terminal type supported by the ICC indicated by the - -34 Bundesamt für Sicherheit in der Informationstechnik - ASN.1 Specifications (Normative) A. - - - corresponding OBJECT IDENTIFIER. See Part 4 for the Terminal Types defined in this - Technical Guideline. - ▪ If the ICC supports Authorization Extensions for the terminal type, these extensions - SHALL be indicated by the corresponding object identifier in the set of - supportedAuthorizationExtensions. - ◦ The integer maxSCNo MAY indicate the maximum number of Session Contexts that can be - handled by the ICC in addition to the default session context. It MUST be present if the ICC - supports switching of session contexts. The value MUST NOT exceed 127. The value of 0x00 - indicates that the ICC supports the default session context only. - ◦ The boolean envInfo MAY be used to indicate if the ICC supports Envelope/GetResponse - TPDUs. - id-CI OBJECT IDENTIFIER ::= { - bsi-de protocols(2) smartcard(2) 6 - } - - CardInfo ::= SEQUENCE { - protocol OBJECT IDENTIFIER(id-CI), - urlCardInfo IA5String, - optionalCardInfoData OptionalCardInfoData OPTIONAL, - } - - FileID ::= SEQUENCE { - fid OCTET STRING (SIZE(2)), - sfid OCTET STRING (SIZE(1)) OPTIONAL - } - - OptionalCardInfoData ::= CHOICE { - efCardInfo EfCardInfo, - extCardInfoData [0] IMPLICIT ExtCardInfoData - } - - EfCardInfo ::= FileID - - ExtCardInfoData ::= SEQUENCE { - efCardInfo [0] IMPLICIT FileID OPTIONAL, - supportedTRVersion [1] IMPLICIT UTF8String OPTIONAL, - suppTerminalTypes [2] IMPLICIT SET OF SupportedTerminalTypes - OPTIONAL, - maxSCNo [3] IMPLICIT INTEGER OPTIONAL, - envInfo [4] IMPLICIT BOOLEAN OPTIONAL - } - - SupportedTerminalTypes ::=SEQUENCE { - supportedTerminalType OBJECT IDENTIFIER, - supportedAuthorizations SET OF OBJECT IDENTIFIER OPTIONAL - } - - -A.1.1.8. EIDSecurityInfo (eIDAS token only) -To protect data stored in the eID application SecurityInfos may contain the following entry: - • Exactly one EIDSecurityInfo SHOULD be present. -EIDSecurityInfo: This data structure provides hash values of selected data groups of the eID -application. - -Bundesamt für Sicherheit in der Informationstechnik 35 - A. ASN.1 Specifications (Normative) - - - • The sequence eIDSecurityObject SHALL define the hash values of selected data groups. - • The sequence eIDVersionInfo MAY be used to identify the version of the eID Application. - id-eIDSecurity OBJECT IDENTIFIER ::= { - bsi-de protocols(2) smartcard(2) 7 - } - - EIDSecurityInfo ::= SEQUENCE { - protocol OBJECT IDENTIFIER(id-eIDSecurity), - eIDSecurityObject EIDSecurityObject, - eIDVersionInfo EIDVersionInfo OPTIONAL - } - - EIDSecurityObject ::= SEQUENCE { - hashAlgorithm AlgorithmIdentifier, - dataGroupHashValues SEQUENCE OF DataGroupHash - } - - DataGroupHash ::= SEQUENCE { - dataGroupNumber INTEGER, - dataGroupHashValue OCTET STRING - } - - EIDVersionInfo ::= SEQUENCE { - eIDVersion PrintableString, - unicodeVersion PrintableString - } - -A.1.1.9. PrivilegedTerminalInfo (eIDAS token only) -To provide additional information about Chip Authentication keys restricted to privileged terminals -SecurityInfos may contain the following entry: - • Exactly one PrivilegedTerminalInfo MUST be present, if some Chip Authentication keys - are only available to privileged terminals. -PrivilegedTerminalInfo: This data structure provides SecurityInfos related to Chip Authentication -using chip-individual keys that are only available to privileged terminals. - • The set privilegedTerminalInfos SHALL encapsulate SecurityInfos corresponding - to Chip Authentication keys that are only available to privileged terminals. - id-PT OBJECT IDENTIFIER ::= { - bsi-de protocols(2) smartcard(2) 8 - } - - PrivilegedTerminalInfo ::= SEQUENCE { - protocol OBJECT IDENTIFIER(id-PT), - privilegedTerminalInfos SecurityInfos - } - - - - -36 Bundesamt für Sicherheit in der Informationstechnik - ASN.1 Specifications (Normative) A. - - - -File Name EF.CardAccess EF.CardSecurity EF.ChipSecurity -File ID 0x011C 0x011D 0x011B -Short File ID 0x1C 0x1D 0x1B -Read Access ALWAYS PACE (m) PACE - + TA (o) + TA[authenticated privileged - terminals] -Write Access NEVER NEVER NEVER -Size variable variable variable -Content DER encoded DER encoded ContentInfo DER encoded ContentInfo - SecurityInfos structure of type id-SignedData structure of type id-SignedData - Table 2: Elementary Files CardAccess, CardSecurity and ChipSecurity - - -A.1.1.10. Other Protocols -SecurityInfos MAY contain references to protocols that are not contained in this specification -(including Active Authentication and Basic Access Control). - - -A.1.2. Storage on the Chip -The ICC SHALL provide SecurityInfos in the following transparent elementary files contained in -the master file (cf. Table 2): - • CardAccess (CONDITIONAL) - SHALL be present if PACE, Chip Authentication version 2 and/or Terminal Authentication - version 2 are implemented by the chip. SHALL be readable by all terminals. - • CardSecurity (CONDITIONAL) - SHALL be present if Chip Authentication version 2 or 3, Terminal Authentication version 2, - Restricted Identification or PSM are implemented by the chip. Read access to CardSecurity - SHALL be restricted to terminals having successfully performed PACE and MAY be further - restricted to authenticated terminals. - • ChipSecurity (OPTIONAL) - Read access to ChipSecurity SHALL be restricted to authenticated privileged terminals. If this - optional file is available, all privacy-relevant SecurityInfos SHOULD be stored in - ChipSecurity and SHOULD NOT be included in CardSecurity. -If PACE according [8], Terminal Authentication version 1 or Chip Authentication version 1 are -implemented, the ICC SHALL provide SecurityInfos in the elementary file DG14 contained in the -ePassport application. - - - - -Bundesamt für Sicherheit in der Informationstechnik 37 - A. ASN.1 Specifications (Normative) - - -A.1.2.1. CardAccess (CONDITIONAL) -If present, the file CardAccess shall contain the relevant SecurityInfos that are required to access -applications: - • PACEInfo (REQUIRED) - • PACEDomainParameterInfo (CONDITIONAL) - ◦ This structure(s) MUST be present if explicit domain parameters are used. - • PasswordInfo (OPTIONAL) - ◦ This structure MAY be present to provide information about supported passwords. - • ChipAuthenticationInfo (CONDITIONAL) - ◦ This structure(s) MUST be present if Chip Authentication in version 2 or 3 is supported and - read access to CardSecurity is restricted to authenticated terminals. - • ChipAuthenticationDomainParameterInfo (CONDITIONAL) - ◦ This structure(s) MUST be present if Chip Authentication in version 2 or 3 is supported and - read access to CardSecurity is restricted to authenticated terminals. - • PSAInfo (CONDITIONAL) - ◦ This structure MUST be present if Chip Authentication in version 3 is supported and read - access to CardSecurity is restricted to authenticated terminals. - • TerminalAuthenticationInfo (CONDITIONAL) - ◦ This structure MUST be present if Terminal Authentication in version 2 is supported. - • PSMInfo (CONDITIONAL) - ◦ This structure MUST be present if Pseudonymous Signature of Messages is supported and - read access to CardSecurity is restricted to authenticated terminals. - • CardInfo (RECOMMENDED) - • PrivilegedTerminalInfo (CONDITIONAL) - ◦ This structure MUST be present if some Chip Authentication version 2 keys are only - available to privileged terminals and read access to CardSecurity is restricted to - authenticated terminals. - ◦ It SHALL encapsulate the corresponding SecurityInfos, i.e. for each Chip - Authentication key that is restricted to privileged terminals a - ChipAuthenticationInfo and ChipAuthenticationDomainParameterInfo - MUST be included referencing the key identifier. - - -A.1.2.2. CardSecurity (CONDITIONAL) -If present, the file CardSecurity - • SHALL contain all SecurityInfos supported by the ICC (except for - PrivilegedTerminalInfo and EIDSecurityInfo for which the conditions as described - below apply) - - - -38 Bundesamt für Sicherheit in der Informationstechnik - ASN.1 Specifications (Normative) A. - - - • SHALL contain all SecurityInfos contained in CardAccess except - PrivilegedTerminalInfo, - • if some Chip Authentication version 2 keys are only available to privileged terminals and no - PrivilegedTerminalInfo is contained in CardAccess, SHALL contain a - PrivilegedTerminalInfo, which encapsulates the corresponding SecurityInfos, - • SHALL contain the corresponding ChipAuthenticationPublicKeyInfo for each key - referenced by a ChipAuthenticationInfo of version 1 or 2 (excluding keys encapsulated - in PrivilegedTerminalInfo). Generation-specific keys SHOULD be used instead of - chip-individual keys, and - • SHOULD NOT contain EIDSecurityInfo. -The SecurityInfos contained in CardSecurity MUST be signed using the data structure specified in -A.1.2.5. - - -A.1.2.3. ChipSecurity (OPTIONAL) -If present, the file ChipSecurity - • SHALL contain all SecurityInfos supported by the ICC. In particular, the file - ◦ SHALL contain all SecurityInfos contained in CardAccess, and - ◦ SHALL contain the corresponding ChipAuthenticationPublicKeyInfo for each key - referenced by a ChipAuthenticationInfo. For each ChipAuthenticationInfo - encapsulated in PrivilegedTerminalInfo, the corresponding - ChipAuthenticationPublicKeyInfo MUST also be included in - PrivilegedTerminalInfo. All keys encapsulated in PrivilegedTerminalInfo - SHOULD be chip-individual keys. - • It is RECOMMENDED that EIDSecurityInfo is used to provide hashes of (static) data groups - related to personal data of the holder. -The SecurityInfos contained in ChipSecurity MUST be signed using the data structure specified in -A.1.2.5. - - -A.1.2.4. ePassport DG14 (CONDITIONAL) -If PACE according to [8], Terminal Authentication version 1 or Chip Authentication version 1 are -implemented by the chip, the ICC SHALL also provide SecurityInfos in data group DG14 of the -ePassport application. It is RECOMMENDED that DG14 and ChipSecurity (if present) contain the same -keys. - - -A.1.2.5. Signature Format for CardSecurity and ChipSecurity -The files CardSecurity and ChipSecurity SHALL be implemented as SignedData according to [7]3 with -content type id-SecurityObject within the field encapContentInfo. The Security Objects -SHALL be signed by the Document Signer. The Document Signer Certificate MUST be included in -SignedData. The following Object Identifier SHALL be used to identify the content type: - id-SecurityObject OBJECT IDENTIFIER ::= { - -3 i.e. a ContentInfo structure with content type id-signed-data and content of type SignedData. - -Bundesamt für Sicherheit in der Informationstechnik 39 - A. ASN.1 Specifications (Normative) - - - bsi-de applications(3) eID(2) 1 - } - -The data structure SignedData is defined as follows; more details can be found in [7]: - SignedData ::= SEQUENCE{ - version CMSVersion, - digestAlgorithms DigestAlgorithmIdentifiers, - encapContentInfo EncapsulatedContentInfo, - certificates [0] IMPLICIT CertificateSet OPTIONAL, - crls [1] IMPLICIT RevocationInfoChoices OPTIONAL, - signerInfos SignerInfos - } - - DigestAlgorithmIdentifiers ::= SET OF DigestAlgorithmIdentifier - - EncapsulatedContentInfo ::= SEQUENCE { - eContentType ContentType, - eContent [0] EXPLICIT OCTET STRING OPTIONAL - } - - ContentType ::= OBJECT IDENTIFIER - - SignerInfos ::= SET OF SignerInfo - - SignerInfo ::= SEQUENCE { - version CMSVersion, - sid SignerIdentifier, - digestAlgorithm DigestAlgorithmIdentifier, - signedAttrs [0] IMPLICIT SignedAttributes OPTIONAL, - signatureAlgoritm SignatureAlgorithmIdentifier, - signature SignatureValue, - unsignedAttrs [1] IMPLICIT UnsignedAttributes OPTIONAL - } - - SignerIdentifier ::= CHOICE { - issuerAndSerialNumber IssuerAndSerialNumber, - subjectKeyIdentifier [0] SubjectKeyIdentifier - } - - SignatureValue ::= OCTET STRING - -Within SignerInfos, the field signedAttrs SHALL consist of the content-type attribute and the field -unsignedAttrs SHALL NOT be present. - - - - -40 Bundesamt für Sicherheit in der Informationstechnik - ASN.1 Specifications (Normative) A. - - - Algorithm / Format DH ECDH - Key Agreement Algorithm PKCS#3 [26] ECKA [4] - X.509 Public Key Format X9.42 [1] ECC [4] - TLV Public Key Format TLV, cf. Appendix D.3.2 TLV, cf. Appendix D.3.3 - Public Key Compression SHA-1 [24] X-Coordinate - Ephemeral Public Key RFC 2631 [25] ECC [4] - Validation - Table 3: Algorithms and Formats for Key Agreement - - -A.2. Key Agreement -PACE, Chip Authentication, Restricted Identification and the pseudonym generation within -Pseudonymous Signatures are based on key agreement protocols. This appendix specifies the general -algorithms, formats and protocols. An overview can be found in table 3. - - -A.2.1. Domain Parameters -With the exception of domain parameters contained in PACEInfo, all domain parameters SHALL be -provided as AlgorithmIdentifier, the data structure is defined as follows; more details can be -found in [6]: - AlgorithmIdentifier ::= SEQUENCE { - algorithm OBJECT IDENTIFIER, - parameters ANY DEFINED BY algorithm OPTIONAL - } - -Within PACEInfo, the ID of standardized domain parameters described in Table 4 SHALL be -referenced directly. Explicit domain parameters provided in the field parameterID by -PACEDomainParameterInfo or in pSParameterID by PSPublicKeyInfo MUST NOT use those -IDs reserved for standardized domain parameters. - - -A.2.1.1. Standardized Domain Parameters -Standardized domain parameters described in Table 4 SHOULD be used4. The following object identifier -SHOULD be used to reference standardized domain parameters in an AlgorithmIdentifier: - standardizedDomainParameters OBJECT IDENTIFIER ::= { - bsi-de algorithms(1) 2 - } - - - - -4 The selection of suitable key lengths is not within the scope of this Technical Guideline. - -Bundesamt für Sicherheit in der Informationstechnik 41 - A. ASN.1 Specifications (Normative) - - - - - ID Name Size Type Reference - 0 1024-bit MODP Group with 160-bit Prime Order Subgroup 1024/160 GFP [18] - 1 2048-bit MODP Group with 224-bit Prime Order Subgroup 2048/224 GFP [18] - 2 2048-bit MODP Group with 256-bit Prime Order Subgroup 2048/256 GFP [18] - 3 - 7 RFU - 8 NIST P-192 (secp192r1) 192 ECP [23], [18] - 9 BrainpoolP192r1 192 ECP [19] - 10 NIST P-224 (secp224r1)* 224 ECP [23], [18] - 11 BrainpoolP224r1 224 ECP [19] - 12 NIST P-256 (secp256r1) 256 ECP [23], [18] - 13 BrainpoolP256r1 256 ECP [19] - 14 BrainpoolP320r1 320 ECP [19] - 15 NIST P-384 (secp384r1) 384 ECP [23], [18] - 16 BrainpoolP384r1 384 ECP [19] - 17 BrainpoolP512r1 512 ECP [19] - 18 NIST P-521 (secp521r1) 521 ECP [23], [18] - 19-31 RFU -* This curve cannot be used with the integrated mapping. - - Table 4: Standardized Domain Parameters - - -Within an AlgorithmIdentifier this object identifier SHALL reference the ID of the standardized -domain parameter as contained in Table 4 as INTEGER. - -Note: Usage of the standardized domain parameter IDs 0, 8 and 9 is deprecated. - - -A.2.1.2. Explicit Domain Parameters -Explicit domain parameters may be contained in the following structures: - • PACEDomainParameterInfo, - • ChipAuthenticationPublicKeyInfo, - • ChipAuthenticationDomainParameterInfo, - • PSPublicKeyInfo, and - • RestrictedIdentificationDomainParameterInfo -The object identifier dhpublicnumber or id-ecPublicKey for DH or ECDH, respectively, SHALL -be used to reference explicit domain parameters in an AlgorithmIdentifier: - dhpublicnumber OBJECT IDENTIFIER ::= { - iso(1) member-body(2) us(840) ansi-x942(10046) number-type(2) 1 - } - - - -42 Bundesamt für Sicherheit in der Informationstechnik - ASN.1 Specifications (Normative) A. - - - id-ecPublicKey OBJECT IDENTIFIER ::= { - iso(1) member-body(2) us(840) ansi-x962(10045) keyType(2) 1 - } -In the case of elliptic curves domain parameters MUST be described explicitly in the ECParameters -structure, i.e. named curves and implicit domain parameters MUST NOT be used. - - -A.2.1.3. PACE, Chip Authentication and Pseudonymous Signatures -The ICC MAY support more than one set of domain parameters (i.e. the chip may support different -algorithms and/or key lengths) for PACE, Chip Authentication version 1, 2 and 3, PSM and PSC. - • Domain parameters contained in EF.CardAccess, i.e. PACEDomainParameterInfo, - ChipAuthenticationDomainParameterInfo (for Chip Authentication version 2 or 3), - are unprotected and may be insecure. Using insecure domain parameters may lead to attacks, - e.g. using insecure domain parameters for PACE will leak the used password. - ◦ ICCs MUST support at least one set of standardized domain parameters for PACE and Chip - Authentication version 2 and 3, if the respective protocols are implemented, as specified in - table 4. - ◦ Terminals MUST NOT use unverified domain parameters for PACE or Chip Authentication - version 2 and 3, i.e. only standardized domain parameters or domain parameters explicitly - known by the terminal to be secure are to be used. - • Domain parameters contained in ChipAuthenticationDomainParameterInfo and - ChipAuthenticationPublicKeyInfo and PSPublicKeyInfo are protected by the - Security Object. - ◦ Chip Authentication in version 1 MUST provide at least one set of explicit domain - parameters. - - -A.2.1.4. Restricted Identification -The domain parameters for Restricted Identification are defined by the Document Verifier and MUST -be provided together with the Sector Public Key in a public key data object as part of Restricted -Identification (cf. Appendix D.3 and Appendix B.4.1). The hash of this public key data object MUST be -contained in the Terminal Certificate as Terminal Sector extension (cf. Appendix C.3.2). The ICC MUST -verify the Sector Public Key using the Terminal Sector extension. - - -A.2.2. Ephemeral Public Keys - -A.2.2.1. PACE and Chip Authentication -The domain parameters contained in PACEInfo or PACEDomainParameterInfo and -ChipAuthenticationDomainParameterInfo or ChipAuthenticationPublicKeyInfo -MUST be used by the terminal for the generation of an ephemeral public key for PACE and Chip -Authentication, respectively. Ephemeral public keys MUST be exchanged as plain public key values. -More information on the encoding can be found in Appendix D.3.4. - - - - -Bundesamt für Sicherheit in der Informationstechnik 43 - A. ASN.1 Specifications (Normative) - - - -Note: The validation of ephemeral public keys is REQUIRED. For DH, the validation algorithm requires -the ICC to have a more detailed knowledge of the domain parameters (i.e. the order of the used -subgroup) than usually provided by PKCS#3. - - -A.2.2.2. Restricted Identification -For Restricted Identification ephemeral public keys are not used. - - -A.2.2.3. Public Key Compression - ~ -The terminal's compressed ephemeral public key Comp( PK PCD ) as required for Terminal -Authentication is defined as follows: - • For DH the compressed ephemeral public key is the SHA-1 hash of the DH public value, i.e. an - octet string of fixed length 20. - • For ECDH the compressed ephemeral public key is the x-coordinate of the ECDH public point, - i.e. an octet string of fixed length ⌈log256 p⌉ . - - -A.2.3. Key Derivation Function -Let KDF Enc (K ,[r ])=KDF( K ,[ r ],1), KDF MAC (K ,[r ])=KDF( K ,[r ],2), be key derivation functions to -derive encryption and authentication keys, respectively, from a shared secret K and an optional nonce - r . Let KDF π (π)=KDF( f (π),3), be a key derivation function to derive encryption keys from a -password  . The encoding of passwords, i.e. K = f ( π) is specified in Table 5. -The key derivation function KDF( K ,[r ] ,c ), is defined as follows: -Input: The following inputs are required: - • The shared secret value K (REQUIRED) - • A nonce r (OPTIONAL) - • A 32-bit, big-endian integer counter c (REQUIRED) -Output: An octet string keydata. -Actions: The following actions are performed: - 1. keydata=H ( K∥r∥c ) - 2. Output octet string keydata -The key derivation function KDF( K ,[r ] ,c ) requires a suitable hash function denoted by H (), i.e the -bit-length of the hash function SHALL be greater or equal to the bit-length of the derived key. The hash -value SHALL be interpreted as big-endian byte output. -The nonce r is used for Chip Authentication version 2 only. - -Note: The shared secret K is defined as an octet string. If the shared secret is generated with ECKA [4], -the x-coordinate of the generated point SHALL be used. - - - - -44 Bundesamt für Sicherheit in der Informationstechnik - ASN.1 Specifications (Normative) A. - - - - Password Encoding - MRZ SHA-1(Serial Number || Date of Birth || Date of Expiry) - CAN Character String (cf. Appendix D.2.1.4) - PIN Character String (cf. Appendix D.2.1.4) - PUK Character String (cf. Appendix D.2.1.4) - Table 5: Encoding of Passwords - - - -A.2.3.1. 3DES -To derive 112-bit 3DES [20] keys the hash function SHA-1 [24] SHALL be used and the following -additional steps MUST be performed: - • Use octets 1 to 8 of keydata to form keydataA and octets 9 to 16 of keydata to form keydataB; - additional octets are not used. - • Adjust the parity bits of keydataA and keydataB to form correct DES keys (OPTIONAL). - - -A.2.3.2. AES -To derive 128-bit AES [21] keys the hash function SHA-1 [24] SHALL be used and the following -additional step MUST be performed: - • Use octets 1 to 16 of keydata; additional octets are not used. -To derive 192-bit and 256-bit AES [21] keys SHA-256 [24] SHALL be used. For 192-bit AES keys the -following additional step MUST be performed: - • Use octets 1 to 24 of keydata; additional octets are not used. - - -A.2.4. Authentication Token -The authentication token used in PACE and Chip Authentication in version 2 SHALL be computed over -a public key data object (cf. Appendix D.3) containing the object identifier of the protocol used, i.e. PACE -or Chip Authentication (as indicated in MSE:Set AT, cf. Appendix B.14.1), and the received ephemeral -public key using an authentication code and the key K MAC derived from the key agreement. - - -A.2.4.1. 3DES -3DES [20] SHALL be used in Retail-mode according to ISO/IEC 9797-1 [15] MAC algorithm 3 / padding -method 2 with block cipher DES and IV =0. - - -A.2.4.2. AES -AES [21] SHALL be used in CMAC-mode [22] with a MAC length of 8 bytes. - - - - -Bundesamt für Sicherheit in der Informationstechnik 45 - A. ASN.1 Specifications (Normative) - - - -A.3. PACE - -A.3.1. PACE with DH -For PACE with DH the respective algorithms and formats from Table 3 and Table 6 MUST be used. - -OID Mapping Sym. Key Secure Auth. - Cipher Len Messaging Token -id-PACE-DH-GM-3DES-CBC-CBC Generic 3DES 112 CBC / CBC CBC -id-PACE-DH-GM-AES-CBC-CMAC-128 Generic AES 128 CBC / CMAC CMAC -id-PACE-DH-GM-AES-CBC-CMAC-192 Generic AES 192 CBC / CMAC CMAC -id-PACE-DH-GM-AES-CBC-CMAC-256 Generic AES 256 CBC / CMAC CMAC -id-PACE-DH-IM-3DES-CBC-CBC Integrated 3DES 112 CBC / CBC CBC -id-PACE-DH-IM-AES-CBC-CMAC-128 Integrated AES 128 CBC / CMAC CMAC -id-PACE-DH-IM-AES-CBC-CMAC-192 Integrated AES 192 CBC / CMAC CMAC -id-PACE-DH-IM-AES-CBC-CMAC-256 Integrated AES 256 CBC / CMAC CMAC - Table 6: Object Identifiers for PACE with DH - - -A.3.2. PACE with ECDH -For PACE with ECDH the respective algorithms and formats from Table 3 and Table 7 MUST be used. - -OID Mapping Sym. Key Secure Auth. - Cipher Len Messaging Token -id-PACE-ECDH-GM-3DES-CBC-CBC Generic 3DES 112 CBC / CBC CBC -id-PACE-ECDH-GM-AES-CBC-CMAC-128 Generic AES 128 CBC / CMAC CMAC -id-PACE-ECDH-GM-AES-CBC-CMAC-192 Generic AES 192 CBC / CMAC CMAC -id-PACE-ECDH-GM-AES-CBC-CMAC-256 Generic AES 256 CBC / CMAC CMAC -id-PACE-ECDH-IM-3DES-CBC-CBC Integrated 3DES 112 CBC / CBC CBC -id-PACE-ECDH-IM-AES-CBC-CMAC-128 Integrated AES 128 CBC / CMAC CMAC -id-PACE-ECDH-IM-AES-CBC-CMAC-192 Integrated AES 192 CBC / CMAC CMAC -id-PACE-ECDH-IM-AES-CBC-CMAC-256 Integrated AES 256 CBC / CMAC CMAC - Table 7: Object Identifiers for PACE with ECDH - - -A.3.3. Encrypted Nonce -The ICC SHALL randomly and uniformly select the nonce s∈ R {0 2 l −1} as a binary bit string of -length l, where l is a positive multiple of the block size in bits of the respective block cipher E chosen -by the ICC. - - - -46 Bundesamt für Sicherheit in der Informationstechnik - ASN.1 Specifications (Normative) A. - - - • The nonce s SHALL be encrypted in CBC mode according to ISO 10116 [9] using the key - K  =KDF    derived from the password  and IV =0. - • The nonce s SHALL be converted to a random generator using an algorithm-specific mapping - function Map. - -Note: Several different algorithms exist for implementing the mapping of the nonce to ephemeral -domain parameters. Currently, all specified mappings implementing  D =Map D PICC , s  map the -nonce to an ephemeral generator. It is RECOMMENDED to implement the mapping as a randomized -function. - - -A.3.4. ECDH Mapping - ~ -Let G and G Mapped be the static and an ephemeral base point on the elliptic curve. - - -A.3.4.1. Generic Mapping - ~ ~ -The function Map : G ↦ G Mapped is defined as G Mapped =s⋅G+ H , where H ∈〈G 〉 is chosen s.t. -log G H is unknown. The point H SHALL be calculated by an anonymous Diffie-Hellman Key -Agreement [4]. - -Note: The key agreement algorithm ECKA prevents small subgroup attacks by using compatible -cofactor multiplication. - - -A.3.4.2. Integrated Mapping -The Integrated ECDH Mapping is specified by ICAO [8]. - - -A.3.5. DH Mapping -Let g and ~ - g Mapped be the static and an ephemeral generator. - - -A.3.5.1. Generic Mapping -The function Map : g ↦~ - g Mapped is defined as ~ s - g Mapped =g ⋅h , where h∈⟨ g ⟩ is chosen s.t. log g h is -unknown. The group element h SHALL be calculated by an anonymous Diffie-Hellman Key -Agreement. - -Note: The public key validation method described in RFC 2631 [25] MUST be used to prevent small -subgroup attacks. - - -A.3.5.2. Integrated Mapping -The Integrated DH Mapping is specified by ICAO [8]. - - - - -Bundesamt für Sicherheit in der Informationstechnik 47 - A. ASN.1 Specifications (Normative) - - - -A.4. Chip Authentication - -A.4.1. Chip Authentication version 1 and 2 - -A.4.1.1. Chip Authentication Key Pair -The Key Pair(s) for Chip Authentication version 1 and 2 MUST be stored on the ICC. - • The private key SHALL be stored securely in the ICC’s memory. - • The public key SHALL be provided as SubjectPublicKeyInfo in the - ChipAuthenticationPublicKeyInfo structure. - • The domain parameters MAY be additionally provided as AlgorithmIdentifier in the - ChipAuthenticationDomainParameterInfo structure. -The data structures SubjectPublicKeyInfo and AlgorithmIdentifier are defined as follows; -more details can be found in [6]: - SubjectPublicKeyInfo ::= SEQUENCE { - algorithm AlgorithmIdentifier, - subjectPublicKey BIT STRING - } - - AlgorithmIdentifier ::= SEQUENCE { - algorithm OBJECT IDENTIFIER, - parameters ANY DEFINED BY algorithm OPTIONAL - } - -The ICC MAY support more than one Chip Authentication Key Pair (i.e. the chip may support different -algorithms and/or key lengths). In this case the local key identifier MUST be disclosed in the -corresponding ChipAuthenticationInfo, ChipAuthenticationPublicKeyInfo, and -ChipAuthenticationDomainParameterInfo (cf. A.1.1.2 for further details on the keyId). - - -A.4.1.2. Chip Authentication version 1 and 2 with DH -For Chip Authentication version 1 and 2 with DH the respective algorithms and formats from Table 3 -and Table 8 MUST be used. For Chip Authentication in version 1 PKCS#3 [26] MUST be used instead of -X9.42 [1]. - - OID Sym. Key Secure Auth. - Cipher Length Messaging Token - id-CA-DH-3DES-CBC-CBC 3DES 112 CBC / CBC CBC - id-CA-DH-AES-CBC-CMAC-128 AES 128 CBC / CMAC CMAC - id-CA-DH-AES-CBC-CMAC-192 AES 192 CBC / CMAC CMAC - id-CA-DH-AES-CBC-CMAC-256 AES 256 CBC / CMAC CMAC - Table 8: Object Identifiers for Chip Authentication with DH - - - - -48 Bundesamt für Sicherheit in der Informationstechnik - ASN.1 Specifications (Normative) A. - - -A.4.1.3. Chip Authentication version 1 and 2 with ECDH -For Chip Authentication version 1 and 2 with ECDH the respective algorithms and formats from Table 3 -and Table 9 MUST be used. - - - OID Sym. Key Secure Auth. - Cipher Length Messaging Token - id-CA-ECDH-3DES-CBC-CBC 3DES 112 CBC / CBC CBC - id-CA-ECDH-AES-CBC-CMAC-128 AES 128 CBC / CMAC CMAC - id-CA-ECDH-AES-CBC-CMAC-192 AES 192 CBC / CMAC CMAC - id-CA-ECDH-AES-CBC-CMAC-256 AES 256 CBC / CMAC CMAC - Table 9: Object Identifiers for Chip Authentication with ECDH - - -A.4.2. Chip Authentication Version 3 - -A.4.2.1. Static keys for Chip Authentication version 3 -Chip Authentication version 3 requires static keys on the ICC for Pseudonymous Signature -Authentication. See A.6 for the requirements. -The ICC MAY support more than one set of static keys for Pseudonymous Signature Authentication or -domain parameters for key agreement during Chip Authentication version 3 (i.e. the chip may support -different algorithms and/or key lengths). In this case, the local key identifier MUST be disclosed in the -corresponding ChipAuthenticationInfo, ChipAuthenticationDomainParameterInfo, -PSAInfo, and PSPublicKeyInfo (cf. A.1.1.2 for further details on the keyId). -For each supported set of static keys for Pseudonymous Signature Authentication, the ICC SHALL grant -access to at least one pseudonym without explicit authorization of the terminal (i.e. ps1-authInfo or -ps2-authInfo SHALL have value '0' in PSAInfo). - - -A.4.2.2. Sector Public Keys -The Sector Public Keys for Chip Authentication version 3 are used within Pseudonymous Signature -Authentication. See A.6.2 for the requirements. - - -A.4.2.3. Chip Authentication version 3 based on ECDH and ECSchnorr -For the Diffie Hellman Key Agreement during Chip Authentication version 3, the respective algorithms -of Table 3 and Table 9 MUST be used. -For Pseudonymous Signature Authentication the algorithms and formats of Table 3 and Table 10 -SHALL be used. The Pseudonymous Signature MUST be of plain signature format as defined in -Appendix A.6.5. - - - - -Bundesamt für Sicherheit in der Informationstechnik 49 - A. ASN.1 Specifications (Normative) - - - - - OID Hash - id-PSA-ECDH-ECSchnorr-SHA-256 SHA-256 - id-PSA-ECDH-ECSchnorr-SHA-384 SHA-384 - id-PSA-ECDH-ECSchnorr-SHA-512 SHA-512 - Table 10: Object Identifiers for PSA based on ECSchnorr with ECDH - - -A.5. Restricted Identification - -A.5.1. ICC Private Key -The generation of the private key SK ID is out of the scope of this specification. If SK ID is generated as -encrypted sequential counter or as encrypted document number, the secret encryption key SHALL be -generated and stored securely by a third party. - - -A.5.2. Sector Public Keys -The Sector Public Keys MUST be generated by a (trusted) third party. - • If the third party MUST be able to link sector-specific identifier across sectors, then the third - party SHALL generate Sector Key Pairs and store the Sector Private Keys securely. - • If the third party MUST NOT be able to link sector-specific identifier across sectors, then the - third party SHALL generate Sector Public Keys in a way that the corresponding private keys are - unknown. - - -A.5.3. Restricted Identification with DH -For Restricted Identification with DH the respective algorithms and formats from Table 3 and Table 11 -MUST be used. - - OID Hash - id-RI-DH-SHA-1 SHA-1 - id-RI-DH-SHA-224 SHA-224 - id-RI-DH-SHA-256 SHA-256 - id-RI-DH-SHA-384 SHA-384 - id-RI-DH-SHA-512 SHA-512 - Table 11: Object Identifiers for Restricted Identification with DH - - - - -50 Bundesamt für Sicherheit in der Informationstechnik - ASN.1 Specifications (Normative) A. - - -A.5.4. Restricted Identification with ECDH -For Restricted Identification with ECDH the respective algorithms and formats from Table 3 and Table -12 MUST be used. Input to the hash function SHALL be the x-coordinate of the point generated by -ECKA [4]. - - OID Hash - id-RI-ECDH-SHA-1 SHA-1 - id-RI-ECDH-SHA-224 SHA-224 - id-RI-ECDH-SHA-256 SHA-256 - id-RI-ECDH-SHA-384 SHA-384 - id-RI-ECDH-SHA-512 SHA-512 - Table 12: Object Identifiers for Restricted Identification with ECDH - - - -A.6. Pseudonymous Signatures - -A.6.1. Static keys for Pseudonymous Signatures -The static keys for Pseudonymous signatures MUST be stored on the ICC. - • The private keys SHALL be stored securely in the ICC’s memory. - • The ICC's public key including the domain parameters and the group manager's public key - SHALL be provided as SubjectPublicKeyInfo in the PSPublicKeyInfo structure. -To indicate public keys for Pseudonymous Signatures, the following algorithm identifier SHALL be used -within the SubjectPublicKeyInfo: - • The algorithm SHALL be of type ecPSPublicKey. - • The parameters SHALL indicate the associated cryptographic parameters and MUST consist of a - sequence containing - ◦ the domain parameters encoded as algorithm identifier according appendix A.2.1. - ◦ the group manager public key encoded as ECPoint. - ecPSPublicKey OBJECT IDENTIFIER ::= { bsi-de algorithms(1) ecc(1) keytype(2) - 3 } - -The ICC MAY support more than one set of static keys for Pseudonymous Signatures (i.e. the chip may -support different algorithms and/or key lengths). In this case, the local key identifier MUST be disclosed -in the corresponding PSAInfo, PSMInfo, PSCInfo and PSPublicKeyInfo (cf. also A.1.1.2 for -further details on the keyId for PSA). - - -A.6.2. Sector Public Keys -The Sector Public Keys for Chip Authentication version 3 and Pseudonymous Signatures MUST be -generated by a (trusted) third party. - - -Bundesamt für Sicherheit in der Informationstechnik 51 - A. ASN.1 Specifications (Normative) - - -If the third party must be able to link sector-specific identifier across sectors, then the third party -SHALL generate Sector Key Pairs and store the Sector Private Keys securely. -If the third party must not be able to link sector-specific identifier across sectors, then the third party -SHALL generate Sector Public Keys in a way that the corresponding private keys are unknown. - - -A.6.3. Digital Signature Information -As part of the pseudonymous signature protocol, the ICC SHALL include the object identifier (including tag -0x06 and length) of the protocol that is used as signature information ID DSI into signature computation. - -A.6.4. Projected representation of a public key -For computation and verification of Pseudonymous Signatures, projected representations of public keys are -used as described in the following: - • For ECSchnorr, the projected representation Π(PK ) of a public key is the x-coordinate of the - public point, i.e. an octet string of fixed length ⌈log 256 p⌉ . - -A.6.5. Pseudonymous Signatures of Messages or Credentials based on -ECSchnorr -The algorithms and formats of Table 3 and Table 13 SHALL be used for Pseudonymous Signature of -Messages and Credentials, respectively. - - - OID Hash - id-PSM-ECDH-ECSchnorr-SHA-256 SHA-256 - id-PSM-ECDH-ECSchnorr-SHA-384 SHA-384 - id-PSM-ECDH-ECSchnorr-SHA-512 SHA-512 - id-PSC-ECDH-ECSchnorr-SHA-256 SHA-256 - id-PSC-ECDH-ECSchnorr-SHA-384 SHA-384 - id-PSC-ECDH-ECSchnorr-SHA-512 SHA-512 - Table 13: Object Identifiers for PSM and PSC based on ECSchnorr with ECDH - - - -For the Pseudonymous Signature based on EC-Schnorr, the plain signature format SHALL be used, i.e. -the signature (e , s 1, s 2 ) SHALL be encoded as an octet string as octet string e||S 1||S 2 format, where - e is of hash length and S 1 and S 2 are the integers s1 and s 2 encoded as octet string with length -equal to the length of the order of the base point, respectively. - - -A.6.5.1. Credentials for PSC -The data that is signed by the ICC during Pseudonymous Signature of Credentials MUST have the -following structure - - - - -52 Bundesamt für Sicherheit in der Informationstechnik - ASN.1 Specifications (Normative) A. - - - • A discretionary data template containing a sequence of discretionary data objects with order as - given by the file IDs or data object tags as specified in the command data field of the - corresponding command APDU. - • Each discretionary data object contains the logical content of the corresponding data group or - Specific Attribute, respectively. - - - Data Object - Discretionary Data Template - Discretionary Data - ... - Table 14: Credential data format for PSC - - - - -A.7. Terminal Authentication - -A.7.1. Public Key References -Public keys to be used for Terminal Authentication MUST be contained in CV Certificates according to -the certificate profile defined in Appendix C.1. Each CV Certificate MUST contain two public key -references, a Certificate Holder Reference and a Certification Authority Reference: -Certificate Holder Reference: The Certificate Holder Reference is an identifier for the public key -provided in the certificate that SHALL be used to reference this public key. -Certification Authority Reference: The Certification Authority Reference is a reference to the (external) -public key of the certification authority that SHALL be used to verify the signature of the certificate. - -Note: As a consequence, the Certification Authority Reference contained in a certificate MUST be equal -to the Certificate Holder Reference in the corresponding certificate of the issuing certification -authority. - - - Encoding Length - Country Code ISO 3166-1 ALPHA-2 2F - Holder Mnemonic ISO/IEC 8859-1 9V - Sequence Number ISO/IEC 8859-1 5F - F: fixed length (exact number of octets) - V: variable length (up to number of octets) - Table 15: Certificate Holder Reference - -The Certificate Holder Reference SHALL consist of the following concatenated elements: Country Code, -Holder Mnemonic, and Sequence Number. Those elements MUST be chosen according to Table 15 and -the following rules: - 1. Country Code - The Country Code SHALL be the ISO 3166-1 ALPHA-2 code of the certificate holder’s country. - -Bundesamt für Sicherheit in der Informationstechnik 53 - A. ASN.1 Specifications (Normative) - - - 2. Holder Mnemonic - The Holder Mnemonic SHALL be assigned as unique identifier as follows: - • The Holder Mnemonic of a CVCA SHALL be assigned by the CVCA itself. - • The Holder Mnemonic of a DV SHALL be assigned by the domestic CVCA. - • The Holder Mnemonic of an IS SHALL be assigned by the supervising DV. - 3. Sequence Number - The Sequence Number SHALL be assigned by the certificate holder. - • The Sequence Number MUST be numeric or alphanumeric: - – A numeric Sequence Number SHALL consist of the characters “0”...”9”. - – An alphanumeric Sequence Number SHALL consist of the characters “0”...”9” and “A”...”Z”. - • The Sequence Number MAY start with the ISO 3166-1 ALPHA-2 country code of the certifying - certification authority, the remaining three characters SHALL be assigned as alphanumeric - Sequence Number. - • The Sequence Number MAY be reset if all available Sequence Numbers are exhausted. - - -A.7.2. Public Key Import -Public keys imported by the certificate validation procedure (cf. Section 2.5) are either permanently or -temporarily stored on the ICC. - -Note: The ICC SHOULD reject to import a public key, if the Certificate Holder Reference is already -known to the ICC. - - -A.7.2.1. Permanent Import -Public keys contained in CVCA Link Certificates SHALL be permanently imported by the ICC and -MUST be stored securely in the ICC's memory. A permanently imported public key and its metadata -SHALL fulfill the following conditions: - • It MAY be overwritten after expiration by a subsequent permanently imported public key. - • It MUST - ◦ either be overwritten by a subsequent permanently imported public key with the same - Certificate Holder Reference - ◦ or the import MUST be rejected. - • It MUST NOT be overwritten by a temporarily imported public key. -Enabling and disabling a permanently imported public key MUST be an atomic operation. - - -A.7.2.2. Temporary Import -Public keys contained in DV and Terminal Certificates SHALL be temporarily imported by the ICC. A -temporarily imported public key and its metadata SHALL fulfill the following conditions: - • It SHALL NOT be selectable or usable after a power down of the ICC. - -54 Bundesamt für Sicherheit in der Informationstechnik - ASN.1 Specifications (Normative) A. - - - • It MUST remain usable until the subsequent cryptographic operation is successfully completed - (i.e. PSO:Verify Certificate or External Authenticate). - • It MAY be overwritten by a subsequent temporarily imported public key. -A terminal MUST NOT make use of any temporarily imported public key but the most recently -imported. - - -A.7.2.3. Imported Metadata -For each permanently or temporarily imported public key the following additional data contained in -the certificate (cf. Appendix C.1) MUST be stored: - • Certificate Holder Reference - • Certificate Holder Authorization (effective role and effective authorization) - • Certificate Effective Date - • Certificate Expiration Date - • Certificate Extensions (where applicable) -The calculation of the effective role (CVCA, DV, or Terminal) and the effective authorization of the -certificate holder is described in Section 2.7. - -Note: The format of the stored data is operating system dependent and out of the scope of this -specification. - - -A.7.2.4. EF.CVCA -Support for the elementary file EF.CVCA is CONDITIONAL. If the ICC supports Terminal -Authentication in version 1 it MUST make the references of CVCA public keys suitable for inspection -systems available in a transparent elementary file EF.CVCA contained in the ePassport application as -specified in Table 16. - - File Name EF.CVCA - File ID 0x011C (default) - Short File ID 0x1C (default) - Read Access BAC or PACE (conditional to protocol support) - Write Access NEVER (internally updated only) - Size 36 bytes (fixed) padded with octets of value 0x00 - Content [CARi ][||CARi-1][||0x00..00] - Table 16: Elementary File EF.CVCA - - -This file SHALL contain a sequence of Certification Authority Reference (CAR) data objects (cf. -Appendix D.2) suitable for Terminal Authentication. - • It SHALL contain at most two Certification Authority Reference data objects. - • The most recent Certification Authority Reference SHALL be the first data object in this list. - - - -Bundesamt für Sicherheit in der Informationstechnik 55 - A. ASN.1 Specifications (Normative) - - - • The file MUST be padded by appending octets of value 0x00. -The file EF.CVCA has a default file identifier and short file identifier. If the default values cannot be used, -the (short) file identifier SHALL be specified in the OPTIONAL parameter efCVCA of the -TerminalAuthenticationInfo. If efCVCA is used to indicate the file identifier to be used, the -default file identifier is overridden. If no short file identifier is given in efCVCA, the file EF.CVCA MUST -be explicitly selected using the given file identifier. - - -A.7.3. Terminal Authentication with RSA -For Terminal Authentication with RSA the following algorithms and formats MUST be used. - - -A.7.3.1. Signature Algorithm -RSA [17], [27] as specified in Table 17 SHALL be used. The default parameters to be used with RSA-PSS -are defined as follows: - • Hash Algorithm: The hash algorithm is selected according to Table 17. - • Mask Generation Algorithm: MGF1 [17], [27] using the selected hash algorithm. - • Salt Length: Octet length of the output of the selected hash algorithm. - • Trailer Field: 0xBC - -A.7.3.2. Public Key Format -The TLV-Format [14] as described in Appendix D.3.1 SHALL be used. - • The object identifier SHALL be taken from Table 17. - • The bit length of the modulus SHALL be 1024, 1280, 1536, 2048, or 3072. - • The bit length of the exponent SHALL be at most 32. - - OID Signature Hash Parameters - id-TA-RSA-v1-5-SHA-1 RSASSA-PKCS1-v1_5 SHA-1 N/A - id-TA-RSA-v1-5-SHA-256 RSASSA-PKCS1-v1_5 SHA-256 N/A - id-TA-RSA-v1-5-SHA-512 RSASSA-PKCS1-v1_5 SHA-512 N/A - id-TA-RSA-PSS-SHA-1 RSASSA-PSS SHA-1 default - id-TA-RSA-PSS-SHA-256 RSASSA-PSS SHA-256 default - id-TA-RSA-PSS-SHA-512 RSASSA-PSS SHA-512 default - Table 17: Object Identifiers for Terminal Authentication with RSA - - -A.7.4. Terminal Authentication with ECDSA -For Terminal Authentication with ECDSA the following algorithms and formats MUST be used. - - - - -56 Bundesamt für Sicherheit in der Informationstechnik - ASN.1 Specifications (Normative) A. - - -A.7.4.1. Signature Algorithm - - - OID Signature Hash - id-TA-ECDSA-SHA-1 ECDSA SHA-1 - id-TA-ECDSA-SHA-224 ECDSA SHA-224 - id-TA-ECDSA-SHA-256 ECDSA SHA-256 - id-TA-ECDSA-SHA-384 ECDSA SHA-384 - id-TA-ECDSA-SHA-512 ECDSA SHA-512 - Table 18: Object Identifiers for Terminal Authentication with ECDSA - -ECDSA with plain signature format [4] as specified in Table 18 SHALL be used. - - -A.7.4.2. Public Key Format -The TLV-Format [14] as described in Appendix D.3.3 SHALL be used. - • The object identifier SHALL be taken from Table 18. - • The bit length of the curve SHALL be 160, 192, 224, 256, 320, 384 or 512. - • Domain Parameters SHALL be compliant to [4]. - - -A.7.5. Authenticated Auxiliary Data for Terminal Authentication Version 2 -Usage of auxiliary data A PCD in Terminal Authentication is CONDITIONAL. It MUST be used if further -operations performed by the terminal require authenticated auxiliary data (details can be found in the -following sections): - • For age verification, the terminal MUST commit to the required date of birth. - • For document validity verification, the terminal MUST commit to the current date. - • For municipality ID verification, the terminal MUST commit to (parts of) the municipality ID. - • For PSM, the terminal MUST commit to the messages to be signed. - • For Data Group Content verification, the terminal MUST commit to the required data to be - verified. -Authenticated auxiliary data MUST be structured as specified in Table 19: - • An authentication data object that contains a sequence of discretionary data templates. - • Each discretionary data template contains an object identifier and a discretionary data object. - The content of the discretionary data object is defined by the object identifier. - - - - -Bundesamt für Sicherheit in der Informationstechnik 57 - A. ASN.1 Specifications (Normative) - - - - - Data Object - Authentication - Discretionary Data Template - Object Identifier - Discretionary Data - Discretionary Data Template - Object Identifier - Discretionary Data - ... - Table 19: Authenticated Auxiliary Data - - - -This structure SHALL be used as input for the signature computation during Terminal Authentication. -Only after a successful authentication of the terminal, the ICC SHALL interpret and make the data -contained in the discretionary data object available for further operations. Depending of the -application, the terminal MAY transmit additional discretionary data templates than listed in the -following. Discretionary data templates with unknown object identifier SHOULD be ignored by the -ICC. - -Note: If the authentication data object contains more than one discretionary data template with the -same object identifier, the data of the last discretionary data template SHALL be made available for -further operations. - - -A.7.5.1. Object Identifier -The following object identifier SHALL be used to identify authenticated auxiliary data: - id-AuxiliaryData OBJECT IDENTIFIER ::= { - bsi-de applications(3) mrtd(1) 4 - } - -A.7.5.2. Age Verification -The following object identifier SHALL be used for age verification: - id-DateOfBirth OBJECT IDENTIFIER ::= {id-AuxiliaryData 1} - -The discretionary data object SHALL contain the date of birth encoded as Date (cf. Part 2) that is -required by the terminal. The ICC SHALL compare the stored date of birth to the required date of birth. -Age Verification is successful if the stored date of birth is not after the required date of birth. - - -A.7.5.3. Document Validity Verification -The following object identifier SHALL be used for document validity verification: - id-DateOfExpiry OBJECT IDENTIFIER ::= {id-AuxiliaryData 2} - - -58 Bundesamt für Sicherheit in der Informationstechnik - ASN.1 Specifications (Normative) A. - - - -The discretionary data object SHALL contain the current date of the terminal encoded as Date (cf. Part -2). The ICC SHALL compare the stored date of expiry to the current date. Document Validity -Verification is successful if the stored date of expiry is not before the given current date. - - -A.7.5.4. Municipality ID Verification -The following object identifier SHALL be used for municipality ID verification: - id-MunicipalityID OBJECT IDENTIFIER ::= {id-AuxiliaryData 3} - -The discretionary data object SHALL contain (parts of) the municipality ID encoded as OctetString -(cf. Part 2). The ICC SHALL compare the leftmost octets of the stored municipality ID to the transmitted -(part of the) requested municipality ID. Municipality ID Verification is successful if the leftmost octets -of the stored data are identical to the transmitted data. - - -A.7.5.5. Pseudonymous Signature of Messages -The following object identifier SHALL be used to authenticate a message to be signed by the ICC via -PSM: - id-PSM-Message OBJECT IDENTIFIER ::= {id-AuxiliaryData 4} - -The discretionary data object SHALL contain the hash value of the input to be signed encoded as -Octet String. When a Pseudonymous Signature is requested by the Terminal after authentication, -the ICC SHALL verify that the hash of the transmitted input was contained in the authenticated -auxiliary data using the hash function defined by Terminal Authentication. If this verification fails, the -ICC MUST deny to sign the input via PSM. - - -A.7.5.6. Data Group Content Verification -The following object identifiers SHALL be used for Data Group Content verification - id-DGContent OBJECT IDENTIFIER ::= {id-AuxiliaryData 5} - - id-DGContent-DG1 OBJECT IDENTIFIER ::= {id-DGContent 1} - id-DGContent-DG2 OBJECT IDENTIFIER ::= {id-DGContent 2} - id-DGContent-DG3 OBJECT IDENTIFIER ::= {id-DGContent 3} - id-DGContent-DG4 OBJECT IDENTIFIER ::= {id-DGContent 4} - id-DGContent-DG5 OBJECT IDENTIFIER ::= {id-DGContent 5} - id-DGContent-DG6 OBJECT IDENTIFIER ::= {id-DGContent 6} - id-DGContent-DG7 OBJECT IDENTIFIER ::= {id-DGContent 7} - id-DGContent-DG8 OBJECT IDENTIFIER ::= {id-DGContent 8} - id-DGContent-DG9 OBJECT IDENTIFIER ::= {id-DGContent 9} - id-DGContent-DG10 OBJECT IDENTIFIER ::= {id-DGContent 10} - id-DGContent-DG11 OBJECT IDENTIFIER ::= {id-DGContent 11} - id-DGContent-DG12 OBJECT IDENTIFIER ::= {id-DGContent 12} - id-DGContent-DG13 OBJECT IDENTIFIER ::= {id-DGContent 13} - id-DGContent-DG14 OBJECT IDENTIFIER ::= {id-DGContent 14} - id-DGContent-DG15 OBJECT IDENTIFIER ::= {id-DGContent 15} - id-DGContent-DG16 OBJECT IDENTIFIER ::= {id-DGContent 16} - id-DGContent-DG17 OBJECT IDENTIFIER ::= {id-DGContent 17} - id-DGContent-DG18 OBJECT IDENTIFIER ::= {id-DGContent 18} - id-DGContent-DG19 OBJECT IDENTIFIER ::= {id-DGContent 19} - - -Bundesamt für Sicherheit in der Informationstechnik 59 - A. ASN.1 Specifications (Normative) - - - id-DGContent-DG20 OBJECT IDENTIFIER ::= {id-DGContent 20} - id-DGContent-DG21 OBJECT IDENTIFIER ::= {id-DGContent 21} - id-DGContent-DG22 OBJECT IDENTIFIER ::= {id-DGContent 22} - -The discretionary data object SHALL contain the data encoded as BIT STRING. The ICC SHALL -compare the data with the binary logical content of the corresponding data group. Data Group -Verification is successful if the transmitted data is identical with the logical content of the -corresponding data group. - -Note: To support Data Group Content Verification for further data groups in future, the list of object -identifiers will be continued accordingly. - - -A.8. Enhanced Role Authentication - -A.8.1. Data format of Attribute Request -For Enhanced Role Authentication, Attribute Requests stored on the ICC SHALL be of the following type. - RequestInfos ::= SET OF RequestInfo - - RequestInfo ::= SEQUENCE { - requestType OBJECT IDENTIFIER, - requiredData ANY DEFINED BY requestType, - optionalData ANY DEFINED BY requestType OPTIONAL - } - -A.8.2. Data format of Specific Attributes -The following ASN.1 structure SHALL be used to store Attributes for Enhanced Role Authentication on the -ICC. - Attribute ::= SEQUENCE { - attributeType OBJECT IDENTIFIER, - requiredData ANY DEFINED BY attributeType - optionalData ANY DEFINED BY attributeType -} - - - - -60 Bundesamt für Sicherheit in der Informationstechnik - ISO 7816 Mapping (Normative) B. - - - -B. ISO 7816 Mapping (Normative) -In this Appendix the protocols for PACE, Chip Authentication and Terminal Authentication are mapped -to ISO 7816 APDUs (Application Protocol Data Units). - - -B.1. PACE -The following sequence of commands SHALL be used to implement PACE. Secure messaging is -CONDITIONAL. It MUST be used for the second execution of PACE if the protocol is executed twice: - 1. MSE:Set AT - 2. General Authenticate -The command MSE:Set AT contains the following data objects (see B.14.1 for details). - Tag Comment -0x80 Cryptographic mechanism reference REQUIRED -0x83 Password reference REQUIRED -0x84 Reference for computing a session key CONDITIONAL -0x7F4C Certificate Holder Authorization Template CONDITIONAL -0x65 Certificate Extensions CONDITIONAL - - -The protocol specific data objects SHALL be exchanged in a chain of General Authenticate commands -as shown below: - Step Description Protocol Command Data Protocol Response Data - 1. Encrypted Nonce - Absent5 0x80 Encrypted Nonce - 2. Map Nonce 0x81 Mapping Data 0x82 Mapping Data - 3. Perform Key Agreement 0x83 Ephemeral Public Key 0x84 Ephemeral Public Key - 4. Mutual Authentication 0x85 Authentication Token 0x86 Authentication Token - 0x87 Certification Authority - Reference - (CONDITIONAL) - 0x88 Certification Authority - Reference - (CONDITIONAL) - -The Certificate Authority Reference(s) are REQUIRED if PACE is used with a Certificate Holder -Authorization Template, i.e. if PACE is to be followed by Terminal Authentication version 2. In this case -the data object 0x87 SHALL contain the most recent Certificate Authority Reference with respect to the -terminal type indicated in the Certificate Holder Authorization Template. The data object 0x88 MAY -contain the previous Certificate Authority Reference. - - - - -5 This implies an empty Dynamic Authentication Data Object. - -Bundesamt für Sicherheit in der Informationstechnik 61 - B. ISO 7816 Mapping (Normative) - - -Note: The domain parameters for PACE supported by the chip are made available in EF.CardAccess (cf. -Appendix A.1.2). If more than one set of domain parameters is supported, the terminal MUST select the -domain parameters to be used within MSE:Set AT. - - -B.1.1. Encrypted Nonce -The encrypted nonce (cf. Appendix A.3.3) SHALL be encoded as octet string. - - -B.1.2. Mapping Data -The exchanged data is specific to the used mapping. - -B.1.2.1. Generic Mapping -The ephemeral public keys (cf. Appendix A.2.2 and Appendix D.3.4) SHALL be encoded as elliptic curve -point (ECDH) or unsigned integer (DH). - - -B.1.2.2. Integrated Mapping -The Integrated Mapping is specified by ICAO [8]. - -B.1.3. Authentication Token -The authentication token (cf. Appendix A.2.4) SHALL be encoded as octet string. - - -B.1.4. Certification Authority Reference -The ICC SHALL return the Certificate Authority References of appropriate CVCA public keys stored on -the ICC: - • The references MUST be dynamically chosen to suit the terminal type indicated by PACE. - • It SHALL return at most two Certification Authority Reference data objects. - • The most recent Certification Authority Reference SHALL be contained in data object 0x87. - - -B.2. Chip Authentication -The following command SHALL be used with secure messaging to implement Chip Authentication in -version 1 with 3DES Secure Messaging: - 1. MSE:Set KAT - -Note: MSE:Set KAT MUST NOT be used for any other algorithms than id-CA-DH-3DES-CBC-CBC -and id-CA-ECDH-3DES-CBC-CBC, i.e. Secure Messaging is restricted to 3DES. -The following sequence of commands SHALL be used with secure messaging - • to implement Chip Authentication in version 1 with AES and - • to implement Chip Authentication in version 2. - - -62 Bundesamt für Sicherheit in der Informationstechnik - ISO 7816 Mapping (Normative) B. - - -Additionally, this sequence MAY be used to implement Chip Authentication version 1 with 3DES. - 1. MSE:Set AT - 2. General Authenticate -The command MSE:Set AT contains the following data objects (see B.14.1 for details). - Tag Comment -0x80 Cryptographic mechanism reference REQUIRED -0x84 Reference of a private key CONDITIONAL -0xE0 Template for Session Context Identifier CONDITIONAL - - -The protocol specific data objects SHALL be exchanged with a General Authenticate command as -shown below: - Step Description Protocol Command Data Protocol Response Data - 1. Chip Authentication 0x80 Ephemeral Public Key 0x81 Nonce - 0x82 Authentication Token - -Note: Support of Protocol Response Data is CONDITIONAL: It MUST be provided for version 2 but -MUST NOT be provided for version 1. - -Note: The public keys for Chip Authentication supported by the chip are made available in the Security -Objects (cf. Appendix A.1.2). If more than one public key is supported, the terminal MUST select the -corresponding private key of the chip to be used within MSE:Set AT. -The following sequence of commands SHALL be used with secure messaging to implement Chip -Authentication Version 3: - 1. MSE:Set AT - 2. General Authenticate - 3. MSE:Set AT - 4. General Authenticate -The first MSE:Set AT command of step 1 contains the following data objects (see B.14.1 for details). - Tag Comment -0x80 Cryptographic mechanism reference REQUIRED -0x84 Reference of a private key REQUIRED -0xE0 Template for Session Context Identifier CONDITIONAL - - -The protocol specific data objects for the key agreement during Chip Authentication Version 3 SHALL -be exchanged in command number 2 by means of a General Authenticate command as shown below. - Step Description Protocol Command Data Protocol Response Data - 1. Perform Key Agreement 0x80 Ephemeral Public Key 0x81 Ephemeral Public Key - - Table 20: Chip Authentication Version 3 - General Authenticate command for Key Agreement - - - -Bundesamt für Sicherheit in der Informationstechnik 63 - B. ISO 7816 Mapping (Normative) - - -The MSE:Set AT command of step 3 contains the following data objects (see B.14.1 for details). - Tag Comment -0x80 Cryptographic mechanism reference REQUIRED -0x84 Reference of a private key REQUIRED - - -The protocol specific data objects for PSA during Chip Authentication Version 3 SHALL be exchanged in -command number 4 with a General Authenticate command as shown below. - Step Description Protocol Command Data Protocol Response Data - 1. Compute Pseudonymous 0x80 Sector Public Key 0x82 1st Pseudonym Public - Signature Key (CONDITIONAL) - 0x83 2nd Pseudonym Public - Key (CONDITIONAL) - 0x84 Pseudonymous - Signature - - Table 21: Chip Authentication Version 3 - General Authenticate command for PSA - -The ICC MUST compute the Pseudonymous Signature over the context-specific data object 0x81 of step -2 (including tag 0x81 and length) encapsulating the ICC's ephemeral public key. -If applicable, the steps 3. and 4. MAY be repeated with a different ICC's private key and/or different -Terminal Sector Public keys. - -Note: The ICC's private key pair for Chip Authentication Version 3 supported by the chip are indicated -in the relevant Security Objects. If more than one private key is supported, the Terminal MUST select -the private key to be used within MSE:Set AT. -Note: If Chip Authentication Version 3 is supported by the ICC, this protocol SHALL be available in the -Master File. Availability on application level is application-specific. - - -B.2.1. Ephemeral Public Key -The ephemeral public keys (cf. Appendix A.2.2 and Appendix D.3.4) SHALL be encoded as elliptic curve -point (ECDH) or unsigned integer (DH). - - -B.2.2. Nonce -The nonce SHALL be encoded as octet string of size 8 octets. - - -B.2.3. Authentication Token -The authentication token (cf. Appendix A.2.4) SHALL be encoded as octet string. - - - - -64 Bundesamt für Sicherheit in der Informationstechnik - ISO 7816 Mapping (Normative) B. - - -B.2.4. Sector Public Key -The Sector Public Key PK Sector for Chip Authentication Version 3 SHALL be encoded as elliptic curve -point (cf. D.2.1.2). The domain parameters SHALL NOT be included. - - -B.2.5. Pseudonym Public Key -The Pseudonym Public Key SHALL be encoded as an elliptic curve point (cf. A.2.2 and D.3.4). The -domain parameters SHALL NOT be included. - - -B.2.6. Pseudonymous signature -The pseudonymous signature SHALL be encoded as an octet string according to A.6.5. - - -B.3. Terminal Authentication -The following sequence of commands SHALL be used with secure messaging to implement Terminal -Authentication: - 1. MSE:Set DST - 2. PSO:Verify Certificate - 3. MSE:Set AT - 4. Get Challenge - 5. External Authenticate -Steps 1 and 2 are repeated for every CV certificate to be verified (CVCA Link Certificates, DV Certificate, -Terminal Certificate). -The command MSE:Set DST contains the following data objects (see B.14.4 for details). - Tag Comment -0x83 Reference of a public key REQUIRED - - -The Command MSE:Set AT contains the following data objects (see B.14.1 for details). - Tag Comment -0x80 Cryptographic mechanism reference REQUIRED -0x83 Reference of a public key REQUIRED -0x67 Auxiliary authenticated data CONDITIONAL -0x91 Ephemeral Public Key REQUIRED - - -For Terminal Authentication in version 2 the ICC MUST in addition support the usage of Get Challenge -before step 1, i.e. the ICC MUST keep a generated challenge upon usage by External Authenticate. - - - - -Bundesamt für Sicherheit in der Informationstechnik 65 - B. ISO 7816 Mapping (Normative) - - - -B.4. Restricted Identification -The following sequence of commands SHALL be used with secure messaging to implement Restricted -Identification: - 1. MSE:Set AT - 2. General Authenticate -The command MSE:Set AT contains the following data objects (see B.14.1 for details). - Tag Comment -0x80 Cryptographic mechanism reference REQUIRED - - -The protocol specific data objects SHALL be exchanged with General Authenticate commands as shown -below, command chaining MUST NOT be used. At least one of the steps MUST be executed: - Step Description Protocol Command Data Protocol Response Data - 1. Restricted Identification 0xA0 1st Sector Public Key 0x81 1st Sector-specific - (CONDITIONAL) Identifier - 2. Restricted Identification 0xA2 2nd Sector Public Key 0x83 2nd Sector-specific - (CONDITIONAL) Identifier - -Note: The private keys for Restricted Identification supported by the chip are indicated in the relevant -Security Objects (cf. Appendix A.1.2). If more than one private key is supported, the terminal MUST -select the private key to be used within MSE:Set AT. - -Note: If Restricted Identification is supported by the ICC, availability of the protocol is -application-specific. - - -B.4.1. Public Key -The Sector Public Key PK Sector SHALL be encoded as public key data object without tag 0x7F49 (i.e. -0x7F49 is replaced by 0xA0/0xA2, respectively) (cf. Appendix D.3), the domain parameters MUST be -included. - - -B.4.2. Sector-specific Identifier -The sector-specific identifier I Sector - ID SHALL be encoded as octet string. - - -B.5. Pseudonymous Signature of Messages or Credentials -The following sequence of commands SHALL be used to implement the Pseudonymous Signature of a -Message: - 1. MSE:Set DST - 2. PSO: Compute Digital Signature -The Command MSE:Set DST contains the following data objects (see B.14.4 for details). - - -66 Bundesamt für Sicherheit in der Informationstechnik - ISO 7816 Mapping (Normative) B. - - - Tag Comment -0x80 Cryptographic mechanism reference REQUIRED -0xE1 File Reference CONDITONAL -x84 Reference of a private key REQUIRED - - -The protocol specific data objects SHALL be exchanged in a PSO:Compute Digital Signature -command as shown below. - Step Description Protocol Command Data Protocol Response Data - 1. Compute Pseudonymous 0x80 Sector Public Key 0x82 Pseudonym Public Key - Signature of a Message (CONDITIONAL) - 0x81 Input to be signed 0x83 Pseudonym Public Key - (CONDITIONAL) (CONDITIONAL) - 0x84 Pseudonymous - Signature - - Table 22: Pseudonymous Signature of Messages - PSO:Compute Digital Signature command - -The input to be signed MUST be present if PSM is performed. In this case, the hash value of the input -using the hash function of Terminal Authentication MUST have been sent to the ICC by the terminal in -authenticated auxiliary data as part of Terminal Authentication. The ICC MUST compute the -Pseudonymous Signature over plain value of tag 0x81. -For PSC, the input MUST be absent. In this case, the ICC MUST compute the Pseudonymous Signature -over the data template defined in A.6.5.1 encapsulating the content of the files and Attributes as -indicated in the MSE:Set DST command. - -Note: If the terminal requests a Specific Attribute to be included into the Pseudonymous Signature of -Credentials computation and the terminal is not authorized to get access to all Terminal Sectors, the -ICC MUST require the terminal to present its user ID before execution of the protocol. - -Note: If the terminal requests Specific Attributes to be included into the Pseudonymous Signature of -Credentials computation and the terminal is authorized to get access to all Terminal Sectors, the ICC -MUST include the Specific Attributes in the same order into the data template of case, the ICC MUST -compute the Pseudonymous Signature over the data template defined in A.6.5.1 as in the Get Data -response according to B.10.5. - -Note: The private keys for Pseudonymous Signature supported by the chip are indicated in the relevant -Security Objects. If more than one private key is supported, the Terminal MUST select the private key to -be used within MSE:Set DST. - -Note: If Pseudonymous Signatures of Messages and/or Pseudonymous Signatures of Credentials are -supported by the ICC, availability of PSM and/or PSC is application-specific. - - -B.5.1. Sector Public Key -The Sector Public Key PK Sector SHALL be encoded as elliptic curve point (ECDH) (cf. A.2.2 and D.3.4). -The domain parameters SHALL NOT be included. - - -Bundesamt für Sicherheit in der Informationstechnik 67 - B. ISO 7816 Mapping (Normative) - - -B.5.2. Pseudonym Public Key -The Pseudonym Public Key SHALL be encoded as an elliptic curve point (cf. A.2.2 and D.3.4). The -domain parameters SHALL NOT be included. - - -B.5.3. Pseudonymous signature -The pseudonymous signature SHALL be encoded as an octet string according to Appendix A.6.5 -(ECDH). - - -B.6. Auxiliary Data Verification -One or both of the following commands SHALL be used with secure messaging to implement Age -Verification, Document Validity Verification and Municipality ID Verification: - • Verify - • Compare -For the remaining verification functions, the following command MUST be used with secure messaging -for implementation: - • Compare -The following authenticated auxiliary data MUST have been sent to the ICC as part of Terminal -Authentication: - • For Age Verification the terminal MUST have sent the required date of birth. - • For Document Validity Verification, the terminal MUST have sent the current date. - • For Municipality ID Verification, the terminal MUST have sent the (part of the) municipality ID. - • For Data Group Content Verification, the terminal MUST have sent the required data to be - compared with a data group. - - -B.7. PIN Management - -B.7.1. Unblock or Change PIN -The following command SHALL be used with secure messaging to implement unblocking and/or -changing of the PIN: - 1. Reset Retry Counter - • To set a new PIN and reset the retry counter the terminal SHALL use Reset Retry Counter - with the new PIN as data. - • To reset the retry counter the terminal SHALL use Reset Retry Counter with no data. -Usage of the command SHALL be restricted to authorized terminals: Before using this command the -terminal must either authenticate as Authentication Terminal with effective authorization for PIN -Management or by using PACE with the PUK/PIN. - - - -68 Bundesamt für Sicherheit in der Informationstechnik - ISO 7816 Mapping (Normative) B. - - -B.7.2. Activate or Deactivate PIN -The following command SHALL be used with secure messaging to activate the PIN: - 1. Activate -The following command SHALL be used with secure messaging to deactivate the PIN: - 1. Deactivate -Usage of the command SHALL be restricted to authorized terminals: Before using this command the -terminal must authenticate as Authentication Terminal with effective authorization for PIN -Management. - - -B.8. eSign Application -Commands for installing, updating, and using the eSign Application are out of scope of this -specification. - - -B.9. Reading Data Groups -The APDUs for selecting and reading EAC-protected data groups already specified by ICAO [8] SHALL -be used (i.e. Select File and Read Binary). In accordance with ICAO specifications any unauthorized -access to EAC-protected data groups SHALL be denied and the ICC MUST respond with status bytes -0x6982 (“Security status not satisfied”). - - -B.10. Enhanced Role Authentication -Usage of the commands of this section SHALL be restricted to authenticated terminals. - -Note: Within this section, the commands Put Data/Get Data/Delete Data are specified only as -interfaces for Enhanced Role Authentication. It is not required to support the whole functionalities of -data objects (e.g. access control management). - - -B.10.1. User Presentation -The following commands SHALL be used with secure messaging to implement the presentation of the -user for writing Attribute Requests or reading/deleting Specific Attributes. - 1. Perform User Operation:Present User - • The terminal SHALL present the hash of its Sector Public key as user ID in the data field of - the command APDU - • The ICC MUST verify that the received hash is contained in the Terminal Sector extension - as defined in C.3.2.1 of the terminal's CV Certificate. -If the user ID is unknown to the ICC, the ICC MUST return a warning 0x62XX to the terminal. In this -case, the ICC SHALL create the respective user by assigning an accessible data container to the user ID -and personalizing the access conditions of the data container. - - - - -Bundesamt für Sicherheit in der Informationstechnik 69 - B. ISO 7816 Mapping (Normative) - - -Note: The moment when a data container is created is implementation specific and out of scope of this -document. - -Note: The presentation of the user ID MUST only be valid within the corresponding session context. - - -B.10.2. Writing Attribute Requests -The following commands SHALL be used with secure messaging to implement writing of an Attribute -Request into the ICC's Attribute Request Container: - 1. Put Data - • The terminal SHALL send the RequestInfos in the data field of the command APDU - -Note: The ICC MUST require the terminal to present its user ID before writing an Attribute Request. -Writing Attribute Requests SHALL be restricted to authorized terminals. - - -B.10.3. Reading Attribute Requests -The following command SHALL be used with secure messaging to implement reading of an Attribute -Request from the ICC - 1. Get Data - • The ICC's response APDU MUST contain the RequestInfos in the data field. -Reading Attribute Requests SHALL be restricted to authorized terminals (Attribute Providers). - - -B.10.4. Writing Specific Attributes -The following command SHALL be used with secure messaging to implement writing of Attributes on -the ICC - 1. Put Data - • The terminal SHALL use the tag P1/P2=0x00FF with a list of discretionary data tags 0x53 - each containing a Specific Attribute in the command data field. -Writing Attribute SHALL be restricted to authorized terminals (Attribute Providers). - - -B.10.5. Reading Specific Attributes -The following command SHALL be used with secure messaging to implement reading of an Attribute -from the ICC - 1. Get Data - • If the terminal has effective authorization to access to Specific Attributes for all Terminal - Sectors, the response data field MUST contain the Specific Attributes for each Terminal - Sector contained in a discretionary data template 0x73. Otherwise, the response MUST - contain the Specific Attributes linked to the presented terminal's Sector Public Key. - - - - -70 Bundesamt für Sicherheit in der Informationstechnik - ISO 7816 Mapping (Normative) B. - - -Note: If the terminal's effective authorization is restricted to read Specific Attributes linked to the -Terminal Sector, the ICC MUST require the terminal to present its user ID before execution of the -command. -Usage of this command SHALL be restricted to authenticated terminals with effective authorization for -reading Specific Attributes. - - -B.10.6. Deleting Specific Attributes -The following command SHALL be used with secure messaging to implement deleting of an Attribute -from the ICC - 1. Delete Data - • If the terminal has effective authorization to delete to Specific Attributes for all Terminal - Sectors, the ICC MUST delete the Specific Attributes for each Terminal Sector. Otherwise, - the ICC MUST delete only the Specific Attributes linked to the presented terminal's Sector - Public Key. - -Note: If the terminal's effective authorization is restricted to delete Specific Attributes linked to the -Terminal Sector, the ICC MUST require the terminal to present its user ID before execution of the -command. -Usage of this command SHALL be restricted to authenticated terminals with effective authorization for -deleting Specific Attributes. - - -B.10.7. Writing and Reading and Erasing Generic Attributes -For reading and writing Generic Attributes the commands Read Binary, Update Binary and Erase Binary are -specified in [12]. - - -B.11. Switching of Session Context -If switching of Session Context is supported by the ICC, the PACE Session Context MUST be stored -immediately before restarting secure messaging or switching from PACE session context to another -session context. -The storage of the Chip Authentication Session Context is indicated within the command MSE: Set AT -of Chip Authentication Version 2 or Version 3. -To restore a stored Session Context, the following command SHALL be used with Secure Messaging: - 1. MSE:Set AT -The command MSE:Set AT contains the following data objects. - Tag Comment -0xE1 Template for Session Context Identifier REQUIRED - -Note: The current DF and current EF (and for Chip Authentication Session Context also a presented -user ID) are part of the session context and MUST be updated by the ICC as part of restoring the session -context accordingly. - - - - -Bundesamt für Sicherheit in der Informationstechnik 71 - B. ISO 7816 Mapping (Normative) - - -B.11.1. Session Context Identifier -The Session Context identifier is an integer encoded as single octet(see D.2.1.1) that MAY have values -between 0 and maxSCNo. The identifier 0 is reserved for the default Session Context and MUST NOT be -used for storing a Chip Authentication Session Context. - - -B.12. Extended Length -Depending on the size of the cryptographic objects (e.g. public keys, signatures), APDUs with extended -length fields MUST be used to send this data to the ICC. For details on extended length see [12]. - - -B.12.1. ICCs -For ICCs support of extended length is CONDITIONAL. If the cryptographic algorithms and key sizes -selected by the issuing state require the use of extended length, the ICCs SHALL support extended -length. In this case, to support terminals without extended length transport capability, ICCs of eIDAS -token SHOULD additionally support receiving extended length APDUs using Envelope/Get Response -TPDUs as specified in Appendix E. -If the ICC supports extended length, this MUST be indicated in the ATR/ATS or in EF.ATR/INFO as -specified in [12]. - - -B.12.2. Terminals -For terminals support of extended length is REQUIRED. A terminal SHOULD examine whether or not -support for extended length is indicated in the ICC’s ATR/ATS or in EF.ATR/INFO before using this -option. The terminal MUST NOT use extended length for APDUs other than the following commands -unless the exact input and output buffer sizes of the ICC are explicitly stated in the ATR/ATS or in -EF.ATR/INFO. - • PSO:Verify Certificate - • PSO:Compute Digital Signature - • MSE:Set KAT - • General Authenticate - • External Authenticate - - -B.12.3. Errors -The ICC SHALL indicate extended length errors with status bytes 0x6700. - - -B.13. Command Chaining -Command chaining is only used for the General Authenticate command. For details on command -chaining see [12]. - - - - -72 Bundesamt für Sicherheit in der Informationstechnik - ISO 7816 Mapping (Normative) B. - - -B.13.1. ICCs -For ICCs support of command chaining is REQUIRED and support for command chaining MUST be -indicated in the historical bytes of the ATR/ATS or in the EF.ATR/INFO as specified in [12]. - - -B.13.2. Terminals -For terminals support of command chaining is REQUIRED. A terminal SHOULD test whether or not -the ICC supports command chaining before using this option. - - -B.13.3. Errors -If the ICC expects the end of the chain, but receives a command that is not marked as the last -command, the ICC SHALL indicate that the last command in a chain was expected with status bytes -0x6883. - - -B.14. APDU Specification -In the following, the APDUs required to implement the protocols are described. The ICC SHALL -implement the APDUs as described but MAY deviate from the description if the APDUs are used in -other contexts. -The omitted CLA byte SHALL be set to indicate secure messaging with authenticated header, command -chaining and application specific encoding as required by the protocols (cf. Appendix F.3). -The sender of a command or response APDU MUST transmit the data objects in the data field in the -order as defined in the following. The receiver SHOULD be capable to process APDUs with data objects -given in any order. - - -B.14.1. MSE:Set AT -The command MSE:Set AT is used to select and initialize the following protocols: PACE, Chip -Authentication, Terminal Authentication, and Restricted Identification. -Command -INS 0x22 Manage Security Environment -P1/P2 0xC1A4 PACE: - Set Authentication Template for mutual authentication. - 0x41A4 Chip Authentication / Restricted Identification: - Set Authentication Template for internal authentication. - 0x81A4 Terminal Authentication: - Set Authentication Template for external authentication. - 0x01A4 Restoring Session Context: - Used to indicate restoring of a stored Session Context -Data 0x80 Cryptographic mechanism reference CONDITIONAL - Object Identifier of the protocol to select (value only, Tag - 0x06 is omitted). This data object is REQUIRED for all - - -Bundesamt für Sicherheit in der Informationstechnik 73 - B. ISO 7816 Mapping (Normative) - - - protocols except Terminal Authentication in version 1. - 0x83 Reference of a public key / secret key CONDITIONAL - This data object is REQUIRED for the following protocols: - – For PACE to indicate the password to be used: - 0x01: MRZ - 0x02: CAN - 0x03: PIN - 0x04: PUK - – For Terminal Authentication to select the public key of - the terminal by its ISO 8859-1 encoded name. - 0x84 Reference of a private key / Reference for computing a session CONDITIONAL - key - This data object is REQUIRED for the following protocols - (cf. Appendix A.2): - – For PACE to indicate the identifier of the domain - parameters to be used if the domain parameters are - ambiguous, i.e. more than one set of domain parameters - is available for PACE. - – For Chip Authentication to indicate the identifier of the - private key (including protocol version) to be used if - Chip Authentication Version 3 is supported or the - private key is ambiguous (cf. A.1.1.2). - – For Restricted Identification to indicate the private key - to be used i.e. more than one private key is available for - Restricted Identification. - 0x67 Auxiliary authenticated data CONDITIONAL - This data object is REQUIRED for Terminal Authentication - (version 2) if auxiliary data verification or PSM shall be - used. - 0x91 Ephemeral Public Key CONDITIONAL - This data object is REQUIRED for Terminal Authentication - if the terminal's ephemeral public key  PK PCD is unknown - or ambiguous to the ICC when Terminal Authentication is - performed (i.e. version 2). In this case the terminal's - compressed ephemeral public key Comp  PK PCD  MUST - be sent to the ICC. - 0x7F4C Certificate Holder Authorization Template CONDITIONAL - This data object (defined in C.1.5) is REQUIRED for PACE if - Terminal Authentication version 2 shall be used after - PACE. - 0x65 Certificate Extensions CONDITIONAL - This data object is REQUIRED for PACE if Terminal - Authentication version 2 shall be used after PACE and the - ICC supports Authorization Extensions. - In this case, it MUST encapsulate a sequence of - Authorization Extensions. - - If the ICC does not support Authorization Extensions, this - data object SHOULD be omitted. - - -74 Bundesamt für Sicherheit in der Informationstechnik - ISO 7816 Mapping (Normative) B. - - - 0xE0 If the ICC supports switching of Session Contexts, this CONDITIONAL - template MUST be present for Chip Authentication Version - 2 and the Key Agreement phase of Chip Authentication - Version 3 in case the corresponding Session Context shall - be stored immediately before switching to another Session - Context. - In this case, the template MUST encapsulate a tag 0x81 - containing the identifier of the Session Context. - - If the ICC does not support switching of Session Contexts, - this template SHOULD be omitted. - 0xE1 This REQUIRED for Restoring Session Context to indicate CONDITIONAL - that a stored Session Context shall be restored. - In this case, the template SHALL encapsulate a data object - 0x81 containing the identifier of the Session Context to be - restored. - - Otherwise, this template MUST be omitted. -Response -Data – Absent -Status 0x9000 Normal operation -Bytes The protocol has been selected and initialized. - 0x6A80 Incorrect parameters in the command data field - – Algorithm not supported or initialization failed. - – Terminal Type indicated by Certificate Holder Authorization Template is not - authorized to use referenced password. (PACE) - 0x6A88 Referenced data not found - The referenced data (i.e. password, private key, public key, domain parameter) is not - available. -PACE 0x63CX Warning - The password has been selected. X indicates the number of remaining verification - tries, if not equal to the initial value: - X=1: The password is suspended. The password MUST be resumed. - X=0: The password is blocked. The password MUST be unblocked. -PACE 0x6283 Warning - The password is deactivated. - other Operating system dependent error - The initialization of the protocol failed. - -Note: - • Some operating systems accept the selection of an unavailable public key and return an error - only when the public key is used for the selected purpose. - • Resuming and unblocking a password requires explicitly setting the CAN or the PUK using - MSE:Set AT. - - - - -Bundesamt für Sicherheit in der Informationstechnik 75 - B. ISO 7816 Mapping (Normative) - - -B.14.2. General Authenticate -The command General Authenticate is used to perform the following protocols: PACE, Chip -Authentication, and Restricted Identification. -Command -INS 0x86 General Authenticate -P1/P2 0x0000 Keys and protocol implicitly known. -Data 0x7C Dynamic Authentication Data REQUIRED - Protocol specific data objects. -Response -Data 0x7C Dynamic Authentication Data CONDITIONAL, see - Protocol specific data objects. below -Status 0x9000 Normal operation -Bytes The protocol (step) was successful. - 0x6300 Authentication failed - The protocol (step) failed. - 0x63CX Authentication failed - The protocol (step) failed. X indicates the number of remaining verification tries: - X=1: The password is suspended. The password MUST be resumed. - X=0: The password is blocked. The password MUST be unblocked. - 0x6982 Security status not satisfied - The terminal is not authorized to perform the protocol (e.g. the password is blocked, - deactivated, or suspended). - 0x6983 Authentication method blocked - The password is blocked. - 0x6984 Reference data not usable - The password is deactivated. - 0x6985 Conditions of use not satisfied - The password is suspended. - 0x6A80 Incorrect parameters in data field - Provided data is invalid. - other Operating system dependent error - The protocol (step) failed. - -Note: The ICC MAY indicate a blocked, deactivated, or suspended password by responding with status -bytes 0x6982 instead of using status bytes 0x6983, 0x6984, or 0x6985, respectively. -The response Dynamic Authentication Data object 0x7C - • MUST be present if the operation is successful, i.e. the Status Bytes are 0x9000, - • MUST be absent in case of an execution error or checking error, i.e. if the Status Bytes are in the - range 0x6400 - 0x6FFF, and - • MAY be absent in case of a warning, i.e. if the Status Bytes are in the range 0x6200 – 0x63FF. - -Note: The General Authenticate command with TPDU chaining is not supported for communication -protocol T=0 according to [11]. - -76 Bundesamt für Sicherheit in der Informationstechnik - ISO 7816 Mapping (Normative) B. - - -B.14.3. MSE:Set KAT -The command MSE:Set KAT is used to perform Chip Authentication version 1 with 3DES. -Command -INS 0x22 Manage Security Environment -P1/P2 0x41A6 Set Key Agreement Template for computation. -Data 0x91 Ephemeral Public Key REQUIRED - Ephemeral public key  PK PCD (cf. Appendix A.2) encoded - as plain public key value. - 0x84 Reference of a private key CONDITIONAL - This data object is REQUIRED if the private key is - ambiguous, i.e. more than one key pair is available for Chip - Authentication (cf. Appendix A.1.1.2, Appendix A.4.1.1 and - Appendix A.4.2.1). -Response -Data – Absent -Status 0x9000 Normal operation -Bytes The key agreement operation was successfully performed. New session keys have - been derived. - 0x6A80 Incorrect Parameters in the command data field - The validation of the ephemeral public key failed. The previously established session - keys remain valid. - other Operating system dependent error - The previously established session keys remain valid. - - -B.14.4. MSE:Set DST -The command MSE:Set DST is used to setup certificate verification for Terminal Authentication and to -setup signature computation for PSM or PSC . - - - - -Bundesamt für Sicherheit in der Informationstechnik 77 - B. ISO 7816 Mapping (Normative) - - -Command -INS 0x22 Manage Security Environment -P1/P2 0x81B6 Set Digital Signature Template for verification. - 0x41B6 Set Digital Signature Template for computation -Data 0x80 Cryptographic mechanism reference CONDITIONAL - This data object is REQUIRED for PSM or PSC to indicate - the object identifier of the protocol to select (value only, - Tag 0x06 is omitted). - 0xE1 File reference CONDITIONAL - The data object is REQUIRED for PSC and MUST contain - the following content: - • 0x80: MAY be present and encapsulate the - concatenation of two byte file IDs for data group - content to be integrated into the signature - computation. - • 0x81: MAY be present and contain the content - 0x00FF encoded as plain octet string (without tag - and length) if the Specific Attribute of the terminal - is to be integrated into signature computation. - 0x83 Reference of a public key CONDITIONAL - This data object is REQUIRED for Terminal Authentication - and contains the ISO 8859-1 encoded name of the public - key to be set - 0x84 Reference of a private key CONDITIONAL - This data object is REQUIRED for PSM or PSC -Response -Data – Absent -Status 0x9000 Normal Operation -Bytes The key has been selected for the given purpose. - 0x6A88 Referenced data not found - The selection failed as the public key is not available. - other Operating system dependent error - The key has not been selected. - -Note: Some operating systems accept the selection of an unavailable public key and return an error -only when the public key is used for the selected purpose. - - -B.14.5. PSO:Verify Certificate -The command PSO:Verify Certificate is used to verify and import certificates for Terminal -Authentication. - - - - -78 Bundesamt für Sicherheit in der Informationstechnik - ISO 7816 Mapping (Normative) B. - - -Command -INS 0x2A Perform Security Operation -P1/P2 0x00BE Verify self-descriptive certificate. -Data 0x7F4E Certificate body REQUIRED - The body of the certificate to be verified. - 0x5F37 Signature REQUIRED - The signature of the certificate to be verified. -Response -Data – Absent -Status 0x9000 Normal operation -Bytes The certificate was successfully validated and the public key has been imported. - other Operating system dependent error - The public key could not be imported (e.g. the certificate was not accepted). - - -B.14.6. Get Challenge -The command Get Challenge is used to perform Terminal Authentication. -Command -INS 0x84 Get Challenge -P1/P2 0x0000 -Data – Absent -Le 0x08 REQUIRED -Response -Data r PICC 8 bytes of randomness. -Status 0x9000 Normal operation -Bytes other Operating system dependent error - - -B.14.7. External Authenticate -The command External Authenticate is used to perform Terminal Authentication. -Command -INS 0x82 External Authenticate -P1/P2 0x0000 Keys and Algorithms implicitly known. -Data Signature generated by the terminal. REQUIRED -Response -Data – Absent -Status 0x9000 Normal operation -Bytes The authentication was successful. Access to data groups will be granted according to - the effective authorization of the corresponding verified certificate. - - - -Bundesamt für Sicherheit in der Informationstechnik 79 - B. ISO 7816 Mapping (Normative) - - -Response - 0x6300 Warning - Signature verification failed. - 0x6982 Security status not satisfied - The authentication failed as the current authentication level of the terminal does not - allow to use Terminal Authentication (e.g. Terminal Authentication was already - performed, etc.). - 0x6985 Conditions of use not satisfied - Terminal type set by PACE does not match terminal type contained in certificate - chain. - other Operating system dependent error - The authentication failed. - - -B.14.8. PSO: Compute Digital Signature -The command PSO:Compute Digital Signature is used to perform PSM or PSC. -Command -INS 0x2B Perform Security Operation -P1/P2 0x0200 Compute Digital Signature -Data 0x73 Discretionary Data Template REQUIRED - Protocol specific data objects. -Response -Data 0x73 Discretionary Data Template CONDITIONAL, see - Protocol specific data objects. below -Status 0x9000 Normal operation -Bytes The protocol (step) was successful. - 0x6982 Security status not satisfied - The terminal is not authorized to perform the protocol - 0x6A80 Incorrect parameters in data field - Provided data is invalid. - other Operating system dependent error - The protocol (step) failed. -The response Discretionary Data Template 0x73 - • MUST be present if the operation is successful, i.e. the Status Bytes are 0x9000, - • MUST be absent in case of an execution error or checking error, i.e. if the Status Bytes are in the - range 0x6400 - 0x6FFF, and - • MAY be absent in case of a warning, i.e. if the Status Bytes are in the range 0x6200 – 0x63FF. - - -B.14.9. Compare -The command Compare is used to verify authenticated auxiliary data, i.e. to perform age verification, -document validity verification, Municipality ID verification, phone number verification, email address -verification, or data group content verification. - -80 Bundesamt für Sicherheit in der Informationstechnik - ISO 7816 Mapping (Normative) B. - - -Command -INS 0x33 Compare -P1 0x00 Compare Binary -P2 0x00 Comparison defined by OID -Data Object Identifier of the auxiliary data to be compared REQUIRED -Response -Data – Absent -Status 0x9000 Normal operation -Bytes Comparison successful. - 0x6340 Comparison failed - Comparison failed. - 0x6A88 Referenced data not found - The referenced data was not found. - 0x6982 Security status not satisfied - The terminal is not authorized to perform verification. - other Operating system dependent error - The protocol (step) failed. - - -B.14.10. Verify -The command Verify is used to verify authenticated auxiliary data, i.e. to perform age verification, -document validity verification, or Municipality ID verification. - -Note: Due to the application specific coding the proprietary class (with secure messaging and no -chaining) MUST be used, i.e. CLA=0x8C. -Command -INS 0x20 Verify -P1/P2 0x8000 Verify authenticated auxiliary data. -Data Object Identifier of the auxiliary data to be verified. REQUIRED -Response -Data – Absent -Status 0x9000 Normal operation -Bytes Verification successful. - 0x6300 Verification failed - Verification failed. - 0x6A88 Referenced data not found - The referenced data was not found. - 0x6982 Security status not satisfied - The terminal is not authorized to perform verification. - other Operating system dependent error - The protocol (step) failed. - - - -Bundesamt für Sicherheit in der Informationstechnik 81 - B. ISO 7816 Mapping (Normative) - - -B.14.11. Reset Retry Counter -The command Reset Retry Counter is used to unblock or change the PIN. -Command -INS 0x2C Reset Retry Counter -P1 0x02-0x03 see below -P2 0x03: PIN - -Data Context specific reset data depending on P1: REQUIRED - P1=0x02: new PIN - P1=0x03: Absent -Response -Data – Absent -Status 0x9000 Normal operation -Bytes Unblocking or changing of the PIN was successful. - 0x6982 Security status not satisfied - The terminal is not authorized to unblock or change the PIN. - other Operating system dependent error - Unblocking or changing of the PIN failed. - - -B.14.12. Activate -The command Activate is used to set the PIN to the state activated. -Command -INS 0x44 Activate -P1 0x10 Activate PIN referenced by parameter P2. -P2 0x03: PIN -Data Absent -Response -Data – Absent -Status 0x9000 Normal operation -Bytes PIN state has been set to activated. - 0x6982 Security status not satisfied - The terminal is not authorized to change the PIN state. - other Operating system dependent error - Changing of the PIN state failed. - - -B.14.13. Deactivate -The command Deactivate is used to set the PIN to the state deactivated. - - - - -82 Bundesamt für Sicherheit in der Informationstechnik - ISO 7816 Mapping (Normative) B. - - -Command -INS 0x04 Deactivate -P1 0x10 Deactivate PIN referenced by parameter P2. -P2 0x03: PIN -Data Absent -Response -Data – Absent -Status 0x9000 Normal operation -Bytes PIN state has been set to deactivated. - 0x6982 Security status not satisfied - The terminal is not authorized to change the PIN state. - other Operating system dependent error - Changing of the PIN state failed. - - -B.14.14. Perform User Operation:Present User -The command Perform User Operation:Present User is used to present the user for writing Attribute -Requests and reading Attributes. -Command -INS 0x14 Perform User Operation -P1/P2 0x0080 Present User -Data 0x7F21 The data object MUST contain a Discretionary Data Template 0x73 encapsulating the - following content: - • 0x80: Hash of Sector Public key -Response -Data – Absent -Status 0x9000 Normal operation -Bytes Operation successful - 0x62XX Warning: Unknown user ID - - other Operating system dependent error - - -B.14.15. Put Data -The command Put Data is used for Enhanced Role Authentication to store attribute requests and -specific attributes on the ICC. -Command -INS 0xDA Put Data -P1/P2 0xFF01 Store attribute request - 0x00FF Store specific attribute -Data Context-specific data depending on P1/P2 and the effective authorization of the - - -Bundesamt für Sicherheit in der Informationstechnik 83 - B. ISO 7816 Mapping (Normative) - - - terminal - P1/P2=0xFF01: Tag 0x53 containing the ASN.1 structure Attribute Request. - P1/P2=0x00FF: Concatenation of tags 0x53 each containing a specific attribute to be - stored on the ICC. -Response -Data – Absent -Status 0x9000 Normal operation -Bytes Operation successful - 0x6982 Security status not satisfied - The terminal is not authorized to perform the operation - other Operating system dependent error - -Note: The Coding of P1/P2=0x00FF appends the content of the currently selected EF supporting DOs or -currently selected DO, respectively. - - -B.14.16. Get Data -The command Get Data is used for Enhanced Role Authentication to read attribute requests and -specific attributes from the ICC. -Command -INS 0xCA Get Data -P1/P2 0xFF01 Get attribute request - 0x00FF Read Specific Attributes: Get Current Template -Data Absent - -Response -Data Context-specific data depending on P1/P2 and the effective authorization of the - terminal - P1/P2=0xFF01: ASN.1 structure RequestInfos - P1/P2=0x00FF: Concatenation of Discretionary Data Templates 0x73 encapsulating - • 0x80: Terminal Sector (CONDITIONAL) - MUST be present if and only if the terminal is authorized to access all - Specific Attributes - • Concatenation of tags 0x53: Specific Attribute (REQUIRED) -Status 0x9000 Normal operation -Bytes Operation successful - 0x6982 Security status not satisfied - The terminal is not authorized to perform the operation - other Operating system dependent error - -Note: The Coding of P1/P2=0x00FF retrieves the content of the currently selected EF supporting DOs -or currently selected DO, respectively. - - - - -84 Bundesamt für Sicherheit in der Informationstechnik - ISO 7816 Mapping (Normative) B. - - -B.14.17. Delete Data -The command Delete Data is used for Enhanced Role Authentication to delete Specific Attributes from -the ICC. -Command -INS 0xEE Delete Data -P1/P2 0x0000 -Data Absent - -Response -Data – Absent -Status 0x9000 Normal operation -Bytes Operation successful - 0x6982 Security status not satisfied - The terminal is not authorized to perform the operation - other Operating system dependent error - - - - -Bundesamt für Sicherheit in der Informationstechnik 85 - C. CV Certificates (normative) - - - -C. CV Certificates (normative) - -C.1. Certificate Profile -Self-descriptive card verifiable (CV) certificates according to ISO 7816 (cf. [12], [13], [14]) and the -certificate profile specified in Table 23 SHALL be used. Details on the encoding of the data objects used -in the certificate profile can be found in Appendix D.2. - - -C.1.1. Certificate Profile Identifier -The version of the profile is indicated by the Certificate Profile Identifier. Version 1 as specified in Table -23 is identified by a value of 0. - - - Data Object Cert - CV Certificate m - Certificate Body m - Certificate Profile Identifier m - Certification Authority Reference m - Public Key m - Certificate Holder Reference m - Certificate Holder Authorization Template m - Certificate Effective Date m - Certificate Expiration Date m - Certificate Extensions o - Signature m - Table 23: CV Certificate Profile - -C.1.2. Certification Authority Reference -The Certification Authority Reference is used to identify the public key to be used to verify the -signature of the certification authority (CVCA or DV). The Certification Authority Reference MUST be -equal to the Certificate Holder Reference in the corresponding certificate of the certification authority -(CVCA Link Certificate or DV Certificate). Details on the Certification Authority Reference can be found -in Appendix A.7.1. - - -C.1.3. Public Key -Details on the encoding of public keys can be found in Appendix D.3. - - - - -86 Bundesamt für Sicherheit in der Informationstechnik - CV Certificates (normative) C. - - -C.1.4. Certificate Holder Reference -The Certificate Holder Reference is used to identify the public key contained in the certificate. Details -on the Certificate Holder Reference can be found in Appendix A.7.1. - - -C.1.5. Certificate Holder Authorization Template -The role and authorization of the certificate holder SHALL be encoded in the Certificate Holder -Authorization Template. This template is a sequence that consists of the following data objects: - 1. An object identifier that specifies the terminal type and the format of the template. - 2. A discretionary data object that encodes the relative authorization, i.e. the role and - authorization of the certificate holder relative to the certification authority. -The content and evaluation of the Certificate Holder Authorization Template is described in Appendix -Part 4 of this Technical Guideline. - - -C.1.6. Certificate Effective/Expiration Date -Indicates the validity period of the certificate. The Certificate Effective Date MUST be the date of the -certificate generation. - - -C.1.7. Certificate Extensions for Terminal Authentication Version 2 -Certificates MAY contain extensions as defined in Appendix C.3. - - -C.1.8. Signature -The signature on the certificate SHALL be created over the encoded certificate body (i.e. including tag -and length). The Certification Authority Reference SHALL identify the public key to be used to verify -the signature. - - -C.2. Certificate Requests -Certificate requests are reduced CV certificates that may carry an additional signature. The certificate -request profile specified in Table 24 SHALL be used. Details on the encoding of the data objects used in -the certificate request profile can be found in Appendix D.2. - - -C.2.1. Certificate Profile Identifier -The version of the profile is identified by the Certificate Profile Identifier. Version 1 as specified in Table -24 is identified by a value of 0. - - - - -Bundesamt für Sicherheit in der Informationstechnik 87 - C. CV Certificates (normative) - - - - Data Object Req - Authentication c - CV Certificate m - Certificate Body m - Certificate Profile Identifier m - Certification Authority Reference r - Public Key m - Certificate Holder Reference m - Certificate Extensions o - Signature m - Certification Authority Reference c - Signature c - Table 24: CV Certificate Request Profile - - - -C.2.2. Certification Authority Reference -The Certification Authority Reference SHOULD be used to inform the certification authority about the -private key that is expected by the applicant to be used to sign the certificate. If the Certification -Authority Reference contained in the request deviates from the Certification Authority Reference -contained in the issued certificate (i.e. the issued certificate is signed by a private key that is not -expected by the applicant), the corresponding certificate of the certification authority SHOULD also be -provided to the applicant in response. -Details on the Certification Authority Reference can be found in Appendix A.7.1. - - -C.2.3. Public Key -Details on the encoding of public keys can be found in Appendix D.3. - - -C.2.4. Certificate Holder Reference -The Certificate Holder Reference is used to identify the public key contained in the request and the -resulting certificate. Details on the Certificate Holder Reference can be found in Appendix A.7.1. - - -C.2.5. Certificate Extensions for Terminal Authentication Version 2 -Requests for certificates MAY contain extensions as defined in Appendix C.3. - - -C.2.6. Signature(s) -A certificate request may have two signatures, an inner signature and an outer signature: - - -88 Bundesamt für Sicherheit in der Informationstechnik - CV Certificates (normative) C. - - -Inner Signature (REQUIRED) - The certificate body is self-signed, i.e. the inner signature SHALL be verifiable with the public key - contained in the certificate request. The signature SHALL be created over the encoded certificate - body (i.e. including tag and length). -Outer Signature (CONDITIONAL) - – The signature is OPTIONAL if an entity applies for the initial certificate. In this case the request - MAY be additionally signed by another entity trusted by the receiving certification authority (e.g. - the national CVCA may authenticate the request of a DV sent to a foreign CVCA). - – The signature is REQUIRED if an entity applies for a successive certificate. In this case the request - MUST be additionally signed by the applicant using a recent key pair previously registered with - the receiving certification authority. -If the outer signature is used, an authentication data object SHALL be used to nest the CV Certificate -(Request), the Certification Authority Reference and the additional signature. The Certification -Authority Reference SHALL identify the public key to be used to verify the additional signature. The -signature SHALL be created over the concatenation of the encoded CV Certificate and the encoded -Certification Authority Reference (i.e. both including tag and length). - - - - Data Object - Certificate Extensions - Discretionary Data Template - Object Identifier - Context Specific Data Object 1 - ... - Context Specific Data Object n - Discretionary Data Template - Object Identifier - Context Specific Data Object 1 - ... - Context Specific Data Object m - ... - Table 25: Certificate Extensions - - -C.3. Certificate Extensions for Terminal Authentication Version 2 -The certificate extension is a sequence of discretionary data templates, where every discretionary data -template SHALL contain a sequence of the following data objects also shown in Table 25: - 1. An object identifier that specifies the content and the format of the extension. - 2. One or more context specific data objects that contain the encoded extension. -The following base object identifier is used to identify the certificate extensions: - - -Bundesamt für Sicherheit in der Informationstechnik 89 - C. CV Certificates (normative) - - - id-extensions OBJECT IDENTIFIER ::= { - bsi-de applictions(3) mrtd(1) 3 - } - -This Part of the Technical Guideline defines application independent extensions. Additional application -specific extensions are defined in Part 4. - -Note: The certificate validation procedure described in Section 2.5.1 does not take certificate extensions -into account. Thus, extensions are uncritical attributes and the ICC MUST NOT reject certificates due to -unknown extensions. Unknown extensions and extensions irrelevant for the ICC SHOULD NOT be -imported. - - -C.3.1. Authorization Extensions -A special type of certificate extension are Authorization Extensions. These extensions convey -authorizations additional to those in the Certificate Holder Authorization Template contained in the -certificate. Authorization Extensions contain exactly one discretionary data object that encodes the -relative authorization. -Authorization Extensions SHALL be evolving, i.e. new authorization bits MAY be appended to the -leftmost authorization bit in future versions of this Technical Guideline (cf. Table 26). Appended -authorization bits that are not supported by the ICC SHALL be ignored by the ICC. - - - Authorization Extension - (before evolution) - Discretionary Data Template - Object Identifier - Authorization Bit Mask - b8s+ b8s+ b8s+ ... b2 b1 b0 - 7 6 5 - - - - - Bits to be appended - ↓ - c8t+7 c8t+6 c8t+5 ... c2 c1 c0 - - - Authorization Extension - (after evolution) - Discretionary Data Template - Object Identifier - Authorization Bit Mask - c8t+7 ... c2 c1 b8s+ b8s+ ... b1 b0 - 7 6 - - - Table 26: Evolution of Authorization Extensions - - - - -90 Bundesamt für Sicherheit in der Informationstechnik - CV Certificates (normative) C. - - -C.3.2. Terminal Sector - -C.3.2.1. Terminal Sector for Restricted Identification -The following object identifier SHALL be used for this extension: - id-sector OBJECT IDENTIFIER ::= {id-extensions 2} - -This extension MUST be supported for Restricted Identification and Enhanced Role Authentication. -The following context specific data objects are used to encode the terminal sector: - • 0x80: Hash of 1st sector public key data object (cf. Appendix D.3). - • 0x81: Hash of 2nd sector public key data object (cf. Appendix D.3). -The hash function to be used SHALL be defined by the hash function used to sign the certificate. The -public key itself is not contained in the certificate and MUST be provided by the terminal as part of -Restricted Identification. The ICC SHALL compute the hash over the received public key and compare it -to the received hash. - -Note: Context-specific tagging is used for the sector public key in Restricted Identification (cf. Appendix -B.4.1). The ICC MUST replace the context-specific tag 0xA0 by the application-specific tag 0x7F49 before -computing the hash value. - - -C.3.2.2. Terminal Sector for Pseudonymous Signatures -The following object identifier SHALL be used to identify the terminal sector extension for the -Pseudonymous Signature (PS terminal sector): - id-PS-Sector OBJECT IDENTIFIER ::= { id-extensions 3 } - -A concatenation of the following context-specific data object is used to encode the PS terminal sector. -The data object MAY occur more than once. - • 0xA0: Discretionary Data Template consisting of - ◦ 0x80: ID of the domain parameters for Pseudonymous Signature - ◦ 0x81: Hash of Sector Public Key encoded as elliptic curve point, i.e. (without domain - parameters). -The hash function to be used SHALL be defined by the hash function used to sign the certificate. The -public key itself is not contained in the certificate and MUST be provided by the terminal as part of the -Pseudonymous Signature. -The ICC SHALL compute the hash of the received Sector Public Key and SHALL verify that the hash value -matches with the hash value encoded in one of the corresponding data templates of the certificate extension. - - -C.4. Certificate Policy -It is RECOMMENDED that each CVCA and every DV publishes a certificate policy and/or a certification -practice statement. - - - - -Bundesamt für Sicherheit in der Informationstechnik 91 - C. CV Certificates (normative) - - -C.4.1. Procedures -The certificate policy SHOULD specify the following procedures: - • Entity identification, authentication, and registration; - • Certificate application, issuance, and distribution; - • Compromise and disaster recovery; - • Auditing. - - -C.4.2. Usage Restrictions -The certificate policy SHOULD imply restrictions on the devices used to store/process corresponding -private keys and other sensitive (personal) data: - • Physical and operational security; - • Access control mechanisms; - • Evaluation and certification (e.g. Common Criteria Protection Profiles); - • Data Protection. - - - - -92 Bundesamt für Sicherheit in der Informationstechnik - DER Encoding (Normative) D. - - - -D. DER Encoding (Normative) -The Distinguished Encoding Rules (DER) according to X.690 [16] SHALL be used to encode both ASN.1 -data structures and (application specific) data objects. The encoding results in a Tag-Length-Value (TLV) -structure as follows: -Tag: The tag is encoded in one or two octets and indicates the content. -Length: The length is encoded as unsigned integer in one, two, or three octets resulting in a maximum - length of 65535 octets. The minimum number of octets SHALL be used. -Value: The value is encoded in zero or more octets. - - -D.1. ASN.1 -The encoding of data structures defined in ASN.1 syntax is described in X.690 [16]. - - -D.2. Data Objects -Table 27 gives an overview on the tags, lengths, and values of the data objects used in this specification. - -Name Tag Len Value Comment - -Object Identifier 0x06 V Object Identifier – -Certification Authority 0x42 16V Character String Identifies the public key of the issuing certification authority -Reference in a certificate. -Discretionary Data 0x53 V Octet String Contains arbitrary data. -Certificate Holder Reference 0x5F20 16V Character String Associates the public key contained in a certificate with an - identifier. -Certificate Expiration Date 0x5F24 6F Date The date after which the certificate expires. -Certificate Effective Date 0x5F25 6F Date The date of the certificate generation. -Certificate Profile Identifier 0x5F29 1F Unsigned Integer Version of the certificate and certificate request format. -Signature 0x5F37 V Octet String Digital signature produced by an asymmetric cryptographic - algorithm. -Certificate Extensions 0x65 V Sequence Nests certificate extensions. -Authentication 0x67 V Sequence Contains authentication related data objects. -Discretionary Data Template 0x73 V Sequence Nests arbitrary data objects. -CV Certificate 0x7F21 V Sequence Nests certificate body and signature. -Public Key 0x7F49 V Sequence Nests the public key value and the domain parameters. -Certificate Holder 0x7F4C V Sequence Encodes the role of the certificate holder (i.e. CVCA, DV, -Authorization Template Terminal) and assigns read/write access rights. -Certificate Body 0x7F4E V Sequence Nests data objects of the certificate body. - F: fixed length (exact number of octets), V: variable length (up to number of octets) - - Table 27: Overview on Data Objects (sorted by Tag) - - - - -Bundesamt für Sicherheit in der Informationstechnik 93 - D. DER Encoding (Normative) - - -D.2.1. Encoding of Values -The basic value types used in this specification are the following: (unsigned) integers, elliptic curve -points, dates, character strings, octet strings, object identifiers, and sequences. - - -D.2.1.1. Unsigned Integers -All integers used in this specification are unsigned integers. An unsigned integer SHALL be converted to -an octet string using the binary representation of the integer in big-endian format. The minimum -number of octets SHALL be used, i.e. leading octets of value 0x00 MUST NOT be used. - -Note: In contrast the ASN.1 type INTEGER is always a signed integer. - - -D.2.1.2. Elliptic Curve Points -The conversion of Elliptic Curve Points to octet strings is specified in [4]. The uncompressed format -SHALL be used. - - -D.2.1.3. Dates -A date is encoded in 6 digits d 1 ⋯d 6 in the format YYMMDD using timezone GMT. It is converted to -an octet string o1 ⋯o 6 by encoding each digit d j to an octet o j as unpacked BCDs 1≤ j≤6 . -The year YY is encoded in two digits and to be interpreted as 20YY, i.e. the year is in the range of 2000 to -2099. - - - - -94 Bundesamt für Sicherheit in der Informationstechnik - DER Encoding (Normative) D. - - -D.2.1.4. Character Strings -A character string c 1 ⋯c n is a concatenation of n characters c j with 1≤ j≤n . It SHALL be -converted to an octet string o1 ⋯o n by converting each character c j to an octet o j using the ISO/IEC -8859-1 character set. For informational purposes the character set can be found in Table 28. -The character codes 0x00-0x1F and 0x7F-0x9F are unassigned and MUST NOT be used. The conversion -of an octet to an unassigned character SHALL result in an error. - - Code 0 1 2 3 4 5 6 7 8 9 A B C D E F - 0 - 1 - 2 SP ! " # $ % & ’ ( ) * + , - . / - 3 0 1 2 3 4 5 6 7 8 9 : ; < = > ? - 4 @ A B C D E F G H I J K L M N O - 5 P Q R S T U V W X Y Z [ \ ] ^ _ - 6 ‘ a b c d e f g h i j k l m n o - 7 p q r s t u v w x y z { | } ~ - 8 - 9 - A NBSP ¡ ¢ £ ¤ ¥ ¦ § ¨ © ª « ¬ SHY ® ¯ - ° - B ± ² ³ ´ µ ¶ · ¹ º » ¼ ½ ¾ ¿ - C À Á Â Ã Ä Å Æ Ç È É Ê Ë Ì Í Î Ï - D Ð Ñ Ò Ó Ô Õ Ö × Ø Ù Ú Û Ü Ý Þ ß - E à á â ã ä å æ ç è é ê ë ì í î ï - F ð ñ ò ó ô õ ö ÷ ø ù ú û ü ý þ ÿ - SP: Space, NBSP: Non-breaking Space, SHY: Soft Hyphen - Table 28: ISO/IEC 8859-1 Character Set - -D.2.1.5. Octet Strings -An octet string o1 ⋯o n is a concatenation of n octets o j with 1≤ j≤n . Every octet o j consists of 8 -bits. - - -D.2.1.6. Object Identifiers -An object identifier i 1 .i 2 .⋯. i n is encoded as an ordered list of n unsigned integers i j with 1≤ j≤n . -It SHALL be converted to an octet string o1 ⋯o n−1 using the following procedure: - 1. The first two integers i 1 and i 2 are packed into a single integer i that is then converted to the - octet string o1 . The value i is calculated as follows: - - - - -Bundesamt für Sicherheit in der Informationstechnik 95 - D. DER Encoding (Normative) - - - i=i 1⋅4 0i 2 - 2. The remaining integers i j are directly converted to octet strings o j−1 with 3≤ j≤n . -More details on the encoding can be found in [16]. - -Note: The unsigned integers are encoded as octet strings using the big-endian format as described in -Appendix D.2.1.1, however only bits 1-7 of each octet are used. Bit 8 (the leftmost bit) set to one is used -to indicate that this octet is not the last octet in the string. - - -D.2.1.7. Sequences -A sequence D1 ⋯ D n is an ordered list of n data objects D j with 1≤ j≤n . The sequence SHALL be -converted to a concatenated list of octet strings O 1 ⋯O n by DER encoding each data object D j to an -octet string O j . - - -D.3. Public Key Data Objects -A public key data object contains a sequence of an object identifier and several context specific data -objects: - • The object identifier is application specific and refers not only to the public key format (i.e. the - context specific data objects) but also to its usage. - • The context specific data objects are defined by the object identifier and contain the public key - value and the domain parameters. -The format of public keys data objects used in this specification is described below. - - -D.3.1. RSA Public Keys -The data objects contained in an RSA public key are shown in Table 29. The order of the data objects is -fixed. - - Data Object Abbrev. Tag Type CV Certificate - Object Identifier 0x06 Object Identifier m - Composite modulus n 0x81 Unsigned Integer m - Public exponent e 0x82 Unsigned Integer m - Table 29: RSA Public Key - - - -D.3.2. Diffie Hellman Public Keys -The data objects contained in a DH public key are shown in Table 30. The order of the data objects is -fixed. - - - - -96 Bundesamt für Sicherheit in der Informationstechnik - DER Encoding (Normative) D. - - -Note: The encoding of key components as unsigned integer implies that each of them is encoded over -the least number of bytes possible, i.e. without preceding bytes set to 0x00. In particular, a DH public -key may be encoded over a number of bytes smaller than the number of bytes of the prime. - - - - Data Object Abbrev. Tag Type - Object Identifier 0x06 Object Identifier - Prime modulus p 0x81 Unsigned Integer - Order of the subgroup q 0x82 Unsigned Integer - Generator g 0x83 Unsigned Integer - Public value y 0x84 Unsigned Integer - Table 30: DH Public Key - - -D.3.3. Elliptic Curve Public Keys -The data objects contained in an EC public key are shown in Table 31. The order of the data objects is -fixed, CONDITIONAL domain parameters MUST be either all present, except the cofactor, or all absent -as follows: - • Self-signed CVCA Certificates SHALL contain domain parameters. - • CVCA Link Certificates MAY contain domain parameters. - • DV and Terminal Certificates MUST NOT contain domain parameters. The domain parameters - of DV and terminal public keys SHALL be inherited from the respective CVCA public key. - • Certificate Requests MUST always contain domain parameters. - - Data Object Abbrev. Tag Type CV Certificate - Object Identifier 0x06 Object Identifier m - Prime modulus p 0x81 Unsigned Integer c - First coefficient a 0x82 Unsigned Integer c - Second coefficient b 0x83 Unsigned Integer c - Base point G 0x84 Elliptic Curve Point c - Order of the base point r 0x85 Unsigned Integer c - Public point Y 0x86 Elliptic Curve Point m - Cofactor f 0x87 Unsigned Integer c - Table 31: EC Public Keys - - - -D.3.4. Ephemeral Public Keys -For ephemeral public keys the format and the domain parameters are already known. Therefore, only -the plain public key value, i.e. the public value y for Diffie-Hellman public keys and the public point Y -for Elliptic Curve public keys, is used to convey the ephemeral public key in a context specific data -object. - - - - -Bundesamt für Sicherheit in der Informationstechnik 97 - E. Envelope/Get Response (Normative) - - - -E. Envelope/Get Response (Normative) -To support terminals without extended length transport capability, chips of part-2 documents -SHOULD support receiving extended length command APDUs/transmitting extended length response -APDUs via Envelope/Get Response as a transport mechanism. The mechanism is designed to separate -the construction of (secured) APDUs from the transport of the APDUs between chip and (local) -terminal, allowing a (remote) terminal to construct APDUs without knowledge about the transport -capabilities of the (local) terminal. -A terminal MAY support this mechanism. -To convey an extended length command APDU via Envelope, the following steps are performed: - 1. The terminal constructs the APDU, including applying Secure Messaging, if applicable. The - terminal SHALL split the APDU in chunks, such that each chunk fits into the data field of a - standard length command TPDU. - 2. The chunks SHALL be transmitted as data fields of a chain of Envelope TPDUs to the chip. The - terminal SHALL NOT apply Secure Messaging to the Envelope TPDUs and SHALL set the - Chaining Bit of CLA for all but the last Envelope of the chain. - 3. The chip receives the chain of the Envelope TPDUs and SHALL reconstruct the extended length - APDU from the data fields. The resulting APDU SHALL be processed by the chip. This includes - processing Secure Messaging, if applicable. -If a command APDU is received via Envelope as described above, the chip SHALL transmit the response -APDU via Get Response as specified below. - 1. The response APDU SHALL be transformed into a Secure Messaging response, if applicable. - 2. The (transformed) APDU SHALL be transmitted in chunks as data fields of response TPDUs to - Get Response command TPDUs. The status words of these Get Response response TPDUs - SHALL be set to 0x9000 for the last chunk and to 0x61XX for all other chunks, respectively. -The terminal MUST send appropriate Get Response TPDUs immediately after the last Envelope TPDU. -The chip MAY dispose the response data if the terminal sends any other command. - -Note: If the terminal is not capable of transporting extended length APDUs and the response to a -command APDU is to be expected to exceed the length of a standard length APDU, the terminal -SHOULD transmit the command APDU via Envelope TPDUs, in order to trigger the chip to use the Get -Response TPDU mechanism for transporting the response APDU. - -Note: The security status is not affected by the usage of Envelope/Get Response, e.g. Secure Messaging -is not affected by using plain Envelope/Get Response TPDUs. - - - - -98 Bundesamt für Sicherheit in der Informationstechnik - Envelope/Get Response (Normative) E. - - - -E.1. Envelope -Command -CLA 0x00 Last command TPDU of a chain - 0x10 Any other command TPDU of a chain -INS 0xC2 Envelope -P1/P2 0x0000 -Lc Length of Data field REQUIRED -Data Part of a command APDU, such that the resulting REQUIRED - Envelope TPDU is a standard length TPDU. -Le MUST be absent -Response -Data MUST be absent -Status 0x9000 Normal operation -Bytes - 0x61XX More response data available - SW2 MUST be equal to '00' or optionally encode the number of response data bytes - available - other Operating system dependent error - - -E.2. Get Response -Command -CLA 0x00 -INS 0xC0 Get Response -P1/P2 0x0000 -Lc MUST be absent -Data MUST be absent -Le Maximum length of response data field expected REQUIRED -Response -Data Part of Response APDU REQUIRED -Status 0x9000 Normal operation -Bytes The complete response APDU has been transmitted, no more data available - 0x61XX More response data available - SW2 MUST be equal to '00' or optionally encode the number of data bytes still - available - other Operating system dependent error - - - - -Bundesamt für Sicherheit in der Informationstechnik 99 - F. Secure Messaging (Normative) - - - -F. Secure Messaging (Normative) -Secure Messaging provides a secure channel (i.e. encrypted and authenticated) between ICC and -terminal. Secure Messaging can be set up by Chip Authentication, PACE, or Basic Access Control. The -provided security level however depends on the mechanism used to set up Secure Messaging. - - -F.1. Session -A session is started when secure messaging is established. The session only ends with the release of -secure messaging, e.g. by sending a command APDU without secure messaging. The state of a session is -not changed by using Envelope/Get Response TPDUs. -Within a session the secure messaging keys (i.e. established by Chip Authentication, PACE, or Basic -Access Control) may be changed. - -Note: The ICC MAY implicitly select the Master File when a session is terminated. - - -F.2. Session Context -The ICC MAY support switching of Session Contexts. Support is REQUIRED if the ICC supports -multiple Extended Access Control executions in one session. -The PACE Session Context SHALL comprise at least: - • the verification state of passwords - • the Secure Messaging state, i.e. Secure Messaging keys and Send Sequence Counter - • the confined authorization - • the Terminal Certificates of the session for which Terminal Authentication was already performed. - • The current DF and the current EF. -The CA Session Context SHALL comprise at least: - • the verification state of passwords - • the Secure Messaging state, i.e. Secure Messaging keys and Send Sequence Counter - • effective access rights - • Authenticated Auxiliary Data - • the Terminal Sector. - • The current DF and the current EF. - • A presented user ID. - - -F.3. Message Structure of Secure Messaging APDUs -As this guideline only considers command APDUs with even instruction byte, this Appendix solely -takes into account Secure Messaging for command/response pairs where the command APDU has an -even INS byte. -Secure Messaging Data Objects SHALL be used according to Table 32 in the following order: - - -100 Bundesamt für Sicherheit in der Informationstechnik - Secure Messaging (Normative) F. - - - • Command APDU: [DO‘87’] [DO‘97’] DO‘8E’ - • Response APDU: [DO‘87’] DO‘99’ DO‘8E’ -All secure messaging data objects SHALL be encoded in DER (cf. Appendix D.2). The actual value of Lc -will be modified to Lc’ after application of secure messaging. If required, an appropriate data object may -optionally be included into the APDU data part in order to convey the original value of Le. In the -protected command APDU the new Le byte SHALL be set to ‘00’. - -Note: Secure messaging MUST be indicated by using class byte CLA = ‘XC’, with a bit mask X, where bit 8 -(set to 0) indicates the interindustry class and bit 5 (set to 1) indicates command chaining. - - -F.3.1. Command APDU -The command with applied Secure Messaging therefore SHALL have the following structure, -depending on the case of the respective unsecured command: -Case 1: CH || Lc’ || DO’8E’ || new Le -Case 2: CH || Lc’ || DO’97’ || DO’8E’ || new Le -Case 3: CH || Lc’ || DO’87’ || DO’8E’ || new Le -Case 4: CH || Lc’ || DO’87’ || DO’97’ || DO’8E’ || new Le -with CH: Command Header (CLA INS P1 P2) - - -F.3.2. Response APDU -The response with applied Secure Messaging SHALL have the following structure, depending on the -case of the respective unsecured command: -Case 1: DO’99’ || DO’8E’ || SW1SW2 -Case 2: DO’87’ || DO’99’ || DO’8E’ || SW1SW2 -Case 3: DO’99’ || DO’8E’ || SW1SW2 -Case 4: DO’87’ || DO’99’ || DO’8E’ || SW1SW2 - - - Name Tag Len Command Response - Padding-content indicator followed by cryptogram 0x87 V c c - Protected Le 0x97 2V c x - Processing Status 0x99 2F x m - Cryptographic Checksum 0x8E 8F m m - F: fixed length (exact number of octets), V: variable length (up to number of octets) - Table 32: Usage of Secure Messaging Data Objects -F.3.3. Padding -The data to be encrypted SHALL be padded according to ISO 7816-4 [12] using padding-content -indicator 0x01. For the calculation of the cryptographic checksum the APDU SHALL be padded -according to ISO 7816-4 [12]. - - - - -Bundesamt für Sicherheit in der Informationstechnik 101 - F. Secure Messaging (Normative) - - -Note: Padding is always performed by the secure messaging layer not by the underlying cryptographic -algorithm. - - -F.3.4. Examples -Three Examples are provided at the end of this section: - • Figure 4 shows the transformation of an unprotected command APDU to a protected command - APDU in the case Data and/or Le are available. If no Data is available, leave building DO ’87’ out. - If Le is not available, leave building DO ’97’ out. - • Figure 5 shows the transformation of an unprotected command APDU to a protected command - APDU in the case Data and Le are not available. - • Figure 6 shows the transformation of an unprotected response APDU to a protected response - APDU in the case Data are available. If no Data is available, leave building DO ’87’ out. - - -F.4. Cryptographic Algorithms -Secure Messaging is based on either 3DES [20] or AES [21] in encrypt-then-authenticate mode, i.e. data -is encrypted first and afterwards the formatted encrypted data is input to the authentication -calculation. The session keys SHALL be derived from PACE or Chip Authentication using the key -derivation function described in Appendix A.2.3. - -Note: If a command does not contain command data, no encryption applies for the command. If a -response does not contain response data, no encryption applies for the response. - - -F.4.1. 3DES -3DES is specified in [20]. - -F.4.1.1. 3DES Encryption -For message encryption two key 3DES SHALL be used in CBC-mode according to ISO 10116 [9] with key -K Enc and IV =0. - -F.4.1.2. 3DES Authentication -For message authentication 3DES SHALL be used in Retail-mode according to ISO/IEC 9797-1 [15] MAC -algorithm 3 with block cipher DES, key K MAC and IV =0. The datagram to be authenticated SHALL be -prepended by the Send Sequence Counter. - - -F.4.2. AES -AES is specified in [21]. - - - - -102 Bundesamt für Sicherheit in der Informationstechnik - Secure Messaging (Normative) F. - - -F.4.2.1. AES Encryption -For message encryption AES SHALL be used in CBC-mode according to ISO 10116 [9] with key K Enc and -IV =E  K Enc , SSC . - -F.4.2.2. AES Authentication -For message authentication AES SHALL be used in CMAC-mode [22] with K MAC with a MAC length of -8 bytes. The datagram to be authenticated SHALL be prepended by the Send Sequence Counter. - - -F.5. Send Sequence Counter -An unsigned integer SHALL be used as Send Sequence Counter (SSC). The bitsize of the SSC SHALL be -equal to the blocksize of the block cipher used for Secure Messaging, i.e. 64 bit for 3DES and 128 bit for -AES. -The SSC SHALL be increased every time before a command or response APDU is generated, i.e. if the -starting value is x, in the next command the value of the SSC is x1. The value of SSC for the first -response is x2. -If Secure Messaging is restarted, the SSC is used as follows: - • The commands used for key agreement are protected with the old session keys and old SSC. - This applies in particular for the response of the last command used for session key agreement. - • The Send Sequence Counter is set to its new start value, i.e. within this specification the SSC is - set to 0. - • The new session keys and the new SSC are used to protect subsequent commands/responses. - - -F.6. Secure Messaging Termination -The ICC MUST abort Secure Messaging if and only if a plain APDU is received or a Secure Messaging -error occurs: - • If expected Secure Messaging data objects are missing, the ICC SHALL respond with status bytes - 0x6987 - • If Secure Messaging data objects are incorrect, the ICC SHALL respond with status bytes 0x6988 -If Secure Messaging is aborted, the ICC SHALL delete the stored session keys and reset the terminal’s -access rights. - - - - -Bundesamt für Sicherheit in der Informationstechnik 103 - F. Secure Messaging (Normative) - - - - Header Lc Data Le - CLA, INS, P1, P2 Lc Data Le - - - - - Data padded to multiple of block size - Header - k bytes k bytes x bytes '80' ['00' .. '00'] Le - - - - Data encryption - - - - '87' L '01' Encrypted Data - - - - - Header '80 00 00 00' ['00' .. '00'] Formatted Encrypted Data '97' L Le '80' ['00' .. '00'] - - - - - MAC calculation - - - - - Header Lc' '87' L '01' Encrypted Data '97' L Le '8E 08' MAC '00' - - Figure 4: Transformation of a command APDU - - - - - Header - CLA, INS, P1, P2 - - - - - Header - - - - - Header '80' ['00' .. '00'] - - - - - MAC calculation - - - - - Header Lc' '8E 08' MAC '00' - - - - - Figure 5: Transformation of a command APDU if no data is available - - - - -104 Bundesamt für Sicherheit in der Informationstechnik - Secure Messaging (Normative) F. - - - - - Data Status - Data SW1-SW2 - - - - - Data padded to multiple of block size - k bytes k bytes x bytes '80' ['00' .. '00'] SW1-SW2 - - - - Data encryption - - - - '87' L '01' Encrypted Data - - - - - Formatted Encrypted Data '99 02' SW1-SW2 '80' ['00' .. '00'] - - - - - MAC calculation - - - - - '87' L '01' Encrypted Data '99 02' SW1-SW2 '8E 08' MAC SW1-SW2 - - - - - Figure 6: Transformation of a response APDU - - - - -Bundesamt für Sicherheit in der Informationstechnik 105 - F. Secure Messaging (Normative) - - - - -Bibliography -[1] ANSI. Public Key Cryptography for the Financial Services Industry: Agreement of - Symmetric Keys Using Discrete Logarithm Cryptography, ANSI X9.42-2003, 2003 -[2] Bradner, Scott. Key words for use in RFCs to indicate requirement levels, RFC 2119, 1997 -[3] BSI. PKIs for Machine Readable Travel Documents – Protocols for the Management of - Certificates and CRLs, TR-03129, 2009 -[4] BSI. Elliptic Curve Cryptography (ECC), TR-03111, -[5] BSI. eCard-API-Framework - ISO24727-3 Interface, TR-03112-4, -[6] Cooper, David; Santesson, Stefan; Farrell, Stephen; Boeyen, Sharon; Housley, Russell and - Polk, Tim. Internet X.509 public key infrastructure - certificate and certificate revocation - list (CRL) profile, RFC 5280, 2008 -[7] Housley, Russel. Cryptographic message syntax (CMS), RFC 5652, 2009 -[8] ICAO. Machine Readable Travel Documents, ICAO Doc 9303, 2015 -[9] ISO/IEC 10116:2006. Information technology − Security techniques − Modes of operation - for an n-bit block cipher, 2006 -[10] ISO/IEC 7816-15. Identification cards – Integrated circuit cards – Part 15: Cryptographic - Information Application, 2004 -[11] ISO/IEC 7816-3:2006. Identification cards – Integrated circuit cards – Part 3: Cards with - contacts — Electrical interface and transmission protocols, 2006 -[12] ISO/IEC 7816-4:2013. Identification cards – Integrated circuit cards – Part 4: - Organization, security and commands for interchange, 2013 -[13] ISO/IEC 7816-6:2004. Identification cards – Integrated circuit cards – Part 6: Interindustry - data elements for interchange, 2004 -[14] ISO/IEC 7816-8:2004. Identification cards – Integrated circuit cards – Part 8: Commands - for security operations, 2004 -[15] ISO/IEC 9797-1:1999. Information technology − Security techniques − Message - Authentication Codes (MACs) − Part 1: Mechanisms using a block cipher, 1999 -[16] ITU-T. Information Technology – ASN.1 encoding rules: Specification of Basic Encoding - Rules(BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER), - X.690, 2002 -[17] Jonsson, Jakob and Kaliski, Burt. Public-key cryptography standards (PKCS)#1: RSA - cryptography specifications version 2.1, RFC 3447, 2003 -[18] Lepinski, Matt; Kent, Stephen. Additional Diffie-Hellman Groups for Use with IETF - Standards, RFC 5114, 2008 -[19] Lochter, Manfred; Merkle, Johannes. Elliptic Curve Cryptography (ECC) Brainpool - Standard Curves and Curve Generation, RFC 5639, 2010 -[20] NIST. Data Encryption Standard (DES), FIPS PUB 46-3, 1999 -[21] NIST. Specification for the Advanced Encryption Standard (AES), FIPS PUB 197, 2001 -[22] NIST. Recommendation for Block Cipher Modes of Operation: The CMAC Mode for - Authentication, Special Publication 800-38B, 2005 -[23] NIST. Digital Signature Standard (DSS), FIPS 186-4, 2013 -[24] NIST. Secure hash standard, FIPS PUB 180-4, 2015 -[25] Rescorla, Eric. Diffie-Hellman key agreement method, RFC 2631, 1999 -[26] RSA Laboratories. PKCS#3: Diffie-Hellman key-agreement standard, RSA Laboratories - Technical Note, 1993 -[27] RSA Laboratories. PKCS#1 v2.2: RSA cryptography standard, RSA Laboratories Technical - Note, 2012 -[28] SOG-IS. Crypto Evaluation Scheme - Agreed Cryptographic Mechanisms, Crypto - Working Group, - - - - -106 Bundesamt für Sicherheit in der Informationstechnik - \ No newline at end of file From 57b4235dcb8a3e34fcaa25d42b8408a3ddeb282d Mon Sep 17 00:00:00 2001 From: Tobias Schwerdtfeger Date: Mon, 12 Jan 2026 11:49:06 +0100 Subject: [PATCH 14/20] OPEN-97: Add license --- core-modules/asn1/src/cv_certificate.rs | 2 +- core-modules/asn1/src/lib.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/core-modules/asn1/src/cv_certificate.rs b/core-modules/asn1/src/cv_certificate.rs index 8355536a..4b02e1b0 100644 --- a/core-modules/asn1/src/cv_certificate.rs +++ b/core-modules/asn1/src/cv_certificate.rs @@ -1,4 +1,4 @@ -// SPDX-FileCopyrightText: Copyright 2025 gematik GmbH +// SPDX-FileCopyrightText: Copyright 2025 - 2026 gematik GmbH // // SPDX-License-Identifier: Apache-2.0 // diff --git a/core-modules/asn1/src/lib.rs b/core-modules/asn1/src/lib.rs index 4d0bb7b4..00da7e55 100644 --- a/core-modules/asn1/src/lib.rs +++ b/core-modules/asn1/src/lib.rs @@ -1,4 +1,4 @@ -// SPDX-FileCopyrightText: Copyright 2025 gematik GmbH +// SPDX-FileCopyrightText: Copyright 2025 - 2026 gematik GmbH // // SPDX-License-Identifier: Apache-2.0 // From 2b45da318b2d324de9bf7f8def85cbc6fb144449 Mon Sep 17 00:00:00 2001 From: "sandra.bieseke" Date: Mon, 12 Jan 2026 13:10:44 +0100 Subject: [PATCH 15/20] OPEN-99: Add support for selecting and retrieving multiple certificate types from health card --- .../healthcard/src/bin/apdu_record.rs | 25 ++++++++++++++++++- docs/tooling/apdu-tools.md | 10 ++++++++ 2 files changed, 34 insertions(+), 1 deletion(-) diff --git a/core-modules/healthcard/src/bin/apdu_record.rs b/core-modules/healthcard/src/bin/apdu_record.rs index 652b689e..4e35174b 100644 --- a/core-modules/healthcard/src/bin/apdu_record.rs +++ b/core-modules/healthcard/src/bin/apdu_record.rs @@ -29,6 +29,7 @@ fn main() { use clap::Parser; use crypto::ec::ec_key::{EcCurve, EcKeyPairSpec}; use healthcard::exchange::apdu_tools::{PcscChannel, RecordingChannel}; + use healthcard::exchange::certificate::{retrieve_certificate_from, CertificateFile}; use healthcard::exchange::secure_channel::{establish_secure_channel_with, CardAccessNumber}; if let Err(err) = run() { @@ -58,6 +59,9 @@ fn main() { /// List available PC/SC readers and exit #[arg(long)] list_readers: bool, + /// Read certificates and print them as hex to stdout + #[arg(long)] + read_certificates: bool, } fn run() -> Result<(), String> { @@ -80,13 +84,25 @@ fn main() { recorder.set_can(can.clone()); let mut generated_keys = Vec::new(); - establish_secure_channel_with(&mut recorder, &card_access_number, |curve: EcCurve| { + let mut secure_channel = establish_secure_channel_with(&mut recorder, &card_access_number, |curve: EcCurve| { let (public_key, private_key) = EcKeyPairSpec { curve: curve.clone() }.generate_keypair()?; generated_keys.push(hex::encode_upper(private_key.as_bytes())); Ok((public_key, private_key)) }) .map_err(|err| format!("PACE failed: {err}"))?; + if args.read_certificates { + let cert = retrieve_certificate_from(&mut secure_channel, CertificateFile::ChAutE256) + .map_err(|err| format!("read DF.ESIGN/EF.C.CH.AUT.E256 failed: {err}"))?; + print_certificate("DF.ESIGN/EF.C.CH.AUT.E256", &cert); + + let cert = retrieve_certificate_from(&mut secure_channel, CertificateFile::EgkAutCvcE256) + .map_err(|err| format!("read MF/EF.C.eGK.AUT_CVC.E256 failed: {err}"))?; + print_certificate("MF/EF.C.eGK.AUT_CVC.E256", &cert); + } + + drop(secure_channel); + if !generated_keys.is_empty() { recorder.set_keys(generated_keys); } @@ -96,6 +112,13 @@ fn main() { Ok(()) } + fn print_certificate(label: &str, data: &[u8]) { + println!("{label} ({} bytes):", data.len()); + for chunk in data.chunks(32) { + println!(" {}", hex::encode_upper(chunk)); + } + } + fn list_pcsc_readers() -> Result<(), String> { let ctx = pcsc::Context::establish(pcsc::Scope::User) .map_err(|err| format!("pcsc context establish failed: {err}"))?; diff --git a/docs/tooling/apdu-tools.md b/docs/tooling/apdu-tools.md index bf43c225..41569edd 100644 --- a/docs/tooling/apdu-tools.md +++ b/docs/tooling/apdu-tools.md @@ -68,6 +68,16 @@ cargo run -p healthcard --bin apdu_record --features apdu-tools -- \ --out ./transcript.jsonl ``` +To additionally read the certificates and print them to the console: + +```sh +cargo run -p healthcard --bin apdu_record --features apdu-tools -- \ + --reader "" \ + --can 123456 \ + --out ./transcript.jsonl \ + --read-certificates +``` + APDU length options: - Default: uses extended-length APDUs when needed. From 0189be224ae93c186dc78a2154b653b8f0ee5067 Mon Sep 17 00:00:00 2001 From: "sandra.bieseke" Date: Mon, 12 Jan 2026 15:00:25 +0100 Subject: [PATCH 16/20] OPEN-99: Add optional dependencies `clap`, `serde`, `serde_json`, and `pcsc` to `healthcard` module --- core-modules/healthcard/Cargo.toml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/core-modules/healthcard/Cargo.toml b/core-modules/healthcard/Cargo.toml index 0f4ffb13..961815b0 100644 --- a/core-modules/healthcard/Cargo.toml +++ b/core-modules/healthcard/Cargo.toml @@ -45,3 +45,7 @@ once_cell = "1.21.3" num-bigint = "0.4" zeroize = { version = "1.8.1", features = ["zeroize_derive"] } uniffi = { version = "0.30.0", optional = true } +clap = { version = "4.5.40", optional = true, features = ["derive"] } +serde = { version = "1.0.219", optional = true, features = ["derive"] } +serde_json = { version = "1.0.117", optional = true } +pcsc = { version = "2.8.2", optional = true } From 3b7a4649efe4c1ee8c0d7cd30fb758817551236e Mon Sep 17 00:00:00 2001 From: "sandra.bieseke" Date: Mon, 12 Jan 2026 15:03:52 +0100 Subject: [PATCH 17/20] parameter formatting --- core-modules/healthcard/src/exchange/certificate.rs | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/core-modules/healthcard/src/exchange/certificate.rs b/core-modules/healthcard/src/exchange/certificate.rs index 61146bfd..0937a144 100644 --- a/core-modules/healthcard/src/exchange/certificate.rs +++ b/core-modules/healthcard/src/exchange/certificate.rs @@ -81,10 +81,7 @@ where /// /// The certificate is read in chunks using the READ BINARY command until the /// card indicates the end of the file. -pub fn retrieve_certificate_from( - session: &mut S, - certificate: CertificateFile, -) -> Result, ExchangeError> +pub fn retrieve_certificate_from(session: &mut S, certificate: CertificateFile) -> Result, ExchangeError> where S: CardChannelExt, { From 3c6485d5e9b7a9edeac1987a12f24db2a4fad0cb Mon Sep 17 00:00:00 2001 From: "sandra.bieseke" Date: Mon, 12 Jan 2026 15:19:54 +0100 Subject: [PATCH 18/20] Refactor `fixed_key_generator` to return `EcKeyPairGenerator` directly instead of an inline closure --- core-modules/healthcard/src/exchange/apdu_tools.rs | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/core-modules/healthcard/src/exchange/apdu_tools.rs b/core-modules/healthcard/src/exchange/apdu_tools.rs index 17dd105d..d3d8bcb5 100644 --- a/core-modules/healthcard/src/exchange/apdu_tools.rs +++ b/core-modules/healthcard/src/exchange/apdu_tools.rs @@ -121,13 +121,11 @@ impl Transcript { self.header.can.as_deref() } - pub fn fixed_key_generator( - &self, - ) -> Result Result<(EcPublicKey, EcPrivateKey), CryptoError>>, TranscriptError> { + pub fn fixed_key_generator(&self) -> Result, TranscriptError> { match &self.header.keys { Some(keys) => { let decoded = - keys.iter().map(|k| Ok(hex::decode(k)?)).collect::, hex::FromHexError>>()?; + keys.iter().map(|k| hex::decode(k)).collect::, hex::FromHexError>>()?; Ok(Some(FixedKeyGenerator::new(decoded).generator())) } None => Ok(None), @@ -303,9 +301,7 @@ impl ReplayChannel { Self { transcript, cursor: 0 } } - pub fn fixed_key_generator( - &self, - ) -> Result Result<(EcPublicKey, EcPrivateKey), CryptoError>>, TranscriptError> { + pub fn fixed_key_generator(&self) -> Result, TranscriptError> { self.transcript.fixed_key_generator() } From e2d2dd18feed1e6dd6f50e07737d1b0a564a2d40 Mon Sep 17 00:00:00 2001 From: "sandra.bieseke" Date: Mon, 12 Jan 2026 15:24:38 +0100 Subject: [PATCH 19/20] Simplify `fixed_key_generator` by inlining `keys.iter().map` logic for clarity --- core-modules/healthcard/src/exchange/apdu_tools.rs | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/core-modules/healthcard/src/exchange/apdu_tools.rs b/core-modules/healthcard/src/exchange/apdu_tools.rs index d3d8bcb5..31e8c037 100644 --- a/core-modules/healthcard/src/exchange/apdu_tools.rs +++ b/core-modules/healthcard/src/exchange/apdu_tools.rs @@ -124,8 +124,7 @@ impl Transcript { pub fn fixed_key_generator(&self) -> Result, TranscriptError> { match &self.header.keys { Some(keys) => { - let decoded = - keys.iter().map(|k| hex::decode(k)).collect::, hex::FromHexError>>()?; + let decoded = keys.iter().map(|k| hex::decode(k)).collect::, hex::FromHexError>>()?; Ok(Some(FixedKeyGenerator::new(decoded).generator())) } None => Ok(None), From 37e77e335a69ffbc7a83f8ebbb77757e504c9a29 Mon Sep 17 00:00:00 2001 From: "sandra.bieseke" Date: Mon, 12 Jan 2026 15:32:18 +0100 Subject: [PATCH 20/20] Refactor `fixed_key_generator` to wrap `FixedKeyGenerator` in a `Box` for consistency with return type --- core-modules/healthcard/src/exchange/apdu_tools.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/core-modules/healthcard/src/exchange/apdu_tools.rs b/core-modules/healthcard/src/exchange/apdu_tools.rs index 31e8c037..95c9fe4d 100644 --- a/core-modules/healthcard/src/exchange/apdu_tools.rs +++ b/core-modules/healthcard/src/exchange/apdu_tools.rs @@ -124,8 +124,8 @@ impl Transcript { pub fn fixed_key_generator(&self) -> Result, TranscriptError> { match &self.header.keys { Some(keys) => { - let decoded = keys.iter().map(|k| hex::decode(k)).collect::, hex::FromHexError>>()?; - Ok(Some(FixedKeyGenerator::new(decoded).generator())) + let decoded = keys.iter().map(hex::decode).collect::, hex::FromHexError>>()?; + Ok(Some(Box::new(FixedKeyGenerator::new(decoded).generator()))) } None => Ok(None), }