# Module: LIBSSL

## About this module

The libssl module performs the following tasks

- Communication with servers supporting the SSL and TLS protocol
- Administrates user's security preferences
- Administrates the CA certificate and client certificate databases (including private keys)
- Performs encryption and decryption of passwords for Wand and M2.
- Creates an abstract class interface to all encryption methods (public key, symmetric and digest) supported by the module
- Creates an abstract class interface to handling of X509 certificates
- Administrates UI access to information about X509 certificates and databases, as well as installation

NOTE: Unless authorized in advance by the core-network group, ALL cryptographic operations must be performed through the APIs provided by this module. Direct use of thirdparty crypto module APIs (such as libopeay) WILL NOT be authorized, except for modules that emulate the corresponding APIs provided by this module.

Additionally, ALL use of external thirdparty libraries that replace libssl as the SSL implementation MUST be inspected and approved by the libssl module owners before being shipped, and after major changes.

### Supported protocols:

- SSL v3
- TLS 1.0
- TLS 1.1
- TLS 1.2 (Jan 21, 2008: Not yet debugged)

### Crypto library

Present versions uses OpenSSL 0.9.7d.

### Supported formats and methods

- RSA
- Diffie-Hellman
- DSA
- AES
- RC4 (called C4)
- 3DES (Triple DES)
- MD5
- SHA-1 (called SHA)
- SHA-256
- SHA-384
- SHA-512
- X509
- PKCS 7 (for certificate distribution)
- Netscape multicert format
- PKCS 12 for certificate and private key export/import
- Netscape SPKAC (for certificate requests)
- PKCS 10 (for certificate requests)
- PEM (Base64 encoding format of the various certificate formats)

## Interface overview and API documentation

The primary APIs for the libssl module are

g_ssl_api
  The g_ssl_api object is an instance of the SSL_API class (defined in "modules/libssl/ssl_api.h")
g_ssl_api->Generate_SSL()
  This function is used to create an SSL protocol object that will administrate the SSL connction to a given server and port.
SSL_Options
  Administrates all certificates and secure protocol options. For more information see the Security Preferences and Ask Password description.
SSL_Certificate_DisplayContext
  This class handles the display of certificates, and the associated actions. For more information see the Certificate dialog API.
SSL_dialog_config
  Dialog configuration structure. For use see the struct's documentation in doxy.

External Certificate Repository
  Allows a product to register a certificate repository that will be searched if Opera's local repository does not contain a Root. The product may also disable Opera's internal repository (including the UI, defaulting to fail). The OpenSSL version is documented here.
External Client Certificate and Private Key provider
  Allows a product to register a provider of SSL/TLS Client Certificates and associated Private Keys. This allows the product to provide automatic Client Authentication for specific servers. (This will later be expanded to support smartcards). Further documentation of the API can be found here.

  ## Implementation description

  The SSL protocol implementation is implemented as state machine that calls specific handling functions based on the current state and the received messages. This code performs almost all of the handshake negotiation

  The representation of records are represented as classes which are able to encode and/or decode the actual binary representation of the the record

  The SSL_RecordLayer class handles the actual decoding of SSL network packets, as well as the decryption and encryption of records.

  All handling of encryption and digest algorithms and certificate decoding and storage, as well as key-exchange and protocolversion specific operations are performed by subclasses of interface baseclasses. This permits a reasonable flexibility when adding new methods or new protocol versions, especially when the new methods are contained in a library different from the current crypto library. It also makes it easier to change crypto libraries, if that is required.

  ### Footprint

  The module is fairly large (in the top 10 of core-2). Unused functionality has been disabled.

  It is possible that a complete rewrite could reduce footprint somewhat, but probably not much, as has been observed in the diffie_3 rewrite. One possible exception is (possibly) if the current flexibility in cipher handling, digest and certificate handling was removed, resulting in a library that cannot easily be extented, except through the crypto library API.

  A contributing factor to the footprintsize is the preshipped root certificate database, which may exceed 50 KB.

  ### Dynamic memory use and OOM handling

  The module uses almost exclusively allocated memory in its operation, most of these have a relatively short lifespan. The structures with the longest timespans are stored either in the SSL_Options manager, or individual ServerName structures. Both of these are destroyed either at exit or when they are no longer used.

  OOM policies

    Most of the protocol code uses the SSL modules internal error code system to register errors. This system will raise the MemoryManager class' OOM condition flag if there are any OOM conditions. In case of an OOM the protocol will take the step required to shut down operations of the connection that failed.

    Some classes, in particular SSL_Options, and API functions are capable of LEAVing or OP_STATUS in case of OOM, in which case it is the caller's responsibility to catch and act on the error.

  Who handles OOM?

    The caller are responsible for handling TRAPped LEAVEs and OP_STATUS error codes. In the case of the MemoryManager flag the responsibility falls on the code dedicated to handling this flag.

  Flow

    Most of the module consists of stateengines (protocol, loadable structures), which are driven either by network events, internal messages, or external input. Functions that are not part of this usually perform specific tasks.

  Heap memory usage
    - Each protocol objects uses some memory, but this is usually limited to buffers.
    - SSL_Options stores the certificate database, whose size depends on the size of the certificats and/or private keys. The root certificate database is at least 50 KB
    - Some SSL information is stored in ServerName objects. These may include server certificates (of unknown size) and encryption key information..
  Stack memory usage

    The module uses little stack space, but may create various temporary vectors and dataprocessing objects, which may exceed 200 bytes.

  Static memory usage

    The module uses a few global variables for the main SSL_Options object and factory objects for the main implementations for MD5, SHA, certificates and 3DES

    There are a number of hardcoded tables, the most significant of which is the cipher suite list in sslinit1.cpp, which is several KB. These can be implemented as allocated arrays on some platforms

  Caching and freeing memory

    ServerName objects contain a cache for accepted certificate and secure sessions. Unless used by a connection no more than one object of these will exist for any given ServerName and port. The cached objects can be freed through the URL module's Delete Private Data API (sensitive data)

  Freeing memory on exit

    The allocated memory is freed by the connections when they are closed, the SSL_Options securityManager when it is destroyed by Terminate() and the ServerName objects when they are deleted upon destruction by the URL_Manager.

  Temp buffers
    - GetTempBuf() is used as a work buffer in the certificate verification SSLEAY_CertificateHandler::Verify_callback function
    - GetTempBufUni() is used as work buffer by SSL_Certificate_Comment::Init().

    No attempts are made to detect that they are already in use. The actual functions in which they are used are leaf functions or calls only leaf functions.

  Memory tuning

    It is not possible to tune the module's memory usage.

  Tests

    Selftests, but no checks on memory usage

  Coverage

    Surf on secure sites that exercises various conditions (wrong servername, verification errors etc.)

  Design choices

    The primary classes are state engines. The primary reason is that the actions are either triggered by outside events, or they may not get complete data in on specific call.

  Improvements

    No improvements are planned