On 2026-11-02 Mon 9:09 PM, Niels Möller wrote:
Thanks. It seems naming is one of the more difficult parts here.
If we use "poly1305_mac" for the context, I think it would make sense to use the same prefix for constants and functions.
I've updated the patch to now consistently use the poly1305_mac_ prefix.
+The standalone Poly1305 algorithm is also available.
I wonder if we should either discourage direct use, or make some recommendations on how to use it without shooting oneself in the foot? E.g., say that if one can arrange to have a unique but predictable nonce for each message, like a sequence number, one can generate at least S, and preferably both R and S, by encrypting that nonce using a cipher with a secret key? (This could go somewhere else, e.g., in the intro paragraphs, I'm not saying it must be at this place).
I've added a word of caution. The introductory paragraph already explains how Poly1305-AES achieves uniqueness and unpredictability for R and S.
+@deftypefun void poly1305_digest (struct poly1305_mac_ctx *@var{ctx}, const uint8_t *s, uint8_t *@var{digest}) +Extracts the digest, writing @code{POLY1305_DIGEST_SIZE} octets to +@var{digest}. Also prepares the context for processing a new message.
...new message with the same R (and to process several messages in this way, each call to _digest *must* use a new secret S).
Added.
--- /dev/null +void +poly1305_digest(struct poly1305_mac_ctx* ctx, const uint8_t *s, uint8_t* digest);
poly1305_mac_digest, or possibly something also referencing the role of s (but I have no great idea. Maybe poly1305_mac_s_digest?).
To follow nettle conventions for _digest functions, it would mak sense if it is possible to start processing a new message after _digest. Which would then reuse the same r, and it would be essential to have a fresh secret s for the next _digest call. Is that how you intend it to work?
Yes, that's how it should work.
A test case for this usage would also be nice.
For testing, you could think about defining a larger test context that includes the s value, and write the glue to test it using test_mac (defined in testutils.c). That way we get somewhat better test coverage for providing the message incrementally to the _update function. Alternatively, add some variants of with two calls to _update for different splitting of the message; that may be simpler.
I didn't see an easy way to use test_mac, so I've pretty much copied its approach to test context reuse and byte-by-byte update.
Regards, Tim