Document Mac OS PIV tokend use and support about piv-guides

[lachellel]

It would go in here!

There have definitely been questions from across agencies and public on configurations. Any easy walk through guides are welcome and appreciated.

I would suggest it as a page under User Guides; maybe even just a Mac section. Nothing is set in stone and you can draft up any notes, submit a pull, and we'll merge them into staging and help iterate.

I've been "holding" on the additional content until .gov launch via Federalist...days or even hours away (clock ticking down)!

[lachellel]

4/25 workshop discussion and plays to be shared:

• Sierra OSX 10.12.3 and 10.12.4
• Native support / configurations needed for linking credentials to the local accounts
• Use of Enterprise Connect; NoMad (https://gitlab.com/Mactroll/NoMAD); and other options for network / kerb

[lachellel]

#17

[godadada]

Hey,
Here is the document in draft for Mac/Linux SSH. We have tested both. It was combined because we were thinking this option. Please review in technical aspects, we are still making editorial and structural change.

Enable PIV for Secure Shell (SSH) to a UNIX-like system from a Linux or a Mac OS X computer

These procedures are intended for network and system administrators, or other IT professionals, who are responsible for the day-to-day network operations of Federal Government agencies. As part of their roles, these professionals will be authorized by their agencies to use secure methods to remotely access other computer hosts.

Your PIV authentication key pair and public cert is exactly like using a self-signed cert and key pair to SSH
The key pair and certificate are on hardware PIV card
Ensure your workstation or jump server can recognize the credential and enabling the correct drivers on the client are included
Hardware Requirements

A Smart Card reader
A PIV card
A Linux or a Mac OS X computer correctly configured to use a PIV card for login, e.g. configure opensc.
Procedures

Obtain and Save Public Key from PIV card

Insert your PIV card into your computer's card reader.

Use the following command to save the user's public SSH key to a file and submit the file to Jump server administrator. Linux:

ssh-keygen -D /usr/lib64/opensc-pkcs11.so > mykey.pub

Max OS X:

ssh-keygen -D /Library/OpenSC/lib/pkcs11/opensc-pkcs11.so > mykey.pub

Configure Linux/Unix Jump Server (SSHD)

Change the configuration in the /etc/ssh/sshd_config file. Then restart the sshd.

AuthorizedKeysFile /etc/sshd/authorized_keys/%u
PasswordAuthentication No

Create the directory: /etc/sshd/authorized_keys.

mkdir /etc/sshd/authorized_keys

To allow one user to have such access, place the user's PIV card's SSH public key in the following directory, according to the user's name: /etc/sshd/authorized_keys/[login ID]. (Note: To ensure that access requirements are enforced, only a root user may modify this directory and its files.)

Disable any alternative means of access (i.e., via passwords), as needed.

Log in via SSH

Insert your PIV card into your computer's card reader.

Use the following command to log into the remote machine. Linux:

ssh -I /usr/lib64/opensc-pkcs11.so <remote-host>

Mac OS X:

ssh -I /Library/OpenSC/lib/pkcs11/opensc-pkcs11.so <remote-host>

At the PIV card password prompt, enter your PIN. You should see remote-host shell prompt.

Note: The card reader may flash. Do not remove the PIV card until the login process has been completed.

[LarryHamid2]

philipashlock,
I'd like to give this a shot. I've sent a request to view the notes you made in Google Doc.
Larry

[acdha]

This has become substantially easier in High Sierra since support is now built-in and you no longer need OpenSC:

https://support.apple.com/en-us/HT208372

Basically now it's just two steps:

1. ssh-keygen -D /usr/lib/ssh-keychain.dylib to extract the public key in the right format
2. Add PKCS11Provider=/usr/lib/ssh-keychain.dylib to ~/.ssh/config to offer keys from the smartcard

[maxwellfunk]

Migrating issue to update playbooks repository. Some instructions are available for loading a security device (PIV for firefox), but not mention of updating a MACos keystore.

Might want MAC instructions on
https://piv.idmanagement.gov/networkconfig/trustedroots/

[maxwellfunk]

closing due to relation to issue #17