From 3358156b5be633b10a59c99403083624c51f4ce5 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Thu, 9 Nov 2017 16:47:13 +0100
Subject: Facilitate test certs with common root

---
 lib/public_key/doc/src/public_key.xml | 112 +++++++++++++++++++++++++++++-----
 1 file changed, 98 insertions(+), 14 deletions(-)

(limited to 'lib/public_key/doc')

diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml
index 5230cef496..dea35bc390 100644
--- a/lib/public_key/doc/src/public_key.xml
+++ b/lib/public_key/doc/src/public_key.xml
@@ -774,6 +774,7 @@ fun(#'DistributionPoint'{}, #'CertificateList'{},
 
   <func>
     <name>pkix_test_data(Options) -> Config </name>
+    <name>pkix_test_data([chain_opts()]) -> [conf_opt()]</name>
     <fsummary>Creates certificate test data.</fsummary>
     <type>
       <v>Options = #{chain_type() := chain_opts()} </v>
@@ -781,30 +782,83 @@ fun(#'DistributionPoint'{}, #'CertificateList'{},
       
       <v>chain_type() = server_chain | client_chain </v>
 
-      <v>chain_opts() = #{chain_end() := [cert_opt()],
-          intermediates => [[cert_opt()]]}</v>
-      <d>A valid chain must have at least a ROOT and a peer cert</d>
-
-      <v>chain_end() = root | peer </v>
-
+      <v>chain_opts() = #{root := [cert_opt()] | root_cert(),
+      peer := [cert_opt()],
+      intermediates => [[cert_opt()]]}</v>
+      <d>
+	A valid chain must have at least a ROOT and a peer cert.
+	The root cert can be given either as a cert pre-generated by
+	<seealso marker="#pkix_test_root_cert-2">
+	  pkix_test_root_cert/2
+	</seealso>, or as root cert generation options.
+      </d>
+      <v>root_cert() = #{cert := der_encoded(), key := Key}</v>
+      <d>
+	A root certificate generated by
+	<seealso marker="#pkix_test_root_cert-2">
+	  pkix_test_root_cert/2
+	</seealso>.
+      </d>
       <v>cert_opt() = {Key, Value}</v>
       <d>For available options see <seealso marker="#cert_opt"> cert_opt()</seealso> below.</d>
 
       <v>Config = #{server_config := [conf_opt()],
       client_config := [conf_opt()]}</v>
 
-      <v>conf_opt() = {cert, der_encoded()} | {key, der_encoded()} |{cacerts, [der_encoded()]}</v>
-      <d>This is a subset of the type <seealso marker="ssl:ssl#type-ssloption"> ssl:ssl_option()</seealso> </d>
+      <v>conf_opt() = {cert, der_encoded()} | {key, PrivateKey} |{cacerts, [der_encoded()]}</v>
+      <d>
+	This is a subset of the type
+	<seealso marker="ssl:ssl#type-ssloption"> ssl:ssl_option()</seealso>.
+	<c>PrivateKey</c> is what
+	<seealso marker="#generate_key-1">generate_key/1</seealso>
+	returns.
+      </d>
     </type>
     
     <desc>
-      <p>Creates certificate test data to facilitate automated testing
-      of applications using X509-certificates often through
-      SSL/TLS. The test data can be used when you have control
-      over both the client and the server in a test scenario.
+      <p>
+	Creates certificate configuration(s) consisting of certificate
+	and its private key plus CA certificate bundle, for a client
+	and a server, intended to facilitate automated testing
+	of applications using X509-certificates,
+	often through SSL/TLS. The test data can be used
+	when you have control over both the client and the server
+	in a test scenario.
+      </p>
+      <p>
+	When this function is called with a map containing
+	client and server chain specifications;
+	it generates both a client and a server certificate chain
+	where the <c>cacerts</c>
+	returned for the server contains the root cert the server
+	should trust and the intermediate certificates the server
+	should present to connecting clients.
+	The root cert the server should trust is the one used
+	as root of the client certificate chain.
+	Vice versa applies to the <c>cacerts</c> returned for the client.
+	The root cert(s) can either be pre-generated with
+	<seealso marker="#pkix_test_root_cert-2">
+	  pkix_test_root_cert/2
+	</seealso>, or if options are specified; it is (they are)
+	 generated.
+      </p>
+      <p>
+	When this function is called with a list of certificate options;
+	it generates a configuration with just one node certificate
+	where <c>cacerts</c> contains the root cert
+	and the intermediate certs that should be presented to a peer.
+	In this case the same root cert must be used for all peers.
+	This is useful in for example an Erlang distributed cluster
+	where any node,	towards another node, acts either
+	as a server or as a client depending on who connects to whom.
+	The generated certificate contains a subject altname,
+	which is not needed in a client certificate,
+	but makes the certificate useful for both roles.
+      </p>
+      <p>
+	The <marker id="cert_opt"/><c>cert_opt()</c>
+	type consists of the following options:
       </p>
-      
-      <p> The <marker id="cert_opt"/> cert_opt() type consists of the following options: </p>
       <taglist>
 	<tag> {digest, digest_type()}</tag>
 	<item><p>Hash algorithm to be used for
@@ -851,6 +905,36 @@ fun(#'DistributionPoint'{}, #'CertificateList'{},
     </desc>
   </func>
   
+  <func>
+    <name>pkix_test_root_cert(Name, Options) -> RootCert</name>
+    <fsummary>Generates a test data root cert.</fsummary>
+    <type>
+      <v>Name = string()</v>
+      <d>The root certificate name.</d>
+      <v>Options = [cert_opt()]</v>
+      <d>
+	For available options see
+	<seealso marker="#cert_opt">cert_opt()</seealso>
+	under
+	<seealso marker="#pkix_test_data-1">pkix_test_data/1</seealso>.
+      </d>
+      <v>RootCert = #{cert := der_encoded(), key := Key}</v>
+      <d>
+	A root certificate and key.  The <c>Key</c> is generated by
+	<seealso marker="#generate_key-1">generate_key/1</seealso>.
+      </d>
+    </type>
+    <desc>
+      <p>
+	Generates a root certificate that can be used
+	in multiple calls to
+	<seealso marker="#pkix_test_data-1">pkix_test_data/1</seealso>
+	when you want the same root certificate for
+	several generated certificates.
+      </p>
+    </desc>
+  </func>
+
   <func>  
     <name>pkix_verify(Cert, Key) -> boolean()</name>
     <fsummary>Verifies PKIX x.509 certificate signature.</fsummary>
-- 
cgit v1.2.3