.\" Copyright (c) 2014 Apple Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 4. Neither the name of Apple Computer nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY APPLE COMPUTER AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"
.Dd Oct 12, 2017
.Dt UserSelector 7
.Os "macOS"
.Sh NAME
.Nm UserSelector
.Nd overview and documentation
.Sh DESCRIPTION
.Nm
is invoked only internally by the CryptoTokenKit framework. It is not intended to be used directly by an end user or an administrator. Unless the string property
.Em UserSelectorPath
is set with full executable path value in the configuration file (
.Em /etc/SmartcardLogin.plist
), the system UserSelector is used.
.Pp
How CryptoTokenKit framework invokes UserSelector:
.Bd -literal -offset indent
UserSelector -o operation -u username -i pubkeyhash1[,pubkeyhash2,...]
.Ed
.Sh Path and format
.Nm
runs in a sandbox which limits its path and file format. A custom
.Nm
must be stored in the /Library/CryptoTokenKit directory. The file format of the UserSelector must be binary. Shell scripts are not supported.
.Sh Supported Operations
.Ss Map Operation
This operation returns a list of users bound with pubkeyhashes from the SmartCard certificates. The
.Em username
parameter is optional. If set, bindings are returned only for the specified user. The list of one or more comma separated
.Em pubkeyhashes
is mandatory.
.Pp
.Em Result format:
.Pp
Recognized bindings are returned through stdout. Each binding is placed on a separate line. Each line begins with the pubkeyhash string, followed by the TAB character (\\t) and by the username.
.Pp
.Em Sample:
.Bd -literal -offset indent
$ UserSelector -o map -i 01234567890123456789,ABCDEF01230123456789,98765432109876543210
ABCDEF01230123456789    user1
98765432109876543210    user2
.Ed
.Ss Bind Operation 
This operation creates binding between the provided
.Em pubkeyhash
and
.Em username
\[char46]
.Pp
.Em Result format:
.Pp
Exit code is set to 0 when succeeded, error code otherwise
.Pp
.Em Sample:
.Pp
.Bd -literal -offset indent
$ UserSelector -o bind -i ABCDEF01230123456789 -u username1
.Ed
.Ss Unbind Operation 
This operation removes SmartCard bindings for the provided
.Em username
If no pubkeyhash is provided, all bindings for that user are removed. If one or more
.Em pubkeyhashes
are provided, only bindings for these are removed.
.Pp
.Em Result format:
.Pp
Exit code is set to 0 when succeeded, error code otherwise
.Pp
.Em Sample:
.Pp
$ UserSelector -o unbind -u username1 -i ABCDEF01230123456789
.Ss Check Operation 
This operation checks SmartCard bindings for a specific user. It returns 0 on stdout when the user has no SmartCard bindings, or 1 when already does. The
.Em username
parameter is mandatory.
.Pp
.Em Sample:
.Pp
.Bd -literal -offset indent
$ UserSelector -o check -u username1
1
.Ed
.Pp
.Sh SEE ALSO
.Xr SmartCardServices 7 ,
.Xr sc_auth 8