Skip to content

askpass-script-flow.md

Latest commit

 

History

History
53 lines (33 loc) · 2.18 KB

askpass-script-flow.md

File metadata and controls

53 lines (33 loc) · 2.18 KB

Askpass Script Flow

This document explains what macos-ssh-askpass-git-signing.sh does without requiring you to read the script directly. The script is an SSH_ASKPASS helper for macOS. OpenSSH calls it when it needs a PIN or passphrase but no usable terminal is available.

Main Flow

flowchart TD
    Start([Start]) --> PromptArg{Prompt argument provided?}
    PromptArg -->|yes| UsePrompt[Use OpenSSH prompt text]
    PromptArg -->|no| DefaultPrompt[Use default SSH signing prompt]

    UsePrompt --> RunOsa[Run osascript in JavaScript mode]
    DefaultPrompt --> RunOsa

    RunOsa --> StandardAdditions[Enable macOS Standard Additions]
    StandardAdditions --> Dialog[Show hidden-answer dialog]

    Dialog --> UserChoice{User action}
    UserChoice -->|OK| ReturnText[Print entered text to stdout]
    UserChoice -->|Cancel or dialog failure| ExitNonZero[Exit non-zero]

    ReturnText --> End([End])
    ExitNonZero --> End
Loading

Inputs And Outputs

The script accepts one optional argument: the prompt text from OpenSSH. If OpenSSH does not pass a prompt, the script uses a generic SSH signing PIN/passphrase prompt.

On success, the script prints only the entered value to standard output. OpenSSH reads that value as the response to its current prompt.

On cancellation or macOS dialog failure, osascript exits non-zero. OpenSSH treats that as a failed prompt.

Prompt Scope

The dialog may be used for different OpenSSH prompt types:

  • local key-stub passphrase,
  • YubiKey FIDO2 PIN,
  • other OpenSSH signing prompt text.

The script does not try to classify the prompt. It displays the text OpenSSH provided and returns the user's answer.

Security Behavior

The dialog uses a hidden-answer field. The script does not store the entered value, log it, or write it to disk.

The value still passes through standard process I/O as part of OpenSSH's askpass protocol. Treat the local machine and desktop session as trusted before using GUI askpass for signing.

Limitations

This script does not handle the physical YubiKey touch. Touch/user-presence is enforced by the YubiKey and OpenSSH. The signing wrapper can show a notification, but the hardware touch must still happen on the device.