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