Update macOS install docs for OpenSSL

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
 =====