From 1cda2783c6a69b52ad0766029ead085f059e6645 Mon Sep 17 00:00:00 2001
From: Natalia Portillo <claunia@claunia.com>
Date: Thu, 31 Jul 2025 19:35:02 +0100
Subject: [PATCH] [Specification] Add checksum block definition (`CKSM`)

---
 docs/spec/spec.adoc             |   6 +-
 docs/spec/structs/checksum.adoc | 110 ++++++++++++++++++++++++++++++++
 2 files changed, 115 insertions(+), 1 deletion(-)
 create mode 100644 docs/spec/structs/checksum.adoc

diff --git a/docs/spec/spec.adoc b/docs/spec/spec.adoc
index 4470069..de4efb6 100644
--- a/docs/spec/spec.adoc
+++ b/docs/spec/spec.adoc
@@ -74,4 +74,8 @@ include::structs/tracks.adoc[]
 
 <<<
 
-include::structs/cicm.adoc[]
\ No newline at end of file
+include::structs/cicm.adoc[]
+
+<<<
+
+include::structs/checksum.adoc[]
\ No newline at end of file
diff --git a/docs/spec/structs/checksum.adoc b/docs/spec/structs/checksum.adoc
new file mode 100644
index 0000000..ae7c288
--- /dev/null
+++ b/docs/spec/structs/checksum.adoc
@@ -0,0 +1,110 @@
+=== Checksum Block (`CKSM`)
+
+This block stores an array of checksums corresponding to the user data embedded in the image.
+For media formats such as CompactDisc, the checksum is calculated over the complete sector—comprising the prefix, user data, and suffix—totaling 2352 bytes.
+
+If the image is modified, the checksum block is considered outdated and should be either removed or excluded from the most recent index to ensure integrity.
+
+==== Structure Definition
+
+[source,c]
+#define CHECKSUM_MAGIC 0x4D534B43
+/**
+ *     Checksum block, contains a checksum of all user data sectors (except for optical discs that is 2352 uint8_ts raw
+ *     sector if available
+ *  */
+typedef struct ChecksumHeader
+{
+    /**Identifier, <see cref="BlockType.ChecksumBlock" /> */
+    uint32_t identifier;
+    /**Length in uint8_ts of the block */
+    uint32_t length;
+    /**How many checksums follow */
+    uint8_t  entries;
+} ChecksumHeader;
+
+==== Field Descriptions
+
+[cols="2,2,2,6",options="header"]
+|===
+|Type
+|Size
+|Name
+|Description
+
+|uint32_t
+|4 bytes
+|identifier
+|The tracks block identifier, always `CKSM`
+
+|uint32_t
+|4 bytes
+|length
+|The length in bytes of the data following this header.
+
+|uint8_t
+|1 byte
+|entries
+|The number of entries following this header
+|===
+
+==== Checksum entries
+
+[source,c]
+/**Checksum entry, followed by checksum data itself */
+typedef struct ChecksumEntry
+{
+    /**Checksum algorithm */
+    uint8_t  type;
+    /**Length in uint8_ts of checksum that follows this structure */
+    uint32_t length;
+} ChecksumEntry;
+
+==== Field Descriptions
+
+[cols="2,2,2,6",options="header"]
+|===
+|Type
+|Size
+|Name
+|Description
+
+|uint8_t
+|1 byte
+|type
+|Checksum algorithm.
+
+|uint32_t
+|4 bytes
+|length
+|Size in bytes of the checksum that immediately follows this entry.
+|===
+
+==== Checksum algorithms
+
+[cols="2,2,6",options="header"]
+|===
+|Type
+|Value
+|Description
+
+|Invalid
+|0
+|Invalid checksum entry, skip.
+
+|Md5
+|1
+|MD5
+
+|Sha1
+|2
+|SHA1
+
+|Sha256
+|3
+|SHA-256
+
+|SpamSum
+|4
+|SpamSum
+|===