Read passwords from stdin with --enable-stdin-passwords (closes #7) (#357)

Author: kwart

AGENTS.md

@@ -24,8 +24,23 @@ jsignpdf-root/
 ├── installcert/       # Certificate installer utility
 ├── distribution/      # Packaging: ZIP assembly, Windows installer, docs
 └── website/           # Hugo documentation site (not a Maven module)
+    └── docs/JSignPdf.adoc  # ★ authoritative user guide (see below)
 ```
 
+## Key Documentation Artifacts
+
+Keep these in sync with the code; user-facing features are not "done" until they land here too.
+
+| File | Role | When to update |
+|---|---|---|
+| `website/docs/JSignPdf.adoc` | **Authoritative user guide.** Single source of truth consumed by both the Hugo site (`website/content/docs/guide/index.adoc` is regenerated from it by `website/prepare.sh`) and the Maven PDF build in `distribution/`. | Any new or changed user-visible feature: new CLI flags, new GUI panels, changed defaults, new keystore types, new exit codes, etc. Update the synopsis block, the relevant option table, and add a dedicated subsection if the feature has non-obvious usage. |
+| `distribution/doc/release-notes/<version>.md` | Release notes bundled with the artifact and used as the GitHub Release body. | Every release-worthy change. |
+| `README.md` | Top-level project landing page. Concise feature overview + pointers to the guide. | Only for high-signal changes (new feature categories, platform support, install paths). |
+| `jsignpdf/src/main/resources/net/sf/jsignpdf/translations/messages.properties` | Canonical English resource bundle (all others are Weblate-synced). CLI `--help` text comes from here. | Any new CLI option or GUI string. Do not hand-edit non-English `messages_*.properties` files. |
+| `design-doc/<version>-<topic>.md` | Design notes for larger changes. | Before implementing a non-trivial feature. |
+
+When a PR touches a user-visible feature without updating `JSignPdf.adoc`, flag it as incomplete.
+
 ## Source Code Layout
 
 All source is under `jsignpdf/src/main/java/net/sf/jsignpdf/`:

README.md

@@ -39,6 +39,53 @@ Requires a **Java 21 (or newer) JRE** unless you use an installer that bundles i
 
 Maven-Central-published artifacts (for embedding the signing engine in your own project) live under `com.github.kwart.jsign`.
 
+## Reading passwords from standard input
+
+Passing a password on the command line exposes it to every local process that can read
+`/proc/<pid>/cmdline` (or to shell history). To avoid that, JSignPdf can read password values
+from standard input (or from an interactive console) instead.
+
+Opt in with `--enable-stdin-passwords` and use `-` as the value of any password option:
+
+```bash
+# Keystore password, piped in
+printf '%s\n' "$KS_PASSWORD" \
+  | java -jar JSignPdf.jar --enable-stdin-passwords \
+      -kst PKCS12 -ksf keystore.p12 -ksp - -ka mykey \
+      -d out/ input.pdf
+```
+
+You can combine several password options in one invocation. When multiple options use `-`, the
+values are consumed from stdin in a **fixed canonical order** regardless of the order in which
+they appear on the command line:
+
+1. `--keystore-password` (`-ksp`)
+2. `--key-password` (`-kp`)
+3. `--owner-password` (`-opwd`)
+4. `--user-password` (`-upwd`)
+5. `--tsa-cert-password` (`-tscp`)
+6. `--tsa-password` (`-tsp`)
+
+```bash
+# Keystore password first, TSA password second — even though the CLI lists them in the other order.
+{ printf '%s\n' "$KS_PASSWORD"; printf '%s\n' "$TSA_PASSWORD"; } \
+  | java -jar JSignPdf.jar --enable-stdin-passwords \
+      -kst PKCS12 -ksf keystore.p12 -ksp - -ka mykey \
+      -ts https://tsa.example/ -tsu tsauser -tsp - \
+      -d out/ input.pdf
+```
+
+Before blocking on each read, JSignPdf prints a progress line such as
+`[jsignpdf] Reading password for --keystore-password (1/2) from stdin...` to stderr so you can
+verify the order matches what your pipe is feeding. Use `-q` (`--quiet`) to suppress it.
+
+When a console is attached (an interactive terminal), `-` switches to a prompted,
+no-echo read via `java.io.Console.readPassword`.
+
+**Backwards compatibility:** without `--enable-stdin-passwords`, a literal `-` is still accepted
+as a password value exactly as before. JSignPdf will emit a one-time warning naming the flag, so
+a typo does not silently turn into a `-` password.
+
 ## Documentation
 
 - User guide: <https://intoolswetrust.github.io/jsignpdf/>

design-doc/3.0.0-stdin-passwords.md

@@ -25,6 +25,13 @@ packaging.
 
 ## Other changes
 
+- **Read passwords from standard input** (#7). Any of the six password
+  CLI options (`-ksp`, `-kp`, `-opwd`, `-upwd`, `-tscp`, `-tsp`) can now
+  be given as `-` to read the value from stdin (or, in an interactive
+  terminal, from the console with no-echo). Opt in with
+  `--enable-stdin-passwords`; multiple passwords are consumed in a fixed
+  canonical order printed on stderr before each read. Avoids leaking
+  secrets to `/proc/<pid>/cmdline` and shell history.
 - "Reset Settings" action added to the JavaFX UI.
 - New and updated translations (Czech, German, French, Spanish, Slovak,
   Portuguese, Croatian, Simplified Chinese, Traditional Chinese, and

distribution/doc/release-notes/3.0.0.md

@@ -289,6 +289,9 @@ public class Constants {
     public static final String ARG_KS_PWD_LONG = "keystore-password";
     public static final String ARG_KS_PWD = "ksp";
 
+    public static final String ARG_ENABLE_STDIN_PWDS_LONG = "enable-stdin-passwords";
+    public static final String STDIN_PWD_SENTINEL = "-";
+
     public static final String ARG_KEY_PWD_LONG = "key-password";
     public static final String ARG_KEY_PWD = "kp";
 

jsignpdf/src/main/java/net/sf/jsignpdf/Constants.java

@@ -31,7 +31,10 @@
 
 import static net.sf.jsignpdf.Constants.*;
 
+import java.io.IOException;
+import java.io.PrintStream;
 import java.net.Proxy;
+import java.util.function.Consumer;
 import java.util.logging.Level;
 import java.util.logging.Logger;
 
@@ -77,6 +80,19 @@ public class SignerOptionsFromCmdLine extends BasicSignerOptions {
 
     private boolean gui;
 
+    private StdinPasswordReader passwordReader;
+    private PrintStream warningOut;
+
+    /** Test seam: override the stdin password reader. */
+    void setPasswordReader(StdinPasswordReader passwordReader) {
+        this.passwordReader = passwordReader;
+    }
+
+    /** Test seam: override the stream the stdin-sentinel warning is written to (default {@link System#err}). */
+    void setWarningOut(PrintStream warningOut) {
+        this.warningOut = warningOut;
+    }
+
     /**
      * Parses options provided as command line arguments.
      * @throws ParseException
@@ -127,14 +143,10 @@ public void loadCmdLine() throws ParseException {
             setKsType(line.getOptionValue(ARG_KS_TYPE));
         if (line.hasOption(ARG_KS_FILE))
             setKsFile(line.getOptionValue(ARG_KS_FILE));
-        if (line.hasOption(ARG_KS_PWD))
-            setKsPasswd(line.getOptionValue(ARG_KS_PWD));
         if (line.hasOption(ARG_KEY_ALIAS))
             setKeyAlias(line.getOptionValue(ARG_KEY_ALIAS));
         if (line.hasOption(ARG_KEY_INDEX))
             setKeyIndex(getInt(line.getParsedOptionValue(ARG_KEY_INDEX), getKeyIndex()));
-        if (line.hasOption(ARG_KEY_PWD))
-            setKeyPasswd(line.getOptionValue(ARG_KEY_PWD));
         if (line.hasOption(ARG_OUTPATH))
             setOutPath(line.getOptionValue(ARG_OUTPATH));
         if (line.hasOption(ARG_OPREFIX))
@@ -160,10 +172,6 @@ public void loadCmdLine() throws ParseException {
             setPdfEncryption(PDFEncryption.PASSWORD);
         if (line.hasOption(ARG_ENCRYPTION))
             setPdfEncryption(line.getOptionValue(ARG_ENCRYPTION));
-        if (line.hasOption(ARG_PWD_OWNER))
-            setPdfOwnerPwd(line.getOptionValue(ARG_PWD_OWNER));
-        if (line.hasOption(ARG_PWD_USER))
-            setPdfUserPwd(line.getOptionValue(ARG_PWD_USER));
         if (line.hasOption(ARG_ENC_CERT))
             setPdfEncryptionCertFile(line.getOptionValue(ARG_ENC_CERT));
         if (line.hasOption(ARG_RIGHT_PRINT))
@@ -215,13 +223,9 @@ public void loadCmdLine() throws ParseException {
             setTsaCertFileType(line.getOptionValue(ARG_TSA_CERT_FILE_TYPE));
         if (line.hasOption(ARG_TSA_CERT_FILE))
             setTsaCertFile(line.getOptionValue(ARG_TSA_CERT_FILE));
-        if (line.hasOption(ARG_TSA_CERT_PWD))
-            setTsaCertFilePwd(line.getOptionValue(ARG_TSA_CERT_PWD));
 
         if (line.hasOption(ARG_TSA_USER))
             setTsaUser(line.getOptionValue(ARG_TSA_USER));
-        if (line.hasOption(ARG_TSA_PWD))
-            setTsaPasswd(line.getOptionValue(ARG_TSA_PWD));
         if (line.hasOption(ARG_TSA_POLICY_LONG))
             setTsaPolicy(line.getOptionValue(ARG_TSA_POLICY_LONG));
         if (line.hasOption(ARG_TSA_HASH_ALG))
@@ -245,6 +249,78 @@ public void loadCmdLine() throws ParseException {
             setInFile(files[0]);
         }
 
+        resolvePasswords(line);
+    }
+
+    /**
+     * Processes the six password options in a fixed canonical order, substituting values read from stdin
+     * (or the interactive console) wherever the user gave the sentinel {@code "-"} together with
+     * {@code --enable-stdin-passwords}. When the flag is missing, a {@code "-"} value is treated as a
+     * literal password (backwards compatible) and a warning is written to stderr unless {@code -q} is set.
+     * See {@code design-doc/3.0.0-stdin-passwords.md}.
+     */
+    private void resolvePasswords(CommandLine line) throws ParseException {
+        final boolean stdinEnabled = line.hasOption(ARG_ENABLE_STDIN_PWDS_LONG);
+        final boolean quiet = line.hasOption(ARG_QUIET);
+
+        final String[][] slots = {
+                { ARG_KS_PWD, ARG_KS_PWD_LONG },
+                { ARG_KEY_PWD, ARG_KEY_PWD_LONG },
+                { ARG_PWD_OWNER, ARG_PWD_OWNER_LONG },
+                { ARG_PWD_USER, ARG_PWD_USER_LONG },
+                { ARG_TSA_CERT_PWD, ARG_TSA_CERT_PWD_LONG },
+                { ARG_TSA_PWD, ARG_TSA_PWD_LONG },
+        };
+        @SuppressWarnings("unchecked")
+        final Consumer<String>[] setters = new Consumer[] {
+                (Consumer<String>) this::setKsPasswd,
+                (Consumer<String>) this::setKeyPasswd,
+                (Consumer<String>) this::setPdfOwnerPwd,
+                (Consumer<String>) this::setPdfUserPwd,
+                (Consumer<String>) this::setTsaCertFilePwd,
+                (Consumer<String>) this::setTsaPasswd,
+        };
+
+        int total = 0;
+        for (String[] slot : slots) {
+            if (line.hasOption(slot[0]) && STDIN_PWD_SENTINEL.equals(line.getOptionValue(slot[0]))) {
+                total++;
+            }
+        }
+
+        int index = 0;
+        for (int i = 0; i < slots.length; i++) {
+            final String shortArg = slots[i][0];
+            final String longArg = slots[i][1];
+            if (!line.hasOption(shortArg)) {
+                continue;
+            }
+            final String raw = line.getOptionValue(shortArg);
+            if (STDIN_PWD_SENTINEL.equals(raw)) {
+                if (stdinEnabled) {
+                    index++;
+                    try {
+                        if (passwordReader == null) {
+                            passwordReader = StdinPasswordReader.systemDefault(quiet);
+                        }
+                        char[] chars = passwordReader.readNext(longArg, index, total);
+                        setters[i].accept(new String(chars));
+                    } catch (IOException ioe) {
+                        throw new ParseException(ioe.getMessage());
+                    }
+                } else {
+                    if (!quiet) {
+                        PrintStream w = warningOut != null ? warningOut : System.err;
+                        w.println("[jsignpdf] Warning: --" + longArg + " value is '-'. Did you mean to pass --"
+                                + ARG_ENABLE_STDIN_PWDS_LONG
+                                + " to read it from stdin? Using '-' as the literal password.");
+                    }
+                    setters[i].accept(raw);
+                }
+            } else {
+                setters[i].accept(raw);
+            }
+        }
     }
 
     /**
@@ -303,6 +379,8 @@ private float getFloat(Object aVal, float aDefVal) {
                 .withType(Number.class).withArgName("index").create(ARG_KEY_INDEX));
         OPTS.addOption(OptionBuilder.withLongOpt(ARG_KEY_PWD_LONG).withDescription(RES.get("hlp.keyPwd")).hasArg()
                 .withArgName("password").create(ARG_KEY_PWD));
+        OPTS.addOption(OptionBuilder.withLongOpt(ARG_ENABLE_STDIN_PWDS_LONG)
+                .withDescription(RES.get("hlp.enableStdinPasswords")).create());
 
         OPTS.addOption(OptionBuilder.withLongOpt(ARG_OUTPATH_LONG).withDescription(RES.get("hlp.outPath")).hasArg()
                 .withArgName("path").create(ARG_OUTPATH));

jsignpdf/src/main/java/net/sf/jsignpdf/SignerOptionsFromCmdLine.java

@@ -0,0 +1,102 @@
+/*
+ * The contents of this file are subject to the Mozilla Public License
+ * Version 1.1 (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.mozilla.org/MPL/
+ *
+ * Software distributed under the License is distributed on an "AS IS"
+ * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
+ * License for the specific language governing rights and limitations
+ * under the License.
+ *
+ * The Original Code is 'JSignPdf, a free application for PDF signing'.
+ *
+ * The Initial Developer of the Original Code is Josef Cacek.
+ * Portions created by Josef Cacek are Copyright (C) Josef Cacek. All Rights Reserved.
+ *
+ * Contributor(s): Josef Cacek.
+ *
+ * Alternatively, the contents of this file may be used under the terms
+ * of the GNU Lesser General Public License, version 2.1 (the  "LGPL License"), in which case the
+ * provisions of LGPL License are applicable instead of those
+ * above. If you wish to allow use of your version of this file only
+ * under the terms of the LGPL License and not to allow others to use
+ * your version of this file under the MPL, indicate your decision by
+ * deleting the provisions above and replace them with the notice and
+ * other provisions required by the LGPL License. If you do not delete
+ * the provisions above, a recipient may use your version of this file
+ * under either the MPL or the LGPL License.
+ */
+package net.sf.jsignpdf;
+
+import java.io.BufferedReader;
+import java.io.Console;
+import java.io.EOFException;
+import java.io.IOException;
+import java.io.InputStreamReader;
+import java.io.PrintStream;
+
+/**
+ * Reads passwords from stdin (or the interactive console) for CLI password options that were
+ * marked with the {@link Constants#STDIN_PWD_SENTINEL} sentinel.
+ *
+ * <p>See {@code design-doc/3.0.0-stdin-passwords.md}.
+ */
+final class StdinPasswordReader {
+
+    private static final String PROGRESS_PREFIX = "[jsignpdf] ";
+
+    private final BufferedReader reader;
+    private final Console console;
+    private final PrintStream progressOut;
+    private final boolean quiet;
+
+    StdinPasswordReader(BufferedReader reader, Console console, PrintStream progressOut, boolean quiet) {
+        this.reader = reader;
+        this.console = console;
+        this.progressOut = progressOut;
+        this.quiet = quiet;
+    }
+
+    /**
+     * Default reader bound to {@link System#in}, {@link System#console()} and {@link System#err}.
+     */
+    static StdinPasswordReader systemDefault(boolean quiet) {
+        return new StdinPasswordReader(new BufferedReader(new InputStreamReader(System.in)), System.console(),
+                System.err, quiet);
+    }
+
+    /**
+     * Reads the next password. Emits a progress line (unless quiet) before blocking on input.
+     *
+     * @param longOptionName the long option name (e.g. {@code keystore-password}), used in progress/error messages
+     * @param index 1-based index of this read among the sentinel-marked options in the current invocation
+     * @param total total count of sentinel-marked options in the current invocation
+     * @return the password characters; never {@code null}
+     * @throws IOException on EOF before a line is read, or on underlying I/O failure
+     */
+    char[] readNext(String longOptionName, int index, int total) throws IOException {
+        if (!quiet && progressOut != null) {
+            progressOut.println(PROGRESS_PREFIX + "Reading password for --" + longOptionName + " (" + index + "/" + total
+                    + ") from " + (console != null ? "console" : "stdin") + "...");
+        }
+        if (console != null) {
+            char[] pwd = console.readPassword("Enter password for --" + longOptionName + ": ");
+            if (pwd == null) {
+                throw new EOFException(
+                        "Unexpected end of input while reading password for --" + longOptionName);
+            }
+            return pwd;
+        }
+        String line;
+        try {
+            line = reader.readLine();
+        } catch (IOException e) {
+            throw new IOException("Failed to read password for --" + longOptionName + ": " + e.getMessage(), e);
+        }
+        if (line == null) {
+            throw new EOFException("Unexpected end of input while reading password for --" + longOptionName);
+        }
+        return line.toCharArray();
+    }
+}