diff options
author | Ludovic Courtès <ludo@gnu.org> | 2020-01-10 15:13:40 +0100 |
---|---|---|
committer | Ludovic Courtès <ludo@gnu.org> | 2020-01-13 11:06:01 +0100 |
commit | 38f14ce65d8d86a9a6acabc4e84df59f5eb13b04 (patch) | |
tree | fa0eeec9ea2a802474b0e74c203bff2f788ee86e /doc/ref | |
parent | bcba2132849bc395f716910e27a9273d1a152a9b (diff) | |
download | guile-38f14ce65d8d86a9a6acabc4e84df59f5eb13b04.tar.gz |
web: 'open-socket-for-uri' can verify the server's X.509 certificate.
This is largely based on Guix commit
bc3c41ce36349ed4ec758c70b48a7059e363043a and subsequent changes to that
code.
* module/web/client.scm (x509-certificate-directory): New variable.
(set-certificate-credentials-x509-trust-file!*)
(make-credendials-with-ca-trust-files, peer-certificate)
(assert-valid-server-certificate, print-tls-certificate-error): New
procedures.
<top level>: Add call to 'set-exception-printer!'.
(tls-wrap): Add #:verify-certificate? parameter. When it is true, call
'make-credendials-with-ca-trust-files', pass it to
'set-session-credentials!', and call 'assert-valid-server-certificate'.
(open-socket-for-uri): Add #:verify-certificate? parameter and pass it
to 'tls-wrap'.
(http-request): Add #:verify-certificate? parameter and pass it to
'open-socket-for-uri'.
(define-http-verb): Add #:verify-certificate? parameter and pass it to
'http-request'.
* doc/ref/web.texi (Web Client): Update documentation of
'open-socket-for-uri' and 'http-request'. Document
'x509-certificate-directory'.
Diffstat (limited to 'doc/ref')
-rw-r--r-- | doc/ref/web.texi | 67 |
1 files changed, 65 insertions, 2 deletions
diff --git a/doc/ref/web.texi b/doc/ref/web.texi index 91b3a4edf..2d07dd7b1 100644 --- a/doc/ref/web.texi +++ b/doc/ref/web.texi @@ -1455,12 +1455,40 @@ the lower-level HTTP, request, and response modules. (use-modules (web client)) @end example -@deffn {Scheme Procedure} open-socket-for-uri uri +@deffn {Scheme Procedure} open-socket-for-uri uri [#:verify-certificate? #t] Return an open input/output port for a connection to URI. Guile dynamically loads GnuTLS for HTTPS support. @xref{Guile Preparations, how to install the GnuTLS bindings for Guile,, gnutls-guile, GnuTLS-Guile}, for more information. + +@cindex certificate verification, for HTTPS +When @var{verify-certificate?} is true, verify the server's X.509 +certificates against those read from @code{x509-certificate-directory}. +When an error occurs---e.g., the server's certificate has expired, or +its host name does not match---raise a @code{tls-certificate-error} +exception. The arguments to the @code{tls-certificate-error} exception +are: + +@enumerate +@item +a symbol indicating the failure cause, @code{host-mismatch} if the +certificate's host name does not match the server's host name, and +@code{invalid-certificate} for other causes; + +@item +the server's X.509 certificate (@pxref{Guile Reference, GnuTLS Guile +reference,, gnutls-guile, GnuTLS-Guile}); + +@item +the server's host name (a string); + +@item +in the case of @code{invalid-certificate} errors, a list of GnuTLS +certificate status values---one of the @code{certificate-status/} +constants, such as @code{certificate-status/signer-not-found} or +@code{certificate-status/revoked}. +@end enumerate @end deffn @anchor{http-request}@deffn {Scheme Procedure} http-request @var{uri} @var{arg}@dots{} @@ -1476,7 +1504,8 @@ their default values. @table @code @item #:method 'GET @item #:body #f -@item #:port (open-socket-for-uri @var{uri})] +@item #:verify-certificate? #t +@item #:port (open-socket-for-uri @var{uri} #:verify-certificate? @var{verify-certificate?}) @item #:version '(1 . 1) @item #:keep-alive? #f @item #:headers '() @@ -1507,6 +1536,10 @@ read. Unless @var{keep-alive?} is true, the port will be closed after the full response body has been read. +If @var{port} is false, @var{uri} denotes an HTTPS URL, and @var{verify-certificate?} is +true, verify X.509 certificates against those available in +@code{x509-certificate-directory}. + Returns two values: the response read from the server, and the response body as a string, bytevector, #f value, or as a port (if @var{streaming?} is true). @@ -1531,6 +1564,36 @@ arguments. @end deffn +@defvr {Scheme Parameter} x509-certificate-directory +@cindex X.509 certificate directory +@cindex HTTPS, X.509 certificates +@cindex certificates, for HTTPS +This parameter gives the name of the directory where X.509 certificates +for HTTPS connections should be looked for. + +Its default value is one of: + +@itemize +@item +@vindex GUILE_TLS_CERTIFICATE_DIRECTORY +the value of the @env{GUILE_TLS_CERTIFICATE_DIRECTORY} environment +variable; + +@item +@vindex SSL_CERT_DIR +or the value of the @env{SSL_CERT_DIR} environment variable (also +honored by the OpenSSL library); + +@item +or, as a last resort, @code{"/etc/ssl/certs"}. +@end itemize + +X.509 certificates are used when authenticating the identity of a remote +site, when the @code{#:verify-certificate?} argument to +@code{open-socket-for-uri}, to @code{http-request}, or to related +procedures is true. +@end defvr + @code{http-get} is useful for making one-off requests to web sites. If you are writing a web spider or some other client that needs to handle a number of requests in parallel, it's better to build an event-driven URL |