/*
 * 	security.h - Runtime function declarations for libglacier
 *
 * 	This file is part of Glacier.
 *
 * 	Glacier is free software: you can redistribute it and/or modify it under the terms of the
 * 	GNU Lesser General Public License as published by the Free Software Foundation, either
 * 	version 3 of the License, or (at your option) any later version.
 *
 * 	Glacier is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
 * 	without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
 * 	PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
 *
 * 	You should have received a copy of the GNU Lesser General Public License along with Glacier. If
 * 	not, see <https://www.gnu.org/licenses/>.
 */

#ifndef GLACIERSECURITY_H_
#define GLACIERSECURITY_H_

typedef unsigned int uint;
typedef unsigned char uchar;

/*
 * compare_file_hash
 *
 * DESCRIPTION: compare_file_hash compares the SHA256 hashes of a file and its original hash
 * PARAMETERS:
 * 		char ORIG_HASH[] -> The file containing the expected hash result
 * 		char FILE[] -> The file to compare against ORIG_HASH[]
 * RETURN VALUES:
 * 		0 on hashes match, 1 on hashes do not match, -1 on library error
 * CAVEATS:
 * 		None.
 * EXAMPLE:
 * 		compare_file_hash("pkg.sha256sum", "pkg.tar.xz");
 */

/* int compare_file_hash(char ORIG_HASH[], char FILE[]); */

/*
 * hash_file
 *
 * DESCRIPTION: Performs a hashing operation on a file and stores the result
 * PARAMETERS:
 *      const char *filename -> The file to hash
 *      unsigned char *out_hash -> Buffer to store the resulting hash
 *      unsigned int *out_length -> Will contain the length of the hash
 * RETURN VALUES:
 *      0 on success, other values for specific errors
 * CAVEATS:
 *      out_hash buffer must be large enough to hold the hash (EVP_MAX_MD_SIZE recommended)
 * EXAMPLE:
 *      unsigned char hash[EVP_MAX_MD_SIZE];
 *      unsigned int hash_len;
 *      hash_file("file.txt", hash, &hash_len);
 */

int hash_file(const char *filename, unsigned char *out_hash, unsigned int *out_length);

/*
 * print_hash
 *
 * DESCRIPTION: Prints a specified hash string to stdout
 * PARAMETERS:
 *      unsigned char *hash -> The hash to print
 *      unsigned int length -> Length of the hash
 * RETURN VALUES:
 *      0 on success, 1 on error
 * CAVEATS:
 *      None
 * EXAMPLE:
 *      print_hash(hash, hash_len);
 */

int print_hash(uchar *hash, uint length);

/*
 * stash_hash
 *
 * DESCRIPTION: Stores a hash inside a string as hexadecimal representation
 * PARAMETERS:
 *      char *stored_hash -> Buffer to store the resulting hash string
 *      unsigned int stored_hash_size -> Size of the stored_hash buffer
 *      const uchar *hash -> The hash to convert to string
 *      uint length -> Length of the hash
 * RETURN VALUES:
 *      0 on success, 1 on error
 * CAVEATS:
 *      stored_hash buffer must be at least (length*2)+1 bytes in size
 * EXAMPLE:
 *      char hash_str[65]; // 32 bytes SHA-256 = 64 hex chars + null terminator
 *      stash_hash(hash_str, sizeof(hash_str), hash, hash_len);
 */

int stash_hash(char *stored_hash, unsigned int stored_hash_size, const uchar *hash, uint length);

/*
 * verify_signature
 *
 * DESCRIPTION: Checks if a package's signature is valid against the trusted keyring
 * PARAMETERS:
 *      char PACKAGE[] -> The package file to verify
 *      char SIGNATURE[] -> The signature file to check against
 * RETURN VALUES:
 *      0 on valid signature, 1 on invalid signature, 2 on file not found
 * CAVEATS:
 *      None
 * EXAMPLE:
 *      if (verify_signature("package.tar", "package.tar.sig") != 0) {
 *          errlog("invalid package signature");
 *          return(EXIT_FAILURE);
 *      }
 */

int verify_signature(char PACKAGE[], char SIGNATURE[]);

/*
 * check_integrity
 *
 * DESCRIPTION: Verifies a package's SHA256 checksum against the expected value
 * PARAMETERS:
 *      char PACKAGE[] -> The package file to check
 *      char EXPECTED_HASH[] -> The expected SHA256 hash
 * RETURN VALUES:
 *      0 on hash match, 1 on hash mismatch, 2 on file not found or hash calculation error
 * CAVEATS:
 *      None
 * EXAMPLE:
 *      char *expected = "d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592";
 *      if (check_integrity("package.tar", expected) != 0) {
 *          errlog("package integrity check failed");
 *          return(EXIT_FAILURE);
 *      }
 */

int check_integrity(char PACKAGE[], char EXPECTED_HASH[]);

#endif