libdvdcss developer documentation

Introduction

libdvdcss is a simple library designed for accessing DVDs like a block device without having to bother about the decryption. The important features are:

• portability: Currently supported platforms are GNU/Linux, FreeBSD, NetBSD, OpenBSD, Haiku, Mac OS X, Solaris, QNX, OS/2, and Windows 2000 or later.
• adaptability: Unlike most similar projects, libdvdcss does not require the region of your drive to be set and will try its best to read from the disc even in the case of a region mismatch.
• simplicity: A DVD player can be built around the libdvdcss API using no more than 4 or 5 library calls.

libdvdcss is free software, released under the GNU General Public License. This ensures that libdvdcss remains free and used only with free software.

The libdvdcss API

The complete libdvdcss programming interface is documented in the dvdcss.h file.

Environment variables

Some environment variables can be used to change the behavior of libdvdcss without having to modify the program which uses it. These variables are:

• DVDCSS_VERBOSE: Sets the verbosity level.
  • 0 outputs no messages at all.
  • 1 outputs error messages to stderr.
  • 2 outputs error messages and debug messages to stderr.

• DVDCSS_METHOD: Sets the authentication and decryption method that libdvdcss will use to read scrambled discs. Can be one of title, key or disc.
  • key is the default method. libdvdcss will use a set of calculated player keys to try and get the disc key. This can fail if the drive does not recognize any of the player keys.
  • disc is a fallback method when key has failed. Instead of using player keys, libdvdcss will crack the disc key using a brute force algorithm. This process is CPU intensive and requires 64 MB of memory to store temporary data.
  • title is the fallback when all other methods have failed. It does not rely on a key exchange with the DVD drive, but rather uses a crypto attack to guess the title key. In rare cases this may fail because there is not enough encrypted data on the disc to perform a statistical attack, but on the other hand it is the only way to decrypt a DVD stored on a hard disc, or a DVD with the wrong region on an RPC2 drive.

• DVDCSS_RAW_DEVICE: Specify the raw device to use. Exact usage will depend on your operating system, the Linux utility to set up raw devices is raw(8) for instance. Please note that on most operating systems, using a raw device requires highly aligned buffers: Linux requires a 2048 bytes alignment (which is the size of a DVD sector).

• DVDCSS_CACHE: Specify a directory in which to cache title key values. This will speed up descrambling of DVDs which are in the cache. The DVDCSS_CACHE directory is created if it does not exist, and a subdirectory is created named after the DVD's title or manufacturing date. If DVDCSS_CACHE is not set or is empty, libdvdcss will use the default value which is "${HOME}/.dvdcss/" under Unix and "C:\Documents and Settings\$USER\Application Data\dvdcss\" under Win32. The special value "off" disables caching.