diff options
Diffstat (limited to 'lib/libfetch/fetch.3')
| -rw-r--r-- | lib/libfetch/fetch.3 | 106 |
1 files changed, 103 insertions, 3 deletions
diff --git a/lib/libfetch/fetch.3 b/lib/libfetch/fetch.3 index 30372f2..34ca445 100644 --- a/lib/libfetch/fetch.3 +++ b/lib/libfetch/fetch.3 @@ -1,5 +1,6 @@ .\"- .\" Copyright (c) 1998-2011 Dag-Erling Smørgrav +.\" Copyright (c) 2013 Michael Gmelin <freebsd@grem.de> .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -25,7 +26,7 @@ .\" .\" $FreeBSD$ .\" -.Dd September 27, 2011 +.Dd January 25, 2013 .Dt FETCH 3 .Os .Sh NAME @@ -392,6 +393,60 @@ method in a manner consistent with the rest of the library, .Fn fetchPutHTTP is currently unimplemented. +.Sh HTTPS SCHEME +Based on HTTP SCHEME. +By default the peer is verified using the CA bundle located in +.Pa /etc/ssl/cert.pem . +The file may contain multiple CA certificates. +A common source of a current CA bundle is +.Pa \%security/ca_root_nss . +.Pp +The CA bundle used for peer verification can be changed by setting the +environment variables +.Ev SSL_CA_CERT_FILE +to point to a concatenated bundle of trusted certificates and +.Ev SSL_CA_CERT_PATH +to point to a directory containing hashes of trusted CAs (see +.Xr verify 1 ) . +.Pp +A certificate revocation list (CRL) can be used by setting the +environment variable +.Ev SSL_CRL_FILE +(see +.Xr crl 1 ) . +.Pp +Peer verification can be disabled by setting the environment variable +.Ev SSL_NO_VERIFY_PEER . +Note that this also disables CRL checking. +.Pp +By default the service identity is verified according to the rules +detailed in RFC6125 (also known as hostname verification). +This feature can be disabled by setting the environment variable +.Ev SSL_NO_VERIFY_HOSTNAME . +.Pp +Client certificate based authentication is supported. +The environment variable +.Ev SSL_CLIENT_CERT_FILE +should be set to point to a file containing key and client certificate +to be used in PEM format. In case the key is stored in a separate +file, the environment variable +.Ev SSL_CLIENT_KEY_FILE +can be set to point to the key in PEM format. +In case the key uses a password, the user will be prompted on standard +input (see +.Xr PEM 3 ) . +.Pp +By default +.Nm libfetch +allows SSLv3 and TLSv1 when negotiating the connecting with the remote +peer. +You can change this behavior by setting the environment variable +.Ev SSL_ALLOW_SSL2 +to allow SSLv2 (not recommended) and +.Ev SSL_NO_SSL3 +or +.Ev SSL_NO_TLS1 +to disable the respective methods. .Sh AUTHENTICATION Apart from setting the appropriate environment variables and specifying the user name and password in the URL or the @@ -579,6 +634,31 @@ which proxies should not be used. Same as .Ev NO_PROXY , for compatibility. +.It Ev SSL_ALLOW_SSL2 +Allow SSL version 2 when negotiating the connection (not recommended). +.It Ev SSL_CA_CERT_FILE +CA certificate bundle containing trusted CA certificates. +Default value: +.Pa /etc/ssl/cert.pem . +.It Ev SSL_CA_CERT_PATH +Path containing trusted CA hashes. +.It Ev SSL_CLIENT_CERT_FILE +PEM encoded client certificate/key which will be used in +client certificate authentication. +.It Ev SSL_CLIENT_KEY_FILE +PEM encoded client key in case key and client certificate +are stored separately. +.It Ev SSL_CRL_FILE +File containing certificate revocation list. +.It Ev SSL_NO_SSL3 +Don't allow SSL version 3 when negotiating the connection. +.It Ev SSL_NO_TLS1 +Don't allow TLV version 1 when negotiating the connection. +.It Ev SSL_NO_VERIFY_HOSTNAME +If set, do not verify that the hostname matches the subject of the +certificate presented by the server. +.It Ev SSL_NO_VERIFY_PEER +If set, do not verify the peer certificate against trusted CAs. .El .Sh EXAMPLES To access a proxy server on @@ -610,6 +690,19 @@ as follows: .Bd -literal -offset indent NO_PROXY=localhost,127.0.0.1 .Ed +.Pp +Access HTTPS website without any certificate verification whatsoever: +.Bd -literal -offset indent +SSL_NO_VERIFY_PEER=1 +SSL_NO_VERIFY_HOSTNAME=1 +.Ed +.Pp +Access HTTPS website using client certificate based authentication +and a private CA: +.Bd -literal -offset indent +SSL_CLIENT_CERT_FILE=/path/to/client.pem +SSL_CA_CERT_FILE=/path/to/myca.pem +.Ed .Sh SEE ALSO .Xr fetch 1 , .Xr ftpio 3 , @@ -678,7 +771,8 @@ with numerous suggestions and contributions from .An Hajimu Umemoto Aq ume@FreeBSD.org , .An Henry Whincup Aq henry@techiebod.com , .An Jukka A. Ukkonen Aq jau@iki.fi , -.An Jean-Fran\(,cois Dockes Aq jf@dockes.org +.An Jean-Fran\(,cois Dockes Aq jf@dockes.org , +.An Michael Gmelin Aq freebsd@grem.de and others. It replaces the older .Nm ftpio @@ -688,7 +782,9 @@ and .An Jordan K. Hubbard Aq jkh@FreeBSD.org . .Pp This manual page was written by -.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org . +.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org +and +.An Michael Gmelin Aq freebsd@grem.de . .Sh BUGS Some parts of the library are not yet implemented. The most notable @@ -717,6 +813,10 @@ implemented, superfluous at this site" in an FTP context and .Fn fetchStatFTP does not check that the result of an MDTM command is a valid date. .Pp +In case password protected keys are used for client certificate based +authentication the user is prompted for the password on each and every +fetch operation. +.Pp The man page is incomplete, poorly written and produces badly formatted text. .Pp |
