iofs-pfs.so

Microsoft PlaysForSure/MTP driver for io-fs

Syntax:

io-fs-media -dpfs,options

Runs on:

ARM, PowerPC, SH, x86

Options:

The options, in addition to the standard io-fs options, include:

Standard options

albdir
Treat .alb objects as directories. See Processing .alb objects below.
debug=n
Set the debug level.
mount=path
Specify the root of the filesystem for PFS devices. If path ends in '$#', then '$#' is replaced with a unit number. Example: -dpfs,mount=/fs/pfs'$#'
norefs
Don't have objects with references appear as directories. This disables playlists (for example,.alb and .pla files on some devices), but can significantly reduce synchronization time.
device=bus_no:device_no:interface_no
Start the iofs-pfs module with one program instance per PFS device. See Directed PFS device startup below.
zune=filename:filename
Specify the key files required by Zune devices. These files are obtained from Microsoft.

DRM options

The DRM options are optional. The iofs-pfs module supports DRM by default, and will function for non-DRM-protected playback even if the DRM support files aren't found on the target. The cfile, kfile, and sfile options are required only if you've changed the default location of these support files from /etc/pfs/.

drm
Don't allow PFS operation without DRM support (initialization fails if no DRM files are found).
cfile=filename
Specify the file containing a certificate to be used with DRM. The certificate file is obtained from Microsoft.
kfile=filename
Specify the file containing an RSA private key to be used with DRM. The key definition is 580 bytes. This file is obtained from Microsoft.
sfile=filename
Specify the file containing a serial number to be used with DRM. This file is expected to be 16 bytes in length. This file is obtained from Microsoft.

Directed PFS device startup

The device option allows the PFS driver to be started with one program instance per PFS device, rather than with a single program instance servicing multiple PFS devices.

To start the iofs-pfs module to support one PFS device per instance of iofs-pfs, use the device option and specify the paths for the bus, device and interface for each. For example, to handle two PFS devices (device=bus_no:device_no:interface_no):

# io-fs-media -dpfs,device=1:3:3
# io-fs-media -dpfs,device=2:4:6

Note: Bus, device and interface numbers are hexadecimal values.

Non-compliant device support options

These options allow you to customize how iofs-pfs interacts with legacy devices that don't fully support the PFS 2.01 specification.

For some of these “fix” options, you can apply the fix to all devices, specific devices (by specifying the vendor ID and device ID), all devices from a specific vendor ID (by specifying only the vendor ID), or a known list of devices that require the fix (by specifying known). In the options below, VVVV (vendor ID) and PPPP (device ID) are four-digit hexadecimal values. These options are additive, so you can use them more than once to add devices to the “fix” list. You can, for example, specify getfix=known,getfix=0e791129 to apply the fix to the known set of devices plus device 0x0e791129.

force[=VVVVPPPP | known]
Force USB devices to be considered as MTP devices.
getfix[=VVVVPPPP | known]
Apply a fix to MTP-extended get-object processing, so that devices have the entire file read in at once (since they do not handle extended duration get object transactions very well). By default, such devices are not supported. The amount of the file that gets read in is determined by the getsize option.
getsize[=size]
Allocate a fixed size buffer to read in the entire contents of objects when the attached PFS device does not support the GetPartialObject MTP command. By default, such devices are not supported. The size of the buffer may be between 1MB to 256MB, with a default of 10MB if no size is specified. Files that exceed the size of the buffer may still be read, but the content of the file will be truncated to fit into the buffer.
getx [=VVVVPPPP | known]
Use the extended-duration get-object mechanism to read files on the specified devices that do not support the GetPartialObject MTP command. If VVVVPPPP is not specified, then the extended duration processing will be used for all devices that do not support the GetPartialObject MTP command.

Note: The getfix option overrides this option, since some devices cannot handle the extended-duration get-object operation.

noplist[=VVVVPPPP | known]
Do not use property list MTP commands since they do not work properly.

Description:

This io-fs module provides a media filesystem interface for Microsoft PlaysForSure (PFS) / Media Transport Protocol (MTP) devices.

Enabling Digital Rights Management (DRM)

The PFS module for the io-fs filesystem supports Microsoft's Windows Media DRM 10 for WMA content on Playsforsure devices.

When PFS starts, it looks for the files cipher-aes.so and iofs-msdrm10.so in the lib/dll directory that is referenced by LD_LIBRARY_PATH. In addition to the dynamic object library files, there are three configuration files required for DRM, which are provided separately by Microsoft. If these files cannot be found, then DRM will not work. By default, iofs-pfs looks for these files in /etc/pfs. You may specify an alternate location for these files with the -kfile, -sfile, and -cfile options for io-fs.

To force PFS to use DRM, specify the drm command-line option when you start io-fs. All required files for using DRM must be present on the target system (see the Required Files section below).

Required Files

These files are required in the PATH on the target system if you start iofs-pfs with DRM enabled:

lib/dll/cipher-aes.so
A library that supports AES decryption.
lib/dll/iofs-msdrm10.so
A library that is used by the PFS module to provide DRM functionality.
/etc/pfs/drm_certificate.bin
The binary image of a certificate. It is typically a text file that you must get from Microsoft. The name and location of this file can be changed by using the -cfile option to io-fs. For example: -dpfs,cfile=/my_certificate.crt.
/etc/pfs/drm_serial_number.bin
This is a binary image of a 16-byte serial number. The serial number is embedded in a DRM message sent to PFS devices. You can change the name and location of this file by using the -sfile option to io-fs. For example: -dpfs,sfile=/my_sn.
/etc/pfs/drm_private_key.bin
A binary file that contains a definition of an RSA private key. You should specify as many fields as possible. You can change the name and location of this file by using the -kfile option to io-fs. For example: -dpfs,kfile=/my_key.key.

The format of the file is given by the following structure definition:

// this structure defines the contents of the PFS drm_private_key.bin file
// - contains information needed to define private key for RSA
// - all fields are big endian numbers (MSB first, LSB last)
// - all fields should contain appropriate values
struct RSA_binary_private_key_ {   // 580 bytes in total
    unsigned char bExponent[4];    // required: exponent for public key
    unsigned char bModulus[128];   // required: modulus for public key
    unsigned char bP[64];          // optional: prime number P
    unsigned char bQ[64];          // optional: prime number Q
    unsigned char bDP[64];         // optional: private exponent modulo P - 1
    unsigned char bDQ[64];         // optional: private exponent modulo Q - 1
    unsigned char bInverseQ[64];   // optional: inverse of prime number Q
    unsigned char bD[128];         // required: this is the private key exponent
};    // 580 bytes total

Processing .alb objects

The io-fs PFS driver albdir option instructs the driver to treat PFS “Abstract Audio Album” (or .alb) objects as directories containing the tracks in an album. The default iofs-pfs.so behavior is to treat these objects as files which cannot be used to access the tracks in an album directly (the tracks are located in a device-dependent location).

“Abstract Audio Album” objects contain references to tracks in a specific album on a PFS device. Whether it is better to use or not to use the albdir option depends on the specific directory and file organization of each PFS device; this option should be used when a directed synchronization of the “Albums” directory on a PFS device is more efficient than synchronizing the entire mediastore.

For more information about synchronizations, see the MME Developer's Guide chapter Synchronizing Media.

.alb objects as files

If the default driver behavior is used: treat .alb objects as files, MME synchronization operations will not find media files via .alb objects files, preventing duplicate entries in the database when the entire mediastore is synchronized. However, because .alb objects are treated as files, their contents can not be browsed with the directed synchronization API.

.alb objects as directories

If the optional driver behavior is used: treat .alb objects as directories, MME synchronization operations may synchronize the contents of .alb objects via multiple directories (such as the “Albums” and “Music” directories), and therefore make multiple entries in the MME database for each track listed in .alb objects. However, because .alb objects are treated as directories, their contents can be browsed with the MME directed synchronization or explorer APIs.

Files:

See Required Files for a list of files required when you enable DRM.

See also:

iofs-ipod.so, io-fs-media, mme