GSSTOOL(1)

NAME
gsstool - command-line interface to GSS-API

SYNOPSIS
gsstool command [args]

DESCRIPTION
gsstool is a program for using the GSS-API from a shell.

command can be one of the following:

mechanisms
    Lists available GSS-API mechanisms.

attributes [- -all]
    Lists all the mechanism attributes known to gsstool.

attributes [- -mech=MECH]
    Lists the attributes of the given MECH.

acquire-cred [- -verbose] [-s - - -shell] [- -initiator] [- -acceptor] [- -mech=MECH] [- -name-type=NAME-TYPE] [- -name=NAME] [- -time-req=SECONDS] [- -from=KEY=VALUE] [- -from-file=echo-on:KEY=FILE] [- -from-prompt=KEY=PROMPT] [- -from-prompt=KEY=PROMPT] [- -into=KEY=VALUE] [- -into-file=echo-on:KEY=FILE] [- -into-prompt=echo-on:KEY=PROMPT] [- -into-prompt=echo-off:KEY=PROMPT] [cmd [arguments...]]

    Acquires a credential for each of the - -mech=MECH mechanisms given for the given principal NAME, or the default principal for the invoking user, as specified by the - -from=KEY=VALUE options and stores it into the given credential store specified by the - -into=KEY=VALUE options, if any are given. If no - -mech=MECH is given, then the Kerberos mechanism will be used. If no - -into=KEY=VALUE options are given, the credential acquired will not be stored anywhere, but the exit status code of gsstool can be used to test if a credential could be acquired.

    In other words, gsstool acquire-cred provides the same kind of functionality as kinit(1) but using pure GSS-API functions rather than “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 KEY=VALUE pairs needed to successfully acquire a credential. Because gsstool uses pure GSS-API functions, it can work with any mechanism that provides functionality similar to the Kerberos mechanism's initial credential acquisition functionality.

    If a cmd [arguments..] 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 cmd [arguments..] is not given, and the - -shell - -s option is given, then environment variable settings may be output.

    Mechanisms may, and the Kerberos GSS-API mechanism does try all the strategies that are possible for the given - -from=KEY=VALUE options, and in a reasonable order (such as: from a credentials cache, using a keytab, using PKINIT, or using a password).

    As well, gsstool acquire-cred can prompt for VALUEs with echo on and echo off, or even read them from files, so that the user experience can be quite like that of kinit(1).

    Note that the KEY=VALUE pairs are specific to the GSS-API mechanisms. See CREDENTIAL STORE SPECIFICATION for more details.

    By default gsstool acquires initiator credentials, unless - -acceptor is given. If both, - -initiator and - -acceptor are given, then gsstool acquires credentials for both. Note though that currently there is no support for storing acquired acceptor credentials.

    MECH values currently accepted:

    all (try acquiring credentials for all mechanisms)

    krb5

    ntlm

    spnego

    sanon_x25519

    any mechanism OID, such as 1.3.6.1.5.5.2.

    NAME-TYPE values currently accepted:

    anonymous

    hostbased-service

    machine-uid

    string-uid

    user

    any name-type OID, such as 1.3.6.1.5.5.2.

CREDENTIAL STORE SPECIFICATION

Some of the KEYs for use in the - -from=KEY=VALUE options for the Kerberos GSS-API mechanism are:

appname=APP
    Use the given APP name for any appdefaults.

only=Ns SOURCE
    Only uses the given SOURCE for credentials acquisition. Valid SOURCEs are:

    cache
        Only look for cached credentials.

    renew
        Only look for cached credentials, and renew them. Requires the renew KEY to be set.

    keytab
        Only acquire credentials with a keytab.

    pkinit
        Only acquire credentials with PKINIT.

    password
        Only acquire credentials with a password.

ccache=CREDENTIALS-CACHE

renew
    Attempts to renew the credential found in the ccache. But note that the renewed credential will not be written to the cache. Use the - -into=KEY=VALUE command-line options to cause fresh/renewed credentials to be stored.

fresh
    Acquire a fresh credential / do not use a cached credential without renewing it. If fresh is given without renew then no cached credential will be used.

initial
    Like fresh, no cached credential will be acquired, but also no credential will be renewed even if renew is set.

service=PRINCIPAL
    Instead of getting the usual TGT for the initiator, get a TGT for the given PRINCIPAL.

keytab=KEYTAB

client_keytab=KEYTAB

password=PASSWORD

kdc=HOSTNAME
    Use the given KDC HOSTNAME.

sitename=SITENAME
    Use the given site name SITENAME when searching for KDCs.

pkinit_cert=CERT-STORE
    Location of PKINIT client certificate and private key. See hxtool(1).

pkinit_pool=CERT-STORE
    Optional store of certificates used to construct the client certificate's chain.

pkinit_anchors=CERT-STORE
    Trust anchors for validating the KDCs' PKINIT certificates.

pkinit_crl=CRL
    CRL for KDC certificate validation.

pkinit_password=PASSWORD
    Optional password for the pkinit_cert=CERT-STORE.

pkinit_use_enckey

pkinit_no_anchors

pkinit_btmm

fast_armor_cache=CREDENTIALS-CACHE
    Use FAST armor, with the credentials in the given CREDENTIALS-CACHE

fast_anon_pkinit
    Use FAST armored with an armor ticket obtained via anonymous PKINIT.

optimistic_fast_anon_pkinit
    Try FAST armored with an armor ticket obtained via anonymous PKINIT.

renewable

forwardable

validate

request_pac

addressless

Some of the KEYs for use in the - -into=KEY=VALUE options for the Kerberos mechanism are:

unique_ccache_type=TYPE
    Create a new, unique credentials cache of the given TYPE. E.g., “FILE”.

ccache=CREDENTIALS-CACHE
    The specific credentials cache to store into. E.g., “FILE:/tmp/some-ccache”.

username=USER-NAME
    This is used for selecting the best credentials cache to use.

appname=APP-NAME
    This is used for resolving appdefaults.

EXAMPLES
Test if there is an unexpired Kerberos credential:

    gsstool acquire-cred --from=only=cache

Test if there is an unexpired Kerberos credential for a specific principal in a principal-specific cache in the default cache collection:

    gsstool acquire-cred --name=some-principal-here \
                         --from=only=cache

Test if there is an unexpired Kerberos credential in a specific cache:

    gsstool acquire-cred --from=only=cache          \
                         --from=ccache=FILE:/tmp/some-ccache

Test what mechanisms the user has cached credentials for:

    gsstool acquire-cred --mech=all --from=only=cache

Renew a credential:

    gsstool acquire-cred --mech=krb5 --from=renew

Acquire a fresh Kerberos credential with a password, prompting for it, then store it in a particular cache:

    gsstool acquire-cred --into=ccache=FILE:/tmp/some-ccache    \
                         --from-prompt=password="Password: "

Acquire a fresh Kerberos credential with a password read from a file:

    gsstool acquire-cred --into=ccache=FILE:/tmp/some-ccache    \
                         --from-file=password=/tmp/password

SEE ALSO
gss-token(1), hxtool(1), kinit(1).