System Preparation

Requirements

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

Get the required packages on macOS

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

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

4. 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?

5. Install GNU GetText:

   bash

6. Install MacPorts by downloading the latest install package from MacPorts.org, then update it:

   bash

7. Install Makedepend from MacPorts:

   bash

8. 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 OpenSSL, the Shibboleth dependencies, and 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

Boost

1. Download Boost:

   bash

2. Build Boost:

   bash
3. Note down the location at the end of the Boost build. You will need it later in this process. In the below examples, we shall use /Users/admin/Desktop/build/boost_1_64_0

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.

Xerces-C

1. Download Xerces from the Apache project site:

   bash

2. Extract Xerces:

   bash

3. Build Xerces:

   bash

XML-Security-C (Santuario)

1. Download XML-Security from the Apache project site:

   bash

2. Extract XML-Security:

   bash

3. Build XML-Security:

   bash

LibConfuse

1. Clone the latest Libconfuse repository:

   bash

2. Build Libconfuse:

   bash

LibEvent

1. Clone the latest Libevent repository:

   bash

2. Build Libevent:

   bash

Log4Shib

Moonshot requires Shibboleth, which in turn requires Log4Shib.

1. Download Log4Shib:

   bash

2. Extract Log4Shib:

   bash

3. Build Log4Shib:

   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. Confgure and build Jansson:

   bash

XMLTooling

XMLTooling is used by the Shibboleth libraries required by Moonshot.

1. Configure and build XMLTooling:

   bash

OpenSAML

OpenSAML is used by the Shibboleth libraries required by Moonshot.

1. Configure and built OpenSAML:

   bash

Shibboleth SP

The Shibboleth SP provides XML parsing and attribute release to the Moonshot mechanism.

1. Generate the Shibboleth SP build script:

   bash

2. Edit the configure script, find the PKG_CHECK_MODULES(SYSTEMD, libsystemd-daemon) line and comment it out. Save the file.

3. Configure and build the Shibboleth SP:

   bash
4. Note down the location of where you built the Shibboleth SP. You will require this location later in Section 6 for the Moonshot ./configure command.

Shibboleth Resolver

1. Generate the Shibboleth Resolver build script:

   bash

2. Edit the configure script, find the if test "x$ac_cv_header_shibsp_SPConfig_h" = xyes; line.

3. Comment out the entire if...else...fi statement that the line is part of.

4. Find the as_fn_error $? "unable to link with Shibboleth SP" "$LINENO" 5 line (15-20 lines below the if...else...fi statement you just commented out).

5. Comment out the entire if...else...fi statement that the line is part of.

6. Save the configure script.

7. Configure the Shibboleth Resolver:

   bash
8. Edit the top-level Makefile, find the LIBS = line. Remove the parameters -L/usr/local/heimdal/lib -lgssapi. Save the file.
9. Edit the Makefile in the src directory, find the LIBS = line. Remove the parameters -L/usr/local/heimdal/lib -lgssapi. Save the file.

10. Build the Shibboleth Resolver:

    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. Otherwise, go 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:

   CPPFLAGS contains three explicit include location references, the first is the Boost library header location from Section 3.1.1, the second the Shibboleth SP source from Section 5.1.5 and the third the general Moonshot location.

   LIBS contains two explicit library location references, the first is the Boost library location from Section 3.1.1, the second the general Moonshot library location.

   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.3.

   --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.3.

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 the following:
   1. include, share, sbin, var directories
5. In the moonshot/etc/shibboleth directory, delete:
   1. all *.dist files
   2. all *.pem files
   3. all shibd-* files
   4. all apache*.config files
6. In the moonshot/lib directory, delete:
   1. all *.a files
   2. all *.la files
   3. the pkgconfig directory
7. Now use tar to package up the contents of your distribution directory. You should have a tarball around 7MB in size.
8. 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.
9. 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, 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.