Secure Remote Access Admin Guide

Created On
Last Updated On
byTimothy Perfitt
You are here:

Secure Remote Access is a macOS application for remotely connecting to Mac systems using smart card authentication to the smart card inserted in a local Mac.

Technical Overview

Secure Remote Access works by establishing a network connection between a local Mac (“Admin Mac”) and another Mac (“Remote Mac”) to allow the remote Mac to authenticate via the smart card on the admin Mac. The admin Mac has a PIV smart card inserted into a smart card reader, while the remote Mac does not have a smart card physically inserted. The remote Mac uses a Secure Remote Access CryptoTokenKit (CTK) extension to authenticate services via the smart card on the admin Mac.

The connection is initiated on the admin Mac by using the Secure Remote Access application to enter the IP address and port of the remote Mac. The admin Mac passes the certificate from a smart card slot to be used for authentication. Once the connection is established, the remote Mac returns a challenge that the admin Mac must sign using the associated private key on the smart card. The admin Mac prompts for the PIN for the signing operation, and the signed data is sent back to the remote Mac. If the data is correctly signed and matches the certificate paired in the user account, the connection is then considered authenticated.

Once the connection is authenticated, the admin Mac can request a VNC token for screen sharing to the remote Mac. This is a single-session-use token consisting of a randomly generated password. This password is sent back to the admin Mac; the password is set for a local user account for VNC authentication in local directory services. The admin Mac follows with a standard screen sharing request using the token.

When the authentication connection is established, the smart card on the admin Mac can be virtually inserted into the remote Mac. The certificates on the admin Mac smart card are both sent to the remote Mac and virtually inserted into the remote Mac (the latter using the custom CTK extension).

Once the certificates are inserted into the system, they can be used as if the certificates were part of a locally inserted smart card. A user account can be paired with the smart card identity either with the standard macOS prompts, the sc_auth pair command, or an authentication authority associated with the user account. Once the smart card certificate has been associated with the user account, the remote Mac can authenticate at the login window, System Preferences, or any other instance that smart cards are supported on macOS.

When a smart card authentication is initiated on the remote Mac, the caller (for example, a System Preferences pane) uses standard macOS authentication that sends a request to the CTK extension, which passes the hash to be signed (and the associated smart card certificate) to the extension. The CTK extension then connects to a local-only network listener on a process that contains the authenticated connection back to the admin Mac. The extension passes the hash and certificate to the daemon, which sends the information over the authenticated connection to the admin Mac.

The hash is then signed using the smart card private key associated with the smart card certificate. This signature is then sent over the authenticated channel back to the remote Mac and then to the CTK extension to complete the transaction.

All traffic between the admin Mac and the remote Mac is secured using a TLS identity installed on the remote Mac. Either a self-signed certificate can be generated and trusted or an SSL certificate can be installed and specified by SHA1 fingerprint using the command line configuration tool.

Requirements

  1. Supported macOS version (see current requirements)
  2. PIV Smart Card
  3. Secure Remote Access installer package in a macOS disk image

Components

The Secure Remote Access installer consists of the following components:

  1. macOS Secure Remote Access application installed in /Applications
  2. CTK Extension in the Secure Remote Access application bundle
  3. Virtual PCSC driver ifd-virtualserial.bundle for generating insertion and removal events. Installed in /usr/local/lib/pcsc/drivers/serial/
  4. Configuration file reader.conf for Virtual PCSC driver installed in /etc.

Installer

The macOS installer installs the files listed in the Components section and enables the virtual PCSC driver.

Installation

The Secure Remote Access installer package is installed on both the admin and remote Mac. The remote Mac does not need the Secure Remote Access.app to be running, but it must be launched at least once to register the CTK Extension.

Setting up Admin Mac

Mount the installer disk image and double-click on the Secure Remote Access installer. Follow the prompts to install the Secure Remote Access application.

Setting up Remote Mac

First, install the Secure Remote Access application on the remote Mac using the same process as the admin Mac. Launch Secure Remote Access once, quit, then activate the Secure Remote Access daemon by running:

sudo /Applications/Secure_Remote_Access.app/Contents/Resources/secure_remote_access.sh -a -g -s

This will create an SSL certificate and trust it in the login keychain. Alternatively, you can specify your own certificate by installing it in the System Keychain, trusting it, and allowing the Secure Remote Access daemon, srad, to have access to it. To tell srad to use a new certificate:

sudo /Applications/Secure_Remote_Access.app/Contents/Resources/secure_remote_access.sh -a -c <SHA1Hash of Certificate> -s

To deactivate the launch daemon, use the “-d” option:

sudo /Applications/Secure_Remote_Access.app/Contents/Resources/secure_remote_access.sh -d

Options:
-a: activate
-g: generate self sign certificate, install in keychain, and trust
-s: add a screen sharing user and turn on ability to screen share

License

The license must be installed on the remote Mac or an error will be returned when the admin Mac attempts to connect to it. The license key is installed using a configuration profile provided with the software. It can be deployed either in the Finder, by double-clicking on it, or by using an MDM to deploy the license to all machines that will use the software.

To verify a license is installed, open Preferences in Secure Remote Access.

Note: only remote Macs require a license; Macs that initiate the connection do not require a license unless other Macs will connect to it using Secure Remote Access.

User Account Pairing

Secure Remote Access supports macOS attribute mapping or PubKeyHash for determining if a smart card can be used to log in to a macOS user account. To learn more about attribute mapping and PubKeyHash, open Terminal in macOS and run:

man SmartCardServices

Generally, if a smart card can be used to log in to a Mac with a smart card reader, the same smart card should be able to log in to the Mac remotely using Secure Remote Access.

Using Secure Remote Access

  1. On the admin Mac, make sure a smart card is inserted.
  2. Launch the Secure Remote Access app. The app should show that the smart card is inserted.
  3. Click Connect and specify the IP address of the remote Mac and port 4116. Click Connect. The port is optional and port 4116 will be used if one is not specified.
  4. Enter the PIN when prompted to authenticate the session.
  5. Click “Screen Share” to connect and start screen sharing with the remote Mac.
  6. In the screen sharing session, have the remote Mac log out and log in as the paired user using the PIN.

Troubleshooting

  1. Test that the network and local listeners are working by using the openssl s_client command on the remote Mac:
    openssl s_client -connect 127.0.0.1:4116
    openssl s_client -connect 127.0.0.1:4117
  2. View logs on either the admin or remote Mac by opening Console and filtering on subsystem com.twocanoes.sra.
  3. On the remote Mac, kill the CTK extension, CTK daemon, or the PCSC driver:
    killall -9 SecureRemoteAccessExtension
    killall -9 ctkd
    sudo killall -9 ctkd
    sudo killall -SIGKILL -m .*com.apple.ifdreader
  4. Verify smart card certificates are inserted on the remote Mac by selecting the smart card section in System Information.

Tags: