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_sni_hook/3, % +Config, +Goal, -Config 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 ]). 54:- use_module(library(socket)). 55:- use_module(library(error)). 56:- use_module(library(option)). 57:- use_module(library(debug)). 58:- use_module(library(crypto), []). % force initialization of libcrypto 59 60:- use_foreign_library(foreign(ssl4pl)). 61 62:- meta_predicate 63 ssl_context(, , ), 64 ssl_set_sni_hook(, , ). 65 66:- predicate_options(ssl_context/3, 3, 67 [ host(atom), 68 port(integer), 69 certificate_file(atom), 70 key_file(atom), 71 certificate_key_pairs(any), 72 password(any), 73 cipher_list(any), 74 ecdh_curve(any), 75 pem_password_hook(callable), 76 cacert_file(any), 77 crl(any), 78 require_crl(boolean), 79 cert_verify_hook(callable), 80 peer_cert(boolean), 81 close_parent(boolean), 82 close_notify(boolean), 83 sni_hook(callable) 84 ]). 85 86/** <module> Secure Socket Layer (SSL) library 87 88An SSL server and client can be built with the (abstracted) 89predicate calls from the table below. The `tcp_` predicates 90are provided by library(socket). The predicate ssl_context/3 91defines properties of the SSL connection, while ssl_negotiate/5 92establishes the SSL connection based on the wire streams created 93by the TCP predicates and the context. 94 95 | *The SSL Server* | *The SSL Client* | 96 | ssl_context/3 | ssl_context/3 | 97 | tcp_socket/1 | | 98 | tcp_accept/3 | tcp_connect/3 | 99 | tcp_open_socket/3 | stream_pair/3 | 100 | ssl_negotiate/5 | ssl_negotiate/5 | 101 102The library is abstracted to communication over streams, and is not 103reliant on those streams being directly attached to sockets. The `tcp_` 104calls here are simply the most common way to use the library. Other 105two-way communication channels such as (named), pipes can just as 106easily be used. 107 108@see library(socket), library(http/http_open), library(crypto) 109*/ 110 111%! ssl_context(+Role, -SSL, :Options) is det. 112% 113% Create an SSL context. The context defines several properties 114% of the SSL connection such as involved keys, preferred 115% encryption, and passwords. After establishing a context, an SSL 116% connection can be negotiated using ssl_negotiate/5, turning two 117% arbitrary plain Prolog streams into encrypted streams. This 118% predicate processes the options below. 119% 120% * host(+HostName) 121% For the client, the host to which it connects. This option 122% _should_ be specified when Role is `client`. Otherwise, 123% certificate verification may fail when negotiating a 124% secure connection. 125% * certificate_file(+FileName) 126% Specify where the certificate file can be found. This can be the 127% same as the key_file(+FileName) option. A server _must_ have at 128% least one certificate before clients can connect. A client 129% _must_ have a certificate only if the server demands the client 130% to identify itself with a client certificate using the 131% peer_cert(true) option. If a certificate is provided, it is 132% necessary to also provide a matching _private key_ via the 133% key_file/1 option. To configure multiple certificates, use the 134% option certificate_key_pairs/1 instead. Alternatively, use 135% ssl_add_certificate_key/4 to add certificates and keys to an 136% existing context. 137% * key_file(+FileName) 138% Specify where the private key that matches the certificate can 139% be found. If the key is encrypted with a password, this must 140% be supplied using the password(+Text) or 141% =|pem_password_hook(:Goal)|= option. 142% * certificate_key_pairs(+Pairs) 143% Alternative method for specifying certificates and keys. The 144% argument is a list of _pairs_ of the form Certificate-Key, 145% where each component is a string or an atom that holds, 146% respectively, the PEM-encoded certificate and key. To each 147% certificate, further certificates of the chain can be 148% appended. Multiple types of certificates can be present at 149% the same time to enable different ciphers. Using multiple 150% certificate types with completely independent certificate 151% chains requires OpenSSL 1.0.2 or greater. 152% * password(+Text) 153% Specify the password the private key is protected with (if 154% any). If you do not want to store the password you can also 155% specify an application defined handler to return the password 156% (see next option). Text is either an atom or string. Using 157% a string is preferred as strings are volatile and local 158% resources. 159% * pem_password_hook(:Goal) 160% In case a password is required to access the private key the 161% supplied predicate will be called to fetch it. The hook is 162% called as call(Goal, +SSL, -Password) and typically unifies 163% `Password` with a _string_ containing the password. 164% * require_crl(+Boolean) 165% If true (default is false), then all certificates will be 166% considered invalid unless they can be verified as not being 167% revoked. You can do this explicity by passing a list of CRL 168% filenames via the crl/1 option, or by doing it yourself in 169% the cert_verify_hook. If you specify require_crl(true) and 170% provide neither of these options, verification will necessarily 171% fail 172% * crl(+ListOfFileNames) 173% Provide a list of filenames of PEM-encoded CRLs that will be 174% given to the context to attempt to establish that a chain of 175% certificates is not revoked. You must also set require_crl(true) 176% if you want CRLs to actually be checked by OpenSSL. 177% * cacert_file(+FileName) 178% Specify a file containing certificate keys of _trusted_ 179% certificates. The peer is trusted if its certificate is 180% signed (ultimately) by one of the provided certificates. Using 181% the FileName `system(root_certificates)` uses a list of 182% trusted root certificates as provided by the OS. See 183% system_root_certificates/1 for details. 184% 185% Additional verification of the peer certificate as well as 186% accepting certificates that are not trusted by the given set 187% can be realised using the hook 188% cert_verify_hook(:Goal). 189% * cert_verify_hook(:Goal) 190% The predicate ssl_negotiate/5 calls Goal as follows: 191% 192% == 193% call(Goal, +SSL, 194% +ProblemCertificate, +AllCertificates, +FirstCertificate, 195% +Error) 196% == 197% 198% In case the certificate was verified by one of the provided 199% certifications from the `cacert_file` option, Error is unified 200% with the atom `verified`. Otherwise it contains the error 201% string passed from OpenSSL. Access will be granted iff the 202% predicate succeeds. See load_certificate/2 for a description 203% of the certificate terms. See cert_accept_any/5 for a dummy 204% implementation that accepts any certificate. 205% * cipher_list(+Atom) 206% Specify a cipher preference list (one or more cipher strings 207% separated by colons, commas or spaces). 208% * ecdh_curve(+Atom) 209% Specify a curve for ECDHE ciphers. If this option is not 210% specified, the OpenSSL default parameters are used. With 211% OpenSSL prior to 1.1.0, `prime256v1` is used by default. 212% * peer_cert(+Boolean) 213% Trigger the request of our peer's certificate while 214% establishing the SSL layer. This option is automatically 215% turned on in a client SSL socket. It can be used in a server 216% to ask the client to identify itself using an SSL certificate. 217% * close_parent(+Boolean) 218% If `true`, close the raw streams if the SSL streams are closed. 219% Default is `false`. 220% * close_notify(+Boolean) 221% If `true` (default is `false`), the server sends TLS 222% `close_notify` when closing the connection. In addition, 223% this mitigates _truncation attacks_ for both client and 224% server role: If EOF is encountered without having received a 225% TLS shutdown, an exception is raised. Well-designed 226% protocols are self-terminating, and this attack is therefore 227% very rarely a concern. 228% * min_protocol_version(+Atom) 229% Set the _minimum_ protocol version that can be negotiated. 230% Atom is one of `sslv3`, `tlsv1`, `tlsv1_1` and `tlsv1_2`. 231% This option is available with OpenSSL 1.1.0 and later, and 232% should be used instead of `disable_ssl_methods/1`. 233% * max_protocol_version(+Atom) 234% Set the _maximum_ protocol version that can be negotiated. 235% Atom is one of `sslv3`, `tlsv1`, `tlsv1_1` and `tlsv1_2`. 236% This option is available with OpenSSL 1.1.0 and later, and 237% should be used instead of `disable_ssl_methods/1`. 238% * disable_ssl_methods(+List) 239% A list of methods to disable. Unsupported methods will be 240% ignored. Methods include `sslv2`, `sslv3`, `sslv23`, 241% `tlsv1`, `tlsv1_1` and `tlsv1_2`. This option is deprecated 242% starting with OpenSSL 1.1.0. Use min_protocol_version/1 and 243% max_protocol_version/1 instead. 244% * ssl_method(+Method) 245% Specify the explicit Method to use when negotiating. For 246% allowed values, see the list for `disable_ssl_methods` above. 247% Using this option is discouraged. When using OpenSSL 1.1.0 248% or later, this option is ignored, and a version-flexible method 249% is used to negotiate the connection. Using version-specific 250% methods is deprecated in recent OpenSSL versions, and this 251% option will become obsolete and ignored in the future. 252% * sni_hook(:Goal) 253% This option provides Server Name Indication (SNI) for SSL 254% servers. This means that depending on the host to which a 255% client connects, different options (certificates etc.) can 256% be used for the server. This TLS extension allows you to host 257% different domains using the same IP address and physical 258% machine. When a TLS connection is negotiated with a client 259% that has provided a host name via SNI, the hook is called as 260% follows: 261% 262% == 263% call(Goal, +SSL0, +HostName, -SSL) 264% == 265% 266% Given the current context SSL0, and the host name of the 267% client request, the predicate computes SSL which is used as 268% the context for negotiating the connection. The first solution 269% is used. If the predicate fails, the default options are 270% used, which are those of the encompassing ssl_context/3 271% call. In that case, if no default certificate and key are 272% specified, the client connection is rejected. 273% 274% @arg Role is one of `server` or `client` and denotes whether the 275% SSL instance will have a server or client role in the 276% established connection. 277% @arg SSL is a SWI-Prolog _blob_ of type `ssl_context`, i.e., the 278% type-test for an SSL context is `blob(SSL, ssl_context)`. 279 280ssl_context(Role, SSL, Module:Options) :- 281 select_option(ssl_method(Method), Options, O1, sslv23), 282 '_ssl_context'(Role, SSL, Module:O1, Method). 283 284%! ssl_add_certificate_key(+SSL0, +Certificate, +Key, -SSL) 285% 286% Add an additional certificate/key pair to SSL0, yielding SSL. 287% Certificate and Key are either strings or atoms that hold the 288% PEM-encoded certificate plus certificate chain and private key, 289% respectively. Using strings is preferred for security reasons. 290% 291% This predicate allows dual-stack RSA and ECDSA servers (for 292% example), and is an alternative for using the 293% `certificate_key_pairs/1` option. As of OpenSSL 1.0.2, multiple 294% certificate types with completely independent certificate chains 295% are supported. If a certificate of the same type is added 296% repeatedly to a context, the result is undefined. Currently, up to 297% 12 additional certificates of different types are admissible. 298 299ssl_add_certificate_key(SSL0, Cert, Key, SSL) :- 300 ssl_copy_context(SSL0, SSL), 301 '_ssl_add_certificate_key'(SSL, Cert, Key). 302 303ssl_copy_context(SSL0, SSL) :- 304 ssl_context(server, SSL, []), 305 '_ssl_init_from_context'(SSL0, SSL). 306 307%! ssl_set_sni_hook(+SSL0, :Goal, -SSL) 308% 309% SSL is the same as SSL0, except that the SNI hook of SSL is Goal. 310% See the sni_hook(:Goal) option of ssl_context/3 for more 311% information about this hook. 312 313ssl_set_sni_hook(SSL0, Goal, SSL) :- 314 ssl_copy_context(SSL0, SSL), 315 '_ssl_set_sni_hook'(SSL, Goal). 316 317%! ssl_negotiate(+SSL, 318%! +PlainRead, +PlainWrite, 319%! -SSLRead, -SSLWrite) is det. 320% 321% Once a connection is established and a read/write stream pair is 322% available, (PlainRead and PlainWrite), this predicate can be 323% called to negotiate an SSL session over the streams. If the 324% negotiation is successful, SSLRead and SSLWrite are returned. 325% 326% After a successful handshake and finishing the communication the 327% user must close SSLRead and SSLWrite, for example using 328% call_cleanup(close(SSLWrite), close(SSLRead)). If the SSL 329% _context_ (created with ssl_context/3 has the option 330% close_parent(true) (default `false`), closing SSLRead and 331% SSLWrite also closes the original PlainRead and PlainWrite 332% streams. Otherwise these must be closed explicitly by the user. 333% 334% @error ssl_error(Code, LibName, FuncName, Reason) is raised 335% if the negotiation fails. The streams PlainRead and PlainWrite 336% are *not* closed, but an unknown amount of data may have been 337% read and written. 338 339%! ssl_peer_certificate(+Stream, -Certificate) is semidet. 340% 341% True if the peer certificate is provided (this is always the 342% case for a client connection) and Certificate unifies with the 343% peer certificate. The example below uses this to obtain the 344% _Common Name_ of the peer after establishing an https client 345% connection: 346% 347% == 348% http_open(HTTPS_url, In, []), 349% ssl_peer_certificate(In, Cert), 350% memberchk(subject(Subject), Cert), 351% memberchk('CN' = CommonName), Subject) 352% == 353 354%! ssl_peer_certificate_chain(+Stream, -Certificates) is det. 355% 356% Certificates is the certificate chain provided by the peer, 357% represented as a list of certificates. 358 359%! ssl_session(+Stream, -Session) is det. 360% 361% Retrieves (debugging) properties from the SSL context associated 362% with Stream. If Stream is not an SSL stream, the predicate 363% raises a domain error. Session is a list of properties, 364% containing the members described below. Except for `Version`, 365% all information are byte arrays that are represented as Prolog 366% strings holding characters in the range 0..255. 367% 368% * ssl_version(Version) 369% The negotiated version of the session as an integer. 370% * cipher(Cipher) 371% The negotiated cipher for this connection. 372% * session_key(Key) 373% The key material used in SSLv2 connections (if present). 374% * master_key(Key) 375% The key material comprising the master secret. This is 376% generated from the server_random, client_random and pre-master 377% key. 378% * client_random(Random) 379% The random data selected by the client during handshaking. 380% * server_random(Random) 381% The random data selected by the server during handshaking. 382% * session_id(SessionId) 383% The SSLv3 session ID. Note that if ECDHE is being used (which 384% is the default for newer versions of OpenSSL), this data will 385% not actually be sent to the server. 386 387%! load_certificate(+Stream, -Certificate) is det. 388% 389% Loads a certificate from a PEM- or DER-encoded stream, returning 390% a term which will unify with the same certificate if presented 391% in cert_verify_hook. A certificate is a list containing the 392% following terms: issuer_name/1, hash/1, signature/1, 393% signature_algorithm/1, version/1, notbefore/1, notafter/1, 394% serial/1, subject/1 and key/1. subject/1 and issuer_name/1 are 395% both lists of =/2 terms representing the name. With OpenSSL 396% 1.0.2 and greater, to_be_signed/1 is also available, yielding 397% the hexadecimal representation of the TBS (to-be-signed) portion 398% of the certificate. 399% 400% Note that the OpenSSL `CA.pl` utility creates certificates that 401% have a human readable textual representation in front of the PEM 402% representation. You can use the following to skip to the 403% certificate if you know it is a PEM certificate: 404% 405% == 406% skip_to_pem_cert(In) :- 407% repeat, 408% ( peek_char(In, '-') 409% -> ! 410% ; skip(In, 0'\n), 411% at_end_of_stream(In), ! 412% ). 413% == 414 415%! load_crl(+Stream, -CRL) is det. 416% 417% Loads a CRL from a PEM- or DER-encoded stream, returning a term 418% containing terms hash/1, signature/1, issuer_name/1 and 419% revocations/1, which is a list of revoked/2 terms. Each 420% revoked/2 term is of the form revoked(+Serial, DateOfRevocation) 421 422%! system_root_certificates(-List) is det. 423% 424% List is a list of trusted root certificates as provided by the 425% OS. This is the list used by ssl_context/3 when using the option 426% `system(root_certificates)`. The list is obtained using an OS 427% specific process. The current implementation is as follows: 428% 429% - On Windows, CertOpenSystemStore() is used to import 430% the `"ROOT"` certificates from the OS. 431% - On MacOSX, the trusted keys are loaded from the 432% _SystemRootCertificates_ key chain. The Apple API 433% for this requires the SSL interface to be compiled 434% with an XCode compiler, i.e., *not* with native gcc. 435% - Otherwise, certificates are loaded from a file defined 436% by the Prolog flag `system_cacert_filename`. The initial 437% value of this flag is operating system dependent. For 438% security reasons, the flag can only be set prior to using 439% the SSL library. For example: 440% 441% == 442% :- use_module(library(ssl)). 443% :- set_prolog_flag(system_cacert_filename, 444% '/home/jan/ssl/ca-bundle.crt'). 445% == 446 447%! load_private_key(+Stream, +Password, -PrivateKey) is det. 448% 449% Load a private key PrivateKey from the given stream Stream, 450% using Password to decrypt the key if it is encrypted. Note that 451% the password is currently only supported for PEM files. 452% DER-encoded keys which are password protected will not load. The 453% key must be an RSA or EC key. DH and DSA keys are not supported, 454% and PrivateKey will be bound to an atom (dh_key or dsa_key) if 455% you try and load such a key. Otherwise PrivateKey will be 456% unified with private_key(KeyTerm) where KeyTerm is an rsa/8 term 457% representing an RSA key, or ec/3 for EC keys. 458 459%! load_public_key(+Stream, -PublicKey) is det. 460% 461% Load a public key PublicKey from the given stream Stream. 462% Supports loading both DER- and PEM-encoded keys. The key must be 463% an RSA or EC key. DH and DSA keys are not supported, and 464% PublicKey will be bound to an atom (dh_key or dsa_key) if you 465% try and load such a key. Otherwise PublicKey will be unified 466% with public_key(KeyTerm) where KeyTerm is an rsa/8 term 467% representing an RSA key, or ec/3 for EC keys. 468 469 470%! cert_accept_any(+SSL, 471%! +ProblemCertificate, +AllCertificates, +FirstCertificate, 472%! +Error) is det. 473% 474% Implementation for the hook `cert_verify_hook(:Hook)` that 475% accepts _any_ certificate. This is intended for http_open/3 if 476% no certificate verification is desired as illustrated below. 477% 478% == 479% http_open('https:/...', In, 480% [ cert_verify_hook(cert_accept_any) 481% ]) 482% == 483 484cert_accept_any(_SSL, 485 _ProblemCertificate, _AllCertificates, _FirstCertificate, 486 _Error). 487 488 489 /******************************* 490 * MESSAGES * 491 *******************************/ 492 493:- multifile 494 prolog:error_message//1. 495 496prologerror_message(ssl_error(ID, _Library, Function, Reason)) --> 497 [ 'SSL(~w) ~w: ~w'-[ID, Function, Reason] ].