PKG_CHECKSUM(3)

NAME
pkg_checksum_file, pkg_checksum_generate_file, pkg_checksum_validate_file, pkg_checksum_type_from_string - compute and validate file checksums

LIBRARY
libpkg

SYNOPSIS
#include <pkg/checksum.h>
unsigned char *
pkg_checksum_file(const char *path, pkg_checksum_type_t type);
char *
pkg_checksum_generate_file(const char *path, pkg_checksum_type_t type);
int
pkg_checksum_validate_file(const char *path, const char *sum);
pkg_checksum_type_t
pkg_checksum_type_from_string(const char *name);

DESCRIPTION
These functions compute and validate checksums of files. Multiple hash algorithms and encodings are supported via the pkg_checksum_type_t enumeration.

pkg_checksum_file() computes the checksum of path using algorithm type and returns the raw encoded hash as a dynamically allocated string. The caller must free the returned pointer. Returns NULL on error.

pkg_checksum_generate_file() is similar to pkg_checksum_file() but returns the checksum in the portable format “type_id$hash”, where type_id is the numeric value of the pkg_checksum_type_t enumeration. This format is self-describing: the type can be recovered from the string, enabling backward-compatible checksum verification. The caller must free the returned pointer. Returns NULL on error.

pkg_checksum_validate_file() verifies that the checksum of path matches sum. The sum argument may be in the portable format “type_id$hash” or a bare SHA-256 hex string for backward compatibility. Returns 0 on success, -1 on checksum mismatch, or an errno(2) value if the file cannot be accessed.

pkg_checksum_type_from_string() converts a human-readable type name to the corresponding pkg_checksum_type_t value. Returns PKG_HASH_TYPE_UNKNOWN if the name is not recognized.

CHECKSUM TYPES
The following types are defined in <pkg/checksum.h>:

PKG_HASH_TYPE_SHA256_HEX
    SHA-256, hexadecimal encoding. String name: "sha256_hex".

PKG_HASH_TYPE_SHA256_BASE32
    SHA-256, z-base-32 encoding. String name: "sha256_base32".

PKG_HASH_TYPE_BLAKE2_BASE32
    BLAKE2b-512, z-base-32 encoding. String name: "blake2_base32".

PKG_HASH_TYPE_BLAKE2S_BASE32
    BLAKE2s-256, z-base-32 encoding. String name: "blake2s_base32".

The raw variants (PKG_HASH_TYPE_SHA256_RAW, PKG_HASH_TYPE_BLAKE2_RAW, PKG_HASH_TYPE_BLAKE2S_RAW) return unencoded binary digests and are intended for internal use.

RETURN VALUES
pkg_checksum_file() and pkg_checksum_generate_file() return a dynamically allocated string on success, or NULL on failure.

pkg_checksum_validate_file() returns 0 if the checksum matches, -1 on mismatch, or a positive errno(2) value if the file cannot be accessed.

pkg_checksum_type_from_string() returns PKG_HASH_TYPE_UNKNOWN if the type name is not recognized.

EXAMPLES
Compute a BLAKE2b checksum with type prefix:

    #include <pkg/checksum.h>
    char *sum = pkg_checksum_generate_file("/usr/local/bin/curl",
        PKG_HASH_TYPE_BLAKE2_BASE32);
    /* sum is "2$ybndr..." */
    free(sum);

Validate a file against a stored checksum:

    if (pkg_checksum_validate_file(path, stored_sum) != 0)
        errx(1, "checksum mismatch");

Resolve a type name:

    pkg_checksum_type_t t = pkg_checksum_type_from_string("blake2_base32");

SEE ALSO
pkg_create(3), pkg_printf(3), pkg_repo_create(3), pkg_repos(3), pkg-keywords(5), pkg-lua-script(5), pkg-repository(5), pkg-script(5), pkg-triggers(5), pkg.conf(5), pkg(8), pkg-add(8), pkg-alias(8), pkg-annotate(8), pkg-audit(8), pkg-autoremove(8), pkg-check(8), pkg-checksum(8), pkg-clean(8), pkg-config(8), pkg-create(8), pkg-delete(8), pkg-fetch(8), pkg-help(8), pkg-info(8), pkg-install(8), pkg-key(8), pkg-lock(8), pkg-plugins(8), pkg-query(8), pkg-register(8), pkg-repo(8), pkg-repositories(8), pkg-rquery(8), pkg-rwhich(8), pkg-search(8), pkg-set(8), pkg-shell(8), pkg-shlib(8), pkg-ssh(8), pkg-stats(8), pkg-triggers(8), pkg-unregister(8), pkg-update(8), pkg-updating(8), pkg-upgrade(8), pkg-version(8), pkg-which(8)