cigetcert

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

cigetcert [OPTION]...

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.

−−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 (without any proxy additions). 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.

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.

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’"

0

Success

1

All fatal errors other than usage errors

2

Usage error

Dave Dykstra

Copyright © 2016 Fermi National Accelerator Laboratory

http://www.cilogon.org/ecp