cigetcert(1)

NAME
cigetcert - get an X.509 certificate using SAML ECP and store proxies

SYNOPSIS
cigetcert [OPTION]...

DESCRIPTION
cigetcert gets an X.509 certificate from a SAML 2.0 Service Provider such as CILogon, using the Enhanced Client or Proxy (ECP) profile. It can authenticate using either kerberos or password authentication. It stores either the certificate or a proxy certificate on the local filesystem, and also optionally stores a proxy in a MyProxy server.

When getting a certificate, the only required option is --institution (or -i). The option may come from a server rather than the command line when --server (or -s) is used.

If an existing certificate has a minimum number of hours of validity remaining, cigetcert will reuse the certificate rather than getting a new one. Details are under the --minhours option below.

OPTIONS

--version
    Show the program's version number and exit.

-h, --help
    Show a help message and exit.

-v, --verbose
    Write detailed progress reports to stdout instead of the default concise reports.

-d, --debug
    Write debug output to stdout. Implies -v. Be aware that this writes a lot of output.

-q, --quiet
    Do not print anything, not the concise progress reports and not even error messages.

-s HostOrURL, --optserver=HostOrURL
    The server host name or URL with default cigetcert options. If it is just a host name, the URL read is
        https://hostname/cigetcertopts.txt
    otherwise the whole URL is read. See also CIGETCERTOPTS in the ENVIRONMENT section below.

-i Name, --institution Name
    The name of the institution that will provide the authentication from its Identity Provider (IdP). This is required.

--listinstitutions
    Show the current list of available instituions and exit.

--idplisturl=URL
    The URL that contains a file mapping IdP URLs to institution names, one per line. If the institution name ends with "(Kerberos)" then that parenthetical ending is removed and that IdP is used when authenticating with kerberos. The URL may begin with https:// or file://. The default URL is
        https://cilogon.org/include/ecpidps.txt

--spurl=URL
    The SAML 2.0 ECP Service Provider (SP) URL. The default is
        https://ecp.cilogon.org/secure/getcert

--cafile=file
    The path to a file containing a bundle of Certifying Authority (CA) certificates. These will be used to verify the validity of https connections. The default is
        /etc/pki/tls/cert.pem
    or, if that doesn't exist, the default is
        /etc/ssl/certs/ca-certificates.crt

--capath=path
    The path to a directory containing Certifying Authority (CA) certificates. These will be used in addition to the --cafile certificates to verify the validity of https connections. The default is $X509_CERT_DIR if it is set, or otherwise the default is
        /etc/grid-security/certificates

-k, --kerberos
    Prefer kerberos authentication with the IdP if a kerberos ticket is available. When not in combination with the --noprompt option, if kerberos authentication fails then password authentication will be attempted. This option is the default if the IdP of the chosen institution has a URL marked with "(Kerberos)" in the idplisturl (unless the --nokerberos option is used).

--nokerberos
    Do not attempt to use kerberos authentication. If multiple --kerberos and --nokerberos options are given, the last one specified applies.

-n, --noprompt
    Do not prompt for a password. Implies --kerberos.

-p str, --promptstr=str
    The string used when prompting for a password. The default is
        Password for %username@%realm
    where %username is the value of the --username option and %realm is the realm value that the IdP supplies.

-u str, --username=str
    The string used as the username when authenticating with the IdP. The default is the current user name.

-o path, --out=path
    The path of the file used to store the certificate/key chain or proxy certificate/key chain on the local machine. The default is $X509_USER_PROXY if it is set, or otherwise the default is
        /tmp/x509up_%uid
    where %uid is the current effective user id.

--reuseonly
    Only check to see if an existing certificate or proxy in the path of the --out option can be reused (according to the algorithm shown in --minhours below); do not get a new certificate if the old one cannot be reused. This defaults to true if a file at the --out path already exists and is read-only, otherwise the default is false.

--noreuseonly
    Negate the --reuseonly option; get a certificate if an old one cannot be reused. If multiple --reuseonly and --noreuseonly options are given, the last one specified applies.

--minhours=num
    The minimum number of hours remaining before the existing local certificate chain expires in order to reuse it instead of making a new one. This feature is intended to reduce load on the servers. num may be a floating point number to specify fractions of hours for this option (similarly for all other *hours options). The default is 1. Also, if myproxy options (below) are set, in order to reuse a proxy it has to already exist in the myproxy server and have a minimum number of hours remaining that is at least the greater of %minhours or
        (%hours - %proxyhours - %minhours)
    where the '%' names are the values of the corresponding options. Finally, if the --myproxyretrievers option is set, that also must match with the value stored with the proxy on MyProxy.

--hours=num
    The number of hours on the certificate created by the SP. The maximum is ordinarly 277.7777 (a million seconds), unless --myproxyserver is set; then the maximum is 10000 hours (a little over 13 months). If a fractional number of hours is requested, the actual certificate will be rounded up to the next whole hour but there will be a proxy generated with the requested time. The default is 168 (a week).

--proxyhours=num
    The number of hours on a proxy certificate stored on the local filesystem. The maximum is 277.7777 (a million seconds). The default is the value of --hours, unless it is greater than 277.7777; then the default is 168 (a week). Implies --proxy if not equal to the value of --hours.

--proxy
    Store a proxy certificate/key chain on the local filesystem instead of the original certificate/key chain created by the SP. Throw away the key of the original certificate. This option is implied when the value of --hours does not match the value of --proxyhours. It is also implied when --hours is not a whole number, because the original certificate cannot be fractions of an hour.

--myproxyserver=Host
    Host name of a MyProxy server for storing a proxy certificate/key chain. The duration of that proxy will be the same as the original certificate, which is the value of --hours.

--myproxyusername=str
    The username of the proxy stored in the MyProxy server. The default is %certsubject which gets replaced with the base certificate subject DN (after stripping off up to 5 proxy levels). The string may contain %username which is replaced with the value of --username.

--myproxyretrievers=expr
    A regular expression of certificate subject DNs that will be permitted to fetch a proxy from the MyProxy server for the username matching the value of --myproxyusername.

--myproxyhours=num
    The maximum number of hours of a proxy that may be fetched from MyProxy. The maximum is 277.7777. The default is the value of --proxyhours.

ENVIRONMENT
The following optional environment variables affect the operation of cigetcert.

CIGETCERTOPTS
    Default options. These options override any conflicting options from the optserver, but are overridden by any conflicting options from the command line.

X509_USER_PROXY
    Default location for the user's proxy certificate on the local disk. For more details see the --out option.

X509_CERT_DIR
    Default directory for CA certificates. See also the --capath option.

KRB5CCNAME
    Location of a kerberos 5 credentials (ticket) cache.

EXAMPLES

To get a 1 week certificate in /tmp, always prompting for a password:

    cigetcert --nokerberos -i 'Fermi National Accelerator Laboratory'

To get a 4 week proxy in a myproxy server and 1 week in /tmp, using kerberos if available (because it is default for the institution) and if not prompt for a password, allowing retrieving by other servers and a maximum time for retrieved proxies of 1 day:

    cigetcert --hours=672 \
        -i 'Fermi National Accelerator Laboratory' \
        --myproxyserver=myproxy.fnal.gov \
        --myproxyretrievers='.*/CN=fifebatch(|1|2).fnal.gov' \
        --myproxyhours=24

To read options including the institution from a server and use only kerberos authentication and not password authentication:

    cigetcert -ns fifebatch.fnal.gov

To always have a default institution:

    export CIGETCERTOPTS="-i 'Fermi National Accelerator Laboratory'"

EXIT VALUES

0   Success

1   All fatal errors other than usage errors

2   Usage error

AUTHOR
Dave Dykstra

COPYRIGHT
Copyright © 2016 Fermi National Accelerator Laboratory

SEE ALSO
http://www.cilogon.org/ecp