## 5 Invoking gss ¶

## Name ¶

GNU GSS (gss) – Command line interface to the GSS Library.

## Description ¶

`gss` is the main program of GNU GSS.

Mandatory or optional arguments to long options are also mandatory or optional for any corresponding short options.

## Commands ¶

`gss` recognizes these commands:

      -l, --list-mechanisms
                        List information about supported mechanisms
                        in a human readable format.
      -m, --major=LONG  Describe a `major status' error code value.
      -a, --accept-sec-context
                        Accept a security context as server.
      -i, --init-sec-context=MECH
                        Initialize a security context as client.
                        MECH is the SASL name of mechanism, use -l
                        to list supported mechanisms.
      -n, --server-name=SERVICE@HOSTNAME
                        For -i, set the name of the remote host.
                        For example, "imap@mail.example.com".

## Other Options ¶

These are some standard parameters.

      -h, --help        Print help and exit
      -V, --version     Print version and exit
      -q, --quiet       Silent operation  (default=off)

## Examples ¶

To list the supported mechanisms, use `gss -l` like this:

    $ src/gss -l
    Found 1 supported mechanisms.

    Mechanism 0:
            Mechanism name: Kerberos V5
            Mechanism description: Kerberos V5 GSS-API mechanism
            SASL Mechanism name: GS2-KRB5
    $

To initialize a Kerberos V5 security context, use the `--init-sec-context` parameter. Kerberos V5 needs to know the name of the remote entity, so you need to supply the `--server-name` parameter as well. That will provide the name of the server. For example, use `imap@mail.example.com` to setup a security context with the `imap` service on the host `mail.example.com`. The Kerberos V5 client will use your ticket-granting ticket (which needs to be available) and acquire a server ticket for the service. The KDC must know about the server for this to work. The tool will print the GSS-API context tokens base64 encoded on standard output.

    $ gss -i GS2-KRB5 -n host@interop.josefsson.org
    Context token (protection is available):

    Input context token:

The tool is waiting for the final Kerberos V5 context token from the server. Note the status text informing you that message protection is available.

To accept a Kerberos V5 context, the process is similar. The server needs to know its name, so that it can find the host key from (typically) `/etc/shishi/shishi.keys`. Once started it will wait for a context token from the client. Below we’ll paste in the token printed above.

    $ gss -a -n host@interop.josefsson.org
    Importing name "host@interop.josefsson.org"...
    Acquiring credentials...
    Input context token:

    Context has been accepted.  Final context token:
    YHEGCSqGSIb3EgECAgIAb2IwYKADAgEFoQMCAQ+iVDBSoAMCARKhAwIBAKJGBESy1Zoy9DrG+DuV/6aWmAp79s9d+ofGXC/WKOzRuxAqo98vMRWbsbILW8z9aF1th4GZz0kjFz/hZAmnWyomZ9JiP3yQvg==
    $

Returning to the client, you may now cut’n’paste the final context token as shown by the server. The client has then authenticated the server as well. The output from the client is shown below.

    YHEGCSqGSIb3EgECAgIAb2IwYKADAgEFoQMCAQ+iVDBSoAMCARKhAwIBAKJGBESy1Zoy9DrG+DuV/6aWmAp79s9d+ofGXC/WKOzRuxAqo98vMRWbsbILW8z9aF1th4GZz0kjFz/hZAmnWyomZ9JiP3yQvg==
    Context has been initialized.
    $