How to use gpg command-line to check passphrase is correct

There is no in-built method for doing this, but it is simple enough to create a test that doesn't modify anything and allows you to just check your passphrase.

You didn't specify, so I will assume you are using GnuPG version less than v2 and are on Linux with Bash for your commandline interpreter.

I will give the command here and below I will explain what each part does - (note: the following is for GnuPG series version 1, see below for GnuPG series v2)

echo "1234" | gpg --no-use-agent -o /dev/null --local-user <KEYID> -as - && echo "The correct passphrase was entered for this key"

What that does is first, pipe some text to sign to GnuPG with echo "1234" | - because we don't really want to sign anything, this is just a test, so we will sign some useless text.

Next, we tell gpg to not use the key agent with --no-use-agent; this is important later because, depending on your key agent, it may not return "0" on success, and that is all we want to do - verify success of your passphrase.

Next, we tell gpg to put the signed data directly into the /dev/null file, meaning we discard it and not write the result to the terminal -- NOTE: if you are not using some variant of Linux/Unix, this file may not exist. On windows you may have to just allow it to write the signed data to the screen by just omitting the -o /dev/null part.

Next, we specify the key we want to do our test with by using --local-user 012345. You can use the KeyID for maximum specificity, or use a username, whichever best suites your needs.

Next we specify -as, which enables ascii output mode, and sets the context mode for signing. The - afterwards just tells GnuPG to get the data to be signed from standard-in, which is the very first part of the command we gave echo "1234" |.

And last, we have && echo "A message that indicates success" -- the "&&" means, if the previous command was successful, print this message. This is just added for clarity, because the success of the command above would otherwise be indicated by no output at all.

I hope that is clear enough for you to understand what is going on, and how you can use it do the testing you want to do. If any part is unclear or you do not understand, I will be glad to clarify. Good luck!

[EDIT] - If you are using GnuPG v2, the above command will need to be modified slightly, like so:

echo "1234" | gpg2 --batch --passphrase-fd 1 -o /dev/null --local-user <KEYID> -as - && echo "The correct passphrase was entered for this key"

The reason being, GnuPG v2 expects the passphrase to be retrieved via an agent, so we cannot disable the use of the agent with --no-use-agent and have the desired effect; instead we need to tell GnuPG v2 that we want to run a "batch" process, and retrieve the passphrase from STDIN (standard in) by using the option --passphrase-fd 1.


This is a shorter command line to check if passphrase is OK:

gpg --export-secret-keys -a <KEYID> > /dev/null && echo OK

For me the simplistic way to check the passphrase is to use gpg --passwd shorthand. It tries to change the passphrase and the step is to confirm the old passphrase, and then you can click 'cancel' on the new passphrase prompt and this keeps the passphrase intact.

gpg --passwd <your-user-id>

As mentioned by ford04, for newer version of GPG, now the above command can be improved to

gpg --dry-run --passwd <your-user-id>

which is even better. See the commit.


Warning do not use echo gpg -o /dev/null as suggested by top answer here. This will cause /dev/null to have invalid permission and corrupting the /dev/null file. You can verify the /dev/null file's permission when running this command to prove this.

You can use this:

echo "1234" | gpg -q --batch --status-fd 1 --sign --local-user $KEY_ID --passphrase-fd 0 > /dev/null

I also created bash script for this (This one is working with Centos 8). This script will ask for passphrase, if it's invalid, it will keep asking to input valid passphrase. Also if you input wrong or non-existing KEY_ID as an argument it can validate that as well:

#!/bin/bash
# usage ./gpgcron KEYID   | ./gpgcron 2B705B8B6FA943B1
script_path=$(dirname $(realpath -s $0))
script_name=$(basename -- "$0")
GPG_CACHE_BIN="/usr/libexec/gpg-preset-passphrase"
KEY_ID=$1
KEY_GRIP=$(gpg --with-keygrip --list-secret-keys $KEY_ID | grep -Pom1 '^ *Keygrip += +\K.*')
RETVAL=$?
if [[ $RETVAL -ne 0 || -z $KEY_ID ]]; then
    echo "Please provide correct KEY_ID. Example ./$script_name KEY_ID"
    exit 1
fi

export GPG_TTY=$(tty)

function set_gpg_cachepass {
    read -s -p "[$script_name | input]: Enter passphrase to cache into gpg-agent: " PASSPHRASE; echo
    $GPG_CACHE_BIN -c $KEY_GRIP <<< $PASSPHRASE
    RETVAL=$?
    echo "[$script_name | info ]: gpg-preset-passphrase return code: [$RETVAL]"
    if [ $RETVAL = 0 ]; then
        echo "[$script_name | info ]: A passphrase has been set and cached in gpg-agent"
        echo "[$script_name | info ]: Paraphrase set return code: [$RETVAL]"
        gpg_validatepass
    else
        echo "[$script_name | info ]: Unsuccessful error occured: [$RETVAL]"
        set_gpg_cachepass
    fi
}

function gpg_validatepass {
    echo "[$script_name | info ]: Validating passphrase cached in gpg-agent ..."
    echo "1234" | gpg -q --batch --status-fd 1 --sign --local-user $KEY_ID --passphrase-fd 0 > /dev/null
    RETVAL=$?
    if [ $RETVAL = 0 ]; then
        echo "[$script_name | info ]: OK, valid passphrase has been cached in gpg-agent"
    else
        echo "[$script_name | info ]: Warning, invalid passphrase or no passphrase is cached in gpg-agent"
        set_gpg_cachepass
    fi
}

RES=$(echo "KEYINFO --no-ask $KEY_GRIP Err Pmt Des" | gpg-connect-agent | awk '{ print $7 }')
if [ "$RES" == "1" ]; then
    echo "[$script_name | info ]: OK, passphrase is already cached in gpg agent for KEY_ID of [$KEY_ID]"
    gpg_validatepass
else
    echo "[$script_name | info ]: Warning, no passphrase is cached in gpg agent for KEY_ID of [$KEY_ID]"
    set_gpg_cachepass
fi

Sample output if no password is cached in gpg-agent:

[root@earth gpg]# ./gpgcron 2B705B8B6FA943B2
[gpgcron | info ]: Warning, no passphrase is cached in gpg agent for KEY_ID of [2B705B8B6FA943B2]
[gpgcron | input]: Enter passphrase to cache into gpg-agent:

Sample output if invalid passphrase is entered (it will keep asking):

[root@earth gpg]# ./gpgcron 2B705B8B6FA943B2
[gpgcron | info ]: OK, passphrase is already cached in gpg agent for KEY_ID of [2B705B8B6FA943B2]
[gpgcron | info ]: Validating passphrase cached in gpg-agent ...
gpg: signing failed: Bad passphrase
gpg: signing failed: Bad passphrase
[gpgcron | info ]: Warning, invalid passphrase or no passphrase is cached in gpg-agent
[gpgcron | input]: Enter passphrase to cache into gpg-agent:

Sample output if valid passphrase is entered:

[gpgcron | input]: Enter passphrase to cache into gpg-agent:
[gpgcron | info ]: gpg-preset-passphrase return code: [0]
[gpgcron | info ]: A passphrase has been set and cached in gpg-agent
[gpgcron | info ]: Paraphrase set return code: [0]
[gpgcron | info ]: Validating passphrase cached in gpg-agent ...
[gpgcron | info ]: OK, valid passphrase has been cached in gpg-agent

When valid passphrase is cached, the next time you run this script, it will not ask you to enter passphrase. So this script give the solution to your question; "Just confirm I am using the right passphrase"