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>