Changeset 40259 in project


Ignore:
Timestamp:
07/05/21 22:25:14 (3 weeks ago)
Author:
Vasilij Schneidermann
Message:

openssl: Release v2.2.0

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/5/openssl

    r40207 r40259  
    6666itself]].
    6767
     68===== Constants
     69
     70Supported SSL protocols for the {{ssl-connect}}, {{ssl-connect*}},
     71{{ssl-make-client-context}}, {{ssl-make-client-context*}},
     72{{ssl-listen}}, {{ssl-listen*}} and {{ssl-start*}} procedures.
     73
     74<constant>supported-ssl-protocols</constant>
     75<constant>ssl-min-protocol</constant>
     76<constant>ssl-min-protocol</constant>
     77
     78The ordered list of supported SSL protocols and the minimum and
     79maximum supported SSL protocol. Supported as of egg version 2.2.0.
     80
    6881===== Parameters
    6982
     
    97110The return values are as tcp-connect; an input port and an output port.
    98111
    99 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}} or {{'tlsv12}} or a pair of two such symbols. See {{ssl-make-client-context}} for further details, including the meanings of the protocol symbols.
     112The 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.
    100113
    101114The 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.
     
    258271interfere with OpenSSL's operation.
    259272
     273===== Example
     274
     275Launch Spiffy with TLSv1.2 and TLSv1.3 support:
     276
     277<enscript highlight="scheme">
     278(import openssl)
     279(import spiffy)
     280(import (chicken process-context))
     281
     282(define (getenv key #!optional default)
     283  (or (get-environment-variable key) default))
     284
     285(define port 8443)
     286(define private-key "cert.key")
     287(define public-key "cert.pem")
     288
     289(server-port port)
     290(define listener (ssl-listen* port: port
     291                              protocol: '(tlsv12 . tlsv13)
     292                              certificate: public-key
     293                              private-key: private-key))
     294(accept-loop listener ssl-accept)
     295</enscript>
     296
     297Make a http-client request using TLSv1.2 or TLSv1.3:
     298
     299<enscript highlight="scheme">
     300(import openssl)
     301(import http-client)
     302(import uri-common)
     303(import (chicken io))
     304
     305(define (http-server-connector uri proxy)
     306  (let ((remote-end (or proxy uri)))
     307    (case (uri-scheme remote-end)
     308      ((#f http) (tcp-connect (uri-host remote-end) (uri-port remote-end)))
     309      ((https) (receive (in out)
     310                   (ssl-connect* hostname: (uri-host remote-end)
     311                                 port: (uri-port remote-end)
     312                                 protocol: 'tlsv12
     313                                 ;; protocol: '(tlsv1 . tlsv12)
     314                                 sni-name: #t
     315                                 verify?: #f)
     316                 (if (and in out) ; Ugly, but necessary
     317                     (values in out)
     318                     (error "You forgot to install the openssl egg."))))
     319      (else (error "This shouldn't happen")))))
     320
     321(server-connector http-server-connector)
     322;; supports TLSv1.2 and v1.3 only
     323(with-input-from-request "https://en.wikipedia.org/wiki/Cat" #f read-string)
     324</enscript>
     325
     326==== (openssl cipher)
     327
     328This API provides access to ciphers such as AES-256-GCM. As of egg
     329version 2.2.0 it can be used with {{(import (openssl cipher))}}.
     330
     331===== Cipher lookup
     332
     333<procedure>(cipher-list)</procedure>
     334
     335Returns a list of cipher names. Each name is a valid argument for the
     336{{cipher-by-name}} procedure.
     337
     338<procedure>(cipher-by-name name)</procedure>
     339
     340Looks up the cipher {{name}} and returns a cipher object or {{#f}} if
     341not found.
     342
     343===== Cipher meta data
     344
     345<procedure>(cipher-key-length cipher)</procedure>
     346<procedure>(cipher-iv-length cipher)</procedure>
     347<procedure>(cipher-block-size cipher)</procedure>
     348<procedure>(cipher-name cipher)</procedure>
     349
     350Obtain the key length, IV length, block length or name of the cipher
     351object {{cipher}}.
     352
     353<constant>max-key-length</constant>
     354<constant>max-iv-length</constant>
     355<constant>max-block-length</constant>
     356
     357Maximum key, IV and block length as defined by OpenSSL.
     358
     359===== Cipher context management
     360
     361<procedure>(cipher-context-allocate!)</procedure>
     362
     363Allocates a cipher context object for use with the below procedures.
     364
     365<procedure>(cipher-context-free! context)</procedure>
     366
     367Explicitly frees the cipher context object {{context}} unless already
     368freed. This procedure is called implicitly on cipher context objcts by
     369a finalizer, but may be called early to reduce memory pressure.
     370
     371<procedure>(cipher-context-reset! context)</procedure>
     372
     373Resets the cipher context object {{context}} so that it may be reused
     374with the {{cipher-context-init!}}, {{cipher-context-update!}},
     375{{cipher-context-final!}} and {{cipher-context-get-tag}} procedures.
     376
     377<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>
     378
     379Set up the cipher context object {{context}} for encryption/decryption
     380using {{cipher}} with the {{key}} and {{iv}} parameters as blobs.
     381{{iv}} may be {{#f}} in case the cipher doesn't require an IV (for
     382example AES-ECB and RC4). The remaining key arguments are optional and
     383follow the below rules:
     384
     385* {{mode}} must be either {{'encrypt}} or {{'decrypt}}.
     386* {{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.
     387* {{effective-key-length}} instructs OpenSSL to use up to the specified number of bytes of the key.
     388* {{auth-data}} specifies an additional blob of non-secret data to use with an AEAD cipher.
     389* {{tag-length}} specifies the length of the generated tag for AEAD ciphers. It must be set for both encryption and decryption mode.
     390* {{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.
     391* {{effective-iv-length}} instructs OpenSSL to use up to the specified number of bytes of the IV.
     392* {{message-length}} specifies the length of the entire message to be encrypted/decrypted. It must be set when using CCM mode.
     393
     394<procedure>(cipher-context-update! context blob)</procedure>
     395
     396Process {{blob}} with the cipher context object {{blob}} and return
     397the corresponding chunk of ciphertext/plaintext. This procedure may be
     398called repeatedly to process large amounts of data, for example when
     399encrypting/decrypting a file in 4096 byte chunks.
     400
     401<procedure>(cipher-context-final! context)</procedure>
     402
     403Retrieve the final cipher output blob if any from the cipher context
     404object {{context}}.
     405
     406<procedure>(cipher-context-get-tag context)</procedure>
     407
     408Obtain the tag blob associated with the cipher context object
     409{{context}}. This may only be called when performing encryption with
     410an AEAD cipher such as AES-GCM and must be called after
     411{{cipher-context-final!}}.
     412
     413===== High-level cipher API
     414
     415<procedure>(string-cipher cipher str key iv #!rest options)</procedure>
     416
     417Convenience procedure which performs a cipher operation with the
     418cipher object {{cipher}} on {{str}}, using {{key}} and {{iv}} as
     419parameters. Extra parameters are set with {{options}}. All parameters
     420are passed to {{cipher-context-init!}} and follow its documentation.
     421Returns an encrypted/decrypted string.
     422
     423<procedure>(string-encrypt-and-digest cipher str key iv #!rest options)</procedure>
     424
     425Convenience procedure to perform authenticated encryption using the
     426AEAD cipher object {{cipher}} on {{str}}, using {{key}} and {{iv}} as
     427parameters. Extra parameters are set with {{options}}. All parameters
     428are passed to {{cipher-context-init!}} and follow its documentation.
     429Returns the encrypted string and a tag blob, both of which can be
     430passed to the {{string-decrypt-and-verify}} procedure.
     431
     432<procedure>(string-decrypt-and-verify cipher str tag key iv #!rest options)</procedure>
     433
     434Convenience procedure to perform authenticated decryption using the
     435AEAD cipher object {{cipher}} on {{str}}, using {{tag}}, {{key}} and
     436{{iv}} as parameters. Extra parameters are set with {{options}}. All
     437parameters are passed to {{cipher-context-init!}} and follow its
     438documentation. Returns the decrypted string and raises an error if
     439verification failed.
     440
     441<procedure>(file-cipher cipher in-path out-path key iv #!rest options)</procedure>
     442
     443Convenience procedure which encrypts/decrypts the file at {{in-path}}
     444into the file at {{out-path}} using the cipher object {{cipher}} and
     445{{key}} and {{iv}} as parameters. Extra parameters are set with
     446{{options}}. All parameters are passed to {{cipher-context-init!}} and
     447follow its documentation.
     448
     449<procedure>(open-cipher-port cipher out key iv #!rest options)</procedure>
     450
     451Wrap output port {{out}} in an output port applying the cipher object
     452{{cipher}} to everything written to it and sends it back to {{out}}.
     453{{key}} and {{iv}} are used as parameters. Extra parameters are set
     454with {{options}}. All parameters are passed to
     455{{cipher-context-init!}} and follow its documentation.
     456
     457===== Example
     458
     459Authenticated encryption using AES-256-GCM:
     460
     461<enscript highlight="scheme">
     462(import (chicken blob))
     463(import (openssl cipher))
     464(import (openssl random))
     465
     466(define aes-256-gcm (cipher-by-name "aes-256-gcm"))
     467
     468(define (generate-param accessor)
     469  (random-bytes (accessor aes-256-gcm)))
     470
     471(define (generate-key) (generate-param cipher-key-length))
     472(define (generate-iv) (generate-param cipher-iv-length))
     473
     474(define (encrypt message key iv #!optional auth-data)
     475  (string-encrypt-and-digest aes-256-gcm message key iv
     476                             tag-length: 16
     477                             auth-data: auth-data))
     478
     479(define (decrypt message tag key iv #!optional auth-data)
     480  (string-decrypt-and-verify aes-256-gcm message tag key iv
     481                             auth-data: auth-data))
     482
     483(let ((key (generate-key))
     484      (iv (generate-iv))
     485      (auth-data (string->blob "v1"))
     486      (plaintext "top secret"))
     487  (receive (ciphertext tag)
     488      (encrypt plaintext key iv auth-data)
     489    (assert (equal? plaintext (decrypt ciphertext tag key iv auth-data)))))
     490</enscript>
     491
     492==== (openssl digest)
     493
     494This API provides access to message digests such as SHA2 and SHA3. As
     495of egg version 2.2.0 it can be used with {{(import (openssl digest))}}.
     496
     497===== Digest lookup
     498
     499<procedure>(digest-list)</procedure>
     500
     501Returns a list of digest names. Each name is a valid argument for the
     502{{digest-by-name}} procedure.
     503
     504<procedure>(digest-by-name name)</procedure>
     505
     506Looks up the digest {{name}} and returns a digest object or {{#f}} if
     507not found.
     508
     509===== Digest meta data
     510
     511<procedure>(digest-size digest)</procedure>
     512<procedure>(digest-block-size digest)</procedure>
     513<procedure>(digest-name digest)</procedure>
     514
     515Obtain the size, block size or name of the digest object {{digest}}.
     516
     517<constant>max-digest-size</constant>
     518
     519Maximum digest size as defined by OpenSSL.
     520
     521===== Digext context management
     522
     523<procedure>(digest-context-allocate!)</procedure>
     524
     525Allocates a digest context object for use with the below procedures.
     526
     527<procedure>(digest-context-free! context)</procedure>
     528
     529Explicitly frees the digest context object {{context}} unless already
     530freed. This procedure is called implicitly on digest context objects
     531by a finalizer, but may be called early to reduce memory pressure.
     532
     533<procedure>(digest-context-reset! context)</procedure>
     534
     535Resets the digest context object {{context}} so that it may be reused
     536with the {{digest-context-init!}}, {{digest-context-update!}} and
     537{{digest-context-final!}} procedures.
     538
     539<procedure>(digest-context-init! context digest #!key (oneshot #f))</procedure>
     540
     541Set up the digest context object {{context}} to use the digest object
     542{{digest}}. If the key argument {{oneshot}} is set to {{#t}}, the
     543context is instructed to optimize for one update operation if
     544possible.
     545
     546<procedure>(digest-context-update! context blob)</procedure>
     547
     548Digest {{blob}} into the digest context object {{context}}. This
     549procedure may be called repeatedly to process large amounts of data,
     550for example when calculating the hash of a file.
     551
     552<procedure>(digest-context-final! context)</procedure>
     553
     554Retrieve the string digest of all data consumed so far by the digest
     555context object {{context}}.
     556
     557===== High-level digest API
     558
     559<procedure>(string-digest digest str)</procedure>
     560
     561Convenience procedure which digests the string {{str}} with the digest
     562object {{digest}} and returns its string digest.
     563
     564<procedure>(file-digest digest path)</procedure>
     565
     566Convenience procedure which digests the file contents at {{path}} with
     567the digest object {{digest}} and returns its string digest.
     568
     569<procedure>(open-digest-port digest out #!rest options)</procedure>
     570
     571Wraps output port {{out}} in an output port applying the digest object
     572{{digest}} to everything written to it and sends it back to {{out}}.
     573Extra options are set with {{options}}, passed to
     574{{digest-context-init!}} and follow its documentation.
     575
     576===== Example
     577
     578<enscript highlight="scheme">
     579(import scheme)
     580(import (chicken base))
     581(import (chicken io))
     582(import (chicken port))
     583(import (chicken process-context))
     584(import (chicken string))
     585(import (openssl digest))
     586
     587(define (hexencode str)
     588  (define (pad n)
     589    (string-append (if (< n 16) "0" "") (number->string n 16)))
     590  (string-intersperse
     591   (map (lambda (char)
     592          (pad (char->integer char)))
     593        (string->list str))
     594   ""))
     595
     596(define (md5sum path)
     597  (hexencode (file-digest (digest-by-name "md5") path)))
     598
     599(for-each
     600 (lambda (path)
     601   (print (md5sum path) "  " path))
     602 (command-line-arguments))
     603</enscript>
     604
     605==== (openssl random)
     606
     607This API provides access to OpenSSL's CSPRNG to obtain random bytes.
     608As of egg version 2.2.0 it can be used with {{(import (openssl
     609random))}}.
     610
     611Please note that the following procedures described here may fail and
     612raise a non-continuable exception of the composite type {{(exn i/o
     613openssl)}}:
     614
     615* {{random-bytes}}
     616* {{load-random-file}}
     617* {{write-random-file}}
     618* {{random-file-name}}
     619
     620<procedure>(random-bytes size)</procedure>
     621
     622Returns a blob of {{size}} bytes.
     623
     624===== RNG management
     625
     626Note that the default CSPRNG automatically takes care of
     627initialization and obtaining extra random state. Additionally,
     628{{random-bytes}} will raise an exception in case the CSPRNG returns an
     629error. Therefore, there should be no need to explicitly call any of
     630the below procedures.
     631
     632<procedure>(random-status)</procedure>
     633
     634Returns {{#t}} if the CSPRNG can be used to obtain random numbers.
     635
     636<procedure>(random-poll)</procedure>
     637
     638Initialize the CSPRNG with randomness. Returns {{#t}} if extra data
     639has been added to the RNG state.
     640
     641<procedure>(random-add blob randomness)</procedure>
     642
     643Add bytes from {{blob}} to the CSPRNG state. {{randomness}} is a
     644flonum between 0 and the size of {{blob}} to estimate its overall
     645randomness.
     646
     647<procedure>(random-seed blob)</procedure>
     648
     649Add bytes from {{blob}} to the CSPRNG state. Equivalent to using
     650{{random-add}} with {{randomness}} set to the size of {{blob}}.
     651
     652<procedure>(write-random-file path)</procedure>
     653
     654Stores an unspecified number of random bytes at {{path}}.
     655
     656<procedure>(load-random-file path max-bytes)</procedure>
     657
     658Add random bytes stored at {{path}} to the CSPRNG. If {{max-bytes}} is
     659-1, use all bytes, otherwise only up to the specified amount.
     660
     661<procedure>(random-file-name)</procedure>
     662
     663Returns a path suitable for the {{load-random-file}} and
     664{{write-random-file}} procedures.
     665
    260666==== (openssl version)
    261667
     
    292698=== Changelog
    293699
     700* 2.2.0 Introduce {{(openssl cipher)}}, {{(openssl digest)}} and {{(openssl random)}} modules. Expose protocol version constants.
    294701* 2.1.1 Introduce {{(openssl socket)}} and {{(openssl version)}} modules.
    295702* 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
Note: See TracChangeset for help on using the changeset viewer.