Function: gnutls-boot-parameters

gnutls-boot-parameters is a byte-compiled function defined in gnutls.el.gz.

Signature

(gnutls-boot-parameters &rest SPEC &key TYPE HOSTNAME PRIORITY-STRING TRUSTFILES CRLFILES KEYLIST MIN-PRIME-BITS VERIFY-FLAGS VERIFY-ERROR VERIFY-HOSTNAME-ERROR PASS FLAGS &allow-other-keys)

Documentation

Return a keyword list of parameters suitable for passing to gnutls-boot.

TYPE is gnutls-x509pki (default) or gnutls-anon. Use nil for the default. HOSTNAME is the remote hostname. It must be a valid string. PRIORITY-STRING is as per the GnuTLS docs, default is based on "NORMAL". TRUSTFILES is a list of CA bundles. It defaults to gnutls-trustfiles(var)/gnutls-trustfiles(fun). CRLFILES is a list of CRL files. KEYLIST is an alist of (client key file, client cert file) pairs. MIN-PRIME-BITS is the minimum acceptable size of Diffie-Hellman keys
(see gnutls-min-prime-bits for more information). Use nil for the
default.

VERIFY-HOSTNAME-ERROR is a backwards compatibility option for putting :hostname in VERIFY-ERROR.

PASS is a string, the password of the key. It may also be nil, for a NULL password.

FLAGS is a list of symbols corresponding to the equivalent ORed bitflag of the gnutls_pkcs_encrypt_flags_t enum of GnuTLS. The empty list corresponds to the bitflag with value 0.

When VERIFY-ERROR is t or a list containing :trustfiles, an error will be raised when the peer certificate verification fails as per GnuTLS' gnutls_certificate_verify_peers2. Otherwise, only warnings will be shown about the verification failure.

When VERIFY-ERROR is t or a list containing :hostname, an error will be raised when the hostname does not match the presented certificate's host name. The exact verification algorithm is a basic implementation of the matching described in RFC2818 (HTTPS), which takes into account wildcards, and the DNSName/IPAddress subject alternative name PKIX extension. See GnuTLS' gnutls_x509_crt_check_hostname for details. Otherwise, only a warning will be issued.

Note that the list in gnutls-verify-error, matched against the HOSTNAME, is the default VERIFY-ERROR.

VERIFY-FLAGS is a numeric OR of verification flags only for gnutls-x509pki connections. See GnuTLS' x509.h for details; here's a recent version of the list.

    GNUTLS_VERIFY_DISABLE_CA_SIGN = 1,
    GNUTLS_VERIFY_ALLOW_X509_V1_CA_CRT = 2,
    GNUTLS_VERIFY_DO_NOT_ALLOW_SAME = 4,
    GNUTLS_VERIFY_ALLOW_ANY_X509_V1_CA_CRT = 8,
    GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2 = 16,
    GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5 = 32,
    GNUTLS_VERIFY_DISABLE_TIME_CHECKS = 64,
    GNUTLS_VERIFY_DISABLE_TRUSTED_TIME_CHECKS = 128,
    GNUTLS_VERIFY_DO_NOT_ALLOW_X509_V1_CA_CRT = 256

It must be omitted, a number, or nil; if omitted or nil it defaults to GNUTLS_VERIFY_ALLOW_X509_V1_CA_CRT.

Source Code

;; Defined in /usr/src/emacs/lisp/net/gnutls.el.gz
(cl-defun gnutls-boot-parameters
    (&rest spec
           &key type hostname priority-string
           trustfiles crlfiles keylist min-prime-bits
           verify-flags verify-error verify-hostname-error
           pass flags
           &allow-other-keys)
  "Return a keyword list of parameters suitable for passing to `gnutls-boot'.

TYPE is `gnutls-x509pki' (default) or `gnutls-anon'.  Use nil for the default.
HOSTNAME is the remote hostname.  It must be a valid string.
PRIORITY-STRING is as per the GnuTLS docs, default is based on \"NORMAL\".
TRUSTFILES is a list of CA bundles.  It defaults to `gnutls-trustfiles'.
CRLFILES is a list of CRL files.
KEYLIST is an alist of (client key file, client cert file) pairs.
MIN-PRIME-BITS is the minimum acceptable size of Diffie-Hellman keys
\(see `gnutls-min-prime-bits' for more information).  Use nil for the
default.

VERIFY-HOSTNAME-ERROR is a backwards compatibility option for
putting `:hostname' in VERIFY-ERROR.

PASS is a string, the password of the key.  It may also be nil,
for a NULL password.

FLAGS is a list of symbols corresponding to the equivalent ORed
bitflag of the gnutls_pkcs_encrypt_flags_t enum of GnuTLS.  The
empty list corresponds to the bitflag with value 0.

When VERIFY-ERROR is t or a list containing `:trustfiles', an
error will be raised when the peer certificate verification fails
as per GnuTLS' gnutls_certificate_verify_peers2.  Otherwise, only
warnings will be shown about the verification failure.

When VERIFY-ERROR is t or a list containing `:hostname', an error
will be raised when the hostname does not match the presented
certificate's host name.  The exact verification algorithm is a
basic implementation of the matching described in
RFC2818 (HTTPS), which takes into account wildcards, and the
DNSName/IPAddress subject alternative name PKIX extension.  See
GnuTLS' gnutls_x509_crt_check_hostname for details.  Otherwise,
only a warning will be issued.

Note that the list in `gnutls-verify-error', matched against the
HOSTNAME, is the default VERIFY-ERROR.

VERIFY-FLAGS is a numeric OR of verification flags only for
`gnutls-x509pki' connections.  See GnuTLS' x509.h for details;
here's a recent version of the list.

    GNUTLS_VERIFY_DISABLE_CA_SIGN = 1,
    GNUTLS_VERIFY_ALLOW_X509_V1_CA_CRT = 2,
    GNUTLS_VERIFY_DO_NOT_ALLOW_SAME = 4,
    GNUTLS_VERIFY_ALLOW_ANY_X509_V1_CA_CRT = 8,
    GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2 = 16,
    GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5 = 32,
    GNUTLS_VERIFY_DISABLE_TIME_CHECKS = 64,
    GNUTLS_VERIFY_DISABLE_TRUSTED_TIME_CHECKS = 128,
    GNUTLS_VERIFY_DO_NOT_ALLOW_X509_V1_CA_CRT = 256

It must be omitted, a number, or nil; if omitted or nil it
defaults to GNUTLS_VERIFY_ALLOW_X509_V1_CA_CRT."
  (let* ((trustfiles (or trustfiles (gnutls-trustfiles)))
         (crlfiles (or crlfiles (gnutls-crlfiles)))
         (maybe-dumbfw (if (memq 'ClientHello\ Padding (gnutls-available-p))
                           ":%DUMBFW"
                         ""))
         (priority-string (or priority-string
                              (cond
                               ((eq type 'gnutls-anon)
                                (concat "NORMAL:+ANON-DH:!ARCFOUR-128"
                                        maybe-dumbfw))
                               ((eq type 'gnutls-x509pki)
                                (if gnutls-algorithm-priority
                                    (upcase gnutls-algorithm-priority)
                                  (concat "NORMAL" maybe-dumbfw))))))
         (verify-error (or verify-error
                           ;; this uses the value of `gnutls-verify-error'
                           (cond
                            ;; if t, pass it on
                            ((eq gnutls-verify-error t)
                             t)
                            ;; if a list, look for hostname matches
                            ((listp gnutls-verify-error)
                             (cadr (cl-find-if (lambda (x)
                                                 (string-match (car x) hostname))
                                               gnutls-verify-error)))
                            ;; else it's nil
                            (t nil))))
         (min-prime-bits (or min-prime-bits gnutls-min-prime-bits)))

    ;; Only add :hostname if `verify-error' is not t, since t
    ;; means "include :hostname" Bug#38602.
    (and verify-hostname-error
         (not (eq verify-error t))
         (push :hostname verify-error))

    `(:priority ,priority-string
                :hostname ,hostname
                :loglevel ,gnutls-log-level
                :min-prime-bits ,min-prime-bits
                :trustfiles ,trustfiles
                :crlfiles ,crlfiles
                :keylist ,keylist
                :verify-flags ,verify-flags
                :verify-error ,verify-error
                :pass ,pass
                :flags ,flags
                :callbacks nil)))