From f8ef502e30c5f2c5e12d43a2c49790862934f065 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Niels=20M=C3=B6ller?= <nisse@lysator.liu.se>
Date: Thu, 12 Mar 2015 20:48:57 +0100
Subject: [PATCH] Document base64url functions.
---
ChangeLog | 4 ++++
nettle.texinfo | 29 ++++++++++++++++++-----------
2 files changed, 22 insertions(+), 11 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index d89896aa..aeb55b56 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2015-03-12 Niels Möller <nisse@diamant.hack.org>
+
+ * nettle.texinfo (ASCII encoding): Document base64url functions.
+
2015-03-10 Niels Möller <nisse@diamant.hack.org>
* nettle.texinfo: Update documentation of curve25519_mul. Say that
diff --git a/nettle.texinfo b/nettle.texinfo
index 80d0f9f4..60712281 100644
--- a/nettle.texinfo
+++ b/nettle.texinfo
@@ -4641,9 +4641,9 @@ Returns an entropy estimate, in bits, suitable for calling
@section ASCII encoding
Encryption will transform your data from text into binary format, and that
-may be a problem if you want, for example, to send the data as if it was
-plain text in an email (or store it along with descriptive text in a
-file). You may then use an encoding from binary to text: each binary byte
+may be a problem if, for example, you want to send the data as if it was
+plain text in an email, or store it along with descriptive text in a
+file. You may then use an encoding from binary to text: each binary byte
is translated into a number of bytes of plain text.
A base-N encoding of data is one representation of data that only uses N
@@ -4653,18 +4653,19 @@ The base64 encoding will always use alphanumeric (upper and lower case)
characters and the '+', '/' and '=' symbols to represent the data. Four
output characters are generated for each three bytes of input. In case
the length of the input is not a multiple of three, padding characters
-are added at the end.
+are added at the end. There's also a ``URL safe'' variant, which is
+useful for encoding binary data into URLs and filenames. See @cite{RFC
+4648}.
The base16 encoding, also known as ``hexadecimal'', uses the decimal
digits and the letters from A to F. Two hexadecimal digits are generated
-for each input byte. Base16 may be useful if you want to use the data
-for filenames or URLs, for example.
+for each input byte.
Nettle supports both base64 and base16 encoding and decoding.
Encoding and decoding uses a context struct to maintain its state (with
the exception of base16 encoding, which doesn't need any). To encode or
-decode the your data, first initialize the context, then call the update
+decode the data, first initialize the context, then call the update
function as many times as necessary, and complete the operation by
calling the final function.
@@ -4675,8 +4676,11 @@ They are defined in @file{<nettle/base64.h>}.
@end deftp
@deftypefun {void} base64_encode_init (struct base64_encode_ctx *@var{ctx})
-Initializes a base64 context. This is necessary before starting an encoding
-session.
+@deftypefunx {void} base64url_encode_init (struct base64_encode_ctx *@var{ctx})
+Initializes a base64 context. This is necessary before starting an
+encoding session. @code{base64_encode_init} selects the standard base64
+alphabet, while @code{base64url_encode_init} selects the URL safe
+alphabet.
@end deftypefun
@@ -4711,8 +4715,11 @@ generated.
@end deftp
@deftypefun {void} base64_decode_init (struct base64_decode_ctx *@var{ctx})
-Initializes a base64 decoding context. This is necessary before starting a decoding
-session.
+@deftypefunx {void} base64url_decode_init (struct base64_decode_ctx *@var{ctx})
+Initializes a base64 decoding context. This is necessary before starting
+a decoding session. @code{base64_decode_init} selects the standard
+base64 alphabet, while @code{base64url_decode_init} selects the URL safe
+alphabet.
@end deftypefun
@deftypefun {int} base64_decode_single (struct base64_decode_ctx *@var{ctx}, uint8_t *@var{dst}, uint8_t @var{src})
--
GitLab