myna_card/
lib.rs

1//! A library for accessing the Japanese Individual Number Card (個人番号カード / My Number Card).
2//!
3//! # Layout
4//!
5//! - [`apdu`] — building ISO/IEC 7816-4 APDUs and interpreting responses. Transport agnostic.
6//! - [`transport`] — abstraction over the link to the card ([`Transmit`]), including a PC/SC backend.
7//! - [`card`] — ISO 7816-4 level operations on top of [`Transmit`] (SELECT FILE, READ BINARY, VERIFY, ...).
8//! - [`ap`] — per-application (AP) DF/EF definitions and higher level accessors.
9//! - [`data`] — the values the card stores, and the credentials derived from them.
10//! - [`ca`] — CA keys for the 券面 card-verifiable certificates, and where they came from.
11//! - [`certificate`] — the X.509 certificates of the 公的個人認証AP.
12//! - [`mf`] — the files under the master file that the JICSAP specification itself defines.
13//! - [`sm`] — secure messaging with the 券面入力補助AP, the one application that offers it.
14//! - [`tlv`] — readers for the two TLV encodings the card uses.
15//!
16//! # Specification
17//!
18//! The card follows the JICSAP specification of IC cards with contacts complying with Japanese
19//! Industrial Standard, version 1.1 (July 1998), which in turn builds on JIS X 6306 and
20//! ISO/IEC 7816-4. Doc comments cite it as "JICSAP" plus a section or table number.
21//!
22//! # Example
23//!
24//! This one needs the default features: the PC/SC backend comes from `pcsc`, and reading a
25//! certificate or checking a signature against it comes from `verify`.
26//!
27//! ```no_run
28//! # #[cfg(all(feature = "pcsc", feature = "verify"))]
29//! # fn main() -> Result<(), myna_card::Error> {
30//! use myna_card::ap::jpki::{JpkiAp, SignatureScheme};
31//! use myna_card::transport::pcsc::Sharing;
32//! use myna_card::{Pin, transport::pcsc};
33//!
34//! // Exclusive because this presents a PIN: a security status outlives the command that set it,
35//! // and sharing the card would leave the unlocked key to whatever else is on the machine.
36//! let mut card = pcsc::connect_any(Sharing::Exclusive)?;
37//! let mut jpki = JpkiAp::select(&mut card)?;
38//!
39//! // The 利用者証明用証明書 is readable without a password.
40//! let cert = jpki.read_auth_certificate()?;
41//! println!("{}", cert.subject());
42//!
43//! // Sign with the key that certificate belongs to, and check the result against it.
44//! jpki.verify_auth_pin(&Pin::numeric("1234")?)?;
45//! let signature =
46//!     jpki.sign_with_auth_key_checked(SignatureScheme::Sha256DigestInfo, b"message")?;
47//!
48//! // The 署名用証明書 and its key need the signature password instead.
49//! jpki.verify_sign_pin(&Pin::new("PASSWORD1234")?)?;
50//! let cert = jpki.read_sign_certificate()?;
51//! # Ok(())
52//! # }
53//! # #[cfg(not(all(feature = "pcsc", feature = "verify")))]
54//! # fn main() {}
55//! ```
56//!
57//! # Warning
58//!
59//! Every failed VERIFY decrements the card's retry counter. Once a counter reaches zero the
60//! corresponding PIN is blocked and can only be unblocked at a municipal office. Use
61//! [`Card::pin_retries`] to query the remaining attempts without consuming one.
62//!
63//! # Security status outlives your program
64//!
65//! A successful VERIFY stays in effect until the card leaves the field. On a real card, neither
66//! dropping the connection nor reconnecting with `SCARD_RESET_CARD` clears it — only
67//! `SCARD_UNPOWER_CARD` does. Selecting a different application clears the one you left
68//! (JICSAP 5.1.3 rule 3), but re-selecting the same one does not (rule 2).
69//!
70//! So a fresh process is not a fresh card. If your code needs to know that a file was genuinely
71//! unlocked by the PIN it just presented, read it before the VERIFY too and check it was locked.
72
73#![forbid(unsafe_code)]
74#![warn(missing_docs)]
75
76pub mod ap;
77pub mod apdu;
78pub mod ca;
79pub mod card;
80#[cfg(feature = "verify")]
81pub mod certificate;
82pub mod data;
83pub mod error;
84pub mod mf;
85pub mod pin;
86#[cfg(feature = "sm")]
87pub mod sm;
88pub mod tlv;
89pub mod transport;
90
91pub use ap::jpki::{TokenInfo, TokenType};
92pub use apdu::{Command, Response, StatusWord};
93pub use card::{Card, Retries, ShortEfId};
94#[cfg(feature = "verify")]
95pub use certificate::Certificate;
96pub use data::{
97    CardVerifiableCertificate, Date, Era, Image, ImageFormat, MyNumber, RsaPublicKey, Sex,
98    verification_code_b,
99};
100pub use error::{Error, Result};
101pub use mf::MasterFile;
102pub use pin::Pin;
103#[cfg(feature = "sm")]
104pub use sm::SecureSession;
105pub use transport::Transmit;
myna_card/lib.rs

myna_card/
lib.rs
