Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/kicksecure/gpg-bash-lib

gpg file verification bash library, addresses comprehensive threat model, that covers file name tampering, indefinite freeze, rollback, endless data attacks, etc.
https://github.com/kicksecure/gpg-bash-lib
bash-scripts diagnostic-output gpg security verification
Last synced: about 2 months ago
JSON representation
gpg file verification bash library, addresses comprehensive threat model, that covers file name tampering, indefinite freeze, rollback, endless data attacks, etc.
Host: GitHub
URL: https://github.com/kicksecure/gpg-bash-lib
Owner: Kicksecure
License: other
Created: 2015-01-16T02:43:53.000Z (almost 10 years ago)
Default Branch: master
Last Pushed: 2023-11-11T20:15:12.000Z (about 1 year ago)
Last Synced: 2023-11-11T21:23:22.630Z (about 1 year ago)
Topics: bash-scripts, diagnostic-output, gpg, security, verification
Language: Shell
Homepage: https://www.kicksecure.com/wiki/imprint
Size: 887 KB
Stars: 12
Watchers: 5
Forks: 5
Open Issues: 1
Metadata Files:
- Readme: README.mediawiki
- Changelog: changelog.upstream
- Contributing: CONTRIBUTING.md
- License: COPYING
Awesome Lists containing this project

README

        = Why =

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.

[http://lists.gnupg.org/pipermail/gnupg-devel/2005-December/022559.html Quote Werner Koch]

([https://gnupg.org/ 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

[https://www.updateframework.com TUF] ([https://github.com/theupdateframework/tuf The Update Framework])'s

[https://github.com/theupdateframework/tuf/blob/develop/SECURITY.md threat model] ([http://www.webcitation.org/6F7Io2ncN w]).)

= What does it do =

* 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.

= What does it NOT do =

* Anything else not mentioned above in "What does it do".

= Requirements =

* bash

= Installation =


sudo make install



Or see [https://github.com/Whonix/gpg-bash-lib/blob/master/README_generic.md README_generic.md].

= Usage =

== Practical ==

=== Examples ===

See [https://github.com/Whonix/gpg-bash-lib/blob/master/usr/share/gpg-bash-lib/examples/ /usr/share/gpg-bash-lib/examples/] folder.

=== Mini Demo ===

After installation, if you would run the following command.

[https://github.com/Whonix/gpg-bash-lib/blob/master/usr/share/gpg-bash-lib/examples/one /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.

== Example Implementations ==

* [https://github.com/Whonix/whonixcheck whonixcheck]: See function [https://github.com/Whonix/whonixcheck/blob/fd60ad1c09d3681fd15c1370d1fbf3a9ba854aad/usr/lib/whonixcheck/check_news#L122 verify_whonix_news].

* [https://github.com/Whonix/tb-updater tb-updater]: See function [https://github.com/Whonix/tb-updater/blob/95d0ce13c601cb62d5f70b06dd80eb92d857cfbe/usr/bin/update-torbrowser#L901 tb_gpg_verify] and function [https://github.com/Whonix/tb-updater/blob/95d0ce13c601cb62d5f70b06dd80eb92d857cfbe/usr/bin/update-torbrowser#L644 tb_confirm_update].

== Theoretical ==

=== Introduction ===

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.

=== Variables ===

==== Input Variables ====

===== gpg_bash_lib_input_temp_folder =====

* 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

===== gpg_bash_lib_input_key_import_dir =====

* 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

===== gpg_bash_lib_input_file_name_enforce =====

* 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

===== gpg_bash_lib_input_cleanup =====

* 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

===== gpg_bash_lib_input_data_file =====

* 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

===== gpg_bash_lib_input_sig_file =====

* 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

===== gpg_bash_lib_input_error_handler_extra =====

* 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'



===== gpg_bash_lib_input_verify_timeout_after =====

* 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

===== gpg_bash_lib_input_verify_kill_after =====

* 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

===== gpg_bash_lib_input_maximum_age_in_seconds =====

* 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

===== gpg_bash_lib_input_slow_clock_lenient_up_to_seconds =====

* 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

==== Output Variables ====

===== gpg_bash_lib_output_failure_status =====

* 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



===== gpg_bash_lib_output_diagnostic_message =====

* 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 " 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 "

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 

[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



===== gpg_bash_lib_output_gpg_import_output =====

* 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.

===== gpg_bash_lib_output_gpg_verify_exit_code =====

* 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



===== gpg_bash_lib_output_gpg_verify_output =====

* 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.

===== gpg_bash_lib_output_gpg_verify_status_fd_output =====

* 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.

===== gpg_bash_lib_output_signed_on_unixtime =====

* 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

===== gpg_bash_lib_output_signed_on_date =====

* 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

===== gpg_bash_lib_output_file_name_tampering =====

* 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



===== gpg_bash_lib_output_notation["file@name"] =====

* 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"]}"



===== gpg_bash_lib_output_slow_clock_lenient_up_to_pretty_output =====

* 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

===== gpg_bash_lib_output_goodsig_status =====

* 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



===== gpg_bash_lib_output_validsig_status =====

* 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



===== gpg_bash_lib_output_fingerprint_in_hex =====

* 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

===== gpg_bash_lib_output_current_unixtime =====

* possible values: integer, unixtime at time of running this library.

===== gpg_bash_lib_output_current_time =====

* 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

===== gpg_bash_lib_output_signed_on_unixtime_minus_current_unixtime =====

* 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.

===== gpg_bash_lib_output_signed_on_unixtime_minus_current_unixtime_pretty =====

* 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



===== gpg_bash_lib_output_current_unixtime_minus_signed_on_unixtime =====

* 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..

===== gpg_bash_lib_output_current_unixtime_minus_signed_on_unixtime_pretty =====

* 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



===== gpg_bash_lib_output_in_future_in_seconds =====

* 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.

===== gpg_bash_lib_output_in_future_pretty_output =====

* 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"



===== gpg_bash_lib_output_freshness_status =====

* 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



===== gpg_bash_lib_output_freshness_detail =====

* description: A string, that contains the result of the comparison of the

local clock (unixtime) with the signature creation date (unixtime). The example

below will explain this better.

* 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

slow, because that would indicate there either something is very wrong with

the signature or with the local system clock, or if the signature freshness

apparently outdated, because then there could be an indefinite freeze or

rollback (downgrade) attack in place. Accept if the signature freshness is

apparently current or lenient. In the latter case, explain that state to

the user. Use a snippet similar to the example below.

* 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



===== gpg_bash_lib_output_freshness_msg =====

* 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).

===== gpg_bash_lib_output_maximum_age_pretty_output =====

* possible values: A textual string, gpg_bash_lib_input_maximum_age_in_seconds converted into a pretty format.

===== gpg_bash_lib_output_alright_status =====

* 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



=== File Name Verification ===

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"

}

=== Security Tips ===

==== Signature Creation Date Storage ====

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.

==== Signature Creation Date Preseeding ====

The above tip will not work for initial signature downloads. Therefore consider preseeding a sane initial value.

==== Abstract it! ====

Like the two above tips? We should abstract that code as well. Interested to implement it into gpg-bash-lib?

==== Signature Freshness Updating ====

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.

=== Library Conventions ===

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_.

=== Goodies ===

==== SIGNAL Friendliness ====

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.

= Known Issues =

* 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.

* [https://phabricator.whonix.org/maniphest/?statuses=open%2Creview&allProjects=PHID-PROJ-y7ggndpa2rbgbboyhoqp#R Issue Tracker]

= Alternatives =

* Writing your own custom code.

* Please add any not listed here.

= Forks, Patches, Testers, Comments, etc. =

Welcome.

= Author =

* Patrick Schleizer

* e-mail: [email protected]

* [https://www.whonix.org/wiki/Patrick_Schleizer gpg]: 916B8D99C38EAF5E8ADC7A2A8D66066A2EEACCDA

* twitter: https://twitter.com/adrelanos

* twitter: https://twitter.com/Whonix

* [https://www.whonix.org/wiki/Donate Donate]

= License =

GPLv3+