Improved documentation. Rename SecureSocketServers->RequestSecureSock…

…etProvider. Add unregister method

Signed-off-by: David Graeff <david.graeff@web.de>

bundles/io/org.eclipse.smarthome.io.security/NOTICE

@@ -0,0 +1,19 @@
+This content is produced and maintained by the Eclipse SmartHome project.
+
+* Project home: https://eclipse.org/smarthome/
+
+== Declared Project Licenses
+
+This program and the accompanying materials are made available under the terms
+of the Eclipse Public License 2.0 which is available at
+https://www.eclipse.org/legal/epl-2.0/.
+
+== Source Code
+
+https://github.com/eclipse/smarthome
+
+== Copyright Holders
+
+See the NOTICE file distributed with the source code at
+https://github.com/eclipse/smarthome/blob/master/NOTICE
+for detailed information regarding copyright ownership.

bundles/io/org.eclipse.smarthome.io.security/build.properties

@@ -1,5 +1,5 @@
 bin.includes = META-INF/,\
                .,\
-               about.html
+               NOTICE
 source.. = src/main/java/
 output.. = target/classes

bundles/io/org.eclipse.smarthome.io.security/src/main/java/org/eclipse/smarthome/io/security/api/RequestSecureSocketProvider.java

@@ -0,0 +1,60 @@
+/**
+ * Copyright (c) 2014,2018 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.eclipse.smarthome.io.security.api;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+/**
+ * A central service interface to provide SSL/DTLS configuration for server-like services within ESH and derived
+ * products.
+ * An implementation is required to return on a best effort approach a working SSLContext or any other secure socket
+ * provider, if required with a self-signed certificate. Network based services within ESH should be able to provide a
+ * secure TLS or DTLS based endpoint from the first start on.
+ *
+ * @author David Graeff - Initial contribution
+ */
+@NonNullByDefault
+public interface RequestSecureSocketProvider {
+    /**
+     * To retrieve a working secure socket provider (usually a SSLContext object), you would call this
+     * method and get an asynchronous callback as soon as the context is ready. It can take a while (some seconds)
+     * to resolve a new SSLContext if there is none so far. Please note that an async behavior is not guaranteed,
+     * and you might get called back straight from this method call.
+     *
+     * You are also automatically registering to change notifications. If the requested provider changes after
+     * some time, for example because a certificate was renewed or the user removed the provider deliberately,
+     * you will get notified with a refreshed or alternative provider. Call
+     * {@link #removeProviderRequest(SecureSocketRequest)} to unregister from such notifications.
+     *
+     * The given request/callback object has a second purpose: You can describe what features your secure socket
+     * provider should fulfil (mandatoryCapabilities) and what features are nice to have (optionalCapabilities).
+     *
+     * For example if you need a Scandium DtlsConnector, you would return
+     * {SecureSocketRequest.SCANDIUM_CONNECTOR,SecureSocketRequest.DTLS} for mandatoryCapabilities().
+     *
+     * The behavior is undefined if you specify two contrary features like SecureSocketRequest.SCANDIUM_CONNECTOR
+     * and SecureSocketRequest.SSLCONTEXT.
+     *
+     */
+    void addProviderRequest(SecureSocketRequest consumer);
+
+    /**
+     * By calling {@link #addProviderRequest(SecureSocketRequest)} you are registering to change notifications. If the
+     * requested provider changes after some time, for example because a certificate was renewed or the user removed the
+     * provider deliberately, you will get notified with a refreshed or alternative provider. Call this method to
+     * unregister from such notifications.
+     *
+     * @param consumer
+     */
+    void removeProviderRequest(SecureSocketRequest consumer);
+}

bundles/io/org.eclipse.smarthome.io.security/src/main/java/org/eclipse/smarthome/io/security/api/SecureSocketCapabilities.java

@@ -16,19 +16,22 @@
  * A set of default capabilities. Implement SecureSocketCapability and define your own for additional capabilities.
  */
 public enum SecureSocketCapabilities implements SecureSocketCapability {
-    /** Capability: Request a TLS capable secure socket implementation */
+    /** Capability: Request a TLS capable secure socket provider */
     TLS,
-    /**
-     * Capability: Request a DTLS capable secure socket implementation.
-     * On Java 8 this is usually a Scandium DtlsConnector. On Java 9 it is a SSLContext.
-     */
+    /** Capability: Request a DTLS capable secure socket provider. */
     DTLS,
     /** Capability: Request a secure socket implementation that has at least one self-signed certificate. */
     SELF_SIGNED,
     /** Capability: Request a secure socket implementation that has at least one (valid) CA signed certificate. */
     CA_SIGNED,
-    /** Capability: Request a secure socket implementation that is a javax.net.ssl.SSLContext */
+    /**
+     * Capability: Request a secure socket implementation that is a javax.net.ssl.SSLContext.
+     * On Java 9 this works for TLS and DTLS. On Java 8 only TLS is supported.
+     */
     SSLCONTEXT,
-    /** Capability: Request a secure socket implementation that is a Scandium Connector. Usually a DTLSConnector. */
+    /**
+     * Capability: Request a Scandium DTLSConnector. This is an alternative for Java 8's missing DTLS support.
+     * The framework needs the corresponding services to be loaded though.
+     */
     SCANDIUM_CONNECTOR
 }

bundles/io/org.eclipse.smarthome.io.security/src/main/java/org/eclipse/smarthome/io/security/api/SecureSocketCapability.java

@@ -15,7 +15,7 @@
 /**
  * Implement this interface with for example a custom `enum` and define your own capabilities.
  * Capabilities are used to decide which secure socket implementation should be returned by
- * {@link SecureSocketServers}.
+ * {@link RequestSecureSocketProvider}.
  *
  * @see SecureSocketCapabilities
  *

bundles/io/org.eclipse.smarthome.io.security/src/main/java/org/eclipse/smarthome/io/security/api/SecureSocketRequest.java

@@ -20,9 +20,9 @@
 
 /**
  * Implement this to request a secure socket implementation (SSLEngine or others) and get notified of the response.
- * Use {@link SecureSocketServers#requestSecureSocketImplementation(SecureSocketRequest)} to issue a request.
+ * Use {@link RequestSecureSocketProvider#addProviderRequest(SecureSocketRequest)} to issue a request.
  *
- * {@link SecureSocketServers} will also notify you about changes of the requested secure socket implementation
+ * {@link RequestSecureSocketProvider} will also notify you about changes of the requested secure socket implementation
  * during the life-time of the service.
  *
  * @author David Graeff - Initial contribution
@@ -44,35 +44,31 @@ public interface SecureSocketRequest {
     Set<SecureSocketCapability> optionalCapabilities();
 
     /**
-     * Returns a potentially new secure socket implementation instance that fulfills the requested mandatory
-     * capabilities and if possible the optional ones as well.
+     * Provides a potentially new secure socket implementation instance to your SecureSocketRequest implementation.
+     * It is guaranteed that all requested mandatory capabilities are present and if possible the optional ones as well.
      *
      * If an existing implementation, for instance a SSLContext, changes in the background this method
-     * will get called again. A change might be that a period renewal took place and new
-     * certificates got loaded or that the user removed that specific implementation.
+     * will get called again another two times. First with a null object and in a subsequent call with the new secure
+     * socket provider.
+     * A change might be that a period renewal took place and new certificates got loaded or that the user removed a
+     * specific provider.
      *
-     * @param secureSocketObject The object may be a SSLContext or Scandium
+     * @param secureSocketProvider The object may be a SSLContext or Scandium
      *            DtlsConnector or any other implementation that the backend matched with the requested capabilities.
-     *            May be null, if at least one capability could not be matched. May be null in a subsequent call if the
-     *            user removed an implementation deliberately.
+     *            May be null, if one or more mandatory capabilities could not be matched. May be null in a subsequent
+     *            call if the user removed a provider deliberately.
      */
-    void secureSocketImplementationResponse(@Nullable Object secureSocketObject);
+    void providerResponse(@Nullable Object secureSocketProvider);
 
     /**
      * Because it is a common case to request the java frameworks own SSLContext, this specific method will get called
-     * instead of {@link SecureSocketRequest#secureSocketImplementationResponse(Object)} if the secure socket
-     * implementation matches a SSLContext.
+     * additionally to {@link SecureSocketRequest#providerResponse(Object)} if the secure socket provider is a
+     * SSLContext.
      *
-     * @param secureSocketContext May be null, if at least one capability could not be matched. May be null in a
-     *            subsequent call if the user removed an implementation deliberately.
-     */
-    void secureSocketImplementationResponse(@Nullable SSLContext secureSocketContext);
-
-    /**
-     * If an error happens while the secure socket implementation is initialized, for example because an algorithm
-     * could not be loaded or an IO error occurred, you will be called by this method.
+     * You need to react to the former mentioned method as well, because here you will not be notified if the provider
+     * vanished.
      *
-     * @param error The exception that occurred.
+     * @param secureSocketProvider A SSLContext that matched all {@link #mandatoryCapabilities()}.
      */
-    void secureSocketImplementationUnavailable(Throwable error);
+    void providerResponse(SSLContext secureSocketProvider);
 }