1.\"- 2.\" Copyright (c) 1998-2013 Dag-Erling Smørgrav 3.\" Copyright (c) 2013-2016 Michael Gmelin <freebsd@grem.de> 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 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 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.\" 27.\" $FreeBSD$ 28.\" 29.Dd November 24, 2020 30.Dt FETCH 3 31.Os 32.Sh NAME 33.Nm fetchMakeURL , 34.Nm fetchParseURL , 35.Nm fetchFreeURL , 36.Nm fetchXGetURL , 37.Nm fetchGetURL , 38.Nm fetchPutURL , 39.Nm fetchStatURL , 40.Nm fetchListURL , 41.Nm fetchXGet , 42.Nm fetchGet , 43.Nm fetchPut , 44.Nm fetchStat , 45.Nm fetchList , 46.Nm fetchXGetFile , 47.Nm fetchGetFile , 48.Nm fetchPutFile , 49.Nm fetchStatFile , 50.Nm fetchListFile , 51.Nm fetchXGetHTTP , 52.Nm fetchGetHTTP , 53.Nm fetchPutHTTP , 54.Nm fetchStatHTTP , 55.Nm fetchListHTTP , 56.Nm fetchReqHTTP , 57.Nm fetchXGetFTP , 58.Nm fetchGetFTP , 59.Nm fetchPutFTP , 60.Nm fetchStatFTP , 61.Nm fetchListFTP 62.Nd file transfer functions 63.Sh LIBRARY 64.Lb libfetch 65.Sh SYNOPSIS 66.In sys/param.h 67.In stdio.h 68.In fetch.h 69.Ft struct url * 70.Fn fetchMakeURL "const char *scheme" "const char *host" "int port" "const char *doc" "const char *user" "const char *pwd" 71.Ft struct url * 72.Fn fetchParseURL "const char *URL" 73.Ft void 74.Fn fetchFreeURL "struct url *u" 75.Ft FILE * 76.Fn fetchXGetURL "const char *URL" "struct url_stat *us" "const char *flags" 77.Ft FILE * 78.Fn fetchGetURL "const char *URL" "const char *flags" 79.Ft FILE * 80.Fn fetchPutURL "const char *URL" "const char *flags" 81.Ft int 82.Fn fetchStatURL "const char *URL" "struct url_stat *us" "const char *flags" 83.Ft struct url_ent * 84.Fn fetchListURL "const char *URL" "const char *flags" 85.Ft FILE * 86.Fn fetchXGet "struct url *u" "struct url_stat *us" "const char *flags" 87.Ft FILE * 88.Fn fetchGet "struct url *u" "const char *flags" 89.Ft FILE * 90.Fn fetchPut "struct url *u" "const char *flags" 91.Ft int 92.Fn fetchStat "struct url *u" "struct url_stat *us" "const char *flags" 93.Ft struct url_ent * 94.Fn fetchList "struct url *u" "const char *flags" 95.Ft FILE * 96.Fn fetchXGetFile "struct url *u" "struct url_stat *us" "const char *flags" 97.Ft FILE * 98.Fn fetchGetFile "struct url *u" "const char *flags" 99.Ft FILE * 100.Fn fetchPutFile "struct url *u" "const char *flags" 101.Ft int 102.Fn fetchStatFile "struct url *u" "struct url_stat *us" "const char *flags" 103.Ft struct url_ent * 104.Fn fetchListFile "struct url *u" "const char *flags" 105.Ft FILE * 106.Fn fetchXGetHTTP "struct url *u" "struct url_stat *us" "const char *flags" 107.Ft FILE * 108.Fn fetchGetHTTP "struct url *u" "const char *flags" 109.Ft FILE * 110.Fn fetchPutHTTP "struct url *u" "const char *flags" 111.Ft int 112.Fn fetchStatHTTP "struct url *u" "struct url_stat *us" "const char *flags" 113.Ft struct url_ent * 114.Fn fetchListHTTP "struct url *u" "const char *flags" 115.Ft FILE * 116.Fn fetchReqHTTP "struct url *u" "const char *method" "const char *flags" "const char *content_type" "const char *body" 117.Ft FILE * 118.Fn fetchXGetFTP "struct url *u" "struct url_stat *us" "const char *flags" 119.Ft FILE * 120.Fn fetchGetFTP "struct url *u" "const char *flags" 121.Ft FILE * 122.Fn fetchPutFTP "struct url *u" "const char *flags" 123.Ft int 124.Fn fetchStatFTP "struct url *u" "struct url_stat *us" "const char *flags" 125.Ft struct url_ent * 126.Fn fetchListFTP "struct url *u" "const char *flags" 127.Sh DESCRIPTION 128These functions implement a high-level library for retrieving and 129uploading files using Uniform Resource Locators (URLs). 130.Pp 131.Fn fetchParseURL 132takes a URL in the form of a null-terminated string and splits it into 133its components function according to the Common Internet Scheme Syntax 134detailed in RFC1738. 135A regular expression which produces this syntax is: 136.Bd -literal 137 <scheme>:(//(<user>(:<pwd>)?@)?<host>(:<port>)?)?/(<document>)? 138.Ed 139.Pp 140If the URL does not seem to begin with a scheme name, the following 141syntax is assumed: 142.Bd -literal 143 ((<user>(:<pwd>)?@)?<host>(:<port>)?)?/(<document>)? 144.Ed 145.Pp 146Note that some components of the URL are not necessarily relevant to 147all URL schemes. 148For instance, the file scheme only needs the <scheme> and <document> 149components. 150.Pp 151.Fn fetchMakeURL 152and 153.Fn fetchParseURL 154return a pointer to a 155.Vt url 156structure, which is defined as follows in 157.In fetch.h : 158.Bd -literal 159#define URL_SCHEMELEN 16 160#define URL_USERLEN 256 161#define URL_PWDLEN 256 162 163struct url { 164 char scheme[URL_SCHEMELEN+1]; 165 char user[URL_USERLEN+1]; 166 char pwd[URL_PWDLEN+1]; 167 char host[MAXHOSTNAMELEN+1]; 168 int port; 169 char *doc; 170 off_t offset; 171 size_t length; 172 time_t ims_time; 173}; 174.Ed 175.Pp 176The 177.Va ims_time 178field stores the time value for 179.Li If-Modified-Since 180HTTP requests. 181.Pp 182The pointer returned by 183.Fn fetchMakeURL 184or 185.Fn fetchParseURL 186should be freed using 187.Fn fetchFreeURL . 188.Pp 189.Fn fetchXGetURL , 190.Fn fetchGetURL , 191and 192.Fn fetchPutURL 193constitute the recommended interface to the 194.Nm fetch 195library. 196They examine the URL passed to them to determine the transfer 197method, and call the appropriate lower-level functions to perform the 198actual transfer. 199.Fn fetchXGetURL 200also returns the remote document's metadata in the 201.Vt url_stat 202structure pointed to by the 203.Fa us 204argument. 205.Pp 206The 207.Fa flags 208argument is a string of characters which specify transfer options. 209The 210meaning of the individual flags is scheme-dependent, and is detailed 211in the appropriate section below. 212.Pp 213.Fn fetchStatURL 214attempts to obtain the requested document's metadata and fill in the 215structure pointed to by its second argument. 216The 217.Vt url_stat 218structure is defined as follows in 219.In fetch.h : 220.Bd -literal 221struct url_stat { 222 off_t size; 223 time_t atime; 224 time_t mtime; 225}; 226.Ed 227.Pp 228If the size could not be obtained from the server, the 229.Fa size 230field is set to -1. 231If the modification time could not be obtained from the server, the 232.Fa mtime 233field is set to the epoch. 234If the access time could not be obtained from the server, the 235.Fa atime 236field is set to the modification time. 237.Pp 238.Fn fetchListURL 239attempts to list the contents of the directory pointed to by the URL 240provided. 241If successful, it returns a malloced array of 242.Vt url_ent 243structures. 244The 245.Vt url_ent 246structure is defined as follows in 247.In fetch.h : 248.Bd -literal 249struct url_ent { 250 char name[PATH_MAX]; 251 struct url_stat stat; 252}; 253.Ed 254.Pp 255The list is terminated by an entry with an empty name. 256.Pp 257The pointer returned by 258.Fn fetchListURL 259should be freed using 260.Fn free . 261.Pp 262.Fn fetchXGet , 263.Fn fetchGet , 264.Fn fetchPut 265and 266.Fn fetchStat 267are similar to 268.Fn fetchXGetURL , 269.Fn fetchGetURL , 270.Fn fetchPutURL 271and 272.Fn fetchStatURL , 273except that they expect a pre-parsed URL in the form of a pointer to 274a 275.Vt struct url 276rather than a string. 277.Pp 278All of the 279.Fn fetchXGetXXX , 280.Fn fetchGetXXX 281and 282.Fn fetchPutXXX 283functions return a pointer to a stream which can be used to read or 284write data from or to the requested document, respectively. 285Note that 286although the implementation details of the individual access methods 287vary, it can generally be assumed that a stream returned by one of the 288.Fn fetchXGetXXX 289or 290.Fn fetchGetXXX 291functions is read-only, and that a stream returned by one of the 292.Fn fetchPutXXX 293functions is write-only. 294.Sh FILE SCHEME 295.Fn fetchXGetFile , 296.Fn fetchGetFile 297and 298.Fn fetchPutFile 299provide access to documents which are files in a locally mounted file 300system. 301Only the <document> component of the URL is used. 302.Pp 303.Fn fetchXGetFile 304and 305.Fn fetchGetFile 306do not accept any flags. 307.Pp 308.Fn fetchPutFile 309accepts the 310.Ql a 311(append to file) flag. 312If that flag is specified, the data written to 313the stream returned by 314.Fn fetchPutFile 315will be appended to the previous contents of the file, instead of 316replacing them. 317.Sh FTP SCHEME 318.Fn fetchXGetFTP , 319.Fn fetchGetFTP 320and 321.Fn fetchPutFTP 322implement the FTP protocol as described in RFC959. 323.Pp 324If the 325.Ql P 326(not passive) flag is specified, an active (rather than passive) 327connection will be attempted. 328.Pp 329The 330.Ql p 331flag is supported for compatibility with earlier versions where active 332connections were the default. 333It has precedence over the 334.Ql P 335flag, so if both are specified, 336.Nm 337will use a passive connection. 338.Pp 339If the 340.Ql l 341(low) flag is specified, data sockets will be allocated in the low (or 342default) port range instead of the high port range (see 343.Xr ip 4 ) . 344.Pp 345If the 346.Ql d 347(direct) flag is specified, 348.Fn fetchXGetFTP , 349.Fn fetchGetFTP 350and 351.Fn fetchPutFTP 352will use a direct connection even if a proxy server is defined. 353.Pp 354If no user name or password is given, the 355.Nm fetch 356library will attempt an anonymous login, with user name "anonymous" 357and password "anonymous@<hostname>". 358.Sh HTTP SCHEME 359The 360.Fn fetchXGetHTTP , 361.Fn fetchGetHTTP , 362.Fn fetchPutHTTP 363and 364.Fn fetchReqHTTP 365functions implement the HTTP/1.1 protocol. 366With a little luck, there is 367even a chance that they comply with RFC2616 and RFC2617. 368.Pp 369If the 370.Ql d 371(direct) flag is specified, 372.Fn fetchXGetHTTP , 373.Fn fetchGetHTTP 374and 375.Fn fetchPutHTTP 376will use a direct connection even if a proxy server is defined. 377.Pp 378If the 379.Ql i 380(if-modified-since) flag is specified, and 381the 382.Va ims_time 383field is set in 384.Vt "struct url" , 385then 386.Fn fetchXGetHTTP 387and 388.Fn fetchGetHTTP 389will send a conditional 390.Li If-Modified-Since 391HTTP header to only fetch the content if it is newer than 392.Va ims_time . 393.Pp 394The function 395.Fn fetchReqHTTP 396can be used to make requests with an arbitrary HTTP verb, 397including POST, DELETE, CONNECT, OPTIONS, TRACE or PATCH. 398This can be done by setting the argument 399.Fa method 400to the intended verb, such as 401.Ql POST , 402and 403.Fa body 404to the content. 405.Pp 406Since there seems to be no good way of implementing the HTTP PUT 407method in a manner consistent with the rest of the 408.Nm fetch 409library, 410.Fn fetchPutHTTP 411is currently unimplemented. 412.Sh HTTPS SCHEME 413Based on HTTP SCHEME. 414By default the peer is verified using the CA bundle located in 415.Pa /usr/local/etc/ssl/cert.pem . 416If this file does not exist, 417.Pa /etc/ssl/cert.pem 418is used instead. 419If neither file exists, and 420.Ev SSL_CA_CERT_PATH 421has not been set, 422OpenSSL's default CA cert and path settings apply. 423The certificate bundle can contain multiple CA certificates. 424A common source of a current CA bundle is 425.Pa \%security/ca_root_nss . 426.Pp 427The CA bundle used for peer verification can be changed by setting the 428environment variables 429.Ev SSL_CA_CERT_FILE 430to point to a concatenated bundle of trusted certificates and 431.Ev SSL_CA_CERT_PATH 432to point to a directory containing hashes of trusted CAs (see 433.Xr verify 1 ) . 434.Pp 435A certificate revocation list (CRL) can be used by setting the 436environment variable 437.Ev SSL_CRL_FILE 438(see 439.Xr crl 1 ) . 440.Pp 441Peer verification can be disabled by setting the environment variable 442.Ev SSL_NO_VERIFY_PEER . 443Note that this also disables CRL checking. 444.Pp 445By default the service identity is verified according to the rules 446detailed in RFC6125 (also known as hostname verification). 447This feature can be disabled by setting the environment variable 448.Ev SSL_NO_VERIFY_HOSTNAME . 449.Pp 450Client certificate based authentication is supported. 451The environment variable 452.Ev SSL_CLIENT_CERT_FILE 453should be set to point to a file containing key and client certificate 454to be used in PEM format. 455When a PEM-format key is in a separate file from the client certificate, 456the environment variable 457.Ev SSL_CLIENT_KEY_FILE 458can be set to point to the key file. 459In case the key uses a password, the user will be prompted on standard 460input. 461.Pp 462By default 463.Nm libfetch 464allows TLSv1 and newer when negotiating the connecting with the remote 465peer. 466You can change this behavior by setting the 467.Ev SSL_NO_TLS1 , 468.Ev SSL_NO_TLS1_1 and 469.Ev SSL_NO_TLS1_2 470environment variables to disable TLS 1.0, 1.1 and 1.2 respectively. 471.Sh AUTHENTICATION 472Apart from setting the appropriate environment variables and 473specifying the user name and password in the URL or the 474.Vt struct url , 475the calling program has the option of defining an authentication 476function with the following prototype: 477.Pp 478.Ft int 479.Fn myAuthMethod "struct url *u" 480.Pp 481The callback function should fill in the 482.Fa user 483and 484.Fa pwd 485fields in the provided 486.Vt struct url 487and return 0 on success, or any other value to indicate failure. 488.Pp 489To register the authentication callback, simply set 490.Va fetchAuthMethod 491to point at it. 492The callback will be used whenever a site requires authentication and 493the appropriate environment variables are not set. 494.Pp 495This interface is experimental and may be subject to change. 496.Sh RETURN VALUES 497.Fn fetchParseURL 498returns a pointer to a 499.Vt struct url 500containing the individual components of the URL. 501If it is 502unable to allocate memory, or the URL is syntactically incorrect, 503.Fn fetchParseURL 504returns a NULL pointer. 505.Pp 506The 507.Fn fetchStat 508functions return 0 on success and -1 on failure. 509.Pp 510All other functions return a stream pointer which may be used to 511access the requested document, or NULL if an error occurred. 512.Pp 513The following error codes are defined in 514.In fetch.h : 515.Bl -tag -width 18n 516.It Bq Er FETCH_ABORT 517Operation aborted 518.It Bq Er FETCH_AUTH 519Authentication failed 520.It Bq Er FETCH_DOWN 521Service unavailable 522.It Bq Er FETCH_EXISTS 523File exists 524.It Bq Er FETCH_FULL 525File system full 526.It Bq Er FETCH_INFO 527Informational response 528.It Bq Er FETCH_MEMORY 529Insufficient memory 530.It Bq Er FETCH_MOVED 531File has moved 532.It Bq Er FETCH_NETWORK 533Network error 534.It Bq Er FETCH_OK 535No error 536.It Bq Er FETCH_PROTO 537Protocol error 538.It Bq Er FETCH_RESOLV 539Resolver error 540.It Bq Er FETCH_SERVER 541Server error 542.It Bq Er FETCH_TEMP 543Temporary error 544.It Bq Er FETCH_TIMEOUT 545Operation timed out 546.It Bq Er FETCH_UNAVAIL 547File is not available 548.It Bq Er FETCH_UNKNOWN 549Unknown error 550.It Bq Er FETCH_URL 551Invalid URL 552.El 553.Pp 554The accompanying error message includes a protocol-specific error code 555and message, like "File is not available (404 Not Found)" 556.Sh ENVIRONMENT 557.Bl -tag -width ".Ev FETCH_BIND_ADDRESS" 558.It Ev FETCH_BIND_ADDRESS 559Specifies a hostname or IP address to which sockets used for outgoing 560connections will be bound. 561.It Ev FTP_LOGIN 562Default FTP login if none was provided in the URL. 563.It Ev FTP_PASSIVE_MODE 564If set to 565.Ql no , 566forces the FTP code to use active mode. 567If set to any other value, forces passive mode even if the application 568requested active mode. 569.It Ev FTP_PASSWORD 570Default FTP password if the remote server requests one and none was 571provided in the URL. 572.It Ev FTP_PROXY 573URL of the proxy to use for FTP requests. 574The document part is ignored. 575FTP and HTTP proxies are supported; if no scheme is specified, FTP is 576assumed. 577If the proxy is an FTP proxy, 578.Nm libfetch 579will send 580.Ql user@host 581as user name to the proxy, where 582.Ql user 583is the real user name, and 584.Ql host 585is the name of the FTP server. 586.Pp 587If this variable is set to an empty string, no proxy will be used for 588FTP requests, even if the 589.Ev HTTP_PROXY 590variable is set. 591.It Ev ftp_proxy 592Same as 593.Ev FTP_PROXY , 594for compatibility. 595.It Ev HTTP_ACCEPT 596Specifies the value of the 597.Va Accept 598header for HTTP requests. 599If empty, no 600.Va Accept 601header is sent. 602The default is 603.Dq */* . 604.It Ev HTTP_AUTH 605Specifies HTTP authorization parameters as a colon-separated list of 606items. 607The first and second item are the authorization scheme and realm 608respectively; further items are scheme-dependent. 609Currently, the 610.Dq basic 611and 612.Dq digest 613authorization methods are supported. 614.Pp 615Both methods require two parameters: the user name and 616password, in that order. 617.Pp 618This variable is only used if the server requires authorization and 619no user name or password was specified in the URL. 620.It Ev HTTP_PROXY 621URL of the proxy to use for HTTP requests. 622The document part is ignored. 623Only HTTP proxies are supported for HTTP requests. 624If no port number is specified, the default is 3128. 625.Pp 626Note that this proxy will also be used for FTP documents, unless the 627.Ev FTP_PROXY 628variable is set. 629.It Ev http_proxy 630Same as 631.Ev HTTP_PROXY , 632for compatibility. 633.It Ev HTTP_PROXY_AUTH 634Specifies authorization parameters for the HTTP proxy in the same 635format as the 636.Ev HTTP_AUTH 637variable. 638.Pp 639This variable is used if and only if connected to an HTTP proxy, and 640is ignored if a user and/or a password were specified in the proxy 641URL. 642.It Ev HTTP_REFERER 643Specifies the referrer URL to use for HTTP requests. 644If set to 645.Dq auto , 646the document URL will be used as referrer URL. 647.It Ev HTTP_USER_AGENT 648Specifies the User-Agent string to use for HTTP requests. 649This can be useful when working with HTTP origin or proxy servers that 650differentiate between user agents. 651If defined but empty, no User-Agent header is sent. 652.It Ev NETRC 653Specifies a file to use instead of 654.Pa ~/.netrc 655to look up login names and passwords for FTP and HTTP sites as well as 656HTTP proxies. 657See 658.Xr ftp 1 659for a description of the file format. 660.It Ev NO_PROXY 661Either a single asterisk, which disables the use of proxies 662altogether, or a comma- or whitespace-separated list of hosts for 663which proxies should not be used. 664.It Ev no_proxy 665Same as 666.Ev NO_PROXY , 667for compatibility. 668.It Ev SOCKS5_PROXY 669Uses SOCKS version 5 to make connection. 670The format must be the IP or hostname followed by a colon for the port. 671IPv6 addresses must enclose the address in brackets. 672If no port is specified, the default is 1080. 673This setting will supercede a connection to an 674.Ev HTTP_PROXY . 675.It Ev SSL_CA_CERT_FILE 676CA certificate bundle containing trusted CA certificates. 677Default value: See HTTPS SCHEME above. 678.It Ev SSL_CA_CERT_PATH 679Path containing trusted CA hashes. 680.It Ev SSL_CLIENT_CERT_FILE 681PEM encoded client certificate/key which will be used in 682client certificate authentication. 683.It Ev SSL_CLIENT_KEY_FILE 684PEM encoded client key in case key and client certificate 685are stored separately. 686.It Ev SSL_CRL_FILE 687File containing certificate revocation list. 688.It Ev SSL_NO_TLS1 689Do not allow TLS version 1.0 when negotiating the connection. 690.It Ev SSL_NO_TLS1_1 691Do not allow TLS version 1.1 when negotiating the connection. 692.It Ev SSL_NO_TLS1_2 693Do not allow TLS version 1.2 when negotiating the connection. 694.It Ev SSL_NO_VERIFY_HOSTNAME 695If set, do not verify that the hostname matches the subject of the 696certificate presented by the server. 697.It Ev SSL_NO_VERIFY_PEER 698If set, do not verify the peer certificate against trusted CAs. 699.El 700.Sh EXAMPLES 701To access a proxy server on 702.Pa proxy.example.com 703port 8080, set the 704.Ev HTTP_PROXY 705environment variable in a manner similar to this: 706.Pp 707.Dl HTTP_PROXY=http://proxy.example.com:8080 708.Pp 709If the proxy server requires authentication, there are 710two options available for passing the authentication data. 711The first method is by using the proxy URL: 712.Pp 713.Dl HTTP_PROXY=http://<user>:<pwd>@proxy.example.com:8080 714.Pp 715The second method is by using the 716.Ev HTTP_PROXY_AUTH 717environment variable: 718.Bd -literal -offset indent 719HTTP_PROXY=http://proxy.example.com:8080 720HTTP_PROXY_AUTH=basic:*:<user>:<pwd> 721.Ed 722.Pp 723To disable the use of a proxy for an HTTP server running on the local 724host, define 725.Ev NO_PROXY 726as follows: 727.Bd -literal -offset indent 728NO_PROXY=localhost,127.0.0.1 729.Ed 730.Pp 731To use a SOCKS5 proxy, set the 732.Ev SOCKS5_PROXY 733environment variable to a 734valid host or IP followed by an optional colon and the port. 735IPv6 addresses must be enclosed in brackets. 736The following are examples of valid settings: 737.Bd -literal -offset indent 738SOCKS5_PROXY=proxy.example.com 739SOCKS5_PROXY=proxy.example.com:1080 740SOCKS5_PROXY=192.0.2.0 741SOCKS5_PROXY=198.51.100.0:1080 742SOCKS5_PROXY=[2001:db8::1] 743SOCKS5_PROXY=[2001:db8::2]:1080 744.Ed 745.Pp 746Access HTTPS website without any certificate verification whatsoever: 747.Bd -literal -offset indent 748SSL_NO_VERIFY_PEER=1 749SSL_NO_VERIFY_HOSTNAME=1 750.Ed 751.Pp 752Access HTTPS website using client certificate based authentication 753and a private CA: 754.Bd -literal -offset indent 755SSL_CLIENT_CERT_FILE=/path/to/client.pem 756SSL_CA_CERT_FILE=/path/to/myca.pem 757.Ed 758.Sh SEE ALSO 759.Xr fetch 1 , 760.Xr ip 4 761.Rs 762.%A J. Postel 763.%A J. K. Reynolds 764.%D October 1985 765.%B File Transfer Protocol 766.%O RFC959 767.Re 768.Rs 769.%A P. Deutsch 770.%A A. Emtage 771.%A A. Marine. 772.%D May 1994 773.%T How to Use Anonymous FTP 774.%O RFC1635 775.Re 776.Rs 777.%A T. Berners-Lee 778.%A L. Masinter 779.%A M. McCahill 780.%D December 1994 781.%T Uniform Resource Locators (URL) 782.%O RFC1738 783.Re 784.Rs 785.%A R. Fielding 786.%A J. Gettys 787.%A J. Mogul 788.%A H. Frystyk 789.%A L. Masinter 790.%A P. Leach 791.%A T. Berners-Lee 792.%D January 1999 793.%B Hypertext Transfer Protocol -- HTTP/1.1 794.%O RFC2616 795.Re 796.Rs 797.%A J. Franks 798.%A P. Hallam-Baker 799.%A J. Hostetler 800.%A S. Lawrence 801.%A P. Leach 802.%A A. Luotonen 803.%A L. Stewart 804.%D June 1999 805.%B HTTP Authentication: Basic and Digest Access Authentication 806.%O RFC2617 807.Re 808.Sh HISTORY 809The 810.Nm fetch 811library first appeared in 812.Fx 3.0 . 813.Sh AUTHORS 814.An -nosplit 815The 816.Nm fetch 817library was mostly written by 818.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org 819with numerous suggestions and contributions from 820.An Jordan K. Hubbard Aq Mt jkh@FreeBSD.org , 821.An Eugene Skepner Aq Mt eu@qub.com , 822.An Hajimu Umemoto Aq Mt ume@FreeBSD.org , 823.An Henry Whincup Aq Mt henry@techiebod.com , 824.An Jukka A. Ukkonen Aq Mt jau@iki.fi , 825.An Jean-Fran\(,cois Dockes Aq Mt jf@dockes.org , 826.An Michael Gmelin Aq Mt freebsd@grem.de 827and others. 828It replaces the older 829.Nm ftpio 830library written by 831.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org 832and 833.An Jordan K. Hubbard Aq Mt jkh@FreeBSD.org . 834.Pp 835This manual page was written by 836.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org 837and 838.An Michael Gmelin Aq Mt freebsd@grem.de . 839.Sh BUGS 840Some parts of the library are not yet implemented. 841The most notable 842examples of this are 843.Fn fetchPutHTTP , 844.Fn fetchListHTTP , 845.Fn fetchListFTP 846and FTP proxy support. 847.Pp 848There is no way to select a proxy at run-time other than setting the 849.Ev HTTP_PROXY 850or 851.Ev FTP_PROXY 852environment variables as appropriate. 853.Pp 854.Nm libfetch 855does not understand or obey 305 (Use Proxy) replies. 856.Pp 857Error numbers are unique only within a certain context; the error 858codes used for FTP and HTTP overlap, as do those used for resolver and 859system errors. 860For instance, error code 202 means "Command not 861implemented, superfluous at this site" in an FTP context and 862"Accepted" in an HTTP context. 863.Pp 864.Fn fetchStatFTP 865does not check that the result of an MDTM command is a valid date. 866.Pp 867In case password protected keys are used for client certificate based 868authentication the user is prompted for the password on each and every 869fetch operation. 870.Pp 871The man page is incomplete, poorly written and produces badly 872formatted text. 873.Pp 874The error reporting mechanism is unsatisfactory. 875.Pp 876Some parts of the code are not fully reentrant. 877