diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index e9020a8..043a7f0 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -33,6 +33,21 @@ jobs: - name: Generate Sphinx docs run: sphinx-build -W --keep-going -b html docs docs/_build/html + # 4b. Build the PDF and ship it inside the HTML tree, so it lands in the + # versioned directory (/vX.Y/cryptnox-id-cli.pdf) on deploy — the + # index page's "Download as PDF" link and the docs hub point there. + - name: Install LaTeX for PDF + run: | + sudo apt-get update + sudo apt-get install -y --no-install-recommends \ + latexmk texlive-latex-recommended texlive-latex-extra \ + texlive-fonts-recommended texlive-fonts-extra tex-gyre + + - name: Build PDF (pdflatex) + run: | + sphinx-build -M latexpdf docs docs/_build + cp docs/_build/latex/cryptnox-id-cli.pdf docs/_build/html/cryptnox-id-cli.pdf + # 5. Fetch what is currently published, to carry earlier versions over # (continue-on-error: the branch does not exist on the very first deploy) - name: Fetch previously published versions diff --git a/docs/conf.py b/docs/conf.py index 4524929..eb771eb 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -62,8 +62,10 @@ html_show_sourcelink = False # no "View page source" link html_copy_source = False # and no _sources/*.rst.txt on the published site -# PDF output name for a local `make latexpdf` run. CI builds HTML only - pdflatex -# cannot render several characters these docs legitimately use. +# PDF built by CI (docs.yml) with pdflatex and shipped inside the versioned HTML +# dir as .pdf. pdflatex cannot render every Unicode character, so the +# sources stay within its set: no emoji outside `.. only:: html`, no arrows or +# math symbols (use ->, at least, ...). The em/en dashes and ellipses it handles. latex_documents = [("index", f"{repo_slug}.tex", product_name, author, "manual")] todo_include_todos = False # .. todo:: blocks must never reach the published site diff --git a/docs/factory/pre-personalization-profiles.rst b/docs/factory/pre-personalization-profiles.rst index cd218e5..a0b3977 100644 --- a/docs/factory/pre-personalization-profiles.rst +++ b/docs/factory/pre-personalization-profiles.rst @@ -50,7 +50,7 @@ Built-in profiles * **generated on-card** — ``piv quickstart --profile ms-logon --slot 9A --algorithm RSA2048`` (the private key never leaves the card); - * **imported**, for an AD-issued credential (CSR → CA → import, or PKCS#12 + * **imported**, for an AD-issued credential (CSR -> CA -> import, or PKCS#12 import via :doc:`/piv/piv-personalization`). The object carries the ``IMPORTABLE`` attribute so the second path is @@ -147,7 +147,7 @@ whole profile before anything is sent to a card: - the admin key mechanism must be AES-128/192/256 (this applet's 9B is AES-only); -- PIN and PUK ``min`` must be at least 6 and ``max`` must be ≥ ``min``; +- PIN and PUK ``min`` must be at least 6 and ``max`` must be at least ``min``; - PIN and PUK ``retries`` must be 0–10; - every key's mechanism must be one this applet actually supports (see ``inspect-defaults``); diff --git a/docs/fido2/fido2-guide.rst b/docs/fido2/fido2-guide.rst index 822da46..8a15f17 100644 --- a/docs/fido2/fido2-guide.rst +++ b/docs/fido2/fido2-guide.rst @@ -43,7 +43,7 @@ doesn't consume a retry. Write operations -------------------- -These use the CTAP2 **PIN/UV Auth Protocol** (ECDH key agreement → +These use the CTAP2 **PIN/UV Auth Protocol** (ECDH key agreement -> AES/HMAC under protocol 1 or 2). PINs are entered by masked prompt or a ``--*-env`` variable, never on the command line, and are registered with the redactor. @@ -100,7 +100,7 @@ authenticatorConfig policy applet exposes two subcommands; each is authorized by a pinUvAuthToken carrying the **authenticatorConfiguration** permission, so pass ``--pin-env NAME`` when a clientPIN is set. (The pinUvAuthParam is MACed -over a mandatory ``32×0xFF`` prefix — per the CTAP 2.1 spec, not a card +over a mandatory prefix of 32 ``0xFF`` bytes — per the CTAP 2.1 spec, not a card quirk.) .. code-block:: console diff --git a/docs/genuine/genuineness-guide.rst b/docs/genuine/genuineness-guide.rst index 6ba4988..fcff0d7 100644 --- a/docs/genuine/genuineness-guide.rst +++ b/docs/genuine/genuineness-guide.rst @@ -23,7 +23,7 @@ that need **no secret key material**: against the on-card leaf certificate's public key. Because the nonce is random per run, a copied certificate or a replayed signature cannot pass — the card must physically hold the device private key *now*. -* **Certificate chain.** ``leaf → Genuineness CA → … → pinned Cryptnox root``, +* **Certificate chain.** ``leaf -> Genuineness CA -> … -> pinned Cryptnox root``, validated (name chaining, signatures, validity windows, CA constraints) and anchored on the pinned trust store. A root is trusted only because it is pinned — never because it appears in a chain read off the card. diff --git a/docs/index.rst b/docs/index.rst index 52608f0..8c3342e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,6 +6,10 @@ Command-line management for the Cryptnox multi-applet smart card: PIV DESFire contactless — three independent functions on one physical card, driven by one tool: |cli|. +.. only:: html + + 📄 `Download this documentation as PDF `__ + .. toctree:: :maxdepth: 2 :caption: General diff --git a/docs/piv/quick-start-a-working-piv-card.rst b/docs/piv/quick-start-a-working-piv-card.rst index 299e928..c1dedbe 100644 --- a/docs/piv/quick-start-a-working-piv-card.rst +++ b/docs/piv/quick-start-a-working-piv-card.rst @@ -35,8 +35,8 @@ The one-command path $ cryptnox-id piv quickstart --default-keys ``piv quickstart`` detects the card state, then runs whatever is still needed -of: PIN → PUK → key in slot 9C (ECC P-256, generated **on-card** — the private -key never exists outside the card) → self-signed certificate → CHUID/CCC → +of: PIN -> PUK -> key in slot 9C (ECC P-256, generated **on-card** — the private +key never exists outside the card) -> self-signed certificate -> CHUID/CCC -> smoke-test. Steps already done are skipped, so re-runs converge. New PIN/PUK values come from masked prompts or ``CRYPTNOX_PIV_NEW_PIN`` / ``CRYPTNOX_PIV_NEW_PUK``. @@ -118,7 +118,7 @@ returns ``6985`` for sign operations). --public-key 9c.pub.pem --out 9c.crt.pem $ cryptnox-id piv perso import-cert --slot 9C --cert 9c.crt.pem -Or CA-issued: ``generate-csr`` → have your CA sign it → ``import-cert``. +Or CA-issued: ``generate-csr`` -> have your CA sign it -> ``import-cert``. Large certificates are written with ISO command chaining automatically. **Step 4 — standard data objects.** Most PIV clients (including diff --git a/docs/piv/ssh-public-key-authentication.rst b/docs/piv/ssh-public-key-authentication.rst index d77e5f7..a77e8d4 100644 --- a/docs/piv/ssh-public-key-authentication.rst +++ b/docs/piv/ssh-public-key-authentication.rst @@ -85,7 +85,7 @@ Fixing it: give 9A the SIGN role ------------------------------------ You don't need the full ``ms-logon`` profile for this — the built-in ``ssh`` -profile changes only 9A's ``role`` (``AUTHENTICATE`` → ``AUTHENTICATE, +profile changes only 9A's ``role`` (``AUTHENTICATE`` -> ``AUTHENTICATE, SIGN``); everything else is identical to ``cryptnox-default``. See :doc:`/factory/pre-personalization-profiles` for the full built-in profile list. diff --git a/docs/piv/tls-client-authentication.rst b/docs/piv/tls-client-authentication.rst index 3c1dbff..38898de 100644 --- a/docs/piv/tls-client-authentication.rst +++ b/docs/piv/tls-client-authentication.rst @@ -60,7 +60,7 @@ platform. Try the target site directly first: 1. Visit the target site. Some Firefox versions detect a PC/SC smart card natively and offer the card's certificate without any setup. 2. If no certificate is offered, register the module manually: - ``about:preferences#privacy`` → **Security Devices** → **Load**. Module + ``about:preferences#privacy`` -> **Security Devices** -> **Load**. Module name: anything recognizable (e.g. ``Cryptnox PIV``). Module filename: the ``opensc-pkcs11.so`` path from :doc:`/piv/ssh-public-key-authentication`. 3. Reload the site. On a certificate request, Firefox shows a picker listing diff --git a/docs/piv/windows-logon-and-remote-desktop.rst b/docs/piv/windows-logon-and-remote-desktop.rst index 6ae5564..33f39db 100644 --- a/docs/piv/windows-logon-and-remote-desktop.rst +++ b/docs/piv/windows-logon-and-remote-desktop.rst @@ -120,7 +120,7 @@ Step 3 — log on * **Local/interactive**: select the smart-card credential tile and enter the PIV PIN. * **Remote Desktop**: in ``mstsc`` the card is redirected by default (Local - Resources → Smart cards). Connect to the domain host and authenticate with + Resources -> Smart cards). Connect to the domain host and authenticate with the PIN at the remote credential prompt. Scope and limits