From 190ef7b8e70166c2a6f57ba23078496c14e2724b Mon Sep 17 00:00:00 2001
From: Jiahao XU <Jiahao_XU@outlook.com>
Date: Sat, 23 Sep 2023 23:13:23 +1000
Subject: [PATCH] Doc: Provide solutions for common problems encountered during
 signing (#1383)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Doc: Provide solutions for common problems encountered during signing

Signed-off-by: Jiahao XU <Jiahao_XU@outlook.com>

* Apply suggestions from code review

Co-authored-by: Félix Saparelli <felix@passcod.name>

---------

Signed-off-by: Jiahao XU <Jiahao_XU@outlook.com>
Co-authored-by: Félix Saparelli <felix@passcod.name>
---
 SIGNING.md | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/SIGNING.md b/SIGNING.md
index d18eff0f..e8cc2871 100644
--- a/SIGNING.md
+++ b/SIGNING.md
@@ -42,6 +42,41 @@ Upload both your package and the matching `.sig`.
 Now when binstall downloads your packages, it will also download the `.sig` file and use the `pubkey` in the Cargo.toml to verify the signature.
 If the signature has a trusted comment, it will print it at install time.
 
+`minisign` and `rsign2` by default prompt for a password when generating a keypair and signing, which can hinder automation.
+
+You can:
+ - Pass `-W` to `minisign` or `rsign2` to generate a password-less private key.
+   NOTE that you also need to pass this when signing.
+ - When signing using `minisign`, it reads from stdin for password so you could use
+   shell redirect to pass the password.
+ - Use [`expect`] to pass password to `rsign2` (since it reads `/dev/tty` for password):
+   For generating private key:
+   ```bash
+   expect <<EXP
+   spawn rsign generate -f -p minisign.pub -s minisign.key
+   expect "Password:"
+   send -- "$SIGNING_KEY_SECRET\r"
+   expect "Password (one more time):"
+   send -- "$SIGNING_KEY_SECRET\r"
+   expect eof
+   EXP
+   ```
+   For signing:
+   ```bash
+   expect <<EXP
+   spawn rsign sign -s minisign.key -x "$file.sig" -t "$comment" "$file"
+   expect "Password:"
+   send -- "$SIGNING_KEY_SECRET\r"
+   expect eof
+   EXP
+   ```
+
+For just-in-time or "keyless" schemes, securely generating and passing the ephemeral key to other jobs or workflows presents subtle issues.
+`cargo-binstall` has an implementation in [its own release process][`release.yml`] that you can use as example.
+
+[`expect`]: https://linux.die.net/man/1/expect
+[`release.yml`]: https://github.com/cargo-bins/cargo-binstall/blob/main/.github/workflows/release.yml
+
 ## Reference
 
 - `algorithm`: required, see below.