document tls_get_peer_subject, tls_get_peer_issuer, and tls_get_peer_hash

ok jsing@

2 files changed, 58 insertions, 3 deletions

diff --git a/lib/libtls/Makefile b/lib/libtls/Makefile
index 2e03e247e4f..b0141c274ff 100644
--- a/lib/libtls/Makefile
+++ b/lib/libtls/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.16 2015/09/11 12:56:55 beck Exp $
+#	$OpenBSD: Makefile,v 1.17 2015/09/11 13:59:20 beck Exp $
 
 CFLAGS+= -Wall -Werror -Wimplicit
 CFLAGS+= -DLIBRESSL_INTERNAL
@@ -48,6 +48,9 @@ MLINKS+=tls_init.3 tls_config_verify_client.3
 MLINKS+=tls_init.3 tls_config_verify_client_optional.3
 MLINKS+=tls_init.3 tls_peer_cert_provided.3
 MLINKS+=tls_init.3 tls_peer_cert_contains_name.3
+MLINKS+=tls_init.3 tls_peer_cert_issuer3
+MLINKS+=tls_init.3 tls_peer_cert_subject.3
+MLINKS+=tls_init.3 tls_peer_cert_hash.3
 MLINKS+=tls_init.3 tls_load_file.3
 MLINKS+=tls_init.3 tls_client.3
 MLINKS+=tls_init.3 tls_server.3
diff --git a/lib/libtls/tls_init.3 b/lib/libtls/tls_init.3
index 4066713603a..c5b0c1df463 100644
--- a/lib/libtls/tls_init.3
+++ b/lib/libtls/tls_init.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: tls_init.3,v 1.38 2015/09/11 12:56:55 beck Exp $
+.\" $OpenBSD: tls_init.3,v 1.39 2015/09/11 13:59:20 beck Exp $
 .\"
 .\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org>
 .\"
@@ -116,6 +116,12 @@
 .Fn tls_peer_cert_provided "struct tls *ctx"
 .Ft "int"
 .Fn tls_peer_cert_contains_name "struct tls *ctx" "const char *name"
+.Ft "int
+.Fn tls_peer_cert_issuer "struct tls *ctx" "char **issuer"
+.Ft "int"
+.Fn tls_peer_cert_subject "struct tls *ctx" "char **subject"
+.Ft "int"
+.Fn tls_peer_cert_hash "struct tls *ctx" "char **hash"
 .Ft "uint8_t *"
 .Fn tls_load_file "const char *file" "size_t *len" "char *password"
 .Ft "struct tls *"
@@ -363,7 +369,7 @@ checks if the peer of
 .Ar ctx 
 has provided a certificate.
 .Fn tls_peer_cert_provided
-will only succeed after the handshake is complete. 
+can only succeed after the handshake is complete. 
 .Em (Server and client)
 .It
 .Fn tls_peer_cert_constains_name
@@ -373,7 +379,52 @@ checks if the peer of a tls
 SAN or CN that matches
 .Ar name
 .Fn tls_peer_cert_contains_name
+can only succeed after the handshake is complete. 
+.Em (Server and client)
+.It
+.Fn tls_peer_cert_subject
+returns a string in
+.Ar subject
+corresponding to the subject of the peer certificate from
+.Ar ctx .
+.Fn tls_peer_cert_subject
+will only succeed after the handshake is complete. 
+Callers must free the string returned in 
+.Ar subject .
+.Em (Server and client)
+.It
+.Fn tls_peer_cert_issuer
+returns a string in 
+.Ar subject
+corresponding to the issuer of the peer certificate from
+.Ar ctx .
+.Fn tls_peer_cert_issuer
 will only succeed after the handshake is complete. 
+Callers must free the string returned in 
+.Ar issuer .
+.Em (Server and client)
+.It
+.Fn tls_peer_cert_hash
+returns a string
+in
+.Ar hash
+corresponding to a hash of the raw peer certificate from
+.Ar ctx
+prefixed by a hash name followed by a colon. 
+The hash currently used is SHA256, however this
+can change in the future. The hash string for a certificate
+in file
+.Ar mycert.crt
+can be generated using the commands:
+.Bd -literal -offset indent
+h=$(openssl x509 -outform der -in mycert.crt | sha256)
+printf "SHA256:${h}\\n"
+.Ed
+.Pp
+.Fn tls_peer_cert_subject
+will only succeed after the handshake is complete. 
+Callers must free the string returned in 
+.Ar hash .
 .Em (Server and client)
 .It
 .Fn tls_config_verify_client_opional
@@ -538,6 +589,7 @@ while (len > 0) {
 }
 \&...
 .Ed
+.Bd -literal -offset indent
 .Pp
 The following example demonstrates how to handle TLS writes on a
 non-blocking file descriptor using