Imported Upstream version 4.8.0.309

Former-commit-id: 5f9c6ae75f295e057a7d2971f3a6df4656fa8850

mcs/class/Mono.Security/Mono.Security.Interface/MonoTlsProviderFactory.cs

@@ -39,7 +39,37 @@ namespace Mono.Security.Interface
 	public static partial class MonoTlsProviderFactory
 	{
 		/*
-		 * Returns the currently installed @MonoTlsProvider, falling back to the default one.
+		 * TLS Provider Initialization
+		 * ===========================
+		 * 
+		 * The "global" TLS Provider (returned by GetProvider()) may only be modified at
+		 * application startup (before any of the TLS / Certificate code has been used).
+		 * 
+		 * On mobile, the default provider is specified at compile time using a property
+		 * in the .csproj file (which can be set from the IDE).  When using the linker, all
+		 * other providers will be linked-out, so you won't be able to choose a different
+		 * provider at run-time.
+		 * 
+		 * On desktop, the default provider can be specified with the MONO_TLS_PROVIDER
+		 * environment variable.  The following options are currently supported:
+		 * 
+		 *    "default" - let Mono pick the best one for you (recommended)
+		 *    "old" or "legacy" - Mono's old managed TLS implementation
+		 *    "appletls" (currently XamMac only, set via .csproj property)
+		 *    "btls" - the new boringssl based provider (coming soon).
+		 * 
+		 * On all platforms (except mobile with linker), you can call
+		 * 
+		 *     MonoTlsProviderFactory.Initialize(string)
+		 * 
+		 * to use a different provider.
+		 * 
+		 */
+
+		#region Provider Initialization
+
+		/*
+		 * Returns the global @MonoTlsProvider, initializing the TLS Subsystem if necessary.
 		 *
 		 * This method throws @NotSupportedException if no TLS Provider can be found.
 		 */
@@ -49,42 +79,64 @@ namespace Mono.Security.Interface
 		}
 
 		/*
-		 * Returns the default @MonoTlsProvider.
-		 *
-		 * This method throws @NotSupportedException if no TLS Provider can be found.
+		 * Check whether the TLS Subsystem is initialized.
 		 */
-		public static MonoTlsProvider GetDefaultProvider ()
-		{
-			return (MonoTlsProvider)NoReflectionHelper.GetDefaultProvider ();
-		}
-
-		/*
-		 * GetProvider() attempts to load and install the default provider and throws on error.
-		 *
-		 * This property checks whether a provider has previously been installed by a call
-		 * to either GetProvider() or InstallProvider().
-		 *
-		 */
-		public static bool HasProvider {
+		public static bool IsInitialized {
 			get {
-				return NoReflectionHelper.HasProvider;
+				return NoReflectionHelper.IsInitialized;
 			}
 		}
 
 		/*
-		 * Selects the default TLS Provider.
-		 *
-		 * May only be called at application startup and will throw
-		 * @InvalidOperationException if a provider has already been installed.
+		 * Initialize the TLS Subsystem.
+		 * 
+		 * This method may be called at any time.  It ensures that the TLS Subsystem is
+		 * initialized and a provider available.
 		 */
-		public static void SetDefaultProvider (string name)
+		public static void Initialize ()
 		{
-			NoReflectionHelper.SetDefaultProvider (name);
+			NoReflectionHelper.Initialize ();
 		}
 
-		public static MonoTlsProvider GetProvider (string name)
+		/*
+		 * Initialize the TLS Subsystem with a specific provider.
+		 * 
+		 * May only be called at application startup (before any of the TLS / Certificate
+		 * APIs have been used).
+		 * 
+		 * Throws @NotSupportedException if the TLS Subsystem is already initialized
+		 * (@IsInitialized returns true) or the requested provider is not supported.
+		 * 
+		 * On mobile, this will always throw @NotSupportedException when using the linker.
+		 */
+		public static void Initialize (string provider)
 		{
-			return (MonoTlsProvider)NoReflectionHelper.GetProvider (name);
+			NoReflectionHelper.Initialize (provider);
+		}
+
+		/*
+		 * Checks whether @provider is supported.
+		 *
+		 * On mobile, this will always return false when using the linker.
+		 */
+		public static bool IsProviderSupported (string provider)
+		{
+			return NoReflectionHelper.IsProviderSupported (provider);
+		}
+
+		#endregion
+
+		#region Call-by-call selection
+
+		/*
+		 * Returns the requested TLS Provider, for use with the call-by-call APIs below.
+		 * 
+		 * Throw @NotSupportedException if the requested provider is not supported or
+		 * when using the linker on mobile.
+		 */
+		public static MonoTlsProvider GetProvider (string provider)
+		{
+			return (MonoTlsProvider)NoReflectionHelper.GetProvider (provider);
 		}
 
 		/*
@@ -108,6 +160,24 @@ namespace Mono.Security.Interface
 		{
 			return (IMonoSslStream)NoReflectionHelper.GetMonoSslStream (stream);
 		}
+
+		#endregion
+
+		#region Obsolete APIs
+
+		[Obsolete]
+		public static MonoTlsProvider GetDefaultProvider ()
+		{
+			return GetProvider ();
+		}
+
+		[Obsolete]
+		public static void SetDefaultProvider (string name)
+		{
+			Initialize (name);
+		}
+
+		#endregion
 	}
 }