Update macOS install docs for OpenSSL

docs/building/macos.md

@@ -20,9 +20,8 @@ and use`Start-PSBootstrap` to install the dependencies.
 The `Start-PSBootstrap` function does the following:
 
 - Uses `brew` to install CMake, OpenSSL, and GNU WGet
-- Links OpenSSL
 - Uninstalls any prior versions of .NET CLI
-- Downloads and installs the latest .NET CLI 1.0.0-preview2 SDK to `~/.dotnet`
+- Downloads and installs the latest .NET CLI 1.0.0-preview3 SDK to `~/.dotnet`
 
 If you want to use `dotnet` outside of `Start-PSBuild`,
 add `~/.dotnet` to your `PATH` environment variable.
@@ -40,7 +39,7 @@ We cannot do this for you in the build module due to #[847][].
 [847]: https://github.com/PowerShell/PowerShell/issues/847
 
 error: dotnet restore
--------------------------
+---------------------
 
 If you run `dotnet restore` and get error like
 
@@ -55,18 +54,11 @@ error:   The type initializer for 'Crypto' threw an exception.
 error:   The type initializer for 'CryptoInitializer' threw an exception.
 error:   Unable to load DLL 'System.Security.Cryptography.Native': The specified module could not be found.
 error:    (Exception from HRESULT: 0x8007007E)
-
 ```
 
-Try the following
+These means you did not use our `Start-PSBootstrap` function to setup your environment,
-
+which handles patching .NET Core's bad cryptography libraries.
-* Make sure you have latest openssl and re-link it
+Please see our [macOS installation instructions](../installation/linux.md#openssl) for explanation.
-
-```
-brew update
-brew install openssl
-brew link --force openssl
-```
 
 Build using our module
 ======================

docs/installation/linux.md

@@ -72,9 +72,11 @@ sudo yum install https://github.com/PowerShell/PowerShell/releases/download/v6.0
 [CentOS 7]: https://www.centos.org/download/
 
 macOS 10.11
-==========
+===========
 
-Using macOS 10.11, download the PKG package `powershell-6.0.0-alpha.9.pkg` from the [releases][] page onto the macOS machine.
+Using macOS 10.11, download the PKG package
+`powershell-6.0.0-alpha.9.pkg`
+from the [releases][] page onto the macOS machine.
 
 Either double-click the file and follow the prompts,
 or install it from the terminal:
@@ -83,6 +85,50 @@ or install it from the terminal:
 sudo installer -pkg powershell-6.0.0-alpha.9.pkg -target /
 ```
 
+OpenSSL
+-------
+
+Also install [Homebrew's OpenSSL][openssl]:
+
+```
+brew install openssl
+```
+
+[Homebrew][brew] is the missing package manager for macOS.
+If the `brew` command was not found,
+you need to install Homebrew following [their instructions][brew].
+
+.NET Core requires Homebrew's OpenSSL because the "OpenSSL" system libraries on macOS are not OpenSSL,
+as Apple deprecated OpenSSL in favor of their own libraries.
+This requirement is not a hard requirement for all of PowerShell;
+however, most networking functions (such as `Invoke-WebRequest`)
+do require OpenSSL to work properly.
+
+**Please ignore** .NET Core's installation instructions to manually link the OpenSSL libraries.
+This is **not** required for PowerShell as we patch .NET Core's cryptography libraries to find Homebrew's OpenSSL in its installed location.
+Again, **do not** run `brew link --force` nor `ln -s` for OpenSSL, regardless of other instructions.
+
+Homebrew previously allowed OpenSSL libraries to be linked to the system library location;
+however, this created major security holes and is [no longer allowed][homebrew-patch].
+Because .NET Core's 1.0.0 release libraries still look in the prior system location for OpenSSL,
+they will fail to work unless the libraries are manually placed there (security risk),
+or their libraries are patched (which we do).
+To patch .NET Core's cryptography libraries, we use `install_name_tool`:
+
+```
+find ~/.nuget -name System.Security.Cryptography.Native.dylib | xargs sudo install_name_tool -add_rpath /usr/local/opt/openssl/lib
+```
+
+This updates .NET Core's library to look in Homebrew's OpenSSL installation location instead of the system library location.
+The PowerShell macOS package come with the necessary libraries patched,
+and the build script patches the libraries on-the-fly when building from source.
+You *can* run this command manually if you're having trouble with .NET Core's cryptography libraries.
+
+
+[openssl]: https://github.com/Homebrew/homebrew-core/blob/master/Formula/openssl.rb
+[brew]: http://brew.sh/
+[homebrew-patch]: https://github.com/Homebrew/brew/pull/597
+
 Paths
 =====