
OpenSSL Cell/B.E. Engine

Copyright 2008 Sony Corporation


What is this?
=============

This is an implementation of OpenSSL which is accelerated and/or
offloaded by Cell Broadband Engine (Cell/B.E). It is implemented as an
'ENGINE', which is an OpenSSL's component to support external hardware
devices.


Which functions bring benefits?
===============================

Currently, the functions below are accelerlated and/or offloaded:

* message digests

  md2, md4, md5, sha, sha1, sha224, sha256, sha384, sha512, ripemd160

* ciphers

  aes-128-cbc, aes-128-ecb, aes-128-ofb, aes-128-cfb, aes-128-cfb1, aes-128-cfb8
  aes-192-cbc, aes-192-ecb, aes-192-ofb, aes-192-cfb, aes-192-cfb1, aes-192-cfb8
  aes-256-cbc, aes-256-ecb, aes-256-ofb, aes-256-cfb, aes-256-cfb1, aes-256-cfb8


Compiling
=========

1. Setup the development environment for Cell/B.E.

   At least, the following programs are required:

   * spu-gcc, spu-binutils and spu-newlib (SPU toolchain)
   * libspe2 (SPE runtime management library)

2. Install a regular OpenSSL with dynamic engine support.

   You can check whether your system has the OpenSSL with dynamic
   engine support by:

     # openssl engine

   If your OpenSSL supports dynamic engine, the message following is
   displayed:

     (dynamic) Dynamic engine loading support

   Make sure that not only runtime of the OpenSSL but also development
   stuffs (e.g. library headers) are installed.

3. Get an OpenSSL source archive and extract it.

     # tar zxf openssl-0.9.8h.tar.gz

   That source is used only to generate SPE side code, and it never
   affects PPE side code. It is strongly recommended to use the same
   version of the OpenSSL as the PPE's one.

4. Build the Cell/B.E. engine.

   Run make command in this directory.

     # make OPENSSL_DIR=../openssl-0.9.8h

   Note that you will need to add
   "OPENSSL_DIR=<OpenSSL-Source-Directory>" to the command line of the
   make.

   The following options are available:

   * OPENSSL_DIR=<OpenSSL-Source-Directory>

     The directory of the OpenSSL source code which was created at the
     step 3.
 
   * CROSS=<prefix-of-ppu-compilers>

     If you'd like to use another compiler than your system's default
     one, set the prefix of that to this option.

       # make OPENSSL_DIR=../openssl-0.9.8h CROSS=ppu-
 
   * SPU_CROSS=<prefix-of-spu-compilers>

     If you'd like to use another compiler's than spu-gcc,
     set the prefix of that to this option.

       # make OPENSSL_DIR=../openssl-0.9.8h SPU_CROSS=spu-elf-

   * ARCH_CFLAGS="<compiler-options>"

     If you'd like to build a binary for a different architecture from
     your compiler's default, set compiler flags to specify the
     architecture to this option:

       # make OPENSSL_DIR=../openssl-0.9.8h CROSS=ppu- ARCH_CFLAGS=-m32

   * RUNTIME_SYSTEM=<name-of-runtime-system>

     You can choose SPE runtime system to run SPE programs by the
     engine by setting this option.

     The following runtime systems are supported:

     - libspe2

       Use libspe2 directly.

     - mars

       Use MARS (Multicore Application Runtime System) as SPE runtime
       system. Default.

       # make OPENSSL_DIR=../openssl-0.9.8h RUNTIME_SYSTEM=mars


Testing
=======

You can test the built Cell/B.E. engine by running the following
command:

  # make check

If you use another runtime system than the default one, add
'RUNTIME_SYSTEM=<name>' to your command line:

  # make RUNTIME_SYSTEM=mars check

You can use other input data than default one by specifying
"TEST_DATA=<file-name>" in the command line.

  # make TEST_DATA=cd.iso check


Benchmarking
============

You can run benchmarks by running the following command:

  # make bench

If you use another runtime system than the default one, add
'RUNTIME_SYSTEM=<name>' to your command line:

  # make RUNTIME_SYSTEM=mars bench

Each benchmark is run by both of the original (non-engine) OpenSSL and
the Cell/B.E. engine.

The following options are available:

  BENCH_THREADS=<#-of-threads>
  BENCH_TYPE=<type>

There are two types of benchmarking.

1. Read input data from /dev/zero and write output data to /dev/null.

   The following options are available in addition to the above:

     BENCH_DATA_SIZE=<size>

2. Read input data from a file and write output data to another file.

   The following options are available in addition to the above:

     TEST_DATA=<input-file>

To switch between these types, specify BENCH_TYPE=<type> in the
command line:

  # make bench BENCH_TYPE=1 BENCH_DATA_SIZE=32M BENCH_THREADS=4
  # make bench BENCH_TYPE=2 TEST_DATA=/lib/libc.so.6


Installing
==========

To install the engine, just copy the shared object 'libcell.so' to
your system's OpenSSL engine directory.

For example, the engine directory of the Fedora 9 is
/usr/lib/openssl/engines/ (32bit) or /usr/lib64/openssl/engines/
(64bit).

Alternatively, you can copy the 'libcell.so' to your preferred
directory then set the directory to the environment variable
OPENSSL_ENGINES.


How to use
==========

a. openssl command

   You can use the engine with the openssl command by adding the
   option '-engine cell' to your command line.

     # openssl dgst -engine cell -sha1 -in dvd.iso

   Of course, only the supported commands with supported algorithmes
   by the engine are accelerated and/or offloaded. So if you specify
   the engine against unsupported commands, it will be just ignored,
   then default implementation (i.e. PPE side code) will be used.

b. OpenSSL API

   You also can directly utilize the engine in your own programs, via
   the OpenSSL API functions.

   Essentially, add following steps to your OpenSSL applications:

   1. Load engines

        ENGINE_load_builtin_engines();

   2. Get the engine

        ENGINE *engine = ENGINE_by_id("cell");

   3. Change the engine's parameters if needed

        ENGINE_ctrl_cmd(engine, "QUEUE_DEPTH", 4, NULL, NULL, 0);

      See the 'Control commands' section below for details.

   4. Initialize the engine

        ENGINE_init(engine);

   5. Use the engine by passing the engine to EVP functions.

        EVP_DigestInit_ex(ctx, md, engine);
        ...

   6. Finalize the engine

        ENGINE_finish(engine);

   7. Release the engine

        ENGINE_free(engine);

   8. Clean up OpenSSL

        ENGINE_cleanup();

   See the man page of 'engine' and the OpenSSL document
   'README.ENGINE' for details.

   The benchmarks 'bench_digest.c' and 'bench_cipher.c' in this
   directory should be sample programs.


Control commands
================

Following control commands are available:

* QUEUE_DEPTH (numeric)

  Specifies the depth of queues to pass data between PPE and SPE.

* UNIT_SIZE (numeric)

  Specifies the size of unit to pass data between PPE and SPE.

* TASK_PRIORITY (numeric)

  Specifies the priority of the engine's SPE tasks. The meaning of
  this value depends on the used SPE runtime system.


Notes
=====

* The digest/cipher algorithms are *NOT* optimized for SPE; i.e. the
  current implementation of the engine uses the original OpenSSL's
  ones without any modifications.

* Most ciphers of the engine are slower than the original (non-engine)
  implementation because OpenSSL has no asynchronous internal
  interface between the OpenSSL core and cipher engines.

* Copy operation of digest contexts (EVP_MD_CTX_copy) is not
  supported.


License
=======

This software, the OpenSSL Cell/B.E. Engine, is licensed under the
terms in the file 'LICENSE' in this directory.


Contact
=======

Use the mailing list below to discuss this engine:

  cbe-oss-dev@ozlabs.org
  https://ozlabs.org/mailman/listinfo/cbe-oss-dev


Notice
======

* "Cell Broadband Engine" is a trademark of Sony Computer
  Entertainment Inc.

* This product includes software developed by the OpenSSL Project for
  use in the OpenSSL Toolkit (http://www.openssl.org/)

---
EOF
