System Preparation

Requirements

To build all of the Moonshot components, you need various packages installed. To install all of these, see below.

Get Xcode for macOS

To get all of the requirements on your macOS platform, you will need to install Xcode and the Xcode command-line extensions:

1. Install Xcode from the Mac App Store.

2. Open a Terminal, then install the Xcode Command Line Tools. You will be prompted with a dialog to install the Command Line Tools after a 130MB download.

   bash

3. If you have never launched Xcode before, do so at least once, or run the following command in your Terminal window.

   bash

Install the GNU tools for macOS

You will need to install several GNU tools:

1. Install the GNU tools that are required for Moonshot by following the instructions at How to install Autoconf, Automake and related tools on Mac OS X from source?

2. Additionally, install GNU GetText:

   bash

Install MacPorts and Makedepend

Makedepend is available from MacPorts. Install MacPorts:

1. Download the latest install package from MacPorts.org, then update it:

   bash

2. Install Makedepend from MacPorts:

   bash

Install JSON from CPAN

1. Update CPAN and install JSON:

   bash

Setting build parameters and locations

Just like on Linux, build and installation locations matter, with one vital difference. On macOS, the /usr tree itself is locked down and inaccessible, even for the privileged (root) user. However, locations like /usr/local are open, and with newer versions of the OS, expect this to change.

For the purposes of this set of instructions, we recommend the following:

1. For all the Moonshot dependencies, including Moonshot itself, but excluding Heimdal, the --prefix parameter should be set to /usr/local/moonshot.
   If you decide to change this location, you should appropriately change the locations in the commands in Sections 3 and 5 to your preference.
2. For Heimdal, the --prefix parameter should be set to /usr/local/heimdal. This is because we are using Heimdal only for the header files that the Heimdal build generates, not for any library linking. It makes the eventual distribution easier.
3. We recommend that you build all libraries with the -rpath parameter enabled for all libraries to avoid any clashes with other libraries (such as the older version of OpenSSL that macOS ships for compatibility reasons). We have been assured by macOS developers that the clang and libtool tools for macOS support this.
4. We do NOT recommend using the Apple-provided sources for some libraries (such as Heimdal) as they have various customisations that may negatively impact how Moonshot works, and because Apple categorically WILL NOT support any of their own source sets (we've tried through a Platinum support path and had the support ticket closed and refunded).
   If you DO try using Apple's OpenSource sources and find that things build and function fine, please let us know by commenting on this document (with instructions that we can update this document with).

5. These instructions should generally be backward-compatible.

Download and build the required external dependencies

OpenSSL

1. Create a directory called openssl.

2. Download the OpenSSL build tree from Apple's OpenSource site. Some scripts that Apple provides will be needed, but we will not build it.

   bash

3. Download the latest OpenSSL build from the OpenSSL website. We will build this version.

   bash
4. Extract OpenSSL098-59.60.1.tar.gz, copy its 'bin' directory into the openssl directory, then delete the extracted source.
5. Edit the extract_source.sh script in the bin directory:
1. Comment out the IDEA removal and patch lines (lines 39-49).
2. Add the following parameters to each of the three ./Configure lines: no-ssl2 enable-ec_nistp_64_gcc_128
3. Change the --openssldir parameter to your appropriate directory. We recommend /usr/local/moonshot/bin
4. Change the --prefix parameter from /usr to /usr/local/moonshot
5. Comment out the line 'rm -f Makefile'
6. Find the line 'rm -f x86_64.h i386.h', and insert the following below it: ln -s crypto/idea/idea.h include/openssl/idea.h

6. From the openssl directory, run the following:

   bash
7. In the src directory, edit the Makefile file:
   1. Add the -DNO_IDEA parameter to the CFLAG line
   2. Add the -DNO_IDEA parameter to the DEPFLAG line

8. Run the following commands:

   bash

Heimdal

Heimdal requires OpenSSL. Once OpenSSL has built successfully, build Heimdal.

1. Download Heimdal:

   bash

2. Extract Heimdal:

   bash

3. Build Heimdal:

   bash
4. Note down both the location in which you built Heimdal, as well as where the Heimdal libraries are installed to (if you changed the --prefix parameter to something else). You will need a binary from the Heimdal build for the Moonshot build in Section 6, and you will need to set the --with-krb5 parameter of the Moonshot ./configure command in Section 6 to the location where you installed Heimdal.

LibConfuse

1. Clone the latest Libconfuse repository:

   bash

2. Build Libconfuse:

   bash

LibEvent

Libevent requires OpenSSL. Once OpenSSL has built successfully, build Libevent.

1. Clone the latest Libevent repository:

   bash

2. Build Libevent:

   bash

Checkout the Moonshot source

The Moonshot source code is all stored in a GIT repository. To fetch it, issue the following command.

Build Moonshot's internal dependencies

The Moonshot repository contains a set of internal dependencies. These need to be built before you can build the Moonshot mechanism itself.

Libradsec

Libradsec is used by the Moonshot libraries.

1. Configure the Libradsec build:

   bash
2. Edit the Makefile:
   1. Find the AM_CFLAGS line, remove the -Werror parameter.
   2. Find the libradsec_la_CFLAGS line, remove the -Werror parameter
   3. Save the file.

3. Build Libradsec:

   bash

Jansson

Jansson is used by the Moonshot libraries.

1. Configure and build Jansson:

   bash

Build Moonshot

1. Before building Moonshot, check what the HEAD of your Git tree is:

   bash
2. Check the output.
3. If your head revision is dfa044b5b, please download the Heimdal patch first, then follow Step 4 to apply it. If your head revision is 3fbcdec or newer, go directly to Step 5.
   

4. Apply the Heimdal patch:

   bash

5. Configure the Moonshot build:

   bashConfigure script parameters

   There are several parameters in the command above that rely on locations noted down previously:

   LIBS contains explicit library location references to the macOS-native Heimdal and GSS frameworks as well as the Moonshot libraries.

   COMPILE_ET contains the full path to the compile_et binary that will be in your Heimdal build tree. You noted this down in the last step of Section 3.1.2.

   --with-krb5 contains the location where the Heimdal libraries and headers were installed. You noted this down in the last step of Section 3.1.2.

6. Edit the top-level Makefile:
   1. Remove the parameter -L/usr/local/heimdal/lib from the KRB5_LDFLAGS line.
   2. Remove the parameters  -L/usr/local/heimdal/lib -lgssapi from the KRB5_LIBS line in the file.
   3. Save the file.
7. Edit the Makefile in the libeap directory:
   1. Remove the parameter -L/usr/local/heimdal/lib from the KRB5_LDFLAGS line.
   2. Remove the parameters -L/usr/local/heimdal/lib -lgssapi from the KRB5_LIBS line in the file.
   3. Save the file.
8. Edit the Makefile in the mech_eap directory:
   1. Remove the parameter -L/usr/local/heimdal/lib from the KRB5_LDFLAGS line.
   2. Remove the parameters -L/usr/local/heimdal/lib -lgssapi from the KRB5_LIBS line in the file.
   3. Remove the parameters -L/usr/local/heimdal/lib -lgssapi from the mech_eap_la_LIBADD line in the file.
   4. Remove the parameter -Werror from the mech_eap_la_CFLAGS line.
   5. Remove the parameter -Werror from the mech_eap_la_CXXFLAGS line.
   6. Save the file.

9. Build Moonshot:

   bash

   You should now have a mech_eap.so file in /usr/local/lib/gss.

Test Moonshot

To test this build of Moonshot, you will need to make some privileged changes to the system you built this on:

1. In /etc, create a gss directory:

   bash

2. Copy the mech file from the Moonshot mech_eap build directory to /etc/gss

   bash
3. As the privileged user, edit the /etc/gss/mech file:
   1. Change the mech_eap.so entry on each line to the full path of the library, e.g. /usr/local/lib/gss/mech_eap.so
   2. Save the file.
4. Create a .gss_eap_id file in your user's home directory:
   1. On the first line of the file, put your Moonshot credential in email form, e.g. username@moonshot.realm.
   2. On the second line of the file, put your password for the Moonshot credential in the first line.
   3. Save the file.

5. Run an SSH command to a Moonshot-enabled system that the credentials you added in the previous step will be valid for:

   bashJisc Assent

   If you have an identity provider on the Jisc Assent network, you can use ssh -Kv moonshot@ssh.test.moonshot.ja.net to test whether your macOS Moonshot mechanism worked successfully.

6. You should successfully connect to the service, and you should see several lines like this in the output:

   bashJisc Assent

   On the Jisc Assent Test SSH Service, the final output for success will be this:

   bash

Distribute and install Moonshot

To distribute this binary set, you will need to trim down the binaries you have built to include only the dynamic libraries and only bare essentials needed to run the mechanism:

1. Make a copy of the /usr/local directory into a second location as the privileged user.

2. Once the duplication process is complete, change to your duplicate location's usr/local directory and delete all directories except the following:

   1. lib

   2. moonshot

3. In the lib directory, delete everything except the following:
   1. gss
   2. libintl.8.dylib
   3. libintl.dylib
4. In the moonshot directory, delete everything except the following:
   1. lib
5. In the moonshot/lib directory, delete:
   
   1. all *.a files
   2. all *.la files
   3. the pkgconfig directory
6. Now use tar to package up the contents of your distribution directory. You should have a tarball around 2 MB in size.
7. On your target machine, extract the tarball in such a way that the files end up in the /usr/local/lib and /usr/local/moonshot directories.
8. To finish the deployment, create the /etc/gss/mech file, then try to run the SSH test (section 7, steps 4 to 6) to check that the mechanism is correctly loaded.

Issues

Current issues with this build include that the macOS SSH client abandons any gssapi-with-mic conversations if the first mechanism it chooses, fails.

In a domain environment, this usually involves a Kerberos interaction, i.e. where you have received a Kerberos ticket before by logging in or by running kinit. Other ssh clients (or a custom build of the ssh client) may not exhibit this behaviour.

On macOS Sierra and High Sierra, the native SSH client is sandboxed when run from its default location in /usr/bin. Making a copy of the binary in /usr/local/bin enables it to authenticate with Moonshot. We are currently investigating this to see how this can be solved and have raised a bug with Apple for this.