ae7d6746d1
This has most of the features needed to act as a kinit that uses GSS APIs, specifically gss_acquire_cred_from() and gss_store_cred_into2(). It's missing some functionality, such as being able to drive prompts from AS responses (if we add minor status codes for representing KDC pre-auth proposals, then we do drive prompts, but we would have to encode a lot of mechanism-specific knowledge into gsstool). The point of this commit is to explore: - GSS functionality for kinit-like actions - credential store key/value pairs supported by the mechanisms - document the credential store key/value pairs (in gsstool.1) that might lead to further enhancements. But gsstool acquire-cred is quite functional at this point!
363 lines
10 KiB
Groff
363 lines
10 KiB
Groff
.\" Copyright (c) 2022 Kungliga Tekniska Högskolan
|
|
.\" (Royal Institute of Technology, Stockholm, Sweden).
|
|
.\" 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.
|
|
.\"
|
|
.\" 3. Neither the name of the Institute 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 THE INSTITUTE 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 INSTITUTE 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.
|
|
.\"
|
|
.\" $Id$
|
|
.\"
|
|
.Dd October 9, 2022
|
|
.Dt GSSTOOL 1
|
|
.Os HEIMDAL
|
|
.Sh NAME
|
|
.Nm gsstool
|
|
.Nd command-line interface to GSS-API
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Ar command
|
|
.Op Ar args
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is a program for using the GSS-API from a shell.
|
|
.Pp
|
|
.Ar command
|
|
can be one of the following:
|
|
.Bl -tag -width srvconvert
|
|
.It Nm mechanisms
|
|
Lists available GSS-API mechanisms.
|
|
.It Nm attributes Oo Fl Fl all Oc
|
|
Lists all the mechanism attributes known to
|
|
.Nm .
|
|
.It Nm attributes Oo Fl Fl mech=MECH Oc
|
|
Lists the attributes of the given
|
|
.Ar MECH .
|
|
.It Nm acquire-cred \
|
|
Oo Fl Fl verbose Oc \
|
|
Oo Fl s \*(Ba Xo Fl Fl shell Xc Oc \
|
|
Oo Fl Fl initiator Oc \
|
|
Oo Fl Fl acceptor Oc \
|
|
Oo Fl Fl mech= Ns Ar MECH Oc \
|
|
Oo Fl Fl name-type= Ns Ar NAME-TYPE Oc \
|
|
Oo Fl Fl name= Ns Ar NAME Oc \
|
|
Oo Fl Fl time-req= Ns Ar SECONDS Oc \
|
|
Oo Fl Fl from= Ns Ar KEY=VALUE Oc \
|
|
Oo Fl Fl from-file=echo-on: Ns Ar KEY=FILE Oc \
|
|
Oo Fl Fl from-prompt= Ns Ar KEY=PROMPT Oc \
|
|
Oo Fl Fl from-prompt= Ns Ar KEY=PROMPT Oc \
|
|
Oo Fl Fl into= Ns Ar KEY=VALUE Oc \
|
|
Oo Fl Fl into-file=echo-on: Ns Ar KEY=FILE Oc \
|
|
Oo Fl Fl into-prompt=echo-on: Ns Ar KEY=PROMPT Oc \
|
|
Oo Fl Fl into-prompt=echo-off: Ns Ar KEY=PROMPT Oc \
|
|
Oo Ar cmd Oo arguments... Oc Oc
|
|
.Pp
|
|
Acquires a credential for each of the
|
|
.Fl Fl mech= Ns Ar MECH
|
|
mechanisms given for the given principal
|
|
.Ar NAME ,
|
|
or the default principal for the invoking user, as specified by
|
|
the
|
|
.Fl Fl from= Ns Ar KEY=VALUE
|
|
options and stores it into the given credential store specified
|
|
by the
|
|
.Fl Fl into= Ns Ar KEY=VALUE
|
|
options, if any are given.
|
|
If no
|
|
.Fl Fl mech= Ns Ar MECH
|
|
is given, then the Kerberos mechanism will be used.
|
|
If no
|
|
.Fl Fl into= Ns Ar KEY=VALUE
|
|
options are given, the credential acquired will not be stored
|
|
anywhere, but the exit status code of
|
|
.Nm
|
|
can be used to test if a credential could be acquired.
|
|
.Pp
|
|
In other words,
|
|
.Nm
|
|
.Nm acquire-cred
|
|
provides the same kind of functionality as
|
|
.Xr kinit 1
|
|
but using pure GSS-API functions rather than
|
|
.Dq krb5
|
|
APIs, though with some limitations, chiefly that the GSS-API
|
|
functions used do not support interaction with the user,
|
|
therefore the user must know a priori all the
|
|
.Ar KEY=VALUE
|
|
pairs needed to successfully acquire a credential.
|
|
Because
|
|
.Nm
|
|
uses pure GSS-API functions, it can work with any mechanism that
|
|
provides functionality similar to the Kerberos mechanism's
|
|
initial credential acquisition functionality.
|
|
.Pp
|
|
If a
|
|
.Ar cmd Oo arguments.. Oc
|
|
is given, then the command will be run, and for as long as it
|
|
runs the credentials will be kept fresh by renewing or
|
|
re-acquiring them.
|
|
Alternatively, if a
|
|
.Ar cmd Oo arguments.. Oc
|
|
is not given, and the
|
|
.Fl Fl shell \*(Ba Xo Fl s Xc
|
|
option is given, then environment variable settings may be
|
|
output.
|
|
.Pp
|
|
Mechanisms may, and the Kerberos GSS-API mechanism does try all
|
|
the strategies that are possible for the given
|
|
.Fl Fl from= Ns Ar KEY=VALUE
|
|
options, and in a reasonable order (such as: from a credentials
|
|
cache, using a keytab, using PKINIT, or using a password).
|
|
.Pp
|
|
As well,
|
|
.Nm
|
|
.Nm acquire-cred
|
|
can prompt for
|
|
.Ar VALUEs
|
|
with echo on and echo off, or even read them from files, so that
|
|
the user experience can be quite like that of
|
|
.Xr kinit 1 .
|
|
.Pp
|
|
Note that the
|
|
.Ar KEY=VALUE
|
|
pairs are specific to the GSS-API mechanisms.
|
|
See
|
|
.Sx CREDENTIAL STORE SPECIFICATION
|
|
for more details.
|
|
.Pp
|
|
By default
|
|
.Nm
|
|
acquires initiator credentials, unless
|
|
.Fl Fl acceptor
|
|
is given.
|
|
If both,
|
|
.Fl Fl initiator
|
|
and
|
|
.Fl Fl acceptor
|
|
are given, then
|
|
.Nm
|
|
acquires credentials for both.
|
|
Note though that currently there is no support for storing
|
|
acquired acceptor credentials.
|
|
.Pp
|
|
.Ar MECH
|
|
values currently accepted:
|
|
.Bl -tag -width Ds -offset indent
|
|
.It Ar all
|
|
(try acquiring credentials for all mechanisms)
|
|
.It Ar krb5
|
|
.It Ar ntlm
|
|
.It Ar spnego
|
|
.It Ar sanon_x25519
|
|
.It any mechanism OID, such as 1.3.6.1.5.5.2.
|
|
.El
|
|
.Pp
|
|
.Ar NAME-TYPE
|
|
values currently accepted:
|
|
.Bl -tag -width Ds -offset indent
|
|
.It Ar anonymous
|
|
.It Ar hostbased-service
|
|
.It Ar machine-uid
|
|
.It Ar string-uid
|
|
.It Ar user
|
|
.It any name-type OID, such as 1.3.6.1.5.5.2.
|
|
.El
|
|
.El
|
|
.Sh CREDENTIAL STORE SPECIFICATION
|
|
.Pp
|
|
Some of the
|
|
.Ar KEYs
|
|
for use in the
|
|
.Fl Fl from= Ns Ar KEY=VALUE
|
|
options for the Kerberos GSS-API mechanism are:
|
|
.Bl -tag -width Ds -offset indent
|
|
.It Nm appname= Ns Ar APP
|
|
Use the given
|
|
.Ar APP
|
|
name for any appdefaults.
|
|
.It Nm only=Ns Ar SOURCE
|
|
Only uses the given
|
|
.Ar SOURCE
|
|
for credentials acquisition.
|
|
Valid
|
|
.Ar SOURCEs
|
|
are:
|
|
.Bl -tag -width Ds -offset indent
|
|
.It Ar cache
|
|
Only look for cached credentials.
|
|
.It Ar renew
|
|
Only look for cached credentials, and renew them.
|
|
Requires the
|
|
.Ar renew KEY
|
|
to be set.
|
|
.It Ar keytab
|
|
Only acquire credentials with a keytab.
|
|
.It Ar pkinit
|
|
Only acquire credentials with PKINIT.
|
|
.It Ar password
|
|
Only acquire credentials with a password.
|
|
.El
|
|
.It Nm ccache= Ns Ar CREDENTIALS-CACHE
|
|
.It Nm renew
|
|
Attempts to renew the credential found in the
|
|
.Ar ccache .
|
|
But note that the renewed credential will not be written to the
|
|
cache.
|
|
Use the
|
|
.Fl Fl into= Ns Ar KEY=VALUE
|
|
command-line options to cause fresh/renewed credentials to be
|
|
stored.
|
|
.It Nm fresh
|
|
Acquire a fresh credential / do not use a cached credential
|
|
without renewing it.
|
|
If
|
|
.Ar fresh
|
|
is given without
|
|
.Ar renew
|
|
then no cached credential will be used.
|
|
.It Nm initial
|
|
Like
|
|
.Ar fresh ,
|
|
no cached credential will be acquired, but also no credential
|
|
will be renewed even if
|
|
.Ar renew
|
|
is set.
|
|
.It Nm service=PRINCIPAL
|
|
Instead of getting the usual TGT for the initiator, get a TGT for
|
|
the given
|
|
.Ar PRINCIPAL .
|
|
.It Nm keytab= Ns Ar KEYTAB
|
|
.It Nm client_keytab= Ns Ar KEYTAB
|
|
.It Nm password= Ns Ar PASSWORD
|
|
.It Nm kdc= Ns Ar HOSTNAME
|
|
Use the given KDC
|
|
.Ar HOSTNAME .
|
|
.It Nm sitename= Ns Ar SITENAME
|
|
Use the given site name
|
|
.Ar SITENAME
|
|
when searching for KDCs.
|
|
.It Nm pkinit_cert= Ns Ar CERT-STORE
|
|
Location of PKINIT client certificate and private key.
|
|
See
|
|
.Xr hxtool 1 .
|
|
.It Nm pkinit_pool= Ns Ar CERT-STORE
|
|
Optional store of certificates used to construct the client
|
|
certificate's chain.
|
|
.It Nm pkinit_anchors= Ns Ar CERT-STORE
|
|
Trust anchors for validating the KDCs' PKINIT certificates.
|
|
.It Nm pkinit_crl= Ns Ar CRL
|
|
CRL for KDC certificate validation.
|
|
.It Nm pkinit_password= Ns Ar PASSWORD
|
|
Optional password for the
|
|
.Nm pkinit_cert= Ns Ar CERT-STORE .
|
|
.It Nm pkinit_use_enckey
|
|
.It Nm pkinit_no_anchors
|
|
.It Nm pkinit_btmm
|
|
.It Nm fast_armor_cache= Ns Ar CREDENTIALS-CACHE
|
|
Use FAST armor, with the credentials in the given
|
|
.Ar CREDENTIALS-CACHE
|
|
.It Nm fast_anon_pkinit
|
|
Use FAST armored with an armor ticket obtained via anonymous
|
|
PKINIT.
|
|
.It Nm optimistic_fast_anon_pkinit
|
|
Try FAST armored with an armor ticket obtained via anonymous
|
|
PKINIT.
|
|
.It Nm renewable
|
|
.It Nm forwardable
|
|
.It Nm validate
|
|
.It Nm request_pac
|
|
.It Nm addressless
|
|
.El
|
|
.Pp
|
|
Some of the
|
|
.Ar KEYs
|
|
for use in the
|
|
.Fl Fl into= Ns Ar KEY=VALUE
|
|
options for the Kerberos mechanism are:
|
|
.Bl -tag -width Ds -offset indent
|
|
.It Nm unique_ccache_type=TYPE
|
|
Create a new, unique credentials cache of the given
|
|
.Ar TYPE .
|
|
E.g.,
|
|
.Dq Ar FILE .
|
|
.It Nm ccache= Ns Ar CREDENTIALS-CACHE
|
|
The specific credentials cache to store into.
|
|
E.g.,
|
|
.Dq Ar FILE:/tmp/some-ccache .
|
|
.It Nm username=USER-NAME
|
|
This is used for selecting the best credentials cache to use.
|
|
.It Nm appname=APP-NAME
|
|
This is used for resolving appdefaults.
|
|
.El
|
|
.Sh EXAMPLES
|
|
Test if there is an unexpired Kerberos credential:
|
|
.Bd -literal -offset indent
|
|
gsstool acquire-cred --from=only=cache
|
|
.Ed
|
|
.Pp
|
|
Test if there is an unexpired Kerberos credential for a specific
|
|
principal in a principal-specific cache in the default cache
|
|
collection:
|
|
.Bd -literal -offset indent
|
|
gsstool acquire-cred --name=some-principal-here \\
|
|
--from=only=cache
|
|
.Ed
|
|
.Pp
|
|
Test if there is an unexpired Kerberos credential in a specific
|
|
cache:
|
|
.Bd -literal -offset indent
|
|
gsstool acquire-cred --from=only=cache \\
|
|
--from=ccache=FILE:/tmp/some-ccache
|
|
.Ed
|
|
.Pp
|
|
Test what mechanisms the user has cached credentials for:
|
|
.Bd -literal -offset indent
|
|
gsstool acquire-cred --mech=all --from=only=cache
|
|
.Ed
|
|
.Pp
|
|
Renew a credential:
|
|
.Bd -literal -offset indent
|
|
gsstool acquire-cred --mech=krb5 --from=renew
|
|
.Ed
|
|
.Pp
|
|
Acquire a fresh Kerberos credential with a password, prompting
|
|
for it, then store it in a particular cache:
|
|
.Bd -literal -offset indent
|
|
gsstool acquire-cred --into=ccache=FILE:/tmp/some-ccache \\
|
|
--from-prompt=password="Password: "
|
|
.Ed
|
|
.Pp
|
|
Acquire a fresh Kerberos credential with a password read from a
|
|
file:
|
|
.Bd -literal -offset indent
|
|
gsstool acquire-cred --into=ccache=FILE:/tmp/some-ccache \\
|
|
--from-file=password=/tmp/password
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr gss-token 1 ,
|
|
.Xr hxtool 1 ,
|
|
.Xr kinit 1 .
|