.\" In .TH, FOO should be all caps, SECTION should be 1-8, maybe w/ subsection
.\" other parms are allowed: see man(7), man(1)
.\"
.TH LCMAPS_VERIFY_PROXY.MOD 8 "October 31, 2012" "@PACKAGE_NAME@ @VERSION@"
.SH NAME
lcmaps_verify_proxy.mod \- LCMAPS plugin to verify a certificate chain including proxies
.SH SYNOPSIS
.nh
.ad l
.B lcmaps_verify_proxy.mod

.RB [ \-\-allow-limited-proxy ]
.RB [ \-certdir | \-cadir | \-capath | \-\-capath
.IR <certificate_directory> ]
.RB [ \-\-disallow-limited-proxy ]
.RB [ \-\-discard_private_key_absence ]
.RB [ \-\-max-proxy-level-ttl=<level> | \-\-max-proxy-level-ttl@<level>
.IR <timeperiod> ]
.RB [ \-\-max-voms-ttl
.IR <timeperiod> ]
.RB [ \-\-never_discard_private_key_absence ]
.RB [ \-\-only-enforce-lifetime-checks ]
.RB [ \-\-require-limited-proxy ]
.hy
.ad b
.SH DESCRIPTION
This plugin will test if the presented proxy certificate is authentic. This is
done using OpenSSL methods to verify the certificate chain, check if the
End-Entity Certificate is not revoked by checking CRLs or OCSP(*). In an
\fBlcmaps.db\fR (5) file it is advised to run this plug-in as the first plug-in
and fail the policy if there is no other way of verifying the input
credentials.

Additional this plug-in can impose other policies, like proxy and VOMS
life-time restrictions or require that the certificate chain is offered in a
certain way, e.g. by offering a Limited proxy or (optionally) without a private
key.

The plug-in takes its input from the LCMAPS framework. The certificate chain is
coming from the registered (derived) STACK_OF(X509) * and the private key (when
available) is taken from the registered PEM string credentials.

A certificate chain will be checked and verified by OpenSSL, but additionally
to these checks this plug-in also performs semantic checks on the certificate
chain based on how GT2, GT3 and RFC 3820 proxy certificates are to be
constructed and used.

.SH  OPTIONS
.TP
.BI "\-\-allow-limited-proxy"
When enabled allow the certificate chain to contain a limited proxy
certificate.  GT2, GT3 and RFC Limited proxies are treated as equal.
.TP
.BI "\-certdir | \-cadir | \-capath | \-\-capath " <certificate_directory>
This option sets the directory used to find the CA certificates, CRLs and other
files used in the verification process of the presented certificate chain.
Setting this option is muted by the option
\fB\-\-only-enforce-lifetime-checks\fR.
When unset, the value of $X509_CERT_DIR will be used, when that is also unset,
/etc/grid-security/certificates will be used.
.TP
.BI "\-\-disallow-limited-proxy"
When enabled all uses of limited proxies will be prohibited and treated as a
failure condition. GT2, GT3 and RFC Limited proxies are treated as equal.
.TP
.BI "\-\-discard_private_key_absence"
When enabled the plug-in verification process will not fail on the absence of
the private key. Having a private key to present is part of the proof of
possession of the certificate chain its delegations, therefore a fundamental
part of the user credentials. Discarding the private key check is useful in
cases where another process has already establish trust in the user credentials
by performing the private key proof of possession steps.
Example: This feature can be enabled in deployments where gLExec is part of the
CREAM CE. The CREAM CE's SSL handshake is taking ensuring that fully verified
credentials get passed down.
Counter example: This feature is not-enabled on a gLExec-on-the-WN deployment,
as gLExec will need to ensure that the pilot-job payload credentials are fully
verified before account mapping should occur.
.TP
.BI "\-\-max-proxy-level-ttl=<level> | \-\-max-proxy-level-ttl@<level> " <timeperiod>
Set a maximum to the allowed validity period of the proxy certificate for a
specific delegation \fB<level>\fR. The first delegation after an EEC
certificate is \fB<level>\fR 0. This delegation level could be used in a
MyProxy. A typical setting would be \fB14d\-00:00\fR to allow for a MyProxy
certificate with a validity period of two weeks.

A special \fB<level>\fR is indicated by an \fBl\fR or \fBL\fR. This is the leaf
proxy or also known as the final delegation. A safe setting for this would be
\fB1d\-00:00\fR to allow a proxy certificate validity period of 1 day/24 hours.

Set the <timeperiod> in the following format: \fB[0\-99]d\-[0\-23][00\-59]\fR. For
example \fB2d\-13:37\fR.
.TP
.BI "\-\-max-voms-ttl " <timeperiod>
Set a maximum to the allowed validity period of the VOMS credentials (when
present). Using VOMS credentials with a validity period longer then the set
timeperiod> will result in a failure.
.TP
.BI "\-\-never_discard_private_key_absence"
This setting will override the option \fB\-\-discard_private_key_absence\fR and
option to set the environment variable
$VERIFY_PROXY_DISCARD_PRIVATE_KEY_ABSENCE which performs the same behavior.
.TP
.BI "\-\-only-enforce-lifetime-checks"
When enable this option will bypass all verification steps and will only
perform the lifetime checks configured by \fB\-\-max-proxy-level-ttl\fR and/or
\fB\-\-max-voms-ttl\fR. This option is ideal to be used in a Globus Gatekeeper,
GridFTPd and/or GSI-OpenSSHd deployment.
.TP
.BI "\-\-require-limited-proxy"
Explicitly require the certificate chain to have a \fBlimited proxy\fR as a
final delegation. The plug-in will fail if the certificate chain does not have
a \fBlimited proxy\fR.

.SH "RETURN VALUES"
.TP
.B LCMAPS_MOD_SUCCESS
Success.
.TP
.B LCMAPS_MOD_FAIL
Failure.
.SH BUGS
OCSP is not functional and will be added when either CAB/Forum or the IGTF
publish a clear profile.

Please report any errors to the Nikhef Grid Middleware Security Team
<grid-mw-security-support@nikhef.nl>.
.SH "SEE ALSO"
.BR lcmaps.db (5), 
.BR lcmaps (3).
.SH AUTHORS
LCMAPS and the LCMAPS plug-ins were written by the Grid Middleware Security Team 
<grid-mw-security@nikhef.nl>.