From: Matt Caswell <matt@openssl.org>
Date: Thu, 29 Sep 2016 13:45:49 +0000 (+0100)
Subject: Add an example of usage to the WPACKET_reserve_bytes() documentation
X-Git-Tag: OpenSSL_1_1_1-pre1~3427
X-Git-Url: https://git.openssl.org/?p=openssl.git;a=commitdiff_plain;h=0023baffb8f648c22d397bfa5e1cc8749749bd29

Add an example of usage to the WPACKET_reserve_bytes() documentation

Reviewed-by: Rich Salz <rsalz@openssl.org>
---

diff --git a/ssl/packet_locl.h b/ssl/packet_locl.h
index 0e50c7ddae..8d3fd37c56 100644
--- a/ssl/packet_locl.h
+++ b/ssl/packet_locl.h
@@ -707,6 +707,16 @@ int WPACKET_sub_allocate_bytes__(WPACKET *pkt, size_t len,
  * maximum size will be. If this function is used, then it should be immediately
  * followed by a WPACKET_allocate_bytes() call before any other WPACKET
  * functions are called (unless the write to the allocated bytes is abandoned).
+ * 
+ * For example: If we are generating a signature, then the size of that
+ * signature may not be known in advance. We can use WPACKET_reserve_bytes() to
+ * handle this:
+ *
+ *  if (!WPACKET_sub_reserve_bytes_u16(&pkt, EVP_PKEY_size(pkey), &sigbytes1)
+ *          || EVP_SignFinal(md_ctx, sigbytes1, &siglen, pkey) <= 0
+ *          || !WPACKET_sub_allocate_bytes_u16(&pkt, siglen, &sigbytes2)
+ *          || sigbytes1 != sigbytes2)
+ *      goto err;
  */
 int WPACKET_reserve_bytes(WPACKET *pkt, size_t len, unsigned char **allocbytes);