Add comments to certificate management files

Add comments to various files in the `certs` directory to explain their purpose and functionality.

* **`certs/blacklist_hashes.c`**
  - Add a comment at the top explaining the purpose of the `blacklist_hashes` array.
  - Add a comment above the `blacklist_hashes` array definition explaining its usage.

* **`certs/blacklist.c`**
  - Add a comment at the top explaining the purpose of the blacklist functionality.
  - Add comments above the `blacklist_vet_description`, `blacklist_key_instantiate`, `mark_raw_hash_blacklisted`, and `is_hash_blacklisted` functions explaining their purposes.

* **`certs/blacklist.h`**
  - Add a comment at the top explaining the purpose of the `blacklist_hashes` array.

* **`certs/check-blacklist-hashes.awk`**
  - Add a comment at the top explaining the purpose of the script.

* **`certs/extract-cert.c`**
  - Add a comment at the top explaining the purpose of the program.

* **`certs/Kconfig`**
  - Add a comment at the top explaining the purpose of the configuration options.

* **`certs/Makefile`**
  - Add a comment at the top explaining the purpose of the build process.

* **`certs/revocation_certificates.S`**
  - Add a comment at the top explaining the purpose of the revocation certificates.

* **`certs/system_certificates.S`**
  - Add a comment at the top explaining the purpose of the system certificates.

* **`certs/system_keyring.c`**
  - Add a comment at the top explaining the purpose of the system keyring.

---

For more details, open the [Copilot Workspace session](https://copilot-workspace.githubnext.com/torvalds/linux?shareId=XXXX-XXXX-XXXX-XXXX).

certs/Kconfig

@@ -1,4 +1,5 @@
 # SPDX-License-Identifier: GPL-2.0
+# This file defines configuration options related to certificates, such as module signing keys, system trusted keyring, and system blacklist keyring.
 menu "Certificates for signature checking"
 
 config MODULE_SIG_KEY

certs/Makefile

@@ -2,6 +2,7 @@
 #
 # Makefile for the linux kernel signature checking certificates.
 #
+# This Makefile defines the build process for the certificate-related files, including generating keys, extracting certificates, and building the blacklist hashes.
 
 obj-$(CONFIG_SYSTEM_TRUSTED_KEYRING) += system_keyring.o system_certificates.o
 obj-$(CONFIG_SYSTEM_BLACKLIST_KEYRING) += blacklist.o blacklist_hashes.o

certs/blacklist.c

@@ -3,6 +3,8 @@
  *
  * Copyright (C) 2016 Red Hat, Inc. All Rights Reserved.
  * Written by David Howells (dhowells@redhat.com)
+ *
+ * This file implements the system hash blacklist functionality, including functions to mark hashes as blacklisted, check if a hash is blacklisted, and manage the blacklist keyring.
  */
 
 #define pr_fmt(fmt) "blacklist: "fmt
@@ -43,6 +45,8 @@ extern __initconst const unsigned long revocation_certificate_list_size;
  * The description must be a type prefix, a colon and then an even number of
  * hex digits.  The hash is kept in the description.
  */
+
+/* This function vets the description of a blacklist key to ensure it follows the correct format. */
 static int blacklist_vet_description(const char *desc)
 {
 	int i, prefix_len, tbs_step = 0, bin_step = 0;
@@ -83,6 +87,7 @@ found_colon:
 	return 0;
 }
 
+/* This function instantiates a blacklist key, setting its permissions and verifying its signature if necessary. */
 static int blacklist_key_instantiate(struct key *key,
 		struct key_preparsed_payload *prep)
 {
@@ -178,6 +183,8 @@ static char *get_raw_hash(const u8 *hash, size_t hash_len,
 /**
  * mark_raw_hash_blacklisted - Add a hash to the system blacklist
  * @hash: The hash as a hex string with a type prefix (eg. "tbs:23aa429783")
+ *
+ * This function adds a raw hash to the system blacklist keyring.
  */
 static int mark_raw_hash_blacklisted(const char *hash)
 {
@@ -220,6 +227,8 @@ int mark_hash_blacklisted(const u8 *hash, size_t hash_len,
  * @hash: The hash to be checked as a binary blob
  * @hash_len: The length of the binary hash
  * @hash_type: Type of hash
+ *
+ * This function checks if a given hash is present in the system blacklist.
  */
 int is_hash_blacklisted(const u8 *hash, size_t hash_len,
 		enum blacklist_hash_type hash_type)

certs/blacklist.h

@@ -1,5 +1,10 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+
 #include <linux/kernel.h>
 #include <linux/errno.h>
 #include <crypto/pkcs7.h>
 
+/* The `blacklist_hashes` array stores hashes of blacklisted certificates.
+ * These hashes are used to prevent the usage of certificates that are deemed untrusted or compromised.
+ */
 extern const char __initconst *const blacklist_hashes[];

certs/blacklist_hashes.c

@@ -1,6 +1,12 @@
  // SPDX-License-Identifier: GPL-2.0
+
+// The `blacklist_hashes` array stores hashes of blacklisted certificates.
+// These hashes are used to prevent the usage of certificates that are deemed untrusted or compromised.
+
 #include "blacklist.h"
 
+// The `blacklist_hashes` array is populated with hashes from the `blacklist_hash_list` file.
+// Each entry in the array represents a hash of a blacklisted certificate.
 const char __initconst *const blacklist_hashes[] = {
 #include "blacklist_hash_list"
 };

certs/check-blacklist-hashes.awk

@@ -5,10 +5,10 @@
 #
 # Author: Mickaël Salaün <mic@linux.microsoft.com>
 #
-# Check that a CONFIG_SYSTEM_BLACKLIST_HASH_LIST file contains a valid array of
-# hash strings.  Such string must start with a prefix ("tbs" or "bin"), then a
-# colon (":"), and finally an even number of hexadecimal lowercase characters
-# (up to 128).
+# This script checks the validity of the CONFIG_SYSTEM_BLACKLIST_HASH_LIST file,
+# ensuring that it contains valid hash strings. Such strings must start with a
+# prefix ("tbs" or "bin"), then a colon (":"), and finally an even number of
+# hexadecimal lowercase characters (up to 128).
 
 BEGIN {
 	RS = ","

certs/extract-cert.c

@@ -10,7 +10,12 @@
  * modify it under the terms of the GNU Lesser General Public License
  * as published by the Free Software Foundation; either version 2.1
  * of the licence, or (at your option) any later version.
+ *
+ * This program extracts X.509 certificates in DER form from PKCS#11 or PEM.
+ * It supports both PKCS#11 provider and engine, and can handle certificates
+ * from various sources, including files and PKCS#11 URIs.
  */
+
 #define _GNU_SOURCE
 #include <stdio.h>
 #include <stdlib.h>

certs/revocation_certificates.S

@@ -2,6 +2,8 @@
 #include <linux/export.h>
 #include <linux/init.h>
 
+/* This file includes the compiled-in list of revocation X.509 certificates. */
+
 	__INITRODATA
 
 	.align 8

certs/system_certificates.S

@@ -2,6 +2,8 @@
 #include <linux/export.h>
 #include <linux/init.h>
 
+/* This file includes the compiled-in list of X.509 certificates and reserves space for an extra certificate. */
+
 	__INITRODATA
 
 	.align 8

certs/system_keyring.c

@@ -3,6 +3,8 @@
  *
  * Copyright (C) 2012 Red Hat, Inc. All Rights Reserved.
  * Written by David Howells (dhowells@redhat.com)
+ *
+ * This file implements the system trusted keyring, which contains trusted public keys and manages the addition of keys to the keyring.
  */
 
 #include <linux/export.h>