| fetch.3 (236105) | fetch.3 (256257) |
|---|---|
| 1.\"- | 1.\"- |
| 2.\" Copyright (c) 1998-2011 Dag-Erling Sm��rgrav | 2.\" Copyright (c) 1998-2013 Dag-Erling Sm��rgrav 3.\" Copyright (c) 2013 Michael Gmelin <freebsd@grem.de> |
| 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright --- 7 unchanged lines hidden (view full) --- 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" | 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright --- 7 unchanged lines hidden (view full) --- 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" |
| 26.\" $FreeBSD: stable/9/lib/libfetch/fetch.3 236105 2012-05-26 16:42:47Z des $ | 27.\" $FreeBSD: stable/9/lib/libfetch/fetch.3 256257 2013-10-10 09:42:41Z glebius $ |
| 27.\" | 28.\" |
| 28.Dd September 27, 2011 | 29.Dd July 30, 2013 |
| 29.Dt FETCH 3 30.Os 31.Sh NAME 32.Nm fetchMakeURL , 33.Nm fetchParseURL , 34.Nm fetchFreeURL , 35.Nm fetchXGetURL , 36.Nm fetchGetURL , --- 350 unchanged lines hidden (view full) --- 387.Va ims_time . 388.Pp 389Since there seems to be no good way of implementing the HTTP PUT 390method in a manner consistent with the rest of the 391.Nm fetch 392library, 393.Fn fetchPutHTTP 394is currently unimplemented. | 30.Dt FETCH 3 31.Os 32.Sh NAME 33.Nm fetchMakeURL , 34.Nm fetchParseURL , 35.Nm fetchFreeURL , 36.Nm fetchXGetURL , 37.Nm fetchGetURL , --- 350 unchanged lines hidden (view full) --- 388.Va ims_time . 389.Pp 390Since there seems to be no good way of implementing the HTTP PUT 391method in a manner consistent with the rest of the 392.Nm fetch 393library, 394.Fn fetchPutHTTP 395is currently unimplemented. |
| 396.Sh HTTPS SCHEME 397Based on HTTP SCHEME. 398By default the peer is verified using the CA bundle located in 399.Pa /etc/ssl/cert.pem . 400The file may contain multiple CA certificates. 401A common source of a current CA bundle is 402.Pa \%security/ca_root_nss . 403.Pp 404The CA bundle used for peer verification can be changed by setting the 405environment variables 406.Ev SSL_CA_CERT_FILE 407to point to a concatenated bundle of trusted certificates and 408.Ev SSL_CA_CERT_PATH 409to point to a directory containing hashes of trusted CAs (see 410.Xr verify 1 ) . 411.Pp 412A certificate revocation list (CRL) can be used by setting the 413environment variable 414.Ev SSL_CRL_FILE 415(see 416.Xr crl 1 ) . 417.Pp 418Peer verification can be disabled by setting the environment variable 419.Ev SSL_NO_VERIFY_PEER . 420Note that this also disables CRL checking. 421.Pp 422By default the service identity is verified according to the rules 423detailed in RFC6125 (also known as hostname verification). 424This feature can be disabled by setting the environment variable 425.Ev SSL_NO_VERIFY_HOSTNAME . 426.Pp 427Client certificate based authentication is supported. 428The environment variable 429.Ev SSL_CLIENT_CERT_FILE 430should be set to point to a file containing key and client certificate 431to be used in PEM format. In case the key is stored in a separate 432file, the environment variable 433.Ev SSL_CLIENT_KEY_FILE 434can be set to point to the key in PEM format. 435In case the key uses a password, the user will be prompted on standard 436input (see 437.Xr PEM 3 ) . 438.Pp 439By default 440.Nm libfetch 441allows SSLv3 and TLSv1 when negotiating the connecting with the remote 442peer. 443You can change this behavior by setting the environment variable 444.Ev SSL_ALLOW_SSL2 445to allow SSLv2 (not recommended) and 446.Ev SSL_NO_SSL3 447or 448.Ev SSL_NO_TLS1 449to disable the respective methods. |
|
| 395.Sh AUTHENTICATION 396Apart from setting the appropriate environment variables and 397specifying the user name and password in the URL or the 398.Vt struct url , 399the calling program has the option of defining an authentication 400function with the following prototype: 401.Pp 402.Ft int --- 108 unchanged lines hidden (view full) --- 511If this variable is set to an empty string, no proxy will be used for 512FTP requests, even if the 513.Ev HTTP_PROXY 514variable is set. 515.It Ev ftp_proxy 516Same as 517.Ev FTP_PROXY , 518for compatibility. | 450.Sh AUTHENTICATION 451Apart from setting the appropriate environment variables and 452specifying the user name and password in the URL or the 453.Vt struct url , 454the calling program has the option of defining an authentication 455function with the following prototype: 456.Pp 457.Ft int --- 108 unchanged lines hidden (view full) --- 566If this variable is set to an empty string, no proxy will be used for 567FTP requests, even if the 568.Ev HTTP_PROXY 569variable is set. 570.It Ev ftp_proxy 571Same as 572.Ev FTP_PROXY , 573for compatibility. |
| 574.It Ev HTTP_ACCEPT 575Specifies the value of the 576.Va Accept 577header for HTTP requests. 578If empty, no 579.Va Accept 580header is sent. 581The default is 582.Dq */* . |
|
| 519.It Ev HTTP_AUTH 520Specifies HTTP authorization parameters as a colon-separated list of 521items. 522The first and second item are the authorization scheme and realm 523respectively; further items are scheme-dependent. 524Currently, the 525.Dq basic 526and --- 47 unchanged lines hidden (view full) --- 574.It Ev NO_PROXY 575Either a single asterisk, which disables the use of proxies 576altogether, or a comma- or whitespace-separated list of hosts for 577which proxies should not be used. 578.It Ev no_proxy 579Same as 580.Ev NO_PROXY , 581for compatibility. | 583.It Ev HTTP_AUTH 584Specifies HTTP authorization parameters as a colon-separated list of 585items. 586The first and second item are the authorization scheme and realm 587respectively; further items are scheme-dependent. 588Currently, the 589.Dq basic 590and --- 47 unchanged lines hidden (view full) --- 638.It Ev NO_PROXY 639Either a single asterisk, which disables the use of proxies 640altogether, or a comma- or whitespace-separated list of hosts for 641which proxies should not be used. 642.It Ev no_proxy 643Same as 644.Ev NO_PROXY , 645for compatibility. |
| 646.It Ev SSL_ALLOW_SSL2 647Allow SSL version 2 when negotiating the connection (not recommended). 648.It Ev SSL_CA_CERT_FILE 649CA certificate bundle containing trusted CA certificates. 650Default value: 651.Pa /etc/ssl/cert.pem . 652.It Ev SSL_CA_CERT_PATH 653Path containing trusted CA hashes. 654.It Ev SSL_CLIENT_CERT_FILE 655PEM encoded client certificate/key which will be used in 656client certificate authentication. 657.It Ev SSL_CLIENT_KEY_FILE 658PEM encoded client key in case key and client certificate 659are stored separately. 660.It Ev SSL_CRL_FILE 661File containing certificate revocation list. 662.It Ev SSL_NO_SSL3 663Don't allow SSL version 3 when negotiating the connection. 664.It Ev SSL_NO_TLS1 665Don't allow TLV version 1 when negotiating the connection. 666.It Ev SSL_NO_VERIFY_HOSTNAME 667If set, do not verify that the hostname matches the subject of the 668certificate presented by the server. 669.It Ev SSL_NO_VERIFY_PEER 670If set, do not verify the peer certificate against trusted CAs. |
|
| 582.El 583.Sh EXAMPLES 584To access a proxy server on 585.Pa proxy.example.com 586port 8080, set the 587.Ev HTTP_PROXY 588environment variable in a manner similar to this: 589.Pp --- 15 unchanged lines hidden (view full) --- 605.Pp 606To disable the use of a proxy for an HTTP server running on the local 607host, define 608.Ev NO_PROXY 609as follows: 610.Bd -literal -offset indent 611NO_PROXY=localhost,127.0.0.1 612.Ed | 671.El 672.Sh EXAMPLES 673To access a proxy server on 674.Pa proxy.example.com 675port 8080, set the 676.Ev HTTP_PROXY 677environment variable in a manner similar to this: 678.Pp --- 15 unchanged lines hidden (view full) --- 694.Pp 695To disable the use of a proxy for an HTTP server running on the local 696host, define 697.Ev NO_PROXY 698as follows: 699.Bd -literal -offset indent 700NO_PROXY=localhost,127.0.0.1 701.Ed |
| 702.Pp 703Access HTTPS website without any certificate verification whatsoever: 704.Bd -literal -offset indent 705SSL_NO_VERIFY_PEER=1 706SSL_NO_VERIFY_HOSTNAME=1 707.Ed 708.Pp 709Access HTTPS website using client certificate based authentication 710and a private CA: 711.Bd -literal -offset indent 712SSL_CLIENT_CERT_FILE=/path/to/client.pem 713SSL_CA_CERT_FILE=/path/to/myca.pem 714.Ed |
|
| 613.Sh SEE ALSO 614.Xr fetch 1 , 615.Xr ftpio 3 , 616.Xr ip 4 617.Rs 618.%A J. Postel 619.%A J. K. Reynolds 620.%D October 1985 --- 52 unchanged lines hidden (view full) --- 673library was mostly written by 674.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org 675with numerous suggestions and contributions from 676.An Jordan K. Hubbard Aq jkh@FreeBSD.org , 677.An Eugene Skepner Aq eu@qub.com , 678.An Hajimu Umemoto Aq ume@FreeBSD.org , 679.An Henry Whincup Aq henry@techiebod.com , 680.An Jukka A. Ukkonen Aq jau@iki.fi , | 715.Sh SEE ALSO 716.Xr fetch 1 , 717.Xr ftpio 3 , 718.Xr ip 4 719.Rs 720.%A J. Postel 721.%A J. K. Reynolds 722.%D October 1985 --- 52 unchanged lines hidden (view full) --- 775library was mostly written by 776.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org 777with numerous suggestions and contributions from 778.An Jordan K. Hubbard Aq jkh@FreeBSD.org , 779.An Eugene Skepner Aq eu@qub.com , 780.An Hajimu Umemoto Aq ume@FreeBSD.org , 781.An Henry Whincup Aq henry@techiebod.com , 782.An Jukka A. Ukkonen Aq jau@iki.fi , |
| 681.An Jean-Fran\(,cois Dockes Aq jf@dockes.org | 783.An Jean-Fran\(,cois Dockes Aq jf@dockes.org , 784.An Michael Gmelin Aq freebsd@grem.de |
| 682and others. 683It replaces the older 684.Nm ftpio 685library written by 686.An Poul-Henning Kamp Aq phk@FreeBSD.org 687and 688.An Jordan K. Hubbard Aq jkh@FreeBSD.org . 689.Pp 690This manual page was written by | 785and others. 786It replaces the older 787.Nm ftpio 788library written by 789.An Poul-Henning Kamp Aq phk@FreeBSD.org 790and 791.An Jordan K. Hubbard Aq jkh@FreeBSD.org . 792.Pp 793This manual page was written by |
| 691.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org . | 794.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org 795and 796.An Michael Gmelin Aq freebsd@grem.de . |
| 692.Sh BUGS 693Some parts of the library are not yet implemented. 694The most notable 695examples of this are 696.Fn fetchPutHTTP , 697.Fn fetchListHTTP , 698.Fn fetchListFTP 699and FTP proxy support. --- 12 unchanged lines hidden (view full) --- 712system errors. 713For instance, error code 202 means "Command not 714implemented, superfluous at this site" in an FTP context and 715"Accepted" in an HTTP context. 716.Pp 717.Fn fetchStatFTP 718does not check that the result of an MDTM command is a valid date. 719.Pp | 797.Sh BUGS 798Some parts of the library are not yet implemented. 799The most notable 800examples of this are 801.Fn fetchPutHTTP , 802.Fn fetchListHTTP , 803.Fn fetchListFTP 804and FTP proxy support. --- 12 unchanged lines hidden (view full) --- 817system errors. 818For instance, error code 202 means "Command not 819implemented, superfluous at this site" in an FTP context and 820"Accepted" in an HTTP context. 821.Pp 822.Fn fetchStatFTP 823does not check that the result of an MDTM command is a valid date. 824.Pp |
| 825In case password protected keys are used for client certificate based 826authentication the user is prompted for the password on each and every 827fetch operation. 828.Pp |
|
| 720The man page is incomplete, poorly written and produces badly 721formatted text. 722.Pp 723The error reporting mechanism is unsatisfactory. 724.Pp 725Some parts of the code are not fully reentrant. | 829The man page is incomplete, poorly written and produces badly 830formatted text. 831.Pp 832The error reporting mechanism is unsatisfactory. 833.Pp 834Some parts of the code are not fully reentrant. |