NAME¶

bsign - embed and verify secure hashes and digital signatures

SYNOPSIS¶

bsign [ options | FILENAMES ]

DESCRIPTION¶

The goal purpose of bsign is to verify and authenticate data files, especially executables and other binaries. The program reads all of the options and FILENAMES from the command line and then begins to operate on the input files. In one invocation in can only one of either hash files, sign files, check hashes, or check signatures. At present, it only works with the ELF (Execution and Link Format) files used by several flavors of UN*X including GNU/Linux, and it only supports gpg for creating and verifying signatures. It embeds a secure hash of the file contents in the file and optionally signs this hash value. Any change in the file contents will be easily discovered. Either the hash value does not match the file contents, the hash is absent, the signature (optional) of the hash value is invalid, ir the signature (optional) is absent.

COMMANDS¶

One of these commands must be present. Only the last one on the command line will be recognized.

-c, --checkhash

Verify the embedded hash value.

-H, --hash

Rewrite the input files with a hash.

-s, --sign

Rewrite the input files with signed hash data. Note that the while rewriting process will fail if generation of the digital signature fails. If no supported facility for creating signatures is available, only the --hash method will work.

-V, --verify

Verify the embedded hash value and digital signature.

--version

Display program version.

-h, --help

Display program options and usage information.

 

OPTIONS¶

-d, --debug

Enable the display of debug messages.

-e, --exclude PATH

Add PATH to the list of directories to exclude for input files, it may be used more than once. A trailing path separator ('/') will be ignored.

-f, --files FILE

Process filenames in FILE, one per line. Use filename - for standard input. This options has the same effect as putting each line in FILE on the command line as a distinct word.

--force-resign

By default, bsign will not resign a file if there is already a signature section present. Note that this means it won't resign a file that has been hashed without a signature, too. This option will override that behavior, replacing the existing signature block.

-G, --ignore-good-sigs

Inhibit information messages about finding good signatures. This option is helpful when verifying from a cron script where all files are expected to have good signatures. Messages about missing or broken signatures are unaffected by --ignore-good-sigs.

-i, --include PATH

Add PATH to the list of directories to search for input files, it may be used more than once. This method will tend to be faster and simpler than using the find program to generate a list of filenames.

-I, --ignore-unsupported

Ignore directories and non-ELF files in error messages. This option reduces bsign output.

--nosymlinks

Treat symlinks as an unsupported file type. This prevents some files from being signed redundantly.

-o, --output FILE

Write signed, rewritten version of the input file to FILE. Without this option, the input file is replaced by the rewritten version. The --output option only works when there is a single input filename on the command line.

-P, --pgoptions OPTS

Pass OPTS to gpg as command lines options. This is helpful for telling gpg where to find keys.

-q, --quiet

Inhibit informational messages. With this option, the result of executing bsign is known only by checking the return status.

-S, --summary

Print a summary after processing the last input file. At the moment, it only tracks the total number of input files reviewed.

-v, --verbose

Report details about program progress.

 

 

RETURN VALUE¶

The program return value reflects the result from the last file processed. Therefore, it is most useful when processing a single file. It returns zero when successfully signing or hashing a file, or when the signature or hash is found to be present and valid. Return codes less than 64 are errno values.

0 no error

 

1 permission denied

 

2 file not found

 

12 no memory

 

21 is directory

 

22 invalid argument

 

24 too many open files

 

26 file busy

 

28 no space on device

 

36 name too long

 

64 no hash found

 

65 no signature found

 

66 bad hash found

 

67 bad signature found

 

68 unsupported file type

 

69 bad pass phrase

 

70 rewrite failed

 

USAGE¶

you intend to use bsign only to protect the contents of the filesystem against corruption, there is little that must be done aside from hashing the files and performing periodic checks for correct hash values. Refer to the EXAMPLES section for some possible invocations. If you intend to use bsign to detect intrusion, the way is less clear. First, the usual reminder: the security of a system is only as strong as the weakest link. More detailed instructions on how to use bsign in this mode may be found in the /usr/share/doc/bsign/README file.

EXAMPLES¶

bsign --hash file

rewrite file with a hash

bsign --check-hash file

verify the hash in file

bsign --sign file -P "--homedir keydir"

rewrite file with a hash and sign it with the default secret key in keydir

bsign --verify file -P "--homedir keydir"

verify the hash and signature in file using the key in keydir

bsign --sign -i / -e /proc -I -s --P "--homedir keydir"

sign the unsigned files in the whole filesystem

bsign --verify -i / -e /proc -I -G --P "--homedir keydir"

verify signatures for all files in the filesystem and only report those that have been tampered or are unsigned.

 

ENVIRONMENT VARIABLES¶

bsign should use environment variables to select the method for generating digital signatures. It doesn't.

BUGS¶

It supports only one hash algorithm, an insignificant bug if one at all. It supports only GNU Privacy Guard for creating and verifying digital signatures. It can embed only in ELF format files, others would be helpful.

AUTHOR¶

Marc Singer <elf@debian.org>