Wiki
Download
Manual
Eggs
API
Tests
Bugs
show
edit
history
You can edit this page using
wiki syntax
for markup.
Article contents:
== openssl === Description Bindings to the OpenSSL SSL/TLS library === Author [[http://www.chust.org/|Thomas Chust]] Currently maintained by Vasilij Schneidermann. === Repository This egg is hosted on the CHICKEN Subversion repository: [[https://anonymous@code.call-cc.org/svn/chicken-eggs/release/5/openssl|https://anonymous@code.call-cc.org/svn/chicken-eggs/release/5/openssl]] If you want to check out the source code repository of this egg and you are not familiar with Subversion, see [[/egg-svn-checkout|this page]]. === Requirements * OpenSSL C library (from 1.1.0 up to 3) * srfi-13, srfi-18 and address-info egg As of egg version 1.10.0, this egg will use the [[tcp6]] egg if it is installed, otherwise it will fall back to the standard {{tcp}} module. ==== OpenBSD 6.8 and 6.9 OpenBSD ships with a partially compatible OpenSSL fork known as LibreSSL which only supports the socket API. To install egg version 2.2.0 and newer, execute the following commands: pkg_add openssl export OPENSSL_CFLAGS=$(pkg-config --cflags eopenssl11) export OPENSSL_LDLIBS=$(pkg-config --libs eopenssl11) ldconfig -m /usr/local/lib/eopenssl11 chicken-install openssl The {{ldconfig}} invocation must be executed after every boot. This can be automated by editing {{/etc/rc.conf.local}} to contain {{shlib_dirs=/usr/local/lib/eopenssl11}}. ==== MacOS 10.14 ("Mojave") Like OpenBSD, it gives you LibreSSL. Homebrew can be used to alleviate that: brew install pkg-config openssl export PKG_CONFIG_PATH="$(brew --prefix openssl)/lib/pkgconfig" chicken-install openssl ==== CentOS 7 This distro only ships OpenSSL 1.0.2, so you're limited to the older versions of the egg before the minimum requirement was bumped to 1.1.0: chicken-install openssl:2.0.8 === Documentation This reference is based on the documentation of [[http://www.plt-scheme.org/|PLT Scheme's]] openssl module. The {{(openssl socket)}} API provided here is largely compatible with that one. The exceptions are the missing {{.../enable-break}} and {{ssl-available?}} procedures and the missing {{reuse?}} argument to {{ssl-listen}}. ==== (openssl socket) This API provides socket procedures to secure TCP connections. As of egg version 2.1.1 it can be used with {{(import (openssl socket))}}, with {{(import openssl)}} being the backwards-compatible alias. Please note that all the procedures described here may fail and raise a non-continuable exception of the composite type {{(exn i/o net openssl)}}. The {{openssl}} property condition contains a property called {{status}} which will be bound to a symbol corresponding to the OpenSSL error code that was encountered. It may have the following values: ; {{'zero-return}} : The SSL/TLS connection was shut down unexpectedly but in a controlled way ; {{'want-read}} : The operation didn't finish because data must be read from a nonblocking socket. This error condition only occurs though, when it could not be handled automatically because there is actually no socket involved or some other strange thing happended in the OpenSSL library. ; {{'want-write}} : The operation didn't finish because data must be read from a nonblocking socket. The same comment as for {{'want-read}} applies. ; {{'want-connect}} : The operation didn't finish because a nonblocking socket must first be connected. The same comment as for {{'want-read}} applies. ; {{'want-accept}} : The operation didn't finish because a nonblocking socket must first be acepted. The same comment as for {{'want-read}} applies. ; {{'want-X509-lookup}} : The operation failed because an application callback that could not even have been registered through this API was apparently registered anyway and has asked to be called again. ; {{'syscall}} : Some low-level I/O error occurred. ; {{'ssl-eof}} : Unexpected EOF, see the BUGS section in the [[https://www.openssl.org/docs/man1.1.1/man3/SSL_get_error.html|{{SSL_get_error}} man page]]. ; {{'ssl}} : Something went wrong in the OpenSSL library itself. ; {{#f}} : The error is not classified Of course the exception that is thrown also has an appropriate message set. If you feel that this documentation lacks some information, please also consider the [[http://www.openssl.org/docs/ssl/ssl.html|manual pages of OpenSSL itself]]. ===== Constants Supported SSL protocols for the {{ssl-connect}}, {{ssl-connect*}}, {{ssl-make-client-context}}, {{ssl-make-client-context*}}, {{ssl-listen}}, {{ssl-listen*}} and {{ssl-start*}} procedures. <constant>supported-ssl-protocols</constant> <constant>ssl-min-protocol</constant> <constant>ssl-max-protocol</constant> The ordered list of supported SSL protocols and the minimum and maximum supported SSL protocol. Supported as of egg version 2.2.0. ===== Parameters For read and write timeouts, {{tcp-read-timeout}} and {{tcp-write-timeout}} are honored (from [[tcp6]] if available, otherwise from {{tcp}}). <parameter>(ssl-handshake-timeout [TIMEOUT])</parameter> The time in milliseconds to wait for a SSL handshake to complete (after {{ssl-connect}} or {{ssl-accept}}). Defaults to 120000, i.e. two minutes. '''Note''': The handshake is only initiated after the first read or the first write action occurs on the connection, so the timer is started upon that first action. <parameter>(ssl-shutdown-timeout [TIMEOUT])</parameter> The time in milliseconds to wait for a SSL shutdown operation to complete (after closing a port). Defaults to 120000, i.e. two minutes. <parameter>(ssl-default-certificate-authorities [FILE])</parameter> <parameter>(ssl-default-certificate-authority-directory [DIRECTORY])</parameter> These parameters can be used to override the default file (for example, {{/etc/ssl/cert.pem}}) and directory (for example, {{/etc/ssl/certs}}) containing all trusted CA certificates. When not customized, the OpenSSL functions {{SSL_CTX_set_default_verify_paths}} and {{SSL_CTX_load_verify_locations}} are used to determine sensible default locations. ===== Client procedures <procedure>(ssl-connect (hostname <string>) #!optional (port <exact>) ((ctx <ssl-client-context-or-symbol-or-pair>) 'tls) (sni-name <string-or-bool>)) => <input-port>, <output-port></procedure> This procedure exists mainly for backwards compatibility. Consider using {{ssl-connect*}} instead, which uses better default settings. Connect to the given {{hostname}} on the given {{port}} (a number from 1 to 65535). This connection will be encrypted using SSL. The return values are as tcp-connect; an input port and an output port. The optional {{ctx}} argument determines which encryption protocol is used, whether the server's certificate is checked, etc. The argument can be either a client context created by {{ssl-make-client-context}} (see below), one of the following symbols: {{'sslv2-or-v3}}, {{'sslv3}}, {{'tls}} (the default), {{'tlsv1}}, {{'tlsv11}}, {{'tlsv12}} or {{'tlsv13}} or a pair of two such symbols. See {{ssl-make-client-context}} for further details, including the meanings of the protocol symbols. The optional {{sni-name}} argument determines whether a virtual hostname is sent with the connection handshake: If {{sni-name}} is a string, that value is sent as the virtual hostname. If {{sni-name}} is {{#t}} and the value of {{hostname}} does not look like a literal IPv4 or IPv6 address, it is sent as the virtual hostname. By default, no virtual hostname is sent. <procedure>(ssl-connect* #!key (hostname <string>) (port <exact>) ((sni-name <string-or-bool>) #t) ((protocol <symbol-or-pair>) 'tlsv12) ((cipher-list <any>) "DEFAULT") (certificate <string-or-blob>) (private-key <string-or-blob>) ((private-key-type <symbol>) 'rsa) (private-key-asn1? <bool>) (certificate-authorities <string>) (certificate-authority-directory <string>) ((verify? <bool>) #t)) => <input-port>, <output-port></procedure> Convenience constructor for SSL connections that uses keyword arguments to convey client context initialization information. Uses sensible defaults for the protocol configuration, enables certificate verification and sends a virtual hostname by default. The {{hostname}} and {{port}} arguments determine the network address to connect to. See {{ssl-make-client-context*}} for a description of the other keyword arguments. <procedure>(ssl-make-client-context #!optional ((protocol <symbol-or-pair>) 'tls)) => <ssl-client-context></procedure> This procedure exists mainly for backwards compatibility. Consider using {{ssl-make-client-context*}} instead, which uses better default settings. Creates a context to be supplied to {{ssl-connect}}. The context identifies a communication protocol (as selected by {{protocol}}), and also holds certificate information (i.e., the client's identity, its trusted certificate authorities, etc.). See the "Certificate procedures" section below for more information on certificates. The {{protocol}} must be either one of the following symbols or a pair of them: ; {{'sslv2-or-v3}} : TLS protocol or SSL protocol versions 2 or 3, as appropriate ; {{'sslv3}} : SSL protocol version 3 ; {{'tls}} or {{'tlsv1}} : the TLS protocol version 1 ; {{'tlsv11}} : the TLS protocol version 1.1 ; {{'tlsv12}} : the TLS protocol version 1.2 ; {{'tlsv13}} : the TLS protocol version 1.3 If a symbol is chosen, only that protocol version is supported, whereas a pair allows negotiation between a minimum and maximum protocol version. For example {{(tlsv1 . tlsv12)}} would allow TLS version 1, 1.1 and 1.2. The default protocol is {{'tls}}, which ensures maximum compatibility with other endpoints. Note, however, that this choice is not particularly secure. It is recommended to use TLSv1.2 instead. As of egg version 2.0.3, the use of the {{sslv2-or-v3}} and {{sslv3}} symbols raises an exception because the underlying library removed support for SSLv2 in OpenSSL 1.1.0. By default, the context returned by {{ssl-make-client-context}} does not request verification of a server's certificate. Use {{ssl-set-verify!}} to enable such verification. <procedure>(ssl-make-client-context* #!key ((protocol <symbol-or-pair>) 'tlsv12) ((cipher-list <any>) "DEFAULT") (certificate <string-or-blob>) (private-key <string-or-blob>) ((private-key-type <symbol>) 'rsa) (private-key-asn1? <bool>) (certificate-authorities <string>) (certificate-authority-directory <string>) ((verify? <bool>) #t)) => <ssl-client-context></procedure> Convenience constructor for client contexts that uses keyword arguments to convey initialization information. Uses sensible defaults for the protocol configuration and enables certificate verification. The {{protocol}} can be any of the choices available for {{ssl-make-client-context}}, but it defaults to the modern {{'tlsv12}}. You can customize the list of allowed cipher suites using the {{cipher-list}} argument, which is passed to {{ssl-set-cipher-list!}}. A client certificate and associated private key can be loaded using the {{certificate}} and {{private-key}} arguments, which may be strings representing file paths or blobs containing the data itself; see {{ssl-load-certificate-chain!}} and {{ssl-load-private-key!}} for details. The verification of server certificates may be enabled (the default) or disabled using {{verify?}}; the set of trusted CA certificates can be specified by {{certificate-authorities}} and {{certificate-authority-directory}}, which are passed to {{ssl-load-verify-root-certificates!}}. <procedure>(ssl-client-context? (obj <top>)) => <bool></procedure> Returns {{#t}} if {{obj}} is a value produced by {{ssl-make-client-context}} or {{ssl-make-client-context*}}, {{#f}} otherwise. ===== Server procedures <procedure>(ssl-listen (port <exact>) #!optional ((backlog <exact>) 4) ((hostname <string>) #f) ((ctx <ssl-client-context-or-symbol-or-pair>) 'tls)) => <ssl-listener></procedure> This procedure exists mainly for backwards compatibility. Consider using {{ssl-listen*}} instead, which uses better default settings. Like {{tcp-listen}}, but the result is an SSL listener. The extra optional {{ctx}} argument is as for {{ssl-connect}}. The default protocol is {{'tls}}, which ensures maximum compatibility with clients. Note, however, that this choice is not particularly secure. Vulnerabilities affecting only the legacy protocols can be avoided by explicitly requesting the {{'tlsv12}} protocol, if every client that will connect to the server is supporting this. Call {{ssl-load-certificate-chain!}} and {{ssl-load-private-key!}} to avoid a {{"no shared cipher"}} error on accepting connections. <procedure>(ssl-listen* #!key (hostname <string>) ((port <exact>) 0) ((backlog <exact>) 4) ((protocol <symbol-or-pair>) 'tlsv12) ((cipher-list <any>) "DEFAULT") (certificate <string-or-blob>) (private-key <string-or-blob>) ((private-key-type <symbol>) 'rsa) (private-key-asn1? <bool>) (certificate-authorities <string>) (certificate-authority-directory <string>) ((verify? <bool>) #f)) => <ssl-listener></procedure> Convenience constructor for an SSL listener that uses keyword arguments to convey initialization information. Uses sensible defaults for the protocol configuration. The {{hostname}} argument determines the local network interface to listen on and defaults to the wildcard address. The {{port}} arguments determine the local network port to listen to and defaults to a randomly selected port. The {{protocol}} can be any of the choices available for {{ssl-listen}}, but it defaults to the modern {{'tlsv12}}. You can customize the list of allowed cipher suites using the {{cipher-list}} argument, which is passed to {{ssl-set-cipher-list!}}. A server certificate and associated private key can be loaded using the {{certificate}} and {{private-key}} arguments, which may be strings representing file paths or blobs containing the data itself; see {{ssl-load-certificate-chain!}} and {{ssl-load-private-key!}} for details. The verification of client certificates may be enabled or disabled (the default) using {{verify?}}; the set of trusted CA certificates can be specified by {{certificate-authorities}} and {{certificate-authority-directory}}, which are passed to {{ssl-load-verify-root-certificates!}}. <procedure>(ssl-close (listener <ssl-listener>)) => <void></procedure><br> <procedure>(ssl-listener? (obj <top>)) => <bool></procedure><br> <procedure>(ssl-listener-port (listener <ssl-listener>)) => <exact></procedure><br> <procedure>(ssl-listener-fileno (listener <ssl-listener>)) => <exact></procedure><br> <procedure>(ssl-listener-accept-ready? (listener <ssl-listener>)) => <bool></procedure><br> <procedure>(ssl-accept (listener <ssl-listener>)) => <input-port>, <output-port></procedure> Analogous to {{tcp-close}}, {{tcp-listener?}}, {{tcp-listener-port}}, {{tcp-listener-fileno}}, {{tcp-accept-ready?}} and {{tcp-accept}}. ===== STARTTLS support <procedure>(ssl-start* (server? <bool>) (tcp-in <input-port>) (tcp-out <output-port>) #!key ((protocol <symbol-or-pair>) 'tlsv12) ((cipher-list <any>) "DEFAULT") (certificate <string-or-blob>) (private-key <string-or-blob>) ((private-key-type <symbol>) 'rsa) (private-key-asn1? <bool>) (certificate-authorities <string>) (certificate-authority-directory <string>) ((verify? <bool>) (not server?)) (sni-name <string>)) => <input-port>, <output-port></procedure> Given existing TCP input and output ports, {{ssl-start*}} establishes an SSL context working on top of the TCP connection. The returned ports should be used for all further communication with the remote peer. {{ssl-start*}} acts similar to {{ssl-connect*}} if {{server?}} is false or to {{ssl-accept}} if {{server?}} is true. The arguments all behave analogous to those for {{ssl-connect*}} or {{ssl-listen*}}. ===== Certificate procedures <procedure>(ssl-load-certificate-chain! (obj <ssl-client-context-or-ssl-listener>) (pathname/blob <string-or-blob>)) => <void></procedure> Loads a PEM-format certification chain file or data blob for connections to be made with the given context (created by {{ssl-make-context}}) or listener (created by {{ssl-listener}}). This chain is used to identify the client or server when it connects or accepts connections. Loading a chain overwrites the old chain. Also call {{ssl-load-private-key!}} to load the certificate's corresponding key. <procedure>(ssl-load-private-key! (obj <ssl-client-context-or-ssl-listener>) (pathname/blob <string-or-blob>) #!optional ((rsa? <symbol-or-bool>) #t) ((asn1? <bool>) #f)) => <void></procedure> Loads the first private key from the file or data blob {{pathname/blob}} for the given client context or listener. The key goes with the certificate that identifies the client or server. If {{rsa?}} is {{#t}} or {{'rsa}}, the first RSA key is read (i.e., non-RSA keys are skipped). If {{rsa?}} is {{#f}} or {{'dsa}}, a DSA key is read. If {{pathname/blob}} is a data blob, the key must be ASN1 encoded and {{rsa?}} may also take the values {{'dh}} or {{'ec}} to load Diffie-Hellman or Elliptic Curve keys respectively. If {{asn1?}} is {{#t}} and {{pathname/blob}} refers to a file, that file is parsed as ASN1 format instead of PEM. <procedure>(ssl-set-verify! (obj <ssl-client-context-or-ssl-listener>) (v <bool>)) => <void></procedure> Enables or disables verification of a connection peer's certificates. By default, verification is disabled. Enabling verification also requires, at a minimum, designating trusted certificate authorities with {{ssl-load-verify-root-certificates!}}. <procedure>(ssl-load-verify-root-certificates! (obj <ssl-client-context-or-ssl-listener>) (pathname <string>) #!optional ((dirname <string>) #f)) => <void></procedure> Loads a PEM-format file containing trusted certificates that are used to verify the certificates of a connection peer. Call this procedure multiple times to load multiple sets of trusted certificates. The optional second argument specifies a directory in which certificates are automatically looked up. You may also only pass a path in this argument and pass {{#f}} as the first argument to this procedure. See the OpenSSL documentation on [[http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html|SSL_CTX_load_verify_locations]] for more details. <procedure>(ssl-load-suggested-certificate-authorities! (obj <ssl-client-context-or-ssl-listener>) (pathname <string>)) => <void></procedure> Loads a PEM-format file containing certificates that are used by a server. The certificate list is sent to a client when the server requests a certificate as an indication of which certificates the server trusts. Loading the suggested certificates does not imply trust, however; any certificate presented by the client will be checked using the trusted roots loaded by {{ssl-load-verify-root-certificates!}}. ===== Cipher selection <procedure>(ssl-set-cipher-list! (obj <ssl-client-context-or-ssl-listener>) (v <any>)) => <void></procedure> Selects a list of allowed cipher suites that are used by an SSL client or server. The given value {{v}} may be a string such as {{"DEFAULT"}}; the format of strings accepted by the OpenSSL library is described in its ciphers(1) manual page. If you pass a list as {{v}}, its elements are joined by {{":"}} characters. Any other value for {{v}} and any list elements are converted to strings using {{->string}}. ===== Port procedures <procedure>(ssl-port? obj) => <boolean></procedure> Predicate for SSL ports; returns {{#t}} if {{obj}} is an SSL port, {{#f}} if it isn't. <procedure>(ssl-port->tcp-port p) => <tcp-port></procedure> Convert SSL port {{p}} to the raw underlying TCP port. This is mostly useful if you need to obtain extra information about the connection, like for example {{tcp-addresses}}. Note that you generally ''cannot'' safely send data over the port, as that would interfere with OpenSSL's operation. ===== Socket API example Launch [[/egg/spiffy|spiffy]] using TLSv1.2 and TLSv1.3 (if supported): <enscript highlight="scheme"> (import (openssl socket)) (import spiffy) (define port 8443) (define private-key "cert.key") (define public-key "cert.pem") (server-port port) (define listener (ssl-listen* port: port protocol: (cons 'tlsv12 ssl-max-protocol) certificate: public-key private-key: private-key)) (accept-loop listener ssl-accept) </enscript> Launch [[/egg/awful|awful]] using TLSv1.2 and TLSv1.3 (if supported): <enscript highlight="scheme"> (import awful) (import (openssl socket)) (import spiffy) (define private-key "cert.key") (define public-key "cert.pem") (define (enable-ssl certificate-file private-key-file) (awful-listen (lambda (port #!optional backlog hostname) (ssl-listen* port: port backlog: backlog hostname: hostname protocol: (cons 'tlsv12 ssl-max-protocol) certificate: certificate-file private-key: private-key-file))) (awful-accept ssl-accept)) (server-port 8443) (enable-ssl public-key private-key) (awful-start (lambda () (define-page (main-page-path) (lambda () "Hello, world!")))) </enscript> Make a [[/egg/http-client|http-client]] request using TLSv1.2 or TLSv1.3 (if supported): <enscript highlight="scheme"> (import (chicken io)) (import (chicken tcp)) (import (openssl socket)) (import http-client) (import uri-common) (define (http-server-connector uri proxy) (let ((remote-end (or proxy uri))) (case (uri-scheme remote-end) ((#f http) (tcp-connect (uri-host remote-end) (uri-port remote-end))) ((https) (ssl-connect* hostname: (uri-host remote-end) port: (uri-port remote-end) protocol: (cons 'tlsv12 ssl-max-protocol) sni-name: #t)) (else (error "Unsupported protocol" (uri-scheme remote-end)))))) (server-connector http-server-connector) ;; supports TLSv1.2 and v1.3 only (with-input-from-request "https://en.wikipedia.org/wiki/Cat" #f read-string) </enscript> ==== (openssl cipher) This API provides access to ciphers such as AES-256-GCM. As of egg version 2.2.0 it can be used with {{(import (openssl cipher))}}. ===== Cipher lookup <procedure>(cipher-list)</procedure> Returns a list of cipher names. Each name is a valid argument for the {{cipher-by-name}} procedure. <procedure>(cipher-by-name name)</procedure> Looks up the cipher {{name}} and returns a cipher object or {{#f}} if not found. ===== Cipher meta data <procedure>(cipher-key-length cipher)</procedure> <procedure>(cipher-iv-length cipher)</procedure> <procedure>(cipher-block-size cipher)</procedure> <procedure>(cipher-name cipher)</procedure> Obtain the key length, IV length, block length or name of the cipher object {{cipher}}. <constant>max-key-length</constant> <constant>max-iv-length</constant> <constant>max-block-length</constant> Maximum key, IV and block length as defined by OpenSSL. ===== Cipher context management <procedure>(cipher-context-allocate!)</procedure> Allocates a cipher context object for use with the below procedures. <procedure>(cipher-context-free! context)</procedure> Explicitly frees the cipher context object {{context}} unless already freed. This procedure is called implicitly on cipher context objcts by a finalizer, but may be called early to reduce memory pressure. <procedure>(cipher-context-reset! context)</procedure> Resets the cipher context object {{context}} so that it may be reused with the {{cipher-context-init!}}, {{cipher-context-update!}}, {{cipher-context-final!}} and {{cipher-context-get-tag}} procedures. <procedure>(cipher-context-init! context cipher key iv #!key (mode 'encrypt) (padding #t) effective-key-length auth-data tag-length expected-tag effective-iv-length message-length)</procedure> Set up the cipher context object {{context}} for encryption/decryption using {{cipher}} with the {{key}} and {{iv}} parameters as blobs. {{iv}} may be {{#f}} in case the cipher doesn't require an IV (for example AES-ECB and RC4). The remaining key arguments are optional and follow the below rules: * {{mode}} must be either {{'encrypt}} or {{'decrypt}}. * {{padding}} may be {{#t}} or {{#f}}. When {{#f}}, the cipher input length must be a multiple of the block length in the case of a block cipher such as AES-CBC. * {{effective-key-length}} instructs OpenSSL to use up to the specified number of bytes of the key. * {{auth-data}} specifies an additional blob of non-secret data to use with an AEAD cipher. * {{tag-length}} specifies the length of the generated tag for AEAD ciphers. It must be set for both encryption and decryption mode. * {{expected-tag}} specifies the expected tag for AEAD ciphers. It must be set for decryption mode and is obtained with {{cipher-context-get-tag}} after encryption. * {{effective-iv-length}} instructs OpenSSL to use up to the specified number of bytes of the IV. * {{message-length}} specifies the length of the entire message to be encrypted/decrypted. It must be set when using CCM mode. <procedure>(cipher-context-update! context blob #!optional effective-length)</procedure> Process {{blob}} with the cipher context object {{blob}} and return the corresponding chunk of ciphertext/plaintext. This procedure may be called repeatedly to process large amounts of data, for example when encrypting/decrypting a file in 4096 byte chunks. To process less than the full blob, pass {{effective-length}} to indicate this many bytes should be processed. Supported as of egg version 2.2.4. <procedure>(cipher-context-final! context)</procedure> Retrieve the final cipher output blob if any from the cipher context object {{context}}. <procedure>(cipher-context-get-tag context)</procedure> Obtain the tag blob associated with the cipher context object {{context}}. This may only be called when performing encryption with an AEAD cipher such as AES-GCM and must be called after {{cipher-context-final!}}. ===== High-level cipher API <procedure>(string-cipher cipher str key iv #!rest options)</procedure> Convenience procedure which performs a cipher operation with the cipher object {{cipher}} on {{str}}, using {{key}} and {{iv}} as parameters. Extra parameters are set with {{options}}. All parameters are passed to {{cipher-context-init!}} and follow its documentation. Returns an encrypted/decrypted string. <procedure>(string-encrypt-and-digest cipher str key iv #!rest options)</procedure> Convenience procedure to perform authenticated encryption using the AEAD cipher object {{cipher}} on {{str}}, using {{key}} and {{iv}} as parameters. Extra parameters are set with {{options}}. All parameters are passed to {{cipher-context-init!}} and follow its documentation. Returns the encrypted string and a tag blob, both of which can be passed to the {{string-decrypt-and-verify}} procedure. <procedure>(string-decrypt-and-verify cipher str tag key iv #!rest options)</procedure> Convenience procedure to perform authenticated decryption using the AEAD cipher object {{cipher}} on {{str}}, using {{tag}}, {{key}} and {{iv}} as parameters. Extra parameters are set with {{options}}. All parameters are passed to {{cipher-context-init!}} and follow its documentation. Returns the decrypted string and raises an error if verification failed. <procedure>(file-cipher cipher in-path out-path key iv #!rest options)</procedure> Convenience procedure which encrypts/decrypts the file at {{in-path}} into the file at {{out-path}} using the cipher object {{cipher}} and {{key}} and {{iv}} as parameters. Extra parameters are set with {{options}}. All parameters are passed to {{cipher-context-init!}} and follow its documentation. <procedure>(open-cipher-port cipher out key iv #!rest options)</procedure> Wrap output port {{out}} in an output port applying the cipher object {{cipher}} to everything written to it and sends it back to {{out}}. {{key}} and {{iv}} are used as parameters. Extra parameters are set with {{options}}. All parameters are passed to {{cipher-context-init!}} and follow its documentation. ===== Cipher API example Authenticated encryption using AES-256-GCM: <enscript highlight="scheme"> (import (chicken blob)) (import (openssl cipher)) (import (openssl random)) (define aes-256-gcm (cipher-by-name "aes-256-gcm")) (define (generate-param accessor) (random-bytes (accessor aes-256-gcm))) (define (generate-key) (generate-param cipher-key-length)) (define (generate-iv) (generate-param cipher-iv-length)) (define (encrypt message key iv #!optional auth-data) (string-encrypt-and-digest aes-256-gcm message key iv tag-length: 16 auth-data: auth-data)) (define (decrypt message tag key iv #!optional auth-data) (string-decrypt-and-verify aes-256-gcm message tag key iv auth-data: auth-data)) (let ((key (generate-key)) (iv (generate-iv)) (auth-data (string->blob "v1")) (plaintext "top secret")) (receive (ciphertext tag) (encrypt plaintext key iv auth-data) (assert (equal? plaintext (decrypt ciphertext tag key iv auth-data))))) </enscript> ==== (openssl digest) This API provides access to message digests such as SHA2 and SHA3. As of egg version 2.2.0 it can be used with {{(import (openssl digest))}}. ===== Digest lookup <procedure>(digest-list)</procedure> Returns a list of digest names. Each name is a valid argument for the {{digest-by-name}} procedure. <procedure>(digest-by-name name)</procedure> Looks up the digest {{name}} and returns a digest object or {{#f}} if not found. ===== Digest meta data <procedure>(digest-size digest)</procedure> <procedure>(digest-block-size digest)</procedure> <procedure>(digest-name digest)</procedure> Obtain the size, block size or name of the digest object {{digest}}. <constant>max-digest-size</constant> Maximum digest size as defined by OpenSSL. ===== Digext context management <procedure>(digest-context-allocate!)</procedure> Allocates a digest context object for use with the below procedures. <procedure>(digest-context-free! context)</procedure> Explicitly frees the digest context object {{context}} unless already freed. This procedure is called implicitly on digest context objects by a finalizer, but may be called early to reduce memory pressure. <procedure>(digest-context-reset! context)</procedure> Resets the digest context object {{context}} so that it may be reused with the {{digest-context-init!}}, {{digest-context-update!}} and {{digest-context-final!}} procedures. <procedure>(digest-context-init! context digest #!key (oneshot #f))</procedure> Set up the digest context object {{context}} to use the digest object {{digest}}. If the key argument {{oneshot}} is set to {{#t}}, the context is instructed to optimize for one update operation if possible. <procedure>(digest-context-update! context blob #!optional effective-length)</procedure> Digest {{blob}} into the digest context object {{context}}. This procedure may be called repeatedly to process large amounts of data, for example when calculating the hash of a file. To process less than the full blob, pass {{effective-length}} to indicate this many bytes should be digested. Supported as of egg version 2.2.4. <procedure>(digest-context-final! context)</procedure> Retrieve the string digest of all data consumed so far by the digest context object {{context}}. ===== High-level digest API <procedure>(string-digest digest str)</procedure> Convenience procedure which digests the string {{str}} with the digest object {{digest}} and returns its string digest. <procedure>(file-digest digest path)</procedure> Convenience procedure which digests the file contents at {{path}} with the digest object {{digest}} and returns its string digest. <procedure>(open-digest-port digest out #!rest options)</procedure> Wraps output port {{out}} in an output port applying the digest object {{digest}} to everything written to it and sends it back to {{out}}. Extra options are set with {{options}}, passed to {{digest-context-init!}} and follow its documentation. ===== Digest API example <enscript highlight="scheme"> (import scheme) (import (chicken base)) (import (chicken io)) (import (chicken port)) (import (chicken process-context)) (import (chicken string)) (import (openssl digest)) (define (hexencode str) (define (pad n) (string-append (if (< n 16) "0" "") (number->string n 16))) (string-intersperse (map (lambda (char) (pad (char->integer char))) (string->list str)) "")) (define (md5sum path) (hexencode (file-digest (digest-by-name "md5") path))) (for-each (lambda (path) (print (md5sum path) " " path)) (command-line-arguments)) </enscript> ==== (openssl random) This API provides access to OpenSSL's CSPRNG to obtain random bytes. As of egg version 2.2.0 it can be used with {{(import (openssl random))}}. Please note that the following procedures described here may fail and raise a non-continuable exception of the composite type {{(exn i/o openssl)}}: * {{random-bytes}} * {{load-random-file}} * {{write-random-file}} * {{random-file-name}} <procedure>(random-bytes size)</procedure> Returns a blob of {{size}} bytes. ===== RNG management Note that the default CSPRNG automatically takes care of initialization and obtaining extra random state. Additionally, {{random-bytes}} will raise an exception in case the CSPRNG returns an error. Therefore, there should be no need to explicitly call any of the below procedures. <procedure>(random-status)</procedure> Returns {{#t}} if the CSPRNG can be used to obtain random numbers. <procedure>(random-poll)</procedure> Initialize the CSPRNG with randomness. Returns {{#t}} if extra data has been added to the RNG state. <procedure>(random-add blob randomness)</procedure> Add bytes from {{blob}} to the CSPRNG state. {{randomness}} is a flonum between 0 and the size of {{blob}} to estimate its overall randomness. <procedure>(random-seed blob)</procedure> Add bytes from {{blob}} to the CSPRNG state. Equivalent to using {{random-add}} with {{randomness}} set to the size of {{blob}}. <procedure>(write-random-file path)</procedure> Stores an unspecified number of random bytes at {{path}}. <procedure>(load-random-file path max-bytes)</procedure> Add random bytes stored at {{path}} to the CSPRNG. If {{max-bytes}} is -1, use all bytes, otherwise only up to the specified amount. <procedure>(random-file-name)</procedure> Returns a path suitable for the {{load-random-file}} and {{write-random-file}} procedures. ==== (openssl version) This API allows to perform version introspection on the underlying OpenSSL library. As of egg version 2.1.1 it can be used with {{(import (openssl version))}}. ===== Version flags <constant>openssl/version</constant> <constant>openssl/cflags</constant> <constant>openssl/built-on</constant> <constant>openssl/platform</constant> <constant>openssl/dir</constant> <constant>openssl/engines-dir</constant> Version flags for use with the {{openssl-version}} procedure. ===== Version procedures <procedure>(openssl-version-number)</procedure> Returns the version as a fixnum. Refer to {{OPENSSL_VERSION_NUMBER(3)}} for details on how to extract individual version components from it. <procedure>(openssl-version version-flag)</procedure> Returns a string describing the version information as specified by {{version-flag}}. {{version-flag}} must be one of the Version flags above. Refer to {{OPENSSL_VERSION_NUMBER(3)}} for details what each flag will print. === Changelog * 2.2.6 Fix test failures related to OpenSSL>=3.0.0 * 2.2.5 Fix current-milliseconds warning * 2.2.4 Add optional {{effective-length}} argument to {{cipher-context-update!}} and {{digest-context-update!}} to process partial blobs and make use of it in the {{file-cipher}} and {{file-digest}} procedures (thanks megane!). * 2.2.3 Disable CCM tests for OpenSSL<1.1.0. * 2.2.2 Fix CCM tests by always providing effective IV length. * 2.2.1 Add missing test dependencies. * 2.2.0 Introduce {{(openssl cipher)}}, {{(openssl digest)}} and {{(openssl random)}} modules. Expose protocol version constants. * 2.1.1 Introduce {{(openssl socket)}} and {{(openssl version)}} modules. * 2.1.0 Bump minimum OpenSSL version to 1.1.0 to avoid deprecated APIs and support selection of min/max protocol and TLSv1.3 * 2.0.8 Print build script call, abort on non-zero exit * 2.0.7 Distinguish between syscall and ssl-eof errors to allow handling an unexpected EOF from server. * 2.0.6 Ensure that dynamic-wind executes after thunk in exceptional case * 2.0.5 Quote build script variables on Windows * 2.0.4 Rewrite build script to Scheme * 2.0.3 Drop SSLv2/v3 support and make CA patch actually work * 2.0.2 Bump minimum OpenSSL version to 1.0.2 to automatically locate the correct CA certificate directory * 2.0.1 Incorporate changes from Kooda's fork * 2.0.0 Port to CHICKEN 5 * 1.10.0 Use the tcp6 egg when it is present to allow binding to IPv6 interfaces or connecting to IPv6 hosts. * 1.9.4 Improved block I/O performance thanks to TheLemonMan * 1.9.2 Use address-info to choose default SNI behaviour * 1.9.1 Add client-side SNI support * 1.8.0 Add ssl-start* to support layering SSL on top of an existing TCP connection * 1.7.0 Various improvements including CHICKEN 4.10 compatibility and new constructors with more secure defaults * 1.6.2 Correct read-byte of chars with high bit set; fixes #954 * 1.5.1 Small bugfixes by Mario Domenech Goulart * 1.5 Do not let ssl-accept or ssl-connect block immediately but defer it until reading or writing to the ports. Add {{ssl-handshake-timeout}} and {{ssl-shutdown-timeout}} options. * 1.4 Fix intermittent bug in ssl-write caused by the GC's moving around of memory locations * 1.3 Make ssl ports completely distinct from tcp ports. Add {{ssl-port?}} and {{ssl-port->tcp-port}} procedures. * 1.1.7 fix for vector deref crash (elf, reported by glogic) * 1.1.6 windows linking fixes by Alex Queiroz * 1.1.5 added static linking support [felix] * 1.1.4 fixed problems with the shutdown sequence * 1.1.3 fixes problem with older chickens and missing newline before `<#' in blocks of foreign code [Thanks to Dan Muresan] * 1.1.2 uses {{foreign-code}} macro insead of obsolete read syntax * 1.1.1 Output that would block properly suspends threads now * 1.1.0 {{##sys#tcp-port->fileno}} and {{tcp-addresses}} are now supported on SSL ports * 1.0.0 Corrections, tests against {{openssl s_server, openssl s_client}} and comparison with the PLT module * 0.4.0 Server functionality added * 0.3.1 Client-only with certificate functions * 0.2.0 Client-only prerelease === License Copyright (c) 2005, Thomas Chust <chust@web.de>. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of the author nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Description of your changes:
I would like to authenticate
Authentication
Username:
Password:
Spam control
What do you get when you add 23 to 11?