.Dd February 10, 2020
.Dt SSH-KEYCHAIN 8
.Os Darwin
.Sh NAME
.Nm ssh-keychain.dylib
.Nd smartcard/token support library
.Sh DESCRIPTION
The ssh-keychain.dylib library is used as a PKCS#11 and Secure Key module replacement for the family of ssh tools.
It provides identities from CryptoTokenKit tokens (SmartCards and persistent tokens) to the tools.
.Sh OVERVIEW
By default, all valid (RSA for PKCS#11 and ecdsa256 for Secure Key module) identities from all SmartCards and persistent tokens currently available in the system are provided.
Manual configuration of
.Nm
is required if there is a need to limit which token identities are provided.
The public key hash is used to select which identities should be provided.
This hash is usually in hexadecimal string form, without the leading
.Em 0x .
To determine the hash for identity use the
.Em sc_auth list-ctk-identities
and
.Em sc_auth identities
commands or
.Em pkhh
attribute from
.Em security export-smartcard
output.
.Sh ENVIRONMENT
Configuration passed through the environment always takes precedence over the configuration file.
The variable
.Em KEYCHAIN_CERTIFICATES
is used to specify hashes.
It should contain a semicolon-separated list of public key hashes of certificates which will be provided to the ssh tools.
.Sh CONFIG FILE
If no enviroment variable configuration is provided,
.Nm
looks for a configuration file located at
.Em ~/.ssh/sshkeychain.plist .
This file is a standard property-list with a dictionary root object.
It should contain the key
.Em KeychainCertificates
with a value that is either a string or an array of strings.
If a string, then the expected value is semicolon-separated list of public key hashes like the environment variable.
If the value is an array, then each hash is an array entry.
.Sh FILES
.Bl -tag -width "~/.ssh/sshkeychain.plist" -compact
.It Pa ~/.ssh/sshkeychain.plist
.El
.Sh EXAMPLES
.Bd -unfilled
.Bl -tag -width Ds
.It Ev Environment:
KEYCHAIN_CERTIFICATES="AE31125DA4AAA294A4FED97B815D7F8DD1A78FF3;168D2C4CDDFCDADD465BAF3E6BCFE8193D8D42D1"
ssh -o PKCS11Provider=/usr/lib/ssh-keychain.dylib machine
.It Ev Configuration plist:
{
    "KeychainCertificates" => [
        0 => "AE31125DA4AAA294A4FED97B815D7F8DD1A78FF3"
        1 => "168D2C4CDDFCDADD465BAF3E6BCFE8193D8D42D1"
    ]
}
.El
.Ed
.Sh SEE ALSO
.Xr security 1 ,
.Xr ssh-add 1 ,
.Xr ssh_config 5 ,
.Xr sc_auth 8