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 (see 461.Xr PEM 3 ) . 462.Pp 463By default 464.Nm libfetch 465allows TLSv1 and newer when negotiating the connecting with the remote 466peer. 467You can change this behavior by setting the 468.Ev SSL_NO_TLS1 , 469.Ev SSL_NO_TLS1_1 and 470.Ev SSL_NO_TLS1_2 471environment variables to disable TLS 1.0, 1.1 and 1.2 respectively. 472.Sh AUTHENTICATION 473Apart from setting the appropriate environment variables and 474specifying the user name and password in the URL or the 475.Vt struct url , 476the calling program has the option of defining an authentication 477function with the following prototype: 478.Pp 479.Ft int 480.Fn myAuthMethod "struct url *u" 481.Pp 482The callback function should fill in the 483.Fa user 484and 485.Fa pwd 486fields in the provided 487.Vt struct url 488and return 0 on success, or any other value to indicate failure. 489.Pp 490To register the authentication callback, simply set 491.Va fetchAuthMethod 492to point at it. 493The callback will be used whenever a site requires authentication and 494the appropriate environment variables are not set. 495.Pp 496This interface is experimental and may be subject to change. 497.Sh RETURN VALUES 498.Fn fetchParseURL 499returns a pointer to a 500.Vt struct url 501containing the individual components of the URL. 502If it is 503unable to allocate memory, or the URL is syntactically incorrect, 504.Fn fetchParseURL 505returns a NULL pointer. 506.Pp 507The 508.Fn fetchStat 509functions return 0 on success and -1 on failure. 510.Pp 511All other functions return a stream pointer which may be used to 512access the requested document, or NULL if an error occurred. 513.Pp 514The following error codes are defined in 515.In fetch.h : 516.Bl -tag -width 18n 517.It Bq Er FETCH_ABORT 518Operation aborted 519.It Bq Er FETCH_AUTH 520Authentication failed 521.It Bq Er FETCH_DOWN 522Service unavailable 523.It Bq Er FETCH_EXISTS 524File exists 525.It Bq Er FETCH_FULL 526File system full 527.It Bq Er FETCH_INFO 528Informational response 529.It Bq Er FETCH_MEMORY 530Insufficient memory 531.It Bq Er FETCH_MOVED 532File has moved 533.It Bq Er FETCH_NETWORK 534Network error 535.It Bq Er FETCH_OK 536No error 537.It Bq Er FETCH_PROTO 538Protocol error 539.It Bq Er FETCH_RESOLV 540Resolver error 541.It Bq Er FETCH_SERVER 542Server error 543.It Bq Er FETCH_TEMP 544Temporary error 545.It Bq Er FETCH_TIMEOUT 546Operation timed out 547.It Bq Er FETCH_UNAVAIL 548File is not available 549.It Bq Er FETCH_UNKNOWN 550Unknown error 551.It Bq Er FETCH_URL 552Invalid URL 553.El 554.Pp 555The accompanying error message includes a protocol-specific error code 556and message, like "File is not available (404 Not Found)" 557.Sh ENVIRONMENT 558.Bl -tag -width ".Ev FETCH_BIND_ADDRESS" 559.It Ev FETCH_BIND_ADDRESS 560Specifies a hostname or IP address to which sockets used for outgoing 561connections will be bound. 562.It Ev FTP_LOGIN 563Default FTP login if none was provided in the URL. 564.It Ev FTP_PASSIVE_MODE 565If set to 566.Ql no , 567forces the FTP code to use active mode. 568If set to any other value, forces passive mode even if the application 569requested active mode. 570.It Ev FTP_PASSWORD 571Default FTP password if the remote server requests one and none was 572provided in the URL. 573.It Ev FTP_PROXY 574URL of the proxy to use for FTP requests. 575The document part is ignored. 576FTP and HTTP proxies are supported; if no scheme is specified, FTP is 577assumed. 578If the proxy is an FTP proxy, 579.Nm libfetch 580will send 581.Ql user@host 582as user name to the proxy, where 583.Ql user 584is the real user name, and 585.Ql host 586is the name of the FTP server. 587.Pp 588If this variable is set to an empty string, no proxy will be used for 589FTP requests, even if the 590.Ev HTTP_PROXY 591variable is set. 592.It Ev ftp_proxy 593Same as 594.Ev FTP_PROXY , 595for compatibility. 596.It Ev HTTP_ACCEPT 597Specifies the value of the 598.Va Accept 599header for HTTP requests. 600If empty, no 601.Va Accept 602header is sent. 603The default is 604.Dq */* . 605.It Ev HTTP_AUTH 606Specifies HTTP authorization parameters as a colon-separated list of 607items. 608The first and second item are the authorization scheme and realm 609respectively; further items are scheme-dependent. 610Currently, the 611.Dq basic 612and 613.Dq digest 614authorization methods are supported. 615.Pp 616Both methods require two parameters: the user name and 617password, in that order. 618.Pp 619This variable is only used if the server requires authorization and 620no user name or password was specified in the URL. 621.It Ev HTTP_PROXY 622URL of the proxy to use for HTTP requests. 623The document part is ignored. 624Only HTTP proxies are supported for HTTP requests. 625If no port number is specified, the default is 3128. 626.Pp 627Note that this proxy will also be used for FTP documents, unless the 628.Ev FTP_PROXY 629variable is set. 630.It Ev http_proxy 631Same as 632.Ev HTTP_PROXY , 633for compatibility. 634.It Ev HTTP_PROXY_AUTH 635Specifies authorization parameters for the HTTP proxy in the same 636format as the 637.Ev HTTP_AUTH 638variable. 639.Pp 640This variable is used if and only if connected to an HTTP proxy, and 641is ignored if a user and/or a password were specified in the proxy 642URL. 643.It Ev HTTP_REFERER 644Specifies the referrer URL to use for HTTP requests. 645If set to 646.Dq auto , 647the document URL will be used as referrer URL. 648.It Ev HTTP_USER_AGENT 649Specifies the User-Agent string to use for HTTP requests. 650This can be useful when working with HTTP origin or proxy servers that 651differentiate between user agents. 652If defined but empty, no User-Agent header is sent. 653.It Ev NETRC 654Specifies a file to use instead of 655.Pa ~/.netrc 656to look up login names and passwords for FTP and HTTP sites as well as 657HTTP proxies. 658See 659.Xr ftp 1 660for a description of the file format. 661.It Ev NO_PROXY 662Either a single asterisk, which disables the use of proxies 663altogether, or a comma- or whitespace-separated list of hosts for 664which proxies should not be used. 665.It Ev no_proxy 666Same as 667.Ev NO_PROXY , 668for compatibility. 669.It Ev SOCKS5_PROXY 670Uses SOCKS version 5 to make connection. 671The format must be the IP or hostname followed by a colon for the port. 672IPv6 addresses must enclose the address in brackets. 673If no port is specified, the default is 1080. 674This setting will supercede a connection to an 675.Ev HTTP_PROXY . 676.It Ev SSL_CA_CERT_FILE 677CA certificate bundle containing trusted CA certificates. 678Default value: See HTTPS SCHEME above. 679.It Ev SSL_CA_CERT_PATH 680Path containing trusted CA hashes. 681.It Ev SSL_CLIENT_CERT_FILE 682PEM encoded client certificate/key which will be used in 683client certificate authentication. 684.It Ev SSL_CLIENT_KEY_FILE 685PEM encoded client key in case key and client certificate 686are stored separately. 687.It Ev SSL_CRL_FILE 688File containing certificate revocation list. 689.It Ev SSL_NO_TLS1 690Do not allow TLS version 1.0 when negotiating the connection. 691.It Ev SSL_NO_TLS1_1 692Do not allow TLS version 1.1 when negotiating the connection. 693.It Ev SSL_NO_TLS1_2 694Do not allow TLS version 1.2 when negotiating the connection. 695.It Ev SSL_NO_VERIFY_HOSTNAME 696If set, do not verify that the hostname matches the subject of the 697certificate presented by the server. 698.It Ev SSL_NO_VERIFY_PEER 699If set, do not verify the peer certificate against trusted CAs. 700.El 701.Sh EXAMPLES 702To access a proxy server on 703.Pa proxy.example.com 704port 8080, set the 705.Ev HTTP_PROXY 706environment variable in a manner similar to this: 707.Pp 708.Dl HTTP_PROXY=http://proxy.example.com:8080 709.Pp 710If the proxy server requires authentication, there are 711two options available for passing the authentication data. 712The first method is by using the proxy URL: 713.Pp 714.Dl HTTP_PROXY=http://<user>:<pwd>@proxy.example.com:8080 715.Pp 716The second method is by using the 717.Ev HTTP_PROXY_AUTH 718environment variable: 719.Bd -literal -offset indent 720HTTP_PROXY=http://proxy.example.com:8080 721HTTP_PROXY_AUTH=basic:*:<user>:<pwd> 722.Ed 723.Pp 724To disable the use of a proxy for an HTTP server running on the local 725host, define 726.Ev NO_PROXY 727as follows: 728.Bd -literal -offset indent 729NO_PROXY=localhost,127.0.0.1 730.Ed 731.Pp 732To use a SOCKS5 proxy, set the 733.Ev SOCKS5_PROXY 734environment variable to a 735valid host or IP followed by an optional colon and the port. 736IPv6 addresses must be enclosed in brackets. 737The following are examples of valid settings: 738.Bd -literal -offset indent 739SOCKS5_PROXY=proxy.example.com 740SOCKS5_PROXY=proxy.example.com:1080 741SOCKS5_PROXY=192.0.2.0 742SOCKS5_PROXY=198.51.100.0:1080 743SOCKS5_PROXY=[2001:db8::1] 744SOCKS5_PROXY=[2001:db8::2]:1080 745.Ed 746.Pp 747Access HTTPS website without any certificate verification whatsoever: 748.Bd -literal -offset indent 749SSL_NO_VERIFY_PEER=1 750SSL_NO_VERIFY_HOSTNAME=1 751.Ed 752.Pp 753Access HTTPS website using client certificate based authentication 754and a private CA: 755.Bd -literal -offset indent 756SSL_CLIENT_CERT_FILE=/path/to/client.pem 757SSL_CA_CERT_FILE=/path/to/myca.pem 758.Ed 759.Sh SEE ALSO 760.Xr fetch 1 , 761.Xr ip 4 762.Rs 763.%A J. Postel 764.%A J. K. Reynolds 765.%D October 1985 766.%B File Transfer Protocol 767.%O RFC959 768.Re 769.Rs 770.%A P. Deutsch 771.%A A. Emtage 772.%A A. Marine. 773.%D May 1994 774.%T How to Use Anonymous FTP 775.%O RFC1635 776.Re 777.Rs 778.%A T. Berners-Lee 779.%A L. Masinter 780.%A M. McCahill 781.%D December 1994 782.%T Uniform Resource Locators (URL) 783.%O RFC1738 784.Re 785.Rs 786.%A R. Fielding 787.%A J. Gettys 788.%A J. Mogul 789.%A H. Frystyk 790.%A L. Masinter 791.%A P. Leach 792.%A T. Berners-Lee 793.%D January 1999 794.%B Hypertext Transfer Protocol -- HTTP/1.1 795.%O RFC2616 796.Re 797.Rs 798.%A J. Franks 799.%A P. Hallam-Baker 800.%A J. Hostetler 801.%A S. Lawrence 802.%A P. Leach 803.%A A. Luotonen 804.%A L. Stewart 805.%D June 1999 806.%B HTTP Authentication: Basic and Digest Access Authentication 807.%O RFC2617 808.Re 809.Sh HISTORY 810The 811.Nm fetch 812library first appeared in 813.Fx 3.0 . 814.Sh AUTHORS 815.An -nosplit 816The 817.Nm fetch 818library was mostly written by 819.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org 820with numerous suggestions and contributions from 821.An Jordan K. Hubbard Aq Mt jkh@FreeBSD.org , 822.An Eugene Skepner Aq Mt eu@qub.com , 823.An Hajimu Umemoto Aq Mt ume@FreeBSD.org , 824.An Henry Whincup Aq Mt henry@techiebod.com , 825.An Jukka A. Ukkonen Aq Mt jau@iki.fi , 826.An Jean-Fran\(,cois Dockes Aq Mt jf@dockes.org , 827.An Michael Gmelin Aq Mt freebsd@grem.de 828and others. 829It replaces the older 830.Nm ftpio 831library written by 832.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org 833and 834.An Jordan K. Hubbard Aq Mt jkh@FreeBSD.org . 835.Pp 836This manual page was written by 837.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org 838and 839.An Michael Gmelin Aq Mt freebsd@grem.de . 840.Sh BUGS 841Some parts of the library are not yet implemented. 842The most notable 843examples of this are 844.Fn fetchPutHTTP , 845.Fn fetchListHTTP , 846.Fn fetchListFTP 847and FTP proxy support. 848.Pp 849There is no way to select a proxy at run-time other than setting the 850.Ev HTTP_PROXY 851or 852.Ev FTP_PROXY 853environment variables as appropriate. 854.Pp 855.Nm libfetch 856does not understand or obey 305 (Use Proxy) replies. 857.Pp 858Error numbers are unique only within a certain context; the error 859codes used for FTP and HTTP overlap, as do those used for resolver and 860system errors. 861For instance, error code 202 means "Command not 862implemented, superfluous at this site" in an FTP context and 863"Accepted" in an HTTP context. 864.Pp 865.Fn fetchStatFTP 866does not check that the result of an MDTM command is a valid date. 867.Pp 868In case password protected keys are used for client certificate based 869authentication the user is prompted for the password on each and every 870fetch operation. 871.Pp 872The man page is incomplete, poorly written and produces badly 873formatted text. 874.Pp 875The error reporting mechanism is unsatisfactory. 876.Pp 877Some parts of the code are not fully reentrant. 878