Adding more info in readme and completing an example

Signed-off-by: Max Lambrecht <maxlambrecht@gmail.com>

java-spiffe-provider/README.md

@@ -1,8 +1,59 @@
-# JAVA-SPIFFE Provider
+# Java SPIFFE Provider
 
-Java Security Provider implementation supporting X509-SVIDs.
+This module provides a Java Security Provider implementation supporting X509-SVIDs and methods for
+creating SSLContexts that are backed by the Workload API.
 
-## Add provider to Java Security
+## Create an SSL Context backed by the Workload API
+
+To create an SSL Context that uses a X509Source backed by the WorkloadAPI, having the environment variable
+` SPIFFE_ENDPOINT_SOCKET` defined with the WorkloadAPI endpoint address, and the `ssl.spiffe.accept` 
+Security property defined in the `java.security` containing the list of SPIFFE IDs that the current workload
+will trust for TLS connections. 
+
+```
+    val sslContextOptions = SslContextOptions
+            .builder()
+            .x509Source(x509Source.newSource().getValue())
+            .build();
+    Result<SSLContext, String> sslContext = SpiffeSslContextFactory.getSslContext(sslContextOptions);
+    if (sslContext.isError()) {
+        // handle sslContext.getError();
+    }
+
+ ```
+
+See [HttpsServer example](src/main/java/spiffe/provider/examples/HttpsServer.java).
+
+Alternatively, a different Workload API address can be used by passing it to the X509Source creation method, and the
+Supplier of accepted SPIFFE IDs list can be provided as part of the `SslContextOptions`:
+
+```
+    val sourceOptions = X509SourceOptions
+            .builder()
+            .spiffeSocketPath(spiffeSocket)
+            .build();
+    val x509Source = X509Source.newSource(sourceOptions);
+    if (x509Source.isError()) {
+        // handle x509source.getError()
+    }
+
+    SslContextOptions sslContextOptions = SslContextOptions
+            .builder()
+            .acceptedSpiffeIdsSupplier(acceptedSpiffeIdsListSupplier)
+            .x509Source(x509Source.getValue())
+            .build();
+    Result<SSLContext, String> sslContext = SpiffeSslContextFactory
+            .getSslContext(sslContextOptions);
+
+    if (sslContext.isError()) {
+        // handle sslContext.getError()
+    }
+```
+
+See [HttpsClient example](src/main/java/spiffe/provider/examples/HttpsClient.java) that defines a Supplier for providing
+the list of SPIFFE IDs from a file.
+
+## Plug Java SPIFFE Provider into Java Security
 
 Java Security Providers are configured in the master security properties file `<java-home>/jre/lib/security/java.security`. 
 
@@ -62,7 +113,6 @@ The socket endpoint can be configured defining an environment variable named `SP
 export SPIFFE_ENDPOINT_SOCKET=/tmp/agent.sock
 ``` 
 
-
 ## Use Cases
 
 ### Configure a Tomcat connector
@@ -79,11 +129,6 @@ A Tomcat TLS connector that uses the `Spiffe` KeyStore can be configured as foll
             clientAuth="true" sslProtocol="TLS"/>
 ```
 
-
-### Create a SSL Context backed by the Workload API
-
-TBD
-
 ## References 
 
 [How to Implement a Provider in the Java Cryptography Architecture](https://docs.oracle.com/javase/8/docs/technotes/guides/security/crypto/HowToImplAProvider.html)

java-spiffe-provider/src/main/java/spiffe/provider/examples/HttpsClient.java

@@ -12,9 +12,13 @@ import javax.net.ssl.SSLContext;
 import javax.net.ssl.SSLSocket;
 import javax.net.ssl.SSLSocketFactory;
 import java.io.IOException;
-import java.util.ArrayList;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
 import java.util.List;
 import java.util.function.Supplier;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
 
 /**
  * Example of a simple HTTPS Client backed by the Workload API to get the X509 Certificates
@@ -74,11 +78,17 @@ public class HttpsClient {
     }
 
     static Result<List<SpiffeId>, String> listOfSpiffeIds() {
-        List<SpiffeId> acceptedSpiffeIds = new ArrayList<>();
+        try {
-        acceptedSpiffeIds.add(
+            Path path = Paths.get("java-spiffe-provider/src/main/java/spiffe/provider/examples/spiffeIds.txt");
-                SpiffeId.parse("spiffe://example.org/workload-server").getValue());
+            Stream<String> lines = Files.lines(path);
-        return Result.ok(acceptedSpiffeIds);
+            List<SpiffeId> list = lines
+                    .map(SpiffeId::parse)
+                    .map(Result::getValue)
+                    .collect(Collectors.toList());
+            return Result.ok(list);
+        } catch (Exception e) {
+           return Result.error("Error getting list of accepted SPIFFE IDs: %s", e.getMessage());
+        }
     }
-
 }
 

java-spiffe-provider/src/main/java/spiffe/provider/examples/spiffeIds.txt

@@ -0,0 +1,3 @@
+spiffe://example.org/workload-server
+spiffe://example.org/workload-server2
+spiffe://example2.org/workload-server