From 946ecbe0c046adc421dd897b34ed5b68229bba22 Mon Sep 17 00:00:00 2001
From: Jeremy Harris <jgh146exb@wizmail.org>
Date: Thu, 31 Jul 2014 21:52:48 +0100
Subject: [PATCH] Add interface documentation for the DANE library

---
 src/src/dane-openssl.c | 91 ++++++++++++++++++++++++++++++++++++++++++
 src/src/tls-openssl.c  |  3 +-
 2 files changed, 93 insertions(+), 1 deletion(-)

diff --git a/src/src/dane-openssl.c b/src/src/dane-openssl.c
index 781557075..c8099f645 100644
--- a/src/src/dane-openssl.c
+++ b/src/src/dane-openssl.c
@@ -1058,6 +1058,22 @@ list_free(((dane_selector) p)->mtype, dane_mtype_free);
 OPENSSL_free(p);
 }
 
+
+
+/*
+
+Tidy up once the connection is finished with.
+
+Arguments
+  ssl		The ssl connection handle
+
+=> Before calling SSL_free()
+tls_close() and tls_getc() [the error path] are the obvious places.
+Could we do it earlier - right after verification?  In tls_client_start()
+right after SSL_connect() returns, in that case.
+
+*/
+
 void
 DANESSL_cleanup(SSL *ssl)
 {
@@ -1105,6 +1121,28 @@ while(*src)
 return head;
 }
 
+
+
+
+/*
+
+Call this for each TLSA record found for the target, after the
+DANE setup has been done on the ssl connection handle.
+
+Arguments:
+  ssl		Connection handle
+  usage		TLSA record field
+  selector	TLSA record field
+  mdname	??? message digest name?
+  data		??? TLSA record megalump?
+  dlen		length of data
+
+Return
+  -1 on error
+  0  action not taken
+  1  record accepted
+*/
+
 int
 DANESSL_add_tlsa(SSL *ssl, uint8_t usage, uint8_t selector, const char *mdname,
         unsigned const char *data, size_t dlen)
@@ -1254,6 +1292,30 @@ else if(klist)
 return 1;
 }
 
+
+
+
+/*
+Call this once we have an ssl connection handle but before
+making the TLS connection.
+
+=> In tls_client_start() after the call to SSL_new()
+and before the call to SSL_connect().  Exactly where
+probably does not matter.
+We probably want to keep our existing SNI handling;
+call this with NULL.
+
+Arguments:
+  ssl		Connection handle
+  sni_domain	Optional peer server name
+  hostnames	?? list of names - but what names?
+
+Return
+  -1 on fatal error
+  0  nonfatal error
+  1  success
+*/
+
 int
 DANESSL_init(SSL *ssl, const char *sni_domain, const char **hostnames)
 {
@@ -1312,6 +1374,25 @@ if(hostnames && !(dane->hosts = host_list_init(hostnames)))
 return 1;
 }
 
+
+/*
+
+Call this once we have a context to work with, but
+before DANESSL_init()
+
+=> in tls_client_start(), after tls_init() call gives us the ctx,
+if we decide we want to (policy) and can (TLSA records available)
+replacing (? what about fallback) everything from testing tls_verify_hosts
+down to just before calling SSL_new() for the conn handle.
+
+Arguments
+  ctx		SSL context
+
+Return
+  -1	Error
+  1	Success
+*/
+
 int
 DANESSL_CTX_init(SSL_CTX *ctx)
 {
@@ -1383,6 +1464,15 @@ if(!EVP_get_digestbyname(LN_sha512)) EVP_add_digest(EVP_sha512());
 dane_idx = SSL_get_ex_new_index(0, 0, 0, 0, 0);
 }
 
+
+
+/*
+
+Call this once.  Probably early in startup will do; may need
+to be after SSL library init.
+
+*/
+
 int
 DANESSL_library_init(void)
 {
@@ -1399,6 +1489,7 @@ DANEerr(DANE_F_SSL_DANE_LIBRARY_INIT, DANE_R_DANE_SUPPORT);
 return 0;
 }
 
+
 #endif /* OPENSSL_VERSION_NUMBER */
 /* vi: aw ai sw=2
 */
diff --git a/src/src/tls-openssl.c b/src/src/tls-openssl.c
index 18994eaa9..eeff64f81 100644
--- a/src/src/tls-openssl.c
+++ b/src/src/tls-openssl.c
@@ -1008,13 +1008,14 @@ return i;
 of the library.  We allocate and return a context structure.
 
 Arguments:
+  ctxp            returned SSL context
   host            connected host, if client; NULL if server
   dhparam         DH parameter file
   certificate     certificate file
   privatekey      private key
   ocsp_file       file of stapling info (server); flag for require ocsp (client)
   addr            address if client; NULL if server (for some randomness)
-  cbp             place to put allocated context
+  cbp             place to put allocated callback context
 
 Returns:          OK/DEFER/FAIL
 */
-- 
2.25.1