tutorial.ipynb

{
	"cells": [{
			"cell_type": "markdown",
			"id": "files-note",
			"metadata": {},
			"source": [
				"Big files are dealt with by just mapping them into memory."
			]
		},
		{
			"cell_type": "markdown",
			"id": "gen-test-buff-md",
			"metadata": {},
			"source": [
				"# Generate a test buffer"
			]
		},
		{
			"cell_type": "code",
			"execution_count": 1,
			"id": "gen-test-buff",
			"metadata": {},
			"outputs": [],
			"source": [
				"from struct import Struct\n",
				"s = Struct(\"<H\")\n",
				"testString = bytearray(b\"\".join(s.pack(i) for i in range(0x7fff)))"
			]
		},
		{
			"cell_type": "markdown",
			"id": "create-hasher-md",
			"metadata": {},
			"source": [
				"# Hashing\n",
				"## Create the hasher"
			]
		},
		{
			"cell_type": "code",
			"execution_count": 2,
			"id": "create-hasher",
			"metadata": {},
			"outputs": [],
			"source": [
				"from DilatedHash import DilatedHash\n",
				"hh = DilatedHash(len(testString))"
			]
		},
		{
			"cell_type": "markdown",
			"id": "hash-buffer-md",
			"metadata": {},
			"source": [
				"## Hash the buffer"
			]
		},
		{
			"cell_type": "code",
			"execution_count": 3,
			"id": "hash-buffer",
			"metadata": {},
			"outputs": [{
				"data": {
					"text/plain": [
						"<DilatedHash.DilatedHash at 0x7f90c040e130>"
					]
				},
				"execution_count": 3,
				"metadata": {},
				"output_type": "execute_result"
			}],
			"source": [
				"hh.digest(testString)"
			]
		},
		{
			"cell_type": "markdown",
			"id": "hash-reading-md",
			"metadata": {},
			"source": [
				"## Get the hash"
			]
		},
		{
			"cell_type": "code",
			"execution_count": 4,
			"id": "hash-reading",
			"metadata": {},
			"outputs": [{
				"data": {
					"text/plain": [
						"b'x\\x9c\\xab\\x97\\xbc0\\x9b\\x01\\x08\"\\xb7Z\\xff\\x02\\xd1\\xf3\\x7f\\x84\\xce\\x07\\xd1\\xee\\xb7\\xff\\xf0\\x83\\xe8rk\\x1fn\\x10m\\xd0o \\x07\\xa2\\xed\\x0f\\xfc\\xd8\\x05\\xa2\\xcf;<\\x00\\x8b\\xef\\xd7zZ\\x0e\\xa2\\x05VK\\xe8\\x83hI5W[\\x10\\xbd\\xf5\\xe4\\xdb\\r \\xba\\xe6\\xf9\\x1e!\\xb09\\xbf\\xd4\\'\\x81\\xe8\\x06/\\xfb\\x83 \\xdaA\\xe6\\x18X\\xdc\\xa3\\xe1\\xf7q\\x10\\xed\\xf4\\xde\\x93\\tD\\xb3(2\\x80\\x01\\x009U\"g'"
					]
				},
				"execution_count": 4,
				"metadata": {},
				"output_type": "execute_result"
			}],
			"source": [
				"h = bytes(hh)\n",
				"h"
			]
		},
		{
			"cell_type": "markdown",
			"id": "hash-loading-md",
			"metadata": {},
			"source": [
				"# Verifying the hash\n",
				"## Load the hash"
			]
		},
		{
			"cell_type": "code",
			"execution_count": 5,
			"id": "hash-loading",
			"metadata": {},
			"outputs": [],
			"source": [
				"hh = DilatedHash(len(testString))  # it's empty\n",
				"hh.load(h)"
			]
		},
		{
			"cell_type": "markdown",
			"id": "hash-verifying-md",
			"metadata": {},
			"source": [
				"## Verifying\n",
				"`-1` means everything is OK.\n",
				"Any positive number is an offset of the block with incorrect hash.\n"
			]
		},
		{
			"cell_type": "code",
			"execution_count": 6,
			"id": "hash-verifying-ok",
			"metadata": {},
			"outputs": [{
				"data": {
					"text/plain": [
						"-1"
					]
				},
				"execution_count": 6,
				"metadata": {},
				"output_type": "execute_result"
			}],
			"source": [
				"hh.verify(testString)"
			]
		},
		{
			"cell_type": "markdown",
			"id": "hash-verifying-shifted-md",
			"metadata": {},
			"source": [
				"Shifting changes are usually detected immediately and are reported as the last block having an incorrect hash"
			]
		},
		{
			"cell_type": "code",
			"execution_count": 7,
			"id": "hash-verifying-shifted",
			"metadata": {},
			"outputs": [{
				"data": {
					"text/plain": [
						"65504"
					]
				},
				"execution_count": 7,
				"metadata": {},
				"output_type": "execute_result"
			}],
			"source": [
				"hh.verify(b\"b\" + testString)"
			]
		},
		{
			"cell_type": "markdown",
			"id": "hash-verifying-not-touched-md",
			"metadata": {},
			"source": [
				"Changes not touching the blocks that are hashed are not detected at all."
			]
		},
		{
			"cell_type": "code",
			"execution_count": 8,
			"id": "hash-verifying-not-touched",
			"metadata": {},
			"outputs": [{
				"data": {
					"text/plain": [
						"-1"
					]
				},
				"execution_count": 8,
				"metadata": {},
				"output_type": "execute_result"
			}],
			"source": [
				"hh.verify(testString + b\"b\")"
			]
		},
		{
			"cell_type": "markdown",
			"id": "get-slice-md",
			"metadata": {},
			"source": [
				"We can get a slice of the `i`-th block"
			]
		},
		{
			"cell_type": "code",
			"execution_count": 9,
			"id": "get-slice",
			"metadata": {},
			"outputs": [{
				"data": {
					"text/plain": [
						"slice(49520, 49536, None)"
					]
				},
				"execution_count": 9,
				"metadata": {},
				"output_type": "execute_result"
			}],
			"source": [
				"s = hh.getBlockSliceByIndex(10)\n",
				"s"
			]
		},
		{
			"cell_type": "markdown",
			"id": "slice-modification-detected-md",
			"metadata": {},
			"source": [
				"And changes within the slice will likely be detected!"
			]
		},
		{
			"cell_type": "code",
			"execution_count": 10,
			"id": "slice-modification-detected",
			"metadata": {},
			"outputs": [{
				"data": {
					"text/plain": [
						"49520"
					]
				},
				"execution_count": 10,
				"metadata": {},
				"output_type": "execute_result"
			}],
			"source": [
				"testString[s.start + 4] = ord(b\"Z\")\n",
				"offsetOfCorruptedBlock = hh.verify(testString)\n",
				"offsetOfCorruptedBlock"
			]
		},
		{
			"cell_type": "code",
			"execution_count": 11,
			"id": "slice-modification-detected-matches-where-we-modified",
			"metadata": {},
			"outputs": [{
				"data": {
					"text/plain": [
						"True"
					]
				},
				"execution_count": 11,
				"metadata": {},
				"output_type": "execute_result"
			}],
			"source": [
				"s.start == offsetOfCorruptedBlock"
			]
		}
	],
	"metadata": {
		"kernelspec": {
			"display_name": "Python 3",
			"language": "python",
			"name": "python3"
		},
		"language_info": {
			"codemirror_mode": {
				"name": "ipython",
				"version": 3
			},
			"file_extension": ".py",
			"mimetype": "text/x-python",
			"name": "python",
			"nbconvert_exporter": "python",
			"pygments_lexer": "ipython3",
			"version": "3.9.7"
		}
	},
	"nbformat": 4,
	"nbformat_minor": 5
}