gpg-bash-lib – gpg file verification bash library – first public release announcement – 0.5-1

gpg-bash-lib is a gpg file verification bash library, addresses comprehensive threat model, that covers file name tampering, indefinite freeze, rollback, endless data attacks, etc.

https://github.com/Whonix/gpg-bash-lib

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. Quote Werner Koch [1] (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 [2] (The Update Framework)’s [3] threat model [4] [5].)

Mini Demo:
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.

Documentation:
https://github.com/Whonix/gpg-bash-lib/blob/master/README.mediawiki

Usage examples:
https://github.com/Whonix/gpg-bash-lib/tree/master/usr/share/gpg-bash-lib/examples

Main code file:
https://github.com/Whonix/gpg-bash-lib/blob/master/usr/lib/gpg-bash-lib/modules.d/50_common

Specifically, does the status-fd parsing code look sane?
https://github.com/Whonix/gpg-bash-lib/blob/d6cff902f40135c3e100a5bb13a6fe8275a41828/usr/lib/gpg-bash-lib/modules.d/50_common#L350

Could you leave some feedback please?

Anyone else interested to contribute?

[1] http://lists.gnupg.org/pipermail/gnupg-devel/2005-December/022559.html
[2] https://www.updateframework.com/
[3] https://github.com/theupdateframework/tuf
[4] https://github.com/theupdateframework/tuf/blob/develop/SECURITY.md
[5] http://www.webcitation.org/6F7Io2ncN

Patrick started developing Whonix, the Anonymous Operating System in 2012, when quickly others joined efforts. He collected experiences working pseudonymous on Whonix for two years, enjoys collaboratively working on privacy preserving software.