[gnutls-dev] GnuTLS OpenPGP key support

[Werner Koch]

On Tue, 11 May 2004 14:34:46 +0300, Nikos Mavroyanopoulos said:

> On Tuesday 11 May 2004 13:31, Werner Koch wrote:
>> On Sun, 11 Apr 2004 02:35:39 +0300, Nikos Mavroyanopoulos said:
>> > Currently it would help having a second implementation of the openpgp
>> > draft.
>> Did you asked the Caudium or Roxen folks?
> No. I don't know them.

There is a mailing list caudium-general at caudium.net and other stuff as
well. www.gnupg.org runs Caudium.

Caudium and Rozen both use their own SSL implementation which comes
with the Pike language.  Below is some documentation on Pike's SSL.


Salam-Shalom,

   Werner


=== snip ===
Overview of the SSL implementation.

FILES

  alert.pike:      Used for creating the alert packets we transmit.
  cipher.pike:     Encryption and MAC algorithms used in SSL.
  connection.pike: SSL packet layer. Inherits handshake.
                   Described below.
  constants.pike:  Protocol constants.
  context.pike:    "Context" state (see below).
  handshake.pike:  SSL handshake and key exchange.
  https.pike:      Dummy https-server. (*)
  packet.pike:     Handle formatting and parsing of packets.
  server.pike:     Not used.
  session.pike:    Session state (see below).
  sslfile.pike:    Interface similar to Stdio.File. Inherits
                   connection and Stdio.File.
  sslport.pike:    Interface similar to Stdio.Port. (*)
  state.pike:      Encryption state.

(*) These files are not currently used by Roxen, and may suffer some
bit-decay.


STATE

There's lot of state in an SSL-server, at several levels. We start at
the top.

SSL.context keeps the state that is shared by all SSL-connections for
one server (or one port). It includes policy configuration, a server
certificate, the server's private key(s), etc. It also includes the
session cache.

SSL.session: The most important information in a session object is a
choice of encryption algorithms and a "master secret" created by
keyexchange with a client. Each connection can either do a full key
exchange to established a new session, or reuse a previously
established session. That is why we have the session abstraction and
the session cache. Each session is used by one or more connections, in
sequence or simultaneously.

It is also possible to change to a new session in the middle of a
connection.

SSL.handshake keeps the state relevant for SSL handshaking. This
includes a pointer to a context object (which doesn't change), various
buffers, a pointer to a session object (reuse or created as
appropriate), and pending read and write states being negotiated.

Each connection will have two sets or read and write state: The
current read and write states used for encryption, and pending read
and write states to be taken into use when the current keyexchange
handshake is finished.

SSL.connection inherits SSL.handshake, and in addition to the state in
the handshake super class, it contains the current read and write
states, packet queues. This object is responsible for receiving and
sending packets, processing handshake packets, and providing a clear
text packages for some application.

SSL.state: At last, the state objects. As described above, a
connection switches from one set of state objects to another, one or
more times during its lifetime. Each state object handles a one-way
stream of packets, and operates in either decryption or encryption
mode.


METHODS and ATTRIBUTES

When describing these classes in more detail, let's start from the
other end.

SSL.state

  object session

    For information about the used algorithms.

  object mac

    Message Authentication Code

  object crypt

    Encryption or decryption object

  object seq_num

    64-bit sequence number

  object decrypt_packet(object packet)

    Decrypts a packet (including inflating and MAC-verification, if
    needed). On success, returns the decrypted packet. On failure,
    returns an alert packet. These cases are distinguished by looking
    at the is_alert attribute of the returned packet.

  object encrypt_packet(object packet)

    Encrypts a packet (including deflating and MAC-generation).


SSL.session (inherits cipher)

  string identity

    Session identifier

  int compression_algorithm

    Always COMPRESSION_null.

  int cipher_suite

    Constant defining a choice of keyexchenge, encryption and mac
    algorithm.

  object cipher_spec

    Information about the encryption method derived from the
    cipher_suite. 

  int ke_method

    Key exchange method, also derived from the cipher_suite.

  string master_secret

    Secret shared with the client. Used for deriving the actual keys.

  void set_cipher_suite(int suite)
  void set_compression_method(int compr)

  array new_server_states(string client_random, string server_random)

    Computes a new set of encryption stetes, derived from the
    client_random, server_random and master_secret strings. Returns an
    array ({ read_state, write_state }).

  array new_client_states(string client_random, string server_random)

    Similar function for the client end.


SSL.context

  object rsa

    The server's private key

  object long_rsa
  object short_rsa

    Temporary, non-certified, private keys, used with a
    server_key_exchange message. The rules are as follows:

    If the negotiated cipher_suite has the "exportable" property, and
    short_rsa is not zero, send a server_key_exchange message with the
    (public part of) the short_rsa key.

    If the negotiated cipher_suite does not have the exportable
    property, and long_rsa is not zero, send a server_key_exchange
    message with the (public part of) the long_rsa key.

    Otherwise, dont send any server_key_exchange message.

  function(int:string) random;

    Used to generate random cookies for the hello-message. If we use
    the RSA keyexchange method, and this is a server, this random
    number generator is not used for generating the master_secret.

  array(string) certificates;

    The server's certificate, or a chain of certificates, with the
    server's certificate first and root certificate last.

  array(int) preferred_auth_methods

    For client authentication. Used only if auth_level is AUTH_ask or
    AUTH_require.

  array(int) preferred_suites

    Cipher suites we want the server to support, best first. 

  array(int) preferred_compressors

    Always ({ COMPRESSION_null })

  int use_cache

    Non-zero to enable cahing of sessions

  int session_lifetime

    Sessions are removed from the cache when they are older than this
    limit (in seconds). Sessions are also removed from the cache if a
    connection using the session dies unexpectedly.

  void export_mode()

    Change the preferred_suites variable to use only exportable
    algorithms. 

  object new_session()

    Create a new session.

  void record_session(object s)

    Add a session to the cache (if caching is enabled).

  void purge_session(object s)

    Remove a session from the cache.

  object lookup_session(string id)

    Lookup a session identifier in the cache. Returns the
    corresponding session, or zero if it is not found or caching is
    disabled.


SSL.handshake

  int auth_level

    Policy for client authentication. One of AUTHLEVEL_none,
    AUTHLEVEL_ask and AUTHLEVEL_require.

  array(string) authorities

    Array of authorities that are accepted for client certificates.
    The client will only send certificates that are signed by any of
    these authorities. The string is the DER-encoded issuer.

  object session
  object context

  object pending_read_state
  object pending_write_state

  int handshake_state
  int certificate_state
  int expect_change_cipher

  string my_random
  string other_random

    Random cookies, sent and received with the hello-messages.

  void send_packet(object packet, int|void fatal)

    Prototype. Must be defined in inheriting classes, i.e.
    SSL.connection.

  int handle_handshake(int type, string data, string raw)

    Do handshake processing. Type is one of HANDSHAKE_*, data is the
    contents of the packet, and raw is the raw packet received (needed
    for supporting SSLv2 hello messages).

    This function returns 0 if hadshake is in progress, 0 if handshake
    is finished, and -1 if a fatal error occured. It uses the
    send_packet() function to trasnmit packets.

  void create(int is_server)

    Only create(1) is implemented.


SSL.connection (inherits SSL.handshake)

  object current_read_state
  object current_write_state

  void create(int is_server)

  void set_alert_callback(function(object,int|object,string:void) callback)

    Installs a callback that is called if a bad packet is received.
    Used to implement Roxen's https->http fallback redirect.

  object recv_packet(string data)

    Low-level recieve handler. Returns a packet, an alert, or zero if
    more data is needed to get a complete packet.

  void send_packet(object packet, int|void priority)

    Queues a packet for write.

  string|int got_data(string s)

    Main receive handler. Returns a string of received application
    data, or 1 if a close was received, or -1 if an error occured.

    This function is intended to be called from an i/o read callback.

  string|int to_write()

    Extracts data from the packet queues. Returns "" if there are no
    pending packets, 1 of the connection is being closed politely,
    and -1 if the connection died unexpectedly.

    This function is intended to be called from an i/o write callback.

  void send_close()

    Initiate close.