Document SHA1 buffer requirements more clearly

There's an inconsistency here; openconnect_set_xmlsha1() takes a redundant
'len' arg which serves no purpose except to check that the caller knows
how big a SHA1 is. If it's not 41, we bail.

Next time the soname is getting bumped, I'll add a similar redundant
check to openconnect_get_cert_sha1() too. I should have done that when
it was first converted from an internal function to a public-facing one
in commit 20840ab0. But I didn't, and it's not worth bumping the soname
again right now *just* for that.

Signed-off-by: David Woodhouse <David.Woodhouse@intel.com>

diff --git a/openconnect.h b/openconnect.h
index 64106576abcbc3dff818e72d9b832f35bd0f0941..48d67cc14810e0872f43762e6fa0c7f70e9f5059 100644 (file)
--- a/openconnect.h
+++ b/openconnect.h
@@ -132,8 +132,13 @@ struct openconnect_info;
 
 #define OPENCONNECT_X509 void
 
-/* Unless otherwise specified, all functions which set strings will take ownership of those strings
-   and should free them later in openconnect_vpninfo_free() */
+/* Unless otherwise specified, all functions which set strings will
+   take ownership of those strings and should free them later in
+   openconnect_vpninfo_free() */
+
+
+/* The buffer 'buf' must be at least 41 bytes. It will receive a hex string
+   with trailing NUL, representing the SHA1 fingerprint of the certificate. */
 int openconnect_get_cert_sha1(struct openconnect_info *vpninfo,
                              OPENCONNECT_X509 *cert, char *buf);
 char *openconnect_get_cert_details(struct openconnect_info *vpninfo,
@@ -154,7 +159,9 @@ char *openconnect_get_urlpath (struct openconnect_info *);
 void openconnect_set_urlpath (struct openconnect_info *, char *);
 
 /* This function does *not* take ownership of the string; it's copied
-   into a static buffer in the vpninfo */
+   into a static buffer in the vpninfo. The size must be 41 bytes,
+   since that's the size of a 20-byte SHA1 represented as hex with
+   a trailing NUL. */
 void openconnect_set_xmlsha1 (struct openconnect_info *, const char *, int size);
 
 void openconnect_set_cafile (struct openconnect_info *, char *);