Writing bash scripts that do file verification using gpg that really is secure and passes a comprehensive threat model, that covers indefinite freeze, rollback, endless data attacks, etc. is hard.
gpg-bash-lib's goal is to provide a bash library that we can collaboratively develop, audit and abstract the hard work into reuseable functions.
Checking gpg exit codes only is insufficient. Quote Werner Koch (gnupg lead developer):
"there is no clear distinction between the codes and for proper error reporting you are advised to use the --status-fd messages."
(For a definition of these attacks, see TUF (The Update Framework)'s threat model (w).)
- Abstracts file verification into common functions.
- Allows detecting of stale files, i.e. detection downgrade or indefinite freeze attacks by implementing a valid-until like mechanism.
- Internally parses gpg's --status-file output.
- It is signal friendly.
- Detects endless data attacks, aborts and reports this.
- Detects indefinite freeze and rollback (downgrade) attacks and reports this.
- Can help with verification of names of files, that are otherwise not covered by default when using gpg.
- Provide diagnostic output (variables) that contain information if the local clock is sane by comparing signature creation date with local clock.
- Anything else not mentioned above in "What does it do".
- bash
sudo make install
Or see README_generic.md.
See /usr/share/gpg-bash-lib/examples/ folder.
After installation, if you would run the following command.
/usr/share/gpg-bash-lib/examples/one
You would see the following output.
your_script_begin: ... verification: BEGIN verification: END your_script_output: BEGIN gpg_bash_lib_output_failure_status: false gpg_bash_lib_output_gpg_verify_exit_code: 0 gpg_bash_lib_output_goodsig_status: true gpg_bash_lib_output_validsig_status: true gpg_bash_lib_output_fingerprint_in_hex: 5E08605EBEA0FE88695DCB88FD0A8B4171DFE4E4 gpg_bash_lib_output_signed_on_unixtime: 1422049448 gpg_bash_lib_output_signed_on_date: March 01 13:56:27 UTC 2015 gpg_bash_lib_output_notation[$file@name]: test-file gpg_bash_lib_output_file_name_tampering: false gpg_bash_lib_output_freshness_status: true gpg_bash_lib_output_freshness_detail: current gpg_bash_lib_output_freshness_msg: - Freshness: Signature is current. - valid-max: Signatures are valid up to 30 days. - Signature Creation Date: March 01 13:56:27 UTC 2015 - Current System Date : March 02 16:0:55 UTC 2015 - Local System Clock: Your clock seems okay. - Relative Signature Creation Time: According to your system clock, signature was created 2 days 26 minutes 3 seconds ago. gpg_bash_lib_output_alright_status: true your_script_output: END
All information (Signature Creation Date, etc.) are easily accessible through separate variables, which are all documented below.
- whonixcheck: See function verify_whonix_news.
- tb-updater: See function tb_gpg_verify and function tb_confirm_update.
It is assumed, that your script downloaded a data file as well as a signature file. A separate folder containing the keys that are supposed to be used for gpg verification, such as for example /usr/share/program-name/signing-keys.d is required as a prerequisite. You can then use this library to do the gpg verification for you.
Set at least all required gpg_bash_lib_input_* variables, that are documented below. Then run the main function gpg_bash_lib_function_main_verify (or just one function you wish to use). Then enjoy the gpg_bash_lib_output_* variables, that this library has set for you.
If you wish to run gpg_bash_lib_function_main_verify another time, store the variables you want to keep in variables of your own, because they will be overridden on subsequent runs.
- description: Folder that can be used for temporary files. Warning: that folder will be deleted before usage to make sure it is clean!
- required: no
- defaults to: "$(mktemp --directory)"
- expected value: /path/to/temp/folder
- example: gpg_bash_lib_input_temp_folder=/home/user/some-tmp-folder
- description: The folder that contains gpg signing keys that are supposed to be accepted. Must already exist. Must contain gpg public keys.
- required: yes
- expected value: /path/to/folder
- example: gpg_bash_lib_input_key_import_dir=/usr/share/program-name/signing-keys.d
- description: Enforce, that the name of the file is stored in the file@name OpenPGP notation and matches the actual file name. If enabled, gpg_bash_lib_output_alright_status will be set to true if it matches. Otherwise to false. Rather gpg_bash_lib_output_file_name_tampering will be set to true (match), missing (no file@name OpenPGP notation inside the signature, false (mismatch) accordingly.
- required: no
- defaults to: disabled by default
- expected value: true or false
- example: gpg_bash_lib_input_file_name_enforce=true
- description: Delete the folder stored in the gpg_bash_lib_input_temp_folder variable or not.
- required: no
- defaults to: disabled by default
- expected value: true or false
- example: gpg_bash_lib_input_cleanup=true
- description: The data file that is supposed to be verified.
- required: yes
- expected value: /path/to/file
- example: gpg_bash_lib_input_data_file=/home/user/some-file.tar.gz
- description: The signature file that is supposed to be verified.
- required: yes
- expected value: /path/to/file
- example: gpg_bash_lib_input_data_file=/home/user/some-file.tar.gz.asc
- description: Custom error handler function you may wish to invoke in case the ERR trap function gpg_bash_lib_function_error_handler gets ever hit.
- required: no
- defaults to: none
- expected value: A command or bash function name.
- example usage:
gpg_bash_lib_input_error_handler_extra='error_handler'
gpg_bash_lib_input_error_handler_extra='error_handler "$gpg_bash_lib_output_error_handler_message"'
gpg_bash_lib_input_error_handler_extra='error_handler "$gpg_bash_lib_output_error_handler_message" ; return 0'
- description: After how many seconds a gpg verification attempt should be forced timeout. Sends signal SIGTERM to gpg. Useful to defeat an endless data attacks or bugs. Increase this value when you are working with bigger files and/or slow systems.
- required: no
- defaults to: 10
- expected value: integer
- example: gpg_bash_lib_input_verify_timeout_after=120
- description: After how many seconds, if gpg did not react to SIGTERM due to timeout (see above), signal SIGKILL should be used. Useful to defeat an endless data attacks or bugs.
- required: no
- defaults to: 10
- expected value: integer
- example: gpg_bash_lib_input_verify_timeout_after=20
- description: After how many seconds, a signature is considered outdated. gpg adds the creation time of the signature (Signature Creation Date) to every signature. That value is detected (see also variables gpg_bash_lib_output_signed_on_unixtime and gpg_bash_lib_output_signed_on_date below) and compared against this variable.
- required: no
- defaults to: 2592000 (which is sane as 1 month)
- expected value: integer
- example: gpg_bash_lib_input_maximum_age_in_seconds=2592000
- description: After how many seconds, a signature is considered outdated.
- required: no
- defaults to: 1800 (which is same as 30 minutes)
- expected value: integer
- example: gpg_bash_lib_input_slow_clock_lenient_up_to_seconds=1800
- possible values: true or false
- recommendation: Make sure to check for this value! Since the trap gpg_bash_lib_function_error_handler has been invoked, something unexpected, a bug has occurred. Regard this as verification failed.
- example usage:
if [ "$gpg_bash_lib_output_failure_status" = "true" ]; then echo 'Fatal signature verification error! Report this bug!' >&2 exit 1 fi
- possible values: A verbose diagnostic textual string.
- recommendation: Display this value when running your script in verbose mode.
- example content:
gpg_bash_lib_internal_gpg_verify_status_fd_file: /tmp/tmp.lZDa3dOyUr/gpg_bash_lib_internal_gpg_verify_status_fd_file gpg_bash_lib_internal_gpg_verify_output_file: /tmp/tmp.lZDa3dOyUr/gpg_bash_lib_internal_gpg_verify_output_file gpg_bash_lib_output_gpg_import_output: gpg: keyring `/tmp/tmp.lZDa3dOyUr/secring.gpg' created gpg: keyring `/tmp/tmp.lZDa3dOyUr/pubring.gpg' created gpg: /tmp/tmp.lZDa3dOyUr/trustdb.gpg: trustdb created gpg: key 01C1FA07: public key "auto generated local signing key <[email protected]>" imported gpg: Total number processed: 1 gpg: imported: 1 (RSA: 1) gpg_bash_lib_output_gpg_verify_output: gpg: Signature made Wed 25 Feb 2015 12:17:44 AM UTC using RSA key ID 8006F538 gpg: Good signature from "auto generated local signing key <[email protected]>" gpg: Signature notation: file@name=test-file gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: EB53 FEB4 7F25 ED3B 22F6 7D8B 87A3 BF01 01C1 FA07 Subkey fingerprint: E0A4 BE54 D1D8 1354 17FB 1CC2 42B6 02D3 8006 F538 gpg_bash_lib_output_gpg_verify_status_fd_output: [GNUPG:] SIG_ID wW/AZUo5pHeQTTOWMwGTynGlLXQ 2015-02-25 1424823464 [GNUPG:] GOODSIG 42B602D38006F538 auto generated local signing key <[email protected]> [GNUPG:] NOTATION_NAME file@name [GNUPG:] NOTATION_DATA test-file [GNUPG:] VALIDSIG E0A4BE54D1D8135417FB1CC242B602D38006F538 2015-02-25 1424823464 0 4 0 1 2 00 EB53FEB47F25ED3B22F67D8B87A3BF0101C1FA07 [GNUPG:] TRUST_UNDEFINED
- possible values: A textual string containing output of the gpg --import part.
- recommendation: Since already included in gpg_bash_lib_output_diagnostic_message, you most likely will not need it.
- possible values: integer. The exit code of the gpg --verify action, most likely 0 or other exit codes such as 1, or if timeout was reached, 124 if sending signal sigterm was sufficient or 137 if sending signal sigkill was required.
- recommendation: Check if it is 0, since other exit codes indicate failures or timeouts. Probably better not to rely on it for anything else but debug output, since the unreliability of gpg verify exit codes is the reason this library has been implemented in the first place.
- example value: 0
- example usage:
case "$gpg_bash_lib_output_gpg_verify_exit_code" in
"0")
true
;;
"124")
echo "Soft gpg verification timeout!" >&2
exit 1
;;
"137")
echo "Hard gpg verification timeout!" >&2
exit 1
;;
*)
echo "gpg_bash_lib_output_gpg_verify_exit_code neither represents success nor timeout. It is: $gpg_bash_lib_output_gpg_verify_exit_code" >&2
exit 125
;;
esac
- possible values: A textual string containing output of the gpg --verify part.
- recommendation: Since already included in gpg_bash_lib_output_diagnostic_message, you most likely will not need it.
- possible values: A textual string containing output of the gpg --status-file part.
- recommendation: Since already included in gpg_bash_lib_output_diagnostic_message, you most likely will not need it.
- possible values: An integer, the Signature Creation Date represented as unixtime.
- recommendation: Consider using this variable instead of gpg_bash_lib_output_signed_on_date by converting it to some formatted date string that you prefer.
- example content: 1419456919
- possible values: gpg_bash_lib_output_signed_on_unixtimeconverted to a textual date string using.
- recommendation: Show this variable in your script, ask the user for confirmation.
- example content: March 01 13:56:27 UTC 2015
- possible values: Set to true (match), missing (no file@name OpenPGP notation inside the signature, false (mismatch) accordingly.
- recommendation: If you are using gpg_bash_lib_input_file_name_enforce=true, you should check this value.
- example content: true
- example usage:
echo "File name is : $(basename "$gpg_bash_lib_input_data_file")"
case "$gpg_bash_lib_output_file_name_tampering" in
"false")
echo "File name should be: ${gpg_bash_lib_output_notation[$"file@name"]}"
echo 'File name okay, has not been tampered with.'
;;
"missing")
## Not trying to access ${gpg_bash_lib_output_notation[$"file@name"]},
## because that variable does not exist then.
echo 'File name tampering detected! file@name OpenPGP notation missing!' >&2
exit 1
;;
"true")
echo "File name should be: ${gpg_bash_lib_output_notation[$"file@name"]}"
echo 'File name tampering detected!' >&2
exit 1
;;
*)
echo "gpg_bash_lib_output_file_name_tampering neither represents false, missing, nor success. It is: $gpg_bash_lib_output_gpg_verify_exit_code" >&2
exit 125
;;
esac
- possible values: name of file that was signed or "" if not in use (not using gpg_bash_lib_input_file_name_enforce=true).
- example content: test-file
- example use:
echo "gpg_bash_lib_output_notation[file@name]: ${gpg_bash_lib_output_notation[$"file@name"]}"
- possible value: Textual string containing the duration of how lenient the clock leniency check is. (Contains the result of the conversion of gpg_bash_lib_input_slow_clock_lenient_up_to_seconds to a pretty format.)
- example content: 30 minutes
- possible values: true (GOODSIG, key and signature valid) or false (BADSIG, EXPSIG, EXPKEYSIG, REVKEYSIG or ERRSIG).
- recommendation: Check if its value is true. Abort otherwise.
- example content: true
- example usage:
if [ ! "$gpg_bash_lib_output_goodsig_status" = "true" ]; then echo 'Key or signature error (BADSIG, EXPSIG, EXPKEYSIG, REVKEYSIG or ERRSIG)!' >&2 exit 1 fi
- possible values: true (successful verification) or false (unsuccessful verification).
- recommendation: Check if its value is true. Abort otherwise.
- example content: true
- example usage:
if [ ! "$gpg_bash_lib_output_validsig_status" = "true" ]; then echo 'Signature verification failed!' >&2 exit 1 fi
- possible values: The fingerprint of the key that signed the file in hex or "" in case of unsuccessful verification.
- recommendation: May or may not be useful to show this value in your script (in verbose mode). Since we expect a separate folder that contains the only keys that will be accepted (see variable gpg_bash_lib_input_key_import_dir), it seems unnecessary to check for the fingerprint.
- example content: F38633B0A3F06A55CC0076C81081641AC4D57DB9
- possible values: integer, unixtime at time of running this library.
- possible values: A textual string, the output of "$(date --utc "+%B %d %H:%M:%S UTC %Y")" at time of running this library.
- example content: March 01 17:59:38 UTC 2015
- possible values: An integer, that represents the Relative Signature Creation Time. See the example of gpg_bash_lib_output_signed_on_unixtime_minus_current_unixtime_pretty below to understand what it is doing. Can be used when gpg_bash_lib_output_freshness_detail is slow or lenient.
- possible values: A textual string, gpg_bash_lib_output_signed_on_unixtime_minus_current_unixtime converted to a pretty format. Can be used when gpg_bash_lib_output_freshness_detail is slow or lenient.
- example usage:
if [ "$gpg_bash_lib_output_freshness_detail" = "slow" ] || [ "$gpg_bash_lib_output_freshness_detail" = "lenient" ]; then echo "Relative Signature Creation Time: According to your system clock, signature was created $gpg_bash_lib_output_signed_on_unixtime_minus_current_unixtime_pretty before current time." fi
- possible values: An integer, that represents the Relative Signature Creation Time. See the example of gpg_bash_lib_output_current_unixtime_minus_signed_on_unixtime_pretty below to understand what it is doing. Can be used if gpg_bash_lib_output_freshness_detail is current or outdated..
- possible values: A textual string, gpg_bash_lib_output_current_unixtime_minus_signed_on_unixtime converted to a pretty format. Can be used if gpg_bash_lib_output_freshness_detail is current or outdated..
- example usage:
if [ "$gpg_bash_lib_output_freshness_detail" = "current" ] || [ "$gpg_bash_lib_output_freshness_detail" = "outdated" ]; then echo "Relative Signature Creation Time: According to your system clock, signature was created $gpg_bash_lib_output_current_unixtime_minus_signed_on_unixtime_pretty ago." fi
- possible values: In case of gpg_bash_lib_output_freshness_detail is outdated, it contains an estimation how many seconds the clock might be fast.
- possible values: A textual string, gpg_bash_lib_output_in_future_in_seconds converted to a pretty format.
- example use:
echo "gpg_bash_lib_output_in_future_pretty_output: $gpg_bash_lib_output_in_future_pretty_output"
- possible values: true (fresh) or false (not fresh).
- example use:
if [ "$gpg_bash_lib_output_freshness_status" = "true" ]; then echo "Signature is current." else echo "Signature NOT current." >&2 exit 1 fi
- description: A string, that contains the result of the comparison of the
- possible values:
- lenient (Signature is not yet valid, still within accepted range.)
- slow (Signature is not yet valid.)
- current (Signature is current.)
- outdated (Signature is no longer valid (outdated).)
- recommended action: Reject files, if the signature freshness is apparently
- example usage:
case "$gpg_bash_lib_output_freshness_detail" in
"lenient")
signature_creation_msg="Your clock might be slow.
According to your system clock, signature was created $gpg_bash_lib_output_signed_on_unixtime_minus_current_unixtime_pretty before current time.
You can probably ignore this, because it still is within range. (Okay up to $gpg_bash_lib_output_maximum_age_pretty_output before.)"
## ...
;;
"slow")
signature_creation_msg="Your clock might be slow.
According to your system clock, signature was created $gpg_bash_lib_output_signed_on_unixtime_minus_current_unixtime_pretty before current time."
## ...
;;
"outdated")
signature_creation_msg="Signature looks quite old already.
Either,
- your clock might be fast (at least $gpg_bash_lib_output_in_future_pretty_output fast). $clock_hint
- there is really no newer signature yet. Signature is really older than $gpg_bash_lib_output_maximum_age_pretty_output. already. (Older than $gpg_bash_lib_output_in_future_pretty_output already.)
- this is a $0 bug
- this is an attack"
## ...
;;
"current")
signature_creation_msg="According to your system clock, signatures was created $gpg_bash_lib_output_current_unixtime_minus_signed_on_unixtime_pretty ago."
## ...
;;
*)
echo "gpg_bash_lib_output_freshness_detail is neither lenient, nor slow, nor outdated, nor current, it is: $gpg_bash_lib_output_freshness_detail" >&2
exit 125
;;
esac
- possible values: A textual string, that contains diagnostic output, that puts gpg_bash_lib_output_freshness_detail into more details, developers speech, that may or may not be useful to show in your script (when in verbose mode).
- possible values: A textual string, gpg_bash_lib_input_maximum_age_in_seconds converted into a pretty format.
- possible values: "", true (if all checks succeeded) or false (if at least one check failed, such as if gpg_bash_lib_input_file_name_enforce was set to true, but verification of the name of the file failed or if the signature was not considered fresh).
- example usage:
if [ ! "$gpg_bash_lib_output_alright_status" = "true" ]; then ## ... exit 1 fi
To verify the names of files, i.e. to verify the file@name OpenPGP Notation, see also variable gpg_bash_lib_input_file_name_enforce above.
To create a signature, that contains this OpenPGP notation, you might like to use something like the following command and and/or function.
sign_cmd() {
## GPG signatures do not authenticate filenames by default, therefore add
## the name of the file as a OpenPGP notation so at least users or scripts
## that look at OpenPGP notations have a chance to detect if file names
## have been tampered with. See also:
## https://github.com/adrelanos/gpg-bash-lib
gpg --detach-sign --armor --yes --set-notation "file@name"="$(basename "$1")" "$1"
}
And for verification.
verify_cmd() {
gpg --verify-options show-notations --verify "$1"
}
To aid detection of indefinite freeze and rollback (downgrade) attacks, consider storing the Signature Creation Date (see variables gpg_bash_lib_output_signed_on_unixtime and/or gpg_bash_lib_output_signed_on_date) in a file, so you can compare them next time you download a supposedly newer signature. If the newly downloaded signature is older than the last known one, then maybe something is wrong.
The above tip will not work for initial signature downloads. Therefore consider preseeding a sane initial value.
Like the two above tips? We should abstract that code as well. Interested to implement it into gpg-bash-lib?
If you are the one providing the signatures, if there are no new releases, often recreate and reupload them to refresh the signature creation date.
To avoid conflicts with variables or function names, which your script might have defined earlier, the following conventions have been applied.
- Function names start with gpg_bash_lib_function_.
- Variable names found out by the library start with gpg_bash_lib_output_.
- Variable names that may be input by the user start with gpg_bash_lib_output_.
- Variable names that are only internally used start with gpg_bash_lib_internal_.
Any operations that could take longer, such as the gpg --verify operation, are executed using bash's wait builtin. To explain this better, see the following pseudo code, it is the style that this library is using.
gpg ... &
gpg_bash_lib_internal_gpg_verify_pid="$!"
wait "$gpg_bash_lib_internal_gpg_verify_pid" || { gpg_bash_lib_output_gpg_verify_exit_code="$?" ; true; };
This has the advantage, that your script can still react to any eventual trap's listening for example for signal SIGTERM.
- Multiple signatures in a single signature file are not well supported yet.
- When there are multiple signatures in a single signature file, the signature will be accepted as valid, when at least one key from the signing key folder (see variable gpg_bash_lib_input_key_import_dir above) made a good signature. Feedback welcome on situations where there are multiple mixed good and bad signatures.
- Issue Tracker
- Writing your own custom code.
- Please add any not listed here.
Welcome.
- Patrick Schleizer
- e-mail: [email protected]
- gpg: 916B8D99C38EAF5E8ADC7A2A8D66066A2EEACCDA
- twitter: https://twitter.com/adrelanos
- twitter: https://twitter.com/Whonix
- Donate
GPLv3+
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent