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, BeOS, Windows 98/ME, Windows NT/2000/XP, Mac OS X, Solaris, HP-UX and OS/2.
- adaptability: unlike most similar projects, libdvdcss doesn't 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 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. On rare cases this may fail because there is not enough encrypted data on the disc to perform a statistical attack, but in 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 store 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.