[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11. Guile Bindings

This chapter describes the GNU Guile Scheme programming interface to GnuTLS. The reader is assumed to have basic knowledge of the protocol and library. Details missing from this chapter may be found in the C API reference.

At this stage, not all the C functions are available from Scheme, but a large subset thereof is available.

11.1 Guile Preparations   Note on installation and environment.
11.2 Guile API Conventions   Naming conventions and other idiosyncrasies.
11.3 Guile Examples   Quick start.
11.4 Guile Reference   The Scheme GnuTLS programming interface.
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.1 Guile Preparations

The GnuTLS Guile bindings are by default installed under the GnuTLS installation directory (e.g., typically `/usr/local/share/guile/site/'). Normally Guile will not find the module there without help. You may experience something like this:

 
$ guile
guile> (use-modules (gnutls))
<unnamed port>: no code for module (gnutls)
guile>

There are two ways to solve this. The first is to make sure that when building GnuTLS, the Guile bindings will be installed in the same place where Guile looks. You may do this by using the --with-guile-site-dir parameter as follows:

 
$ ./configure --with-guile-site-dir=no

This will instruct GnuTLS to attempt to install the Guile bindings where Guile will look for them. It will use guile-config info pkgdatadir to learn the path to use.

If Guile was installed into /usr, you may also install GnuTLS using the same prefix:

 
$ ./configure --prefix=/usr

If you want to specify the path to install the Guile bindings you can also specify the path directly:

 
$ ./configure --with-guile-site-dir=/opt/guile/share/guile/site

The second solution requires some more work but may be easier to use if you do not have system administrator rights to your machine. You need to instruct Guile so that it finds the GnuTLS Guile bindings. Either use the GUILE_LOAD_PATH environment variable as follows:

 
$ GUILE_LOAD_PATH="/usr/local/share/guile/site:$GUILE_LOAD_PATH" guile
guile> (use-modules (gnutls))
guile>

Alternatively, you can modify Guile's %load-path variable (see Guile's run-time options: (guile)Build Config section `Build Config' in The GNU Guile Reference Manual).

At this point, you might get an error regarding `libguile-gnutls-v-0' similar to:

 
gnutls.scm:361:1: In procedure dynamic-link in expression (load-extension "libguile-gnutls-v-0" "scm_init_gnutls"):
gnutls.scm:361:1: file: "libguile-gnutls-v-0", message: "libguile-gnutls-v-0.so: cannot open shared object file: No such file or directory"

In this case, you will need to modify the run-time linker path, for example as follows:

 
$ LD_LIBRARY_PATH=/usr/local/lib GUILE_LOAD_PATH=/usr/local/share/guile/site guile
guile> (use-modules (gnutls))
guile>
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.2 Guile API Conventions

This chapter details the conventions used by Guile API, as well as specificities of the mapping of the C API to Scheme.

11.2.1 Enumerates and Constants   Representation of C-side constants.
11.2.2 Procedure Names   Naming conventions.
11.2.3 Representation of Binary Data   Binary data buffers.
11.2.4 Input and Output   Input and output.
11.2.5 Exception Handling   Exceptions.
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.2.1 Enumerates and Constants

Lots of enumerates and constants are used in the GnuTLS C API. For each C enumerate type, a disjoint Scheme type is used--thus, enumerate values and constants are not represented by Scheme symbols nor by integers. This makes it impossible to use an enumerate value of the wrong type on the Scheme side: such errors are automatically detected by type-checking.

The enumerate values are bound to variables exported by the (gnutls) and (gnutls extra) modules. These variables are named according to the following convention:

Consider for instance this C-side enumerate:

 
typedef enum
{
  GNUTLS_CRD_CERTIFICATE = 1,
  GNUTLS_CRD_ANON,
  GNUTLS_CRD_SRP,
  GNUTLS_CRD_PSK,
  GNUTLS_CRD_IA
} gnutls_credentials_type_t;

The corresponding Scheme values are bound to the following variables exported by the (gnutls) module:

 
credentials/certificate
credentials/anonymous
credentials/srp
credentials/psk
credentials/ia

Hopefully, most variable names can be deduced from this convention.

Scheme-side "enumerate" values can be compared using eq? (see equality predicates: (guile)Equality section `Equality' in The GNU Guile Reference Manual). Consider the following example:

 
(let ((session (make-session connection-end/client)))

  ;;
  ;; ...
  ;;

  ;; Check the ciphering algorithm currently used by SESSION.
  (if (eq? cipher/arcfour (session-cipher session))
      (format #t "We're using the ARCFOUR algorithm")))

In addition, all enumerate values can be converted to a human-readable string, in a type-specific way. For instance, (cipher->string cipher/arcfour) yields "ARCFOUR 128", while (key-usage->string key-usage/digital-signature) yields "digital-signature". Note that these strings may not be sufficient for use in a user interface since they are fairly concise and not internationalized.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.2.2 Procedure Names

Unlike C functions in GnuTLS, the corresponding Scheme procedures are named in a way that is close to natural English. Abbreviations are also avoided. For instance, the Scheme procedure corresponding to gnutls_certificate_set_dh_params is named set-certificate-credentials-dh-parameters!. The gnutls_ prefix is always omitted from variable names since a similar effect can be achieved using Guile's nifty binding renaming facilities, should it be needed (see (guile)Using Guile Modules section `Using Guile Modules' in The GNU Guile Reference Manual).

Often Scheme procedure names differ from C function names in a way that makes it clearer what objects they operate on. For example, the Scheme procedure named set-session-transport-port! corresponds to gnutls_transport_set_ptr, making it clear that this procedure applies to session.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.2.3 Representation of Binary Data

Many procedures operate on binary data. For instance, pkcs3-import-dh-parameters expects binary data as input and, similarly, procedures like pkcs1-export-rsa-parameters return binary data.

Binary data is represented on the Scheme side using SRFI-4 homogeneous vectors (see (guile)SRFI-4 section `SRFI-4' in The GNU Guile Reference Manual). Although any type of homogeneous vector may be used, u8vectors (i.e., vectors of bytes) are highly recommended.

As an example, generating and then exporting RSA parameters in the PEM format can be done as follows:

 
(let* ((rsa-params (make-rsa-parameters 1024))
       (raw-data
        (pkcs1-export-rsa-parameters rsa-params
                                     x509-certificate-format/pem)))
  (uniform-vector-write raw-data (open-output-file "some-file.pem")))

For an example of OpenPGP key import from a file, see Importing OpenPGP Keys Guile Example.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.2.4 Input and Output

The underlying transport of a TLS session can be any Scheme input/output port (see (guile)Ports and File Descriptors section `Ports and File Descriptors' in The GNU Guile Reference Manual). This has to be specified using set-session-transport-port!.

However, for better performance, a raw file descriptor can be specified, using set-session-transport-fd!. For instance, if the transport layer is a socket port over an OS-provided socket, you can use the port->fdes or fileno procedure to obtain the underlying file descriptor and pass it to set-session-transport-fd! (see port->fdes and fileno: (guile)Ports and File Descriptors section `Ports and File Descriptors' in The GNU Guile Reference Manual). This would work as follows:

 
(let ((socket (socket PF_INET SOCK_STREAM 0))
      (session (make-session connection-end/client)))

  ;;
  ;; Establish a TCP connection...
  ;;

  ;; Use the file descriptor that underlies SOCKET.
  (set-session-transport-fd! session (fileno socket)))

Once a TLS session is established, data can be communicated through it (i.e., via the TLS record layer) using the port returned by session-record-port:

 
(let ((session (make-session connection-end/client)))

  ;;
  ;; Initialize the various parameters of SESSION, set up
  ;; a network connection, etc...
  ;;

  (let ((i/o (session-record-port session)))
    (write "Hello peer!" i/o)
    (let ((greetings (read i/o)))

      ;; ...

      (bye session close-request/rdwr))))

A lower-level I/O API is provided by record-send and record-receive! which take an SRFI-4 vector to represent the data sent or received. While it might improve performance, it is much less convenient than the above and should rarely be needed.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.2.5 Exception Handling

GnuTLS errors are implemented as Scheme exceptions (see exceptions in Guile: (guile)Exceptions section `Exceptions' in The GNU Guile Reference Manual). Each time a GnuTLS function returns an error, an exception with key gnutls-error is raised. The additional arguments that are thrown include an error code and the name of the GnuTLS procedure that raised the exception. The error code is pretty much like an enumerate value: it is one of the errcode> variables exported by the (gnutls) module (see section Enumerates and Constants). Exceptions can be turned into error messages using the error->string procedure.

The following examples illustrates how GnuTLS exceptions can be handled:

 
(let ((session (make-session connection-end/server)))

  ;;
  ;; ...
  ;;

  (catch 'gnutls-error
    (lambda ()
      (handshake session))
    (lambda (key err function . currently-unused)
      (format (current-error-port)
              "a GnuTLS error was raised by `~a': ~a~%"
              function (error->string err)))))

Again, error values can be compared using eq?:

 
    ;; `gnutls-error' handler.
    (lambda (key err function . currently-unused)
      (if (eq? err error/fatal-alert-received)
          (format (current-error-port)
                  "a fatal alert was caught!~%")
          (format (current-error-port)
                  "something bad happened: ~a~%"
                  (error->string err))))

Note that the catch handler is currently passed only 3 arguments but future versions might provide it with additional arguments. Thus, it must be prepared to handle more than 3 arguments, as in this example.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.3 Guile Examples

This chapter provides examples that illustrate common use cases.

11.3.1 Anonymous Authentication Guile Example   Simplest client and server.
11.3.2 OpenPGP Authentication Guile Example   Using OpenPGP-based authentication.
11.3.3 Importing OpenPGP Keys Guile Example   Importing keys from files.
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.3.1 Anonymous Authentication Guile Example

Anonymous authentication is very easy to use. No certificates are needed by the communicating parties. Yet, it allows them to benefit from end-to-end encryption and integrity checks.

The client-side code would look like this (assuming some-socket is bound to an open socket port):

 
;; Client-side.

(let ((client (make-session connection-end/client)))
  ;; Use the default settings.
  (set-session-default-priority! client)

  ;; Don't use certificate-based authentication.
  (set-session-certificate-type-priority! client '())

  ;; Request the "anonymous Diffie-Hellman" key exchange method.
  (set-session-kx-priority! client (list kx/anon-dh))

  ;; Specify the underlying socket.
  (set-session-transport-fd! client (fileno some-socket))

  ;; Create anonymous credentials.
  (set-session-credentials! client
                            (make-anonymous-client-credentials))

  ;; Perform the TLS handshake with the server.
  (handshake client)

  ;; Send data over the TLS record layer.
  (write "hello, world!" (session-record-port client))

  ;; Terminate the TLS session.
  (bye client close-request/rdwr))

The corresponding server would look like this (again, assuming some-socket is bound to a socket port):

 
;; Server-side.

(let ((server (make-session connection-end/server)))
  (set-session-default-priority! server)
  (set-session-certificate-type-priority! server '())
  (set-session-kx-priority! server (list kx/anon-dh))

  ;; Specify the underlying transport socket.
  (set-session-transport-fd! server (fileno some-socket))

  ;; Create anonymous credentials.
  (let ((cred (make-anonymous-server-credentials))
        (dh-params (make-dh-parameters 1024)))
    ;; Note: DH parameter generation can take some time.
    (set-anonymous-server-dh-parameters! cred dh-params)
    (set-session-credentials! server cred))

  ;; Perform the TLS handshake with the client.
  (handshake server)

  ;; Receive data over the TLS record layer.
  (let ((message (read (session-record-port server))))
    (format #t "received the following message: ~a~%"
            message)

    (bye server close-request/rdwr)))

This is it!

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.3.2 OpenPGP Authentication Guile Example

GnuTLS allows users to authenticate using OpenPGP certificates. The relevant procedures are provided by the (gnutls extra) module. Using OpenPGP-based authentication is not more complicated than using anonymous authentication. It requires a bit of extra work, though, to import the OpenPGP public and private key of the client/server. Key import is omitted here and is left as an exercise to the reader (see section Importing OpenPGP Keys Guile Example).

Assuming some-socket is bound to an open socket port and pub and sec are bound to the client's OpenPGP public and secret key, respectively, client-side code would look like this:

 
;; Client-side.

(define %certs (list certificate-type/openpgp))

(let ((client (make-session connection-end/client))
      (cred   (make-certificate-credentials)))
  (set-session-default-priority! client)

  ;; Choose OpenPGP certificates.
  (set-session-certificate-type-priority! client %certs)

  ;; Prepare appropriate client credentials.
  (set-certificate-credentials-openpgp-keys! cred pub sec)
  (set-session-credentials! client cred)

  ;; Specify the underlying transport socket.
  (set-session-transport-fd! client (fileno some-socket))

  (handshake client)
  (write "hello, world!" (session-record-port client))
  (bye client close-request/rdwr))

Similarly, server-side code would be along these lines:

 
;; Server-side.

(define %certs (list certificate-type/openpgp))

(let ((server (make-session connection-end/server))
      (rsa    (make-rsa-parameters 1024))
      (dh     (make-dh-parameters 1024)))
  (set-session-default-priority! server)

  ;; Choose OpenPGP certificates.
  (set-session-certificate-type-priority! server %certs)

  (let ((cred (make-certificate-credentials)))
    ;; Prepare credentials with RSA and Diffie-Hellman parameters.
    (set-certificate-credentials-dh-parameters! cred dh)
    (set-certificate-credentials-rsa-export-parameters! cred rsa)
    (set-certificate-credentials-openpgp-keys! cred pub sec)
    (set-session-credentials! server cred))

  (set-session-transport-fd! server (fileno some-socket))

  (handshake server)
  (let ((msg (read (session-record-port server))))
    (format #t "received: ~a~%" msg)

    (bye server close-request/rdwr)))

In practice, generating RSA parameters (and Diffie-Hellman parameters) can time a long time. Thus, you may want to generate them once and store them in a file for future re-use (see section pkcs1-export-rsa-parameters and pkcs1-import-rsa-parameters).

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.3.3 Importing OpenPGP Keys Guile Example

The following example provides a simple way of importing "ASCII-armored" OpenPGP keys from files, using the import-openpgp-certificate and import-openpgp-private-key procedures provided by the (gnutls extra) module.

 
(use-modules (srfi srfi-4)
             (gnutls extra))

(define (import-key-from-file import-proc file)
  ;; Import OpenPGP key from FILE using IMPORT-PROC.

  ;; Prepare a u8vector large enough to hold the raw
  ;; key contents.
  (let* ((size (stat:size (stat path)))
         (raw  (make-u8vector size)))

    ;; Fill in the u8vector with the contents of FILE.
    (uniform-vector-read! raw (open-input-file file))

    ;; Pass the u8vector to the import procedure.
    (import-proc raw openpgp-certificate-format/base64)))


(define (import-public-key-from-file file)
  (import-key-from-file import-openpgp-certificate file))

(define (import-private-key-from-file file)
  (import-key-from-file import-openpgp-private-key file))

The procedures import-public-key-from-file and import-private-key-from-file can be passed a file name. They return an OpenPGP public key and private key object, respectively (see section OpenPGP key objects).

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.4 Guile Reference

This chapter documents GnuTLS Scheme procedures available to Guile programmers.

11.4.1 Core Interface   Bindings for core GnuTLS.
11.4.2 Extra Interface   Bindings for GnuTLS-Extra.
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.4.1 Core Interface

This section lists the Scheme procedures exported by the (gnutls) module (see (guile)The Guile module system section `The Guile module system' in The GNU Guile Reference Manual). This module is licenced under the GNU Lesser General Public Licence, version 2.1 or later.

Scheme Procedure: set-log-level! level

Enable GnuTLS logging up to level (an integer).

Scheme Procedure: set-log-procedure! proc

Use proc (a two-argument procedure) as the global GnuTLS log procedure.

Scheme Procedure: x509-certificate-subject-alternative-name cert index

Return two values: the alternative name type for cert (i.e., one of the x509-subject-alternative-nacode> values) and the actual subject alternative name (a string) at index. Both values are #f if no alternative name is available at index.

Scheme Procedure: x509-certificate-subject-key-id cert

Return the subject key ID (a u8vector) for cert.

Scheme Procedure: x509-certificate-authority-key-id cert

Return the key ID (a u8vector) of the X.509 certificate authority of cert.

Scheme Procedure: x509-certificate-key-id cert

Return a statistically unique ID (a u8vector) for cert that depends on its public key parameters. This is normally a 20-byte SHA-1 hash.

Scheme Procedure: x509-certificate-version cert

Return the version of cert.

Scheme Procedure: x509-certificate-key-usage cert

Return the key usage of cert (i.e., a list of key-usacode> values), or the empty list if cert does not contain such information.

Scheme Procedure: x509-certificate-public-key-algorithm cert

Return two values: the public key algorithm (i.e., one of the pk-algoritcode> values) of cert and the number of bits used.

Scheme Procedure: x509-certificate-signature-algorithm cert

Return the signature algorithm used by cert (i.e., one of the sign-algoritcode> values).

Scheme Procedure: x509-certificate-matches-hostname? cert hostname

Return true if cert matches hostname, a string denoting a DNS host name. This is the basic implementation of RFC 2818 (aka. HTTPS).

Scheme Procedure: x509-certificate-issuer-dn-oid cert index

Return the OID (a string) at index from cert's issuer DN. Return #f if no OID is available at index.

Scheme Procedure: x509-certificate-dn-oid cert index

Return OID (a string) at index from cert. Return #f if no OID is available at index.

Scheme Procedure: x509-certificate-issuer-dn cert

Return the distinguished name (DN) of X.509 certificate cert.

Scheme Procedure: x509-certificate-dn cert

Return the distinguished name (DN) of X.509 certificate cert. The form of the DN is as described in RFC 2253.

Scheme Procedure: pkcs8-import-x509-private-key data format [pass [encrypted]]

Return a new X.509 private key object resulting from the import of data (a uniform array) according to format. Optionally, if pass is not #f, it should be a string denoting a passphrase. encrypted tells whether the private key is encrypted (#t by default).

Scheme Procedure: import-x509-private-key data format

Return a new X.509 private key object resulting from the import of data (a uniform array) according to format.

Scheme Procedure: import-x509-certificate data format

Return a new X.509 certificate object resulting from the import of data (a uniform array) according to format.

Scheme Procedure: server-session-psk-username session

Return the username associated with PSK server session session.

Scheme Procedure: set-psk-client-credentials! cred username key key-format

Set the client credentials for cred, a PSK client credentials object.

Scheme Procedure: make-psk-client-credentials

Return a new PSK client credentials object.

Scheme Procedure: set-psk-server-credentials-file! cred file

Use file as the password file for PSK server credentials cred.

Scheme Procedure: make-psk-server-credentials

Return new PSK server credentials.

Scheme Procedure: peer-certificate-status session

Verify the peer certificate for session and return a list of certificate-status values (such as certificate-status/revoked), or the empty list if the certificate is valid.

Scheme Procedure: set-certificate-credentials-verify-flags! cred [flags...]

Set the certificate verification flags to flags, a series of certificate-verify values.

Scheme Procedure: set-certificate-credentials-verify-limits! cred max-bits max-depth

Set the verification limits of peer-certificate-status for certificate credentials cred to max_bits bits for an acceptable certificate and max_depth as the maximum depth of a certificate chain.

Scheme Procedure: set-certificate-credentials-x509-keys! cred certs privkey

Have certificate credentials cred use the X.509 certificates listed in certs and X.509 private key privkey.

Scheme Procedure: set-certificate-credentials-x509-key-data! cred cert key format

Use X.509 certificate cert and private key key, both uniform arrays containing the X.509 certificate and key in format format, for certificate credentials cred.

Scheme Procedure: set-certificate-credentials-x509-crl-data! cred data format

Use data (a uniform array) as the X.509 CRL (certificate revocation list) database for cred. On success, return the number of CRLs processed.

Scheme Procedure: set-certificate-credentials-x509-trust-data! cred data format

Use data (a uniform array) as the X.509 trust database for cred. On success, return the number of certificates processed.

Scheme Procedure: set-certificate-credentials-x509-crl-file! cred file format

Use file as the X.509 CRL (certificate revocation list) file for certificate credentials cred. On success, return the number of CRLs processed.

Scheme Procedure: set-certificate-credentials-x509-trust-file! cred file format

Use file as the X.509 trust file for certificate credentials cred. On success, return the number of certificates processed.

Scheme Procedure: set-certificate-credentials-x509-key-files! cred cert-file key-file format

Use file as the password file for PSK server credentials cred.

Scheme Procedure: set-certificate-credentials-rsa-export-parameters! cred rsa-params

Use RSA parameters rsa_params for certificate credentials cred.

Scheme Procedure: set-certificate-credentials-dh-parameters! cred dh-params

Use Diffie-Hellman parameters dh_params for certificate credentials cred.

Scheme Procedure: make-certificate-credentials

Return new certificate credentials (i.e., for use with either X.509 or OpenPGP certificates.

Scheme Procedure: pkcs1-export-rsa-parameters rsa-params format

Export Diffie-Hellman parameters rsa_params in PKCS1 format according for format (an x509-certificate-format value). Return a u8vector containing the result.

Scheme Procedure: pkcs1-import-rsa-parameters array format

Import Diffie-Hellman parameters in PKCS1 format (further specified by format, an x509-certificate-format value) from array (a homogeneous array) and return a new rsa-params object.

Scheme Procedure: make-rsa-parameters bits

Return new RSA parameters.

Scheme Procedure: set-anonymous-server-dh-parameters! cred dh-params

Set the Diffie-Hellman parameters of anonymous server credentials cred.

Scheme Procedure: make-anonymous-client-credentials

Return anonymous client credentials.

Scheme Procedure: make-anonymous-server-credentials

Return anonymous server credentials.

Scheme Procedure: set-session-dh-prime-bits! session bits

Use bits DH prime bits for session.

Scheme Procedure: pkcs3-export-dh-parameters dh-params format

Export Diffie-Hellman parameters dh_params in PKCS3 format according for format (an x509-certificate-format value). Return a u8vector containing the result.

Scheme Procedure: pkcs3-import-dh-parameters array format

Import Diffie-Hellman parameters in PKCS3 format (further specified by format, an x509-certificate-format value) from array (a homogeneous array) and return a new dh-params object.

Scheme Procedure: make-dh-parameters bits

Return new Diffie-Hellman parameters.

Scheme Procedure: set-session-transport-port! session port

Use port as the input/output port for session.

Scheme Procedure: set-session-transport-fd! session fd

Use file descriptor fd as the underlying transport for session.

Scheme Procedure: session-record-port session

Return a read-write port that may be used to communicate over session. All invocations of session-port on a given session return the same object (in the sense of eq?).

Scheme Procedure: record-receive! session array

Receive data from session into array, a uniform homogeneous array. Return the number of bytes actually received.

Scheme Procedure: record-send session array

Send the record constituted by array through session.

Scheme Procedure: set-session-credentials! session cred

Use cred as session's credentials.

Scheme Procedure: cipher-suite->string kx cipher mac

Return the name of the given cipher suite.

Scheme Procedure: set-session-default-export-priority! session

Have session use the default export priorities.

Scheme Procedure: set-session-default-priority! session

Have session use the default priorities.

Scheme Procedure: set-session-certificate-type-priority! session items

Use items (a list) as the list of preferred certificate-type for session.

Scheme Procedure: set-session-protocol-priority! session items

Use items (a list) as the list of preferred protocol for session.

Scheme Procedure: set-session-kx-priority! session items

Use items (a list) as the list of preferred kx for session.

Scheme Procedure: set-session-compression-method-priority! session items

Use items (a list) as the list of preferred compression-method for session.

Scheme Procedure: set-session-mac-priority! session items

Use items (a list) as the list of preferred mac for session.

Scheme Procedure: set-session-cipher-priority! session items

Use items (a list) as the list of preferred cipher for session.

Scheme Procedure: set-server-session-certificate-request! session request

Tell how session, a server-side session, should deal with certificate requests. request should be either certificate-request/request or certificate-request/require.

Scheme Procedure: session-our-certificate-chain session

Return our certificate chain for session (as sent to the peer) in raw format (a u8vector). In the case of OpenPGP there is exactly one certificate. Return the empty list if no certificate was used.

Scheme Procedure: session-peer-certificate-chain session

Return the a list of certificates in raw format (u8vectors) where the first one is the peer's certificate. In the case of OpenPGP, there is always exactly one certificate. In the case of X.509, subsequent certificates indicate form a certificate chain. Return the empty list if no certificate was sent.

Scheme Procedure: session-client-authentication-type session

Return the client authentication type (a credential-type value) used in session.

Scheme Procedure: session-server-authentication-type session

Return the server authentication type (a credential-type value) used in session.

Scheme Procedure: session-authentication-type session

Return the authentication type (a credential-type value) used by session.

Scheme Procedure: session-protocol session

Return the protocol used by session.

Scheme Procedure: session-certificate-type session

Return session's certificate type.

Scheme Procedure: session-compression-method session

Return session's compression method.

Scheme Procedure: session-mac session

Return session's MAC.

Scheme Procedure: session-kx session

Return session's kx.

Scheme Procedure: session-cipher session

Return session's cipher.

Scheme Procedure: alert-send session level alert

Send alert via session.

Scheme Procedure: alert-get session

Get an aleter from session.

Scheme Procedure: rehandshake session

Perform a re-handshaking for session.

Scheme Procedure: handshake session

Perform a handshake for session.

Scheme Procedure: bye session how

Close session according to how.

Scheme Procedure: make-session end

Return a new session for connection end end, either connection-end/server or connection-end/client.

Scheme Procedure: gnutls-version

Return a string denoting the version number of the underlying GnuTLS library, e.g., "1.7.2".

Scheme Procedure: x509-private-key? obj

Return true if obj is of type x509-private-key.

Scheme Procedure: x509-certificate? obj

Return true if obj is of type x509-certificate.

Scheme Procedure: psk-client-credentials? obj

Return true if obj is of type psk-client-credentials.

Scheme Procedure: psk-server-credentials? obj

Return true if obj is of type psk-server-credentials.

Scheme Procedure: srp-client-credentials? obj

Return true if obj is of type srp-client-credentials.

Scheme Procedure: srp-server-credentials? obj

Return true if obj is of type srp-server-credentials.

Scheme Procedure: certificate-credentials? obj

Return true if obj is of type certificate-credentials.

Scheme Procedure: rsa-parameters? obj

Return true if obj is of type rsa-parameters.

Scheme Procedure: dh-parameters? obj

Return true if obj is of type dh-parameters.

Scheme Procedure: anonymous-server-credentials? obj

Return true if obj is of type anonymous-server-credentials.

Scheme Procedure: anonymous-client-credentials? obj

Return true if obj is of type anonymous-client-credentials.

Scheme Procedure: session? obj

Return true if obj is of type session.

Scheme Procedure: error->string enumval

Return a string describing enumval, a error value.

Scheme Procedure: certificate-verify->string enumval

Return a string describing enumval, a certificate-verify value.

Scheme Procedure: key-usage->string enumval

Return a string describing enumval, a key-usage value.

Scheme Procedure: psk-key-format->string enumval

Return a string describing enumval, a psk-key-format value.

Scheme Procedure: sign-algorithm->string enumval

Return a string describing enumval, a sign-algorithm value.

Scheme Procedure: pk-algorithm->string enumval

Return a string describing enumval, a pk-algorithm value.

Scheme Procedure: x509-subject-alternative-name->string enumval

Return a string describing enumval, a x509-subject-alternative-name value.

Scheme Procedure: x509-certificate-format->string enumval

Return a string describing enumval, a x509-certificate-format value.

Scheme Procedure: certificate-type->string enumval

Return a string describing enumval, a certificate-type value.

Scheme Procedure: protocol->string enumval

Return a string describing enumval, a protocol value.

Scheme Procedure: close-request->string enumval

Return a string describing enumval, a close-request value.

Scheme Procedure: certificate-request->string enumval

Return a string describing enumval, a certificate-request value.

Scheme Procedure: certificate-status->string enumval

Return a string describing enumval, a certificate-status value.

Scheme Procedure: handshake-description->string enumval

Return a string describing enumval, a handshake-description value.

Scheme Procedure: alert-description->string enumval

Return a string describing enumval, a alert-description value.

Scheme Procedure: alert-level->string enumval

Return a string describing enumval, a alert-level value.

Scheme Procedure: connection-end->string enumval

Return a string describing enumval, a connection-end value.

Scheme Procedure: compression-method->string enumval

Return a string describing enumval, a compression-method value.

Scheme Procedure: digest->string enumval

Return a string describing enumval, a digest value.

Scheme Procedure: mac->string enumval

Return a string describing enumval, a mac value.

Scheme Procedure: credentials->string enumval

Return a string describing enumval, a credentials value.

Scheme Procedure: params->string enumval

Return a string describing enumval, a params value.

Scheme Procedure: kx->string enumval

Return a string describing enumval, a kx value.

Scheme Procedure: cipher->string enumval

Return a string describing enumval, a cipher value.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.4.2 Extra Interface

This section lists the Scheme procedures exported by the (gnutls extra) module. This module is licenced under the GNU General Public Licence, version 3 or later.

Scheme Procedure: set-certificate-credentials-openpgp-keys! cred pub sec

Use certificate pub and secret key sec in certificate credentials cred.

Scheme Procedure: openpgp-keyring-contains-key-id? keyring id

Return #f if key ID id is in keyring, #f otherwise.

Scheme Procedure: import-openpgp-keyring data format

Import data (a u8vector) according to format and return the imported keyring.

Scheme Procedure: openpgp-certificate-usage key

Return a list of values denoting the key usage of key.

Scheme Procedure: openpgp-certificate-version key

Return the version of the OpenPGP message format (RFC2440) honored by key.

Scheme Procedure: openpgp-certificate-algorithm key

Return two values: the certificate algorithm used by key and the number of bits used.

Scheme Procedure: openpgp-certificate-names key

Return the list of names for key.

Scheme Procedure: openpgp-certificate-name key index

Return the indexth name of key.

Scheme Procedure: openpgp-certificate-fingerprint key

Return a new u8vector denoting the fingerprint of key.

Scheme Procedure: openpgp-certificate-fingerprint! key fpr

Store in fpr (a u8vector) the fingerprint of key. Return the number of bytes stored in fpr.

Scheme Procedure: openpgp-certificate-id! key id

Store the ID (an 8 byte sequence) of certificate key in id (a u8vector).

Scheme Procedure: openpgp-certificate-id key

Return the ID (an 8-element u8vector) of certificate key.

Scheme Procedure: import-openpgp-private-key data format [pass]

Return a new OpenPGP private key object resulting from the import of data (a uniform array) according to format. Optionally, a passphrase may be provided.

Scheme Procedure: import-openpgp-certificate data format

Return a new OpenPGP certificate object resulting from the import of data (a uniform array) according to format.

Scheme Procedure: openpgp-certificate-format->string enumval

Return a string describing enumval, a openpgp-certificate-format value.

Scheme Procedure: openpgp-keyring? obj

Return true if obj is of type openpgp-keyring.

Scheme Procedure: openpgp-private-key? obj

Return true if obj is of type openpgp-private-key.

Scheme Procedure: openpgp-certificate? obj

Return true if obj is of type openpgp-certificate.

[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated on July, 20 2009 using texi2html 1.76.