1/* Part of SWI-Prolog 2 3 Author: Jan van der Steen, Matt Lilley and Jan Wielemaker, 4 E-mail: J.Wielemaker@vu.nl 5 WWW: http://www.swi-prolog.org 6 Copyright (c) 2004-2017, SWI-Prolog Foundation 7 VU University Amsterdam 8 All rights reserved. 9 10 Redistribution and use in source and binary forms, with or without 11 modification, are permitted provided that the following conditions 12 are met: 13 14 1. Redistributions of source code must retain the above copyright 15 notice, this list of conditions and the following disclaimer. 16 17 2. Redistributions in binary form must reproduce the above copyright 18 notice, this list of conditions and the following disclaimer in 19 the documentation and/or other materials provided with the 20 distribution. 21 22 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 23 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 24 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 25 FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 26 COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 27 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 28 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 29 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 30 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 32 ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 33 POSSIBILITY OF SUCH DAMAGE. 34*/ 35 36:- module(ssl, 37 [ load_certificate/2, % +Stream, -Certificate 38 load_private_key/3, % +Stream, +Password, -Key 39 load_public_key/2, % +Stream, -Key 40 load_crl/2, % +Stream, -Crl 41 system_root_certificates/1, % -List 42 cert_accept_any/5, % +SSL, +ProblemCertificate, 43 % +AllCertificates, +FirstCertificate, 44 % +Error 45 ssl_context/3, % +Role, -Config, :Options 46 ssl_add_certificate_key/4, % +Config, +Cert, +Key, -Config 47 ssl_set_options/3, % +Config0, -Config, +Options 48 ssl_negotiate/5, % +Config, +PlainRead, +PlainWrite, 49 % -SSLRead, -SSLWrite 50 ssl_peer_certificate/2, % +Stream, -Certificate 51 ssl_peer_certificate_chain/2, % +Stream, -Certificates 52 ssl_session/2, % +Stream, -Session 53 ssl_secure_ciphers/1 % -Ciphers 54 ]). 55:- use_module(library(option)). 56:- use_module(library(settings)). 57:- use_module(library(crypto), []). % force initialization of libcrypto 58 59:- use_foreign_library(foreign(ssl4pl)). 60 61:- meta_predicate 62 ssl_context(, , ), 63 ssl_set_options(, , ). 64 65:- predicate_options(ssl_context/3, 3, 66 [ host(atom), 67 port(integer), 68 certificate_file(atom), 69 key_file(atom), 70 certificate_key_pairs(any), 71 password(any), 72 cipher_list(any), 73 ecdh_curve(any), 74 pem_password_hook(callable), 75 cacert_file(any), 76 crl(any), 77 require_crl(boolean), 78 cert_verify_hook(callable), 79 peer_cert(boolean), 80 close_parent(boolean), 81 close_notify(boolean), 82 sni_hook(callable), 83 alpn_protocols(any), 84 alpn_protocol_hook(callable) 85 ]). 86 87/** <module> Secure Socket Layer (SSL) library 88 89An SSL server and client can be built with the (abstracted) 90predicate calls from the table below. The `tcp_` predicates 91are provided by library(socket). The predicate ssl_context/3 92defines properties of the SSL connection, while ssl_negotiate/5 93establishes the SSL connection based on the wire streams created 94by the TCP predicates and the context. 95 96 | *The SSL Server* | *The SSL Client* | 97 | ssl_context/3 | ssl_context/3 | 98 | tcp_socket/1 | | 99 | tcp_accept/3 | tcp_connect/3 | 100 | tcp_open_socket/3 | stream_pair/3 | 101 | ssl_negotiate/5 | ssl_negotiate/5 | 102 103The library is abstracted to communication over streams, and is not 104reliant on those streams being directly attached to sockets. The `tcp_` 105calls here are simply the most common way to use the library. Other 106two-way communication channels such as (named), pipes can just as 107easily be used. 108 109@see library(socket), library(http/http_open), library(crypto) 110*/ 111 112:- setting(secure_ciphers, atom, 113 'EECDH+AESGCM:EDH+AESGCM:EECDH+AES256:EDH+AES256:EECDH+CHACHA20:EDH+CHACHA20', 114 "Default set of ciphers considered secure"). 115 116%! ssl_context(+Role, -SSL, :Options) is det. 117% 118% Create an SSL context. The context defines several properties 119% of the SSL connection such as involved keys, preferred 120% encryption, and passwords. After establishing a context, an SSL 121% connection can be negotiated using ssl_negotiate/5, turning two 122% arbitrary plain Prolog streams into encrypted streams. This 123% predicate processes the options below. 124% 125% * host(+HostName) 126% For the client, the host to which it connects. This option 127% _should_ be specified when Role is `client`. Otherwise, 128% certificate verification may fail when negotiating a 129% secure connection. 130% * certificate_file(+FileName) 131% Specify where the certificate file can be found. This can be the 132% same as the key_file(+FileName) option. A server _must_ have at 133% least one certificate before clients can connect. A client 134% _must_ have a certificate only if the server demands the client 135% to identify itself with a client certificate using the 136% peer_cert(true) option. If a certificate is provided, it is 137% necessary to also provide a matching _private key_ via the 138% key_file/1 option. To configure multiple certificates, use the 139% option certificate_key_pairs/1 instead. Alternatively, use 140% ssl_add_certificate_key/4 to add certificates and keys to an 141% existing context. 142% * key_file(+FileName) 143% Specify where the private key that matches the certificate can 144% be found. If the key is encrypted with a password, this must 145% be supplied using the password(+Text) or 146% =|pem_password_hook(:Goal)|= option. 147% * certificate_key_pairs(+Pairs) 148% Alternative method for specifying certificates and keys. The 149% argument is a list of _pairs_ of the form Certificate-Key, 150% where each component is a string or an atom that holds, 151% respectively, the PEM-encoded certificate and key. To each 152% certificate, further certificates of the chain can be 153% appended. Multiple types of certificates can be present at 154% the same time to enable different ciphers. Using multiple 155% certificate types with completely independent certificate 156% chains requires OpenSSL 1.0.2 or greater. 157% * password(+Text) 158% Specify the password the private key is protected with (if 159% any). If you do not want to store the password you can also 160% specify an application defined handler to return the password 161% (see next option). Text is either an atom or string. Using 162% a string is preferred as strings are volatile and local 163% resources. 164% * pem_password_hook(:Goal) 165% In case a password is required to access the private key the 166% supplied predicate will be called to fetch it. The hook is 167% called as call(Goal, +SSL, -Password) and typically unifies 168% `Password` with a _string_ containing the password. 169% * require_crl(+Boolean) 170% If true (default is false), then all certificates will be 171% considered invalid unless they can be verified as not being 172% revoked. You can do this explicity by passing a list of CRL 173% filenames via the crl/1 option, or by doing it yourself in 174% the cert_verify_hook. If you specify require_crl(true) and 175% provide neither of these options, verification will necessarily 176% fail 177% * crl(+ListOfFileNames) 178% Provide a list of filenames of PEM-encoded CRLs that will be 179% given to the context to attempt to establish that a chain of 180% certificates is not revoked. You must also set require_crl(true) 181% if you want CRLs to actually be checked by OpenSSL. 182% * cacert_file(+FileName) 183% Specify a file containing certificate keys of _trusted_ 184% certificates. The peer is trusted if its certificate is 185% signed (ultimately) by one of the provided certificates. Using 186% the FileName `system(root_certificates)` uses a list of 187% trusted root certificates as provided by the OS. See 188% system_root_certificates/1 for details. 189% 190% Additional verification of the peer certificate as well as 191% accepting certificates that are not trusted by the given set 192% can be realised using the hook 193% cert_verify_hook(:Goal). 194% * cert_verify_hook(:Goal) 195% The predicate ssl_negotiate/5 calls Goal as follows: 196% 197% == 198% call(Goal, +SSL, 199% +ProblemCertificate, +AllCertificates, +FirstCertificate, 200% +Error) 201% == 202% 203% In case the certificate was verified by one of the provided 204% certifications from the `cacert_file` option, Error is unified 205% with the atom `verified`. Otherwise it contains the error 206% string passed from OpenSSL. Access will be granted iff the 207% predicate succeeds. See load_certificate/2 for a description 208% of the certificate terms. See cert_accept_any/5 for a dummy 209% implementation that accepts any certificate. 210% * cipher_list(+Atom) 211% Specify a cipher preference list (one or more cipher strings 212% separated by colons, commas or spaces). See ssl_secure_ciphers/1. 213% * ecdh_curve(+Atom) 214% Specify a curve for ECDHE ciphers. If this option is not 215% specified, the OpenSSL default parameters are used. With 216% OpenSSL prior to 1.1.0, `prime256v1` is used by default. 217% * peer_cert(+Boolean) 218% Trigger the request of our peer's certificate while 219% establishing the SSL layer. This option is automatically 220% turned on in a client SSL socket. It can be used in a server 221% to ask the client to identify itself using an SSL certificate. 222% * close_parent(+Boolean) 223% If `true`, close the raw streams if the SSL streams are closed. 224% Default is `false`. 225% * close_notify(+Boolean) 226% If `true` (default is `false`), the server sends TLS 227% `close_notify` when closing the connection. In addition, 228% this mitigates _truncation attacks_ for both client and 229% server role: If EOF is encountered without having received a 230% TLS shutdown, an exception is raised. Well-designed 231% protocols are self-terminating, and this attack is therefore 232% very rarely a concern. 233% * min_protocol_version(+Atom) 234% Set the _minimum_ protocol version that can be negotiated. 235% Atom is one of `sslv3`, `tlsv1`, `tlsv1_1`, `tlsv1_2` and 236% `tlsv1_3`. This option is available with OpenSSL 1.1.0 and 237% later, and should be used instead of `disable_ssl_methods/1`. 238% * max_protocol_version(+Atom) 239% Set the _maximum_ protocol version that can be negotiated. 240% Atom is one of `sslv3`, `tlsv1`, `tlsv1_1`, `tlsv1_2` and 241% `tlsv1_3`. This option is available with OpenSSL 1.1.0 and 242% later, and should be used instead of `disable_ssl_methods/1`. 243% * disable_ssl_methods(+List) 244% A list of methods to disable. Unsupported methods will be 245% ignored. Methods include `sslv2`, `sslv3`, `sslv23`, 246% `tlsv1`, `tlsv1_1` and `tlsv1_2`. This option is deprecated 247% starting with OpenSSL 1.1.0. Use min_protocol_version/1 and 248% max_protocol_version/1 instead. 249% * ssl_method(+Method) 250% Specify the explicit Method to use when negotiating. For 251% allowed values, see the list for `disable_ssl_methods` above. 252% Using this option is discouraged. When using OpenSSL 1.1.0 253% or later, this option is ignored, and a version-flexible method 254% is used to negotiate the connection. Using version-specific 255% methods is deprecated in recent OpenSSL versions, and this 256% option will become obsolete and ignored in the future. 257% * sni_hook(:Goal) 258% This option provides Server Name Indication (SNI) for SSL 259% servers. This means that depending on the host to which a 260% client connects, different options (certificates etc.) can 261% be used for the server. This TLS extension allows you to host 262% different domains using the same IP address and physical 263% machine. When a TLS connection is negotiated with a client 264% that has provided a host name via SNI, the hook is called as 265% follows: 266% 267% == 268% call(Goal, +SSL0, +HostName, -SSL) 269% == 270% 271% Given the current context SSL0, and the host name of the 272% client request, the predicate computes SSL which is used as 273% the context for negotiating the connection. The first solution 274% is used. If the predicate fails, the default options are 275% used, which are those of the encompassing ssl_context/3 276% call. In that case, if no default certificate and key are 277% specified, the client connection is rejected. 278% * alpn_protocols(+ListOfProtoIdentifiers) 279% Provide a list of acceptable ALPN protocol identifiers as atoms. 280% ALPN support requires OpenSSL 1.0.2 or greater. 281% * alpn_protocol_hook(:Goal) 282% This options provides a callback for a server context to use to 283% select an ALPN protocol. It will be called as follows: 284% 285% === 286% call(Goal, +SSLCtx0, +ListOfClientProtocols, -SSLCtx1, -SelectedProtocol) 287% === 288% 289% If this option is unset and the `alpn_protocols/1` option is 290% set, then the first common protocol between client & server will 291% be selected. 292% 293% @arg Role is one of `server` or `client` and denotes whether the 294% SSL instance will have a server or client role in the 295% established connection. 296% @arg SSL is a SWI-Prolog _blob_ of type `ssl_context`, i.e., the 297% type-test for an SSL context is `blob(SSL, ssl_context)`. 298 299ssl_context(Role, SSL, Module:Options) :- 300 select_option(ssl_method(Method), Options, O1, sslv23), 301 '_ssl_context'(Role, SSL, Module:O1, Method). 302 303%! ssl_add_certificate_key(+SSL0, +Certificate, +Key, -SSL) 304% 305% Add an additional certificate/key pair to SSL0, yielding SSL. 306% Certificate and Key are either strings or atoms that hold the 307% PEM-encoded certificate plus certificate chain and private key, 308% respectively. Using strings is preferred for security reasons. 309% 310% This predicate allows dual-stack RSA and ECDSA servers (for 311% example), and is an alternative for using the 312% `certificate_key_pairs/1` option. As of OpenSSL 1.0.2, multiple 313% certificate types with completely independent certificate chains 314% are supported. If a certificate of the same type is added 315% repeatedly to a context, the result is undefined. Currently, up to 316% 12 additional certificates of different types are admissible. 317 318ssl_add_certificate_key(SSL0, Cert, Key, SSL) :- 319 ssl_copy_context(SSL0, SSL), 320 '_ssl_add_certificate_key'(SSL, Cert, Key). 321 322ssl_copy_context(SSL0, SSL) :- 323 ssl_context(server, SSL, []), 324 '_ssl_init_from_context'(SSL0, SSL). 325 326%! ssl_set_options(+SSL0, -SSL, +Options) 327% 328% SSL is the same as SSL0, except for the options specified in 329% Options. The following options are supported: close_notify/1, 330% close_parent/1, host/1, peer_cert/1, ecdh_curve/1, 331% min_protocol_version/1, max_protocol_version/1, 332% disable_ssl_methods/1, sni_hook/1, cert_verify_hook/1, 333% alpn_protocols/1, and alpn_protocol_hook/1. See ssl_context/3 for 334% more information about these options. This predicate allows you to 335% tweak existing SSL contexts, which can be useful in hooks when 336% creating servers with the HTTP infrastructure. 337 338ssl_set_options(SSL0, SSL, Options) :- 339 ssl_copy_context(SSL0, SSL), 340 '_ssl_set_options'(SSL, Options). 341 342%! ssl_negotiate(+SSL, 343%! +PlainRead, +PlainWrite, 344%! -SSLRead, -SSLWrite) is det. 345% 346% Once a connection is established and a read/write stream pair is 347% available, (PlainRead and PlainWrite), this predicate can be 348% called to negotiate an SSL session over the streams. If the 349% negotiation is successful, SSLRead and SSLWrite are returned. 350% 351% After a successful handshake and finishing the communication the 352% user must close SSLRead and SSLWrite, for example using 353% call_cleanup(close(SSLWrite), close(SSLRead)). If the SSL 354% _context_ (created with ssl_context/3 has the option 355% close_parent(true) (default `false`), closing SSLRead and 356% SSLWrite also closes the original PlainRead and PlainWrite 357% streams. Otherwise these must be closed explicitly by the user. 358% 359% @error ssl_error(Code, LibName, FuncName, Reason) is raised 360% if the negotiation fails. The streams PlainRead and PlainWrite 361% are *not* closed, but an unknown amount of data may have been 362% read and written. 363 364%! ssl_peer_certificate(+Stream, -Certificate) is semidet. 365% 366% True if the peer certificate is provided (this is always the 367% case for a client connection) and Certificate unifies with the 368% peer certificate. The example below uses this to obtain the 369% _Common Name_ of the peer after establishing an https client 370% connection: 371% 372% == 373% http_open(HTTPS_url, In, []), 374% ssl_peer_certificate(In, Cert), 375% memberchk(subject(Subject), Cert), 376% memberchk('CN' = CommonName), Subject) 377% == 378 379%! ssl_peer_certificate_chain(+Stream, -Certificates) is det. 380% 381% Certificates is the certificate chain provided by the peer, 382% represented as a list of certificates. 383 384%! ssl_session(+Stream, -Session) is det. 385% 386% Retrieves (debugging) properties from the SSL context associated 387% with Stream. If Stream is not an SSL stream, the predicate 388% raises a domain error. Session is a list of properties, 389% containing the members described below. Except for `Version`, 390% all information are byte arrays that are represented as Prolog 391% strings holding characters in the range 0..255. 392% 393% * ssl_version(Version) 394% The negotiated version of the session as an integer. 395% * cipher(Cipher) 396% The negotiated cipher for this connection. 397% * session_key(Key) 398% The key material used in SSLv2 connections (if present). 399% * master_key(Key) 400% The key material comprising the master secret. This is 401% generated from the server_random, client_random and pre-master 402% key. 403% * client_random(Random) 404% The random data selected by the client during handshaking. 405% * server_random(Random) 406% The random data selected by the server during handshaking. 407% * session_id(SessionId) 408% The SSLv3 session ID. Note that if ECDHE is being used (which 409% is the default for newer versions of OpenSSL), this data will 410% not actually be sent to the server. 411% * alpn_protocol(Protocol) 412% The negotiated ALPN protocol, if supported. If no protocol was 413% negotiated, this will be an empty string. 414 415%! load_certificate(+Stream, -Certificate) is det. 416% 417% Loads a certificate from a PEM- or DER-encoded stream, returning 418% a term which will unify with the same certificate if presented 419% in cert_verify_hook. A certificate is a list containing the 420% following terms: issuer_name/1, hash/1, signature/1, 421% signature_algorithm/1, version/1, notbefore/1, notafter/1, 422% serial/1, subject/1 and key/1. subject/1 and issuer_name/1 are 423% both lists of =/2 terms representing the name. With OpenSSL 424% 1.0.2 and greater, to_be_signed/1 is also available, yielding 425% the hexadecimal representation of the TBS (to-be-signed) portion 426% of the certificate. 427% 428% Note that the OpenSSL `CA.pl` utility creates certificates that 429% have a human readable textual representation in front of the PEM 430% representation. You can use the following to skip to the 431% certificate if you know it is a PEM certificate: 432% 433% == 434% skip_to_pem_cert(In) :- 435% repeat, 436% ( peek_char(In, '-') 437% -> ! 438% ; skip(In, 0'\n), 439% at_end_of_stream(In), ! 440% ). 441% == 442 443%! load_crl(+Stream, -CRL) is det. 444% 445% Loads a CRL from a PEM- or DER-encoded stream, returning a term 446% containing terms hash/1, signature/1, issuer_name/1 and 447% revocations/1, which is a list of revoked/2 terms. Each 448% revoked/2 term is of the form revoked(+Serial, DateOfRevocation) 449 450%! system_root_certificates(-List) is det. 451% 452% List is a list of trusted root certificates as provided by the 453% OS. This is the list used by ssl_context/3 when using the option 454% `system(root_certificates)`. The list is obtained using an OS 455% specific process. The current implementation is as follows: 456% 457% - On Windows, CertOpenSystemStore() is used to import 458% the `"ROOT"` certificates from the OS. 459% - On MacOSX, the trusted keys are loaded from the 460% _SystemRootCertificates_ key chain. The Apple API 461% for this requires the SSL interface to be compiled 462% with an XCode compiler, i.e., *not* with native gcc. 463% - Otherwise, certificates are loaded from a file defined 464% by the Prolog flag `system_cacert_filename`. The initial 465% value of this flag is operating system dependent. For 466% security reasons, the flag can only be set prior to using 467% the SSL library. For example: 468% 469% == 470% :- use_module(library(ssl)). 471% :- set_prolog_flag(system_cacert_filename, 472% '/home/jan/ssl/ca-bundle.crt'). 473% == 474 475%! load_private_key(+Stream, +Password, -PrivateKey) is det. 476% 477% Load a private key PrivateKey from the given stream Stream, 478% using Password to decrypt the key if it is encrypted. Note that 479% the password is currently only supported for PEM files. 480% DER-encoded keys which are password protected will not load. The 481% key must be an RSA or EC key. DH and DSA keys are not supported, 482% and PrivateKey will be bound to an atom (dh_key or dsa_key) if 483% you try and load such a key. Otherwise PrivateKey will be 484% unified with private_key(KeyTerm) where KeyTerm is an rsa/8 term 485% representing an RSA key, or ec/3 for EC keys. 486 487%! load_public_key(+Stream, -PublicKey) is det. 488% 489% Load a public key PublicKey from the given stream Stream. 490% Supports loading both DER- and PEM-encoded keys. The key must be 491% an RSA or EC key. DH and DSA keys are not supported, and 492% PublicKey will be bound to an atom (dh_key or dsa_key) if you 493% try and load such a key. Otherwise PublicKey will be unified 494% with public_key(KeyTerm) where KeyTerm is an rsa/8 term 495% representing an RSA key, or ec/3 for EC keys. 496 497 498%! cert_accept_any(+SSL, 499%! +ProblemCertificate, +AllCertificates, +FirstCertificate, 500%! +Error) is det. 501% 502% Implementation for the hook `cert_verify_hook(:Hook)` that 503% accepts _any_ certificate. This is intended for http_open/3 if 504% no certificate verification is desired as illustrated below. 505% 506% == 507% http_open('https:/...', In, 508% [ cert_verify_hook(cert_accept_any) 509% ]) 510% == 511 512cert_accept_any(_SSL, 513 _ProblemCertificate, _AllCertificates, _FirstCertificate, 514 _Error). 515 516%! ssl_secure_ciphers(-Ciphers:atom) is det. 517% 518% Ciphers is a secure cipher preference list that can be used in the 519% cipher_list/1 option of ssl_context/3. 520% 521% Secure ciphers must guarantee forward secrecy, and must mitigate all 522% known critical attacks. As of 2018, using these ciphers allows you 523% to obtain grade A on https://www.ssllabs.com. For A+, you must also 524% enable HTTP Strict Transport Security (HSTS) by sending a suitable 525% header field in replies. 526% 527% Note that obsolete ciphers *must* be disabled to reliably prevent 528% protocol downgrade attacks. 529% 530% The Ciphers list is read from the setting `ssl:secure_ciphers` and 531% can be controlled using set_setting/2 and other predicates from 532% library(settings). 533% 534% *BEWARE*: This list must be changed when attacks on these ciphers 535% become known! Keep an eye on this setting and adapt it 536% as necessary in the future. 537 538ssl_secure_ciphers(Cs) :- 539 setting(secure_ciphers, Cs). 540 541 542 /******************************* 543 * MESSAGES * 544 *******************************/ 545 546:- multifile 547 prolog:error_message//1. 548 549prologerror_message(ssl_error(ID, _Library, Function, Reason)) --> 550 [ 'SSL(~w) ~w: ~w'-[ID, Function, Reason] ]