NAME

TeXLive::TLCrypto -- TeX Live checksums and cryptographic signatures

SYNOPSIS

  use TeXLive::TLCrypto;  # requires Digest::MD5 and Digest::SHA

Setup

  TeXLive::TLCrypto::setup_checksum_method();

Checksums

  TeXLive::TLCrypto::tlchecksum($path);
  TeXLive::TLCrypto::verify_checksum($file, $url);
  TeXLive::TLCrypto::verify_checksum_and_check_return($file, $url);

Signatures

  TeXLive::TLCrypto::setup_gpg();
  TeXLive::TLCrypto::verify_signature($file, $url);

DESCRIPTION

setup_checksum_method()

Tries to find a checksum method: check usability of Digest::SHA, then the programs openssl, sha512sum, and shasum, in that order. On old-enough Macs, openssl is present but does not have the option -sha512, while the separate program shasum does suffice.

Returns the checksum method as a string, and also sets <$::checksum_method>, or false if none found.

tlchecksum($file)

Return checksum of $file.

tl_short_digest($str)

Return short digest (MD5) of $str.

verify_checksum_and_check_return($file, $tlpdburl [, $is_main, $localcopymode ])

Calls <verify_checksum> and checks the various return values for critical errors, and dies if necessary.

If $is_main is given and true, an unsigned tlpdb is considered fatal. If $localcopymode is given and true, do not die for checksum and connection errors, thus allowing for re-downloading of a copy.

verify_checksum($file, $checksum_url)

Verifies that $file has checksum $checksum_url, and if gpg is available also verifies that the checksum is signed.

Returns $VS_VERIFIED on success, $VS_CONNECTION_ERROR on connection error, $VS_UNSIGNED on missing signature file, $VS_GPG_UNAVAILABLE if no gpg program is available, $VS_PUBKEY_MISSING if the pubkey is not available, $VS_CHECKSUM_ERROR on checksum errors, $VS_EXPKEYSIG if the signature is good but was made with an expired key, $VS_REVKEYSIG if the signature is good but was made with a revoked key, and $VS_SIGNATURE_ERROR on signature errors. In case of errors returns an informal message as second argument.

setup_gpg()

Tries to set up gpg command line $::gpg used for verification of downloads. Checks for the environment variable TL_GNUPG; if that envvar is not set, first gpg, then gpg2, then, on Windows only, tlpkg/installer/gpg/gpg.exe is looked for. Further adaptation of the invocation of gpg can be done using the two enviroment variables TL_GNUPGHOME, which is passed to gpg with --homedir, and TL_GNUPGARGS, which replaces the default arguments --no-secmem-warning --no-permission-warning.

Returns 1/0 on success/failure.

verify_signature($file, $url)

Verifies a download of $url into $file by cheking the gpg signature in $url.asc.

Returns $VS_VERIFIED on success, $VS_REVKEYSIG on good signature but from revoked key, $VS_EXPKEYSIG on good signature but from expired key, $VS_UNSIGNED on missing signature file, $VS_SIGNATURE_ERROR on signature error, $VS_GPG_UNAVAILABLE if no gpg is available, and $VS_PUBKEY_MISSING if a pubkey is missing. In case of errors returns an informal message as second argument.

gpg_verify_signature($file, $sig)

Internal routine running gpg to verify signature $sig of $file.

%VerificationStatusDescription

Provides a textual representation for the verification status values.

AUTHORS AND COPYRIGHT

This script and its documentation were written for the TeX Live distribution (https://tug.org/texlive) and both are licensed under the GNU General Public License Version 2 or later.