From eee7d0d84dc7731df2359b243aa5e75d85f6eaef Mon Sep 17 00:00:00 2001
From: JP Aumasson <jp@taurusgroup.ch>
Date: Sat, 22 Oct 2022 07:14:59 +0200
Subject: comments

---
 README.md     |  4 ++--
 halfsiphash.c |  8 ++++++++
 siphash.c     | 10 +++++++++-
 3 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index fa4839e..de90fa7 100644
--- a/README.md
+++ b/README.md
@@ -54,8 +54,8 @@ security for any function with the same key and output size.
 
 The standard PRF security goal allow the attacker access to the output of SipHash on messages chosen adaptively by the attacker.
 
-Security is limited by the key size (128 bits). 
-Attackers searching 2<sup>*s*</sup> keys have chance 2<sup>*s*−128</sup> of finding
+Security is limited by the key size (128 bits for SipHash), such that
+attackers searching 2<sup>*s*</sup> keys have chance 2<sup>*s*−128</sup> of finding
 the SipHash key. 
 Security is also limited by the output size. In particular, when
 SipHash is used as a MAC, an attacker who blindly tries 2<sup>*s*</sup> tags will
diff --git a/halfsiphash.c b/halfsiphash.c
index 18ebadd..455c27c 100644
--- a/halfsiphash.c
+++ b/halfsiphash.c
@@ -71,6 +71,14 @@
 #define TRACE
 #endif
 
+/*
+    Computes a SipHash value
+    *in: pointer to input data (read-only)
+    inlen: input data length in bytes (any size_t value)
+    *k: pointer to the key data (read-only), must be 8 bytes 
+    *out: pointer to output data (write-only), outlen bytes must be allocated
+    outlen: length of the output in bytes, must be 4 or 8
+*/
 int halfsiphash(const void *in, const size_t inlen, const void *k, uint8_t *out,
                 const size_t outlen) {
 
diff --git a/siphash.c b/siphash.c
index 083ca19..c6d16e2 100644
--- a/siphash.c
+++ b/siphash.c
@@ -1,7 +1,7 @@
 /*
    SipHash reference C implementation
 
-   Copyright (c) 2012-2021 Jean-Philippe Aumasson
+   Copyright (c) 2012-2022 Jean-Philippe Aumasson
    <jeanphilippe.aumasson@gmail.com>
    Copyright (c) 2012-2014 Daniel J. Bernstein <djb@cr.yp.to>
 
@@ -78,6 +78,14 @@
 #define TRACE
 #endif
 
+/*
+    Computes a SipHash value
+    *in: pointer to input data (read-only)
+    inlen: input data length in bytes (any size_t value)
+    *k: pointer to the key data (read-only), must be 16 bytes 
+    *out: pointer to output data (write-only), outlen bytes must be allocated
+    outlen: length of the output in bytes, must be 8 or 16
+*/
 int siphash(const void *in, const size_t inlen, const void *k, uint8_t *out,
             const size_t outlen) {
 
-- 
cgit v1.2.3