Stowage/clamav
2
0
Fork 0
mirror of https://github.com/Cisco-Talos/clamav.git synced 2025-10-19 10:23:17 +00:00
Code Issues Projects Releases Packages Wiki Activity
clamav/docs/man/sigtool.1.in
Valerie Snyder 13c4788f36
FIPS & FIPS-like limits on hash algs for cryptographic uses 
ClamAV will not function when using a FIPS-enabled OpenSSL 3.x.
This is because ClamAV uses MD5 and SHA1 algorithms for a variety of
purposes including matching for malware detection, matching to prevent
false positives on known-clean files, and for verification of MD5-based
RSA digital signatures for determining CVD (signature database archive)
authenticity.

Interestingly, FIPS had been intentionally bypassed when creating hashes
based whole buffers and whole files (by descriptor or `FILE`-pointer):
78d4a9985a
Note: this bypassed FIPS the 1.x way with:
`EVP_MD_CTX_set_flags(ctx, EVP_MD_CTX_FLAG_NON_FIPS_ALLOW);`

It was NOT disabled when using `cl_hash_init()` / `cl_update_hash()` /
`cl_finish_hash()`. That likely worked by coincidence in that the hash
was already calculated most of the time. It certainly would have made
use of those functions if the hash had not been calculated prior:
78d4a9985a/libclamav/matcher.c (L743)

Regardless, bypassing FIPS entirely is not the correct solution.
The FIPS restrictions against using MD5 and SHA1 are valid, particularly
when verifying CVD digital siganatures, but also I think when using a
hash to determine if the file is known-clean (i.e. the "clean cache" and
also MD5-based and SHA1-based FP signatures).

This commit extends the work to bypass FIPS using the newer 3.x method:
`md = EVP_MD_fetch(NULL, alg, "-fips");`

It does this for the legacy `cl_hash*()` functions including
`cl_hash_init()` / `cl_update_hash()` / `cl_finish_hash()`.
It also introduces extended versions that allow the caller to choose if
they want to bypass FIPS:
- `cl_hash_data_ex()`
- `cl_hash_init_ex()`
- `cl_update_hash_ex()`
- `cl_finish_hash_ex()`
- `cl_hash_destroy_ex()`
- `cl_hash_file_fd_ex()`
See the `flags` parameter for each.

Ironically, this commit does NOT use the new functions at this time.
The rational is that ClamAV may need MD5, SHA1, and SHA-256 hashes of
the same files both for determining if the file is malware, and for
determining if the file is clean.

So instead, this commit will do a checks when:

1. Creating a new ClamAV scanning engine. If FIPS-mode enabled, it will
   automatically toggle the "FIPS limits" engine option.
   When loading signatures, if the engine "FIPS limits" option is enabled,
   then MD5 and SHA1 FP signatures will be skipped.

2. Before verifying a CVD (e.g. also for loading, unpacking when
   verification enabled).
   If "FIPS limits" or FIPS-mode are enabled, then the legacy MD5-based RSA
   method is disabled.

   Note: This commit also refactors the interface for `cl_cvdverify_ex()`
   and `cl_cvdunpack_ex()` so they take a `flags` parameters, rather than a
   single `bool`. As these functions are new in this version, it does not
   break the ABI.

The cache was already switched to use SHA2-256, so that's not a concern
for checking FIPS-mode / FIPS limits options.

This adds an option for `freshclam.conf` and `clamd.conf`:

   FIPSCryptoHashLimits yes

And an equivalent command-line option for `clamscan` and `sigtool`:

   --fips-limits

You may programmatically enable FIPS-limits for a ClamAV engine like this:
```C
   cl_engine_set_num(engine, CL_ENGINE_FIPS_LIMITS, 1);
```

CLAM-2792
2025-08-14 22:39:15 -04:00

221 lines
6.7 KiB
Groff
Raw Blame History

.TH "sigtool" "1" "February 12, 2007" "ClamAV @VERSION@" "Clam AntiVirus"
.SH "NAME"
.LP
sigtool \- signature and database management tool
.SH "SYNOPSIS"
.LP
sigtool [options]
.SH "DESCRIPTION"
.LP
sigtool can be used to generate MD5 checksums, convert data into hexadecimal format, list virus signatures and build/unpack/test/verify CVD databases and update scripts.
.SH "COMMON OPTIONS"
.LP
.TP
\fB\-h, \-\-help\fR
Output help information and exit.
.TP
\fB\-V, \-\-version\fR
Print version number and exit.
.TP
\fB\-\-quiet\fR
Be quiet, output only error messages.
.TP
\fB\-\-debug\fR
Enable debug messages
.TP
\fB\-\-stdout\fR
Write all messages to stdout.
.TP
\fB\-\-tempdir=DIRECTORY\fR
Create temporary files in DIRECTORY. Directory must be writable for the user running sigtool.
.TP
\fB\-\-leave\-temps\fR
Do not remove temporary files.
.TP
\fB\-\-datadir=DIR\fR
Use DIR as the default database directory for all operations.
.SH "COMMANDS FOR WORKING WITH SIGNATURES"
.LP
.TP
\fB\-l[FILE], \-\-list\-sigs[=FILE]\fR
List all signature names from the local database directory (default) or from FILE.
.TP
\fB\-fREGEX, \-\-find\-sigs=REGEX\fR
Find and display signatures from the local database directory which match the given REGEX. The whole signature body (name, hex string, etc.) is checked.
.TP
\fB\-\-decode\-sigs=REGEX\fR
Decode signatures read from the standard input (eg. piped from \-\-find\-sigs)
.TP
\fB\-\-test\-sigs=DATABASE TARGET_FILE\fR
Test all signatures from DATABASE against TARGET_FILE. This option will only give valid results if the target file is the final one (after unpacking, normalization, etc.) for which the signatures were created.
.SH "COMMANDS TO GENERATE SIGNATURES"
.LP
.TP
\fB\-\-md5 [FILES]\fR
Generate MD5 checksum from stdin or MD5 sigs for FILES.
.TP
\fB\-\-sha1 [FILES]\fR
Generate SHA1 checksum from stdin or SHA1 sigs for FILES.
.TP
\fB\-\-sha2-256 [FILES]\fR
Generate SHA2-256 checksum from stdin or SHA2-256 sigs for FILES.
The previous option \-\-sha256 is deprecated and may be removed in a future version.
.TP
\fB\-\-mdb [FILES]\fR
Generate .mdb (PE section hash) signatures for FILES.
.TP
\fB\-\-imp [FILES]\fR
Generate .imp (PE import address table hash) signatures for FILES.
.TP
\fB\-\-fuzzy\-img [FILES]\fR
Generate image fuzzy hash for each file.
.SH "COMMANDS TO NORMALIZE FILES"
.LP
.TP
\fB\-\-html\-normalise=FILE\fR
Create normalised HTML files comment.html, nocomment.html, and script.html in current working directory.
.TP
\fB\-\-ascii\-normalise=FILE\fR
Create normalised text file from ascii source.
.TP
\fB\-\-utf16\-decode=FILE\fR
Decode UTF16 encoded data.
.SH "COMMANDS FOR FILE ANALYSIS"
.LP
.TP
\fB\-\-vba=FILE\fR
Extract VBA/Word6 macros from given MS Office document.
.TP
\fB\-\-vba\-hex=FILE\fR
Extract Word6 macros from given MS Office document and display the corresponding hex values.
.TP
\fB\-\-print\-certs=FILE\fR
Print Authenticode details from a PE file.
.TP
\fB\-\-hex\-dump\fR
Read data from stdin and write hex string to stdout.
.SH "COMMANDS FOR WORKING WITH CVDS"
.LP
.TP
\fB\-i, \-\-info\fR
Print a CVD information and verify MD5 and a digital signature.
.TP
.TP
\fB\-\-build=FILE, \-b FILE\fR
Build a CVD file. \-s, \-\-server is required for signed virus databases(.cvd), or, \-\-unsigned for unsigned(.cud).
.TP
\fB\-\-max\-bad\-sigs=NUMBER\fR
Maximum number of mismatched signatures when building a CVD. Default: 3000
.TP
\fB\-\-flevel\fR
Specify a custom flevel. Default: 77
.TP
\fB\-\-cvd\-version\fR
Specify the version number to use for the build. Default is to use the value+1
from the current CVD in \-\-datadir. If no datafile is found the default
behaviour is to prompt for a version number, this switch will prevent the
prompt.
NOTE: If a CVD is found in the \-\-datadir its version+1 is used and this value is ignored.
.TP
\fB\-\-no\-cdiff\fR
Don't create a .cdiff file when building a new database file.
.TP
\fB\-\-hybrid\fR
Create a hybrid (standard and bytecode) database file.
.TP
\fB\-\-unsigned\fR
Create a database file without digital signatures (.cud).
.TP
\fB\-\-server=ADDR\fR
ClamAV Signing Service address (for virus database maintainers only).
.TP
.TP
\fB\-\-unpack=FILE, \-u FILE\fR
Unpack FILE (CVD) to a current directory.
.TP
.TP
\fB\-\-unpack\-current\fR
Unpack a local CVD file (main or daily) to current directory.
.TP
\fB\-\-fips\-limits\fR
Enforce FIPS\-like limits on using hash algorithms for cryptographic purposes. Will disable MD5 & SHA1 FP sigs and will require '.sign' files to verify CVD authenticity.
.SH "COMMANDS FOR WORKING WITH CDIFF PATCH FILES"
.LP
.TP
\fB\-\-diff=OLD NEW, \-d OLD NEW\fR
Create a diff file for OLD and NEW CVDs/INCDIRs.
.TP
\fB\-\-compare=OLD NEW, \-c OLD NEW\fR
This command will compare two text files and print differences in a cdiff format.
.TP
\fB\-\-run\-cdiff=FILE, \-r FILE\fR
Execute update script FILE in current directory.
.TP
\fB\-\-verify\-cdiff=FILE, \-r FILE\fR
Verify DIFF against CVD/INCDIR.
.SH "COMMANDS FOR CREATING AND VERIFYING DETACHED DIGITAL SIGNATURES"
.LP
.TP
\fB\-\-sign\fR
Sign a file. The resulting .sign file name will be in the form: dbname\-version.cvd.sign
or FILE.sign for non\-CVD targets. It will be created next to the target file.
If a .sign file already exists, then the new signature will be appended to file.
.TP
\fB\-\-key=FILE\fR
Specify a signing key.
.TP
\fB\-\-cert=FILE\fR
Specify a signing cert. May be used more than once to add intermediate and root certificates.
.TP
\fB\-\-append\fR
Use to add a signature line to an existing .sign file. Otherwise an existing .sign file will be overwritten.
.TP
.TP
\fB\-\-verify\fR
Find and verify a detached digital signature for the given file.
The digital signature file name must be in the form: dbname\-version.cvd.sign or FILE.sign for non-CVD targets.
It must be found next to the target file.
.TP
\fB\-\-cvdcertsdir=DIR\fR
Specify a directory containing the root CA cert needed to verify the signature.
If not provided, then sigtool will look in the default certs directory.
.SH "ENVIRONMENT VARIABLES"
.LP
Sigtool uses the following environment variables:
.TP
\fBSIGNDUSER\fR
The username to authenticate with the signing server when building a signed CVD database.
.TP
\fBSIGNDPASS\fR
The password to authenticate with the signing server when building a signed CVD database.
.TP
\fBCVD_CERTS_DIR\fR
Specify a directory containing the root CA cert needed to verify detached CVD digital signatures. If not provided, then sigtool will look in the default directory.
.SH "EXAMPLES"
.LP
.TP
Generate hex string from testfile and save it to testfile.hex:
\fBcat testfile | sigtool \-\-hex\-dump > testfile.hex\fR
.SH "CREDITS"
Please check the full documentation for credits.
.SH "AUTHOR"
.LP
Tomasz Kojm <tkojm@clamav.net>
.SH "SEE ALSO"
.LP
freshclam(1), freshclam.conf(5)
Reference in a new issue View git blame Copy permalink