Documentation »  ACCESS Linux Platform Native Development »  Content Management »  Digital Rights Management

Design Overview ^TOP^

ACCESS Linux Platform includes a Digital Rights Management (DRM) component that is designed to be fully compliant with the Open Mobile Alliance (OMA) DRM version 1.0 specification. Because it is fully compliant, this component supports the following:

• Forward Lock (FL)¹
• Combined Delivery (CD)
• Separate Delivery (SD)
• Superdistribution

It securely stores DRM-protected content provided by content provider applications or services such as the Download Manager or the email client. The DRM Agent allows trusted content-rendering applications—such as Media Player or Picture Viewer—to retrieve DRM-protected content in accordance with the rules specified in the OMA DRM specification.

As ACCESS Linux Platform is an open operating system, special considerations must be applied to protect the content. The following security mechanisms are used:

• Access to DRM-protected content is only granted to trusted applications.
• DRM-protected content is stored encrypted (in standard DCF format). DRM files can reside on the device or on removable memory cards.
• Rights objects (RO) are stored in the Vault. Only trusted applications have access to rights objects.
• To simplify handling of DRM-protected files, the system stores all DRM-protected files in a designated directory.
• Only trusted applications are able to load and execute the functions exported by the DRM library (see <alp/alpdrm.h>).

The complete OMA DRM v1.0 specifications can be obtained from the Open Mobile Alliance's website, at http://www.openmobilealliance.org/release_program/drm_v1_0.html.

The DRM Trust Model ^TOP^

ACCESS Linux Platform applications are grouped into two categories: trusted and untrusted. Platform components and platform applications are always considered trusted. ACCESS Linux Platform assumes that trusted (signed) applications and operating system components behave correctly when dealing with DRM-protected content and follow the OMA DRM 1.0 standard. Untrusted applications are unsigned third-party applications. They are not given access to certain system resources and are not assumed to behave correctly when accessing DRM-protected content.

For example, when receiving DRM-protected content, the Download Manager identifies the correct received DRM content and calls the proper DRM functions to secure the content. As well, the WAP push component identifies the correct received DRM rights object and then turns to the Exchange Manager to call the appropriate DRM functions.

In order for trusted components to access rights objects stored in the Vault, they have to belong to either the "trusted" or the "root" groups.

Architecture ^TOP^

Figure 2.1 illustrates the basic DRM architecture.

Figure 2.1  DRM architecture

The DRM component is divided into two parts: a client library and a daemon (the DRM Agent). From the view of the DRM Agent, all applications and services that need to integrate with the DRM Agent fall into one of two categories: either Content Provider or Content Consumer. Accordingly, the DRM APIs are grouped into two sets, one for content providers and one for content consumers. Content provider APIs are listed under "Content Provider APIs." "Content Consumer APIs" lists the APIs to be used by DRM content consumers.

Content Providers ^TOP^

Figure 2.2 shows applications or services which are considered to provide DRM content. These applications and services integrate with the appropriate DRM capabilities of ACCESS Linux Platform.

Figure 2.2  DRM content providers

Content Consumers ^TOP^

Figure 2.3 lists those applications or services which are considered to be DRM content consumers and which therefore integrate with the appropriate DRM capabilities of ACCESS Linux Platform.

Figure 2.3  DRM content consumers

Features ^TOP^

The following sections detail some of the principal features of the ACCESS Linux Platform DRM component.

DRM Content Management ^TOP^

All DRM content, whether on the device or on an SD card, is stored in DCF format with the filename suffix .dcf. This means that Forward Lock and Combined Delivery content is encrypted and stored in DCF format when it arrives on an ACCESS Linux Platform device. For each new Forward Lock-protected file, a rights object without usage limitations is created. The DRM component stores DRM-protected content in a dedicated DRM folder for easier handling.

This approach enables DRM-protected content of any type to be freely moved to removable media, such as an SD card. Because the content is encrypted, it is secure and cannot be used on other devices.

Acquisition of Rights Objects ^TOP^

The acquisition of rights objects for Separate Delivery (SD) content is implemented at a high level. Consumer applications don't need to know the details of the rights issuer's address and the way to get the appropriate right objects. They just need to call the alp_drm_activate_drm_content_block() function, specifying the DRM content file for which the rights objects should be retrieved. The DRM Agent launches the web browser with the specified issuer address (the URL is embedded in the content file; it can be obtained by calling alp_drm_check_rights_info()). Once the user finishes the operation and confirms the purchase of the content, when the rights objects are delivered a notification is sent to the DRM Agent. The DRM agent then gets the rights objects from the WAP Push module and notifies the consumer application. It is important to note that consumer applications are blocked until the user either cancels the dialog or the rights object arrives.

Content Provider APIs ^TOP^

The following DRM APIs, exported through <alp/alpdrm.h> and <alp/alpdrm_ui.h>, are for use by DRM content providers.

alp_drm_add_content Function ^TOP^

Purpose

Adds a DRM file to the device or card. This function encrypts the file into DCF format if it is Forward Lock or Combined Delivery and returns the saved filename to the caller.

Prototype

alp_status_t alp_drm_add_content(
    const char *mimetype,
   const char *filename,
   const char *udi,
   gboolean keep,
   char **out_filename
);

alp_drm_add_license Function ^TOP^

Purpose

Adds a license (rights object) for a certain type. This function is called in the DRM daemon process and usually isn't used by providers.

Prototype

alp_status_t alp_drm_add_license(
    const char *mimetype,
   const char *filename
);

alp_drm_process_license_xml Function ^TOP^

Purpose

Processes a license. This function is called in the DRM daemon process and usually isn't used by providers.

Prototype

alp_status_t alp_drm_process_license_xml(
    const char *mimetype,
   const char *buffer,
   int size
);

Content Consumer APIs ^TOP^

The following APIs are intended for use by DRM content consumers.

alp_drm_is_drm_file Function ^TOP^

Purpose

Determine whether a file is a DRM file.

Prototype

gboolean alp_drm_is_drm_file(
   const char *filename
);

alp_drm_get_meta_data Function ^TOP^

Purpose

Get metadata, including the content ID, version, type, and vendor, the rights issuer, a URI for the appropriate icon, the delivery method, and a title and description appropriate to the content.

Prototype

alp_status_t alp_drm_get_meta_data(
    const char *filename,
   int flags,
   AlpDrmMetaInfo *info
);

alp_drm_free_meta_data Function ^TOP^

Purpose

Frees a metadata info structure obtained with alp_drm_get_meta_data().

Prototype

void alp_drm_free_meta_data(
    AlpDrmMetaInfo *info
);

alp_drm_check_rights_info Function ^TOP^

Purpose

Determine whether there is a rights object or rights for a specific type of permission (such as play, display, execute, print).

Prototype

alp_status_t alp_drm_check_rights_info(
    const char *filename,
   AlpDrmPermissionType permission_type,
   char **content_id,
   char **rights_issuer
);

alp_drm_get_file_constraints Function ^TOP^

Purpose

Get DRM file constraints for a specific type of permission (such as play, display, execute, print), given the name of the file.

Prototype

alp_status_t alp_drm_get_file_constraints(
    const char *filename,
   AlpDrmPermissionType permission_type,
   int *count,
   time_t *start_data_time,
   time_t *end_data_time,
   time_t *interval_start,
   time_t *interval_duration
);

alp_drm_get_constraints Function ^TOP^

Purpose

Get DRM constraints for a specific type of permission (such as play, display, execute, print), given the content ID.

Prototype

alp_status_t alp_drm_get_constraints(
    const char *content_id,
   AlpDrmPermissionType permission_type,
   int *count,
   time_t *start_data_time,
   time_t *end_data_time,
   time_t *interval_start,
   time_t *interval_duration
);

alp_drm_update_constraints Function ^TOP^

Purpose

Update a file's constraints. Content consumers should call this function shortly after it is clear that the user has begun consumption of the DRM file's contents.

Prototype

alp_status_t alp_drm_update_constraints(
    const char *content_id,
   AlpDrmPermissionType permission_type,
   int count
);

alp_drm_activate_drm_content_block Function ^TOP^

Purpose

Launch the browser to obtain a rights object for separate delivery.

Prototype

alp_status_t alp_drm_activate_drm_content_block(
    const char *content_id,
   const char *rights_issuer,
   GtkWindow *parent
);GtkWidget* alp_drm_detail_dialog_run(
   const gchar * filename,
   gboolean isdialog
);

Comments

When you invoke the alp_drm_detail_dialog_run function with isdialog=TRUE, the return GtkWidget* widget is a dialog. You must set the title for it (this is why there is no parameter named title), and if necessary, set the parents for it. The following illustration shows how to run this function in dialog mode:

Sometimes, there may be more than only one OK button in the dialog. In this case, invoke this function with isdialog=FALSE. The returned widget is a scrollwindow, and you can embed it into any other container, such as a dialog. The following figure shows how to run this function without dialog mode:

The three buttons in the preceding illustration are the action buttons created by the owner application. You may need this to deal with the response ID. Sample code for this function can be found
../app/tests/DRMTester.

The alp_drm_activate_drm_content_block function launches the web browser through the Exchange Manager. It blocks until either the rights object arrives or the user cancels the dialog. The dialog looks something like the following:

Figure 2.4 illustrates the working of this function. When the system boots and the daemon starts up, it registers to receive and handle special WAP Push messages. Then, a content consumer calls alp_drm_activate_drm_content_block(),

1. Using IPC the function registers with the daemon as waiting for a rights object.
2. After the user has confirmed the purchase, the rights object is sent to the daemon using WAP Push.
3. Upon receiving a rights object, the daemon checks the waiting list and notifies the client of the received object.

The content consumer can now consume the content using the "Content Access Functions" listed in the following section.

Figure 2.4  How alp_drm_activate_drm_content_block() operates

Content Access Functions ^TOP^

Purpose

Functions used by content consumers to access DRM content.

Prototype

FILE *alp_drm_fopen_with_permission(
   const char * filename,
   const char *mode,
   AlpDrmPermissionType permission_type
);

int alp_drm_fclose(
   FILE * fp
);

size_t alp_drm_fread(
   void *buf,
   size_t size,
   size_t count,
   FILE *fp
);

int alp_drm_fseek(
   FILE *fp,
   long offset,
   int whence
); // SEEK_SET,
   SEEK_CUR,
   SEEK_END

int alp_drm_ftell(
   FILE *fp
);

int alp_drm_ferror(
   FILE *fp
);

int alp_drm_feof(
   FILE *fp
);

Integration Considerations ^TOP^

This section describes how other components are seamlessly integrated with the DRM 1.0 component.

Integration with Download Manager ^TOP^

The DRM daemon registers two Exchange Manager verbs ("store" and "open") to store or render DRM content. Thus, there are two mechanisms by which Download Manager can store a DRM file: directly call DRM APIs, or send it to Exchange Manager.

Figure 2.5  Integration with the Download Manager

Integration with File Manager ^TOP^

Figure 2.6  Integration with the File Manager

Why does ACCESS Linux Platform allow the user to move FL or CD content to an SD card, but prevent the user from sending the content using other methods such as MMS, email, IM, or Bluetooth? There are two primary reasons:

• The user is allowed to directly save downloaded content to an SD card as this feature is required by OMA, and FL or CD is stored on the SD card in encrypted format. To be consistent, ACCESS Linux Platform allows the user to move FL or CD to an SD card in case the user has previously saved the content on device.
• Content cannot be sent using other methods because even if it was allowed, the receiver still cannot use the content: the file is encrypted and a rights object has been created just for the original device.

File Manager uses functionality provided by the Media Cataloger and its related Extractors. File Manager interacts with a special extractor to handle DCF files and integrate with the DRM Module.

Integration with Media Player ^TOP^

Figure 2.7  Integration with the Media Player

This alp_drm_activate_drm_content_block() function launches the browser application with the URL of the rights issuer. It blocks, showing a dialog until the rights object arrives or until the user cancels the dialog. As soon as the rights object is received (or when the user cancels the dialog), the function closes the dialog and returns.

Integration with MMS, IM, and Email ^TOP^

Figure 2.8  Integration with MMS, IM, and email

MMS, IM and email messages can contain attachments which are DRM-protected. Usually, these components need to maintain the relationship between the DRM-protected attachment and the message envelope after the protected attachment has been encrypted. This is done at the plug-in level. Plugins can either store DRM content by sending it to the Exchange Manager or they can use DRM APIs to retrieve the pathname; based on the returned pathname, they can maintain the relationship.

Integration with the WAP Push Module ^TOP^

Figure 2.9 illustrates the integration with the WAP Push module. Neither the WAP Push module nor the Exchange Manager need to do anything special for DRM content.

Figure 2.9  Integration with the WAP Push module

Backup/Restore ^TOP^

DRM-protected content files stored in the default DRM folder are backed up. However, data managed by the ACCESS Linux Platform Vault is not backed up. This means that during a restore operation, the DRM content files will be restored but the rights objects will not. ACCESS Linux Platform is not able to recover rights objects for content that was delivered as FL or CD content. SD content is handled like a superdistribution: the user is redirected to the rights issuer for purchase or, in certain cases if recognized by the server, issued a new rights object without charge.

Using DRM ^TOP^

The following sections illustrate how you perform a number of common DRM-related tasks.

Storing a DRM-Protected File ^TOP^

To store a DRM-protected file, trusted code can call the appropriate DRM functions directly. The DRM functions can only be used by trusted applications. In the case of storing a DRM-protected file, the relevant function is alp_drm_add_content(), as shown Listing 2.1:

In the following example, the filename variable is assumed to contain the pathname of the DRM file (.dm or .dcf, only .dcf supported in this release) to be saved. The mimetype variable should contain the correct MIME type, which should be "application/vnd.oma.drm.message" or "application/vnd.oma.drm.content".

Listing 2.1  Storing a DRM-protected file using DRM APIs

alp_status_t status; 
 
status = alp_drm_add_content(mimetype, filename, udi, FALSE,
	NULL); 

The above code ignores the new location of the saved file. If you need it, supply a non-NULL value for the final parameter and free the result when done, as shown here:

alp_status_t status; 
char *out_filename = NULL; 
 
status = alp_drm_add_content(mimetype, filename, udi, FALSE,
	&out_filename); 
if(ALP_DRM_STATUS_OK == status) 
{ 
	// Do something with out_filename 
	... 
 
	g_free(out_filename); 
} 

Opening a DRM File ^TOP^

All DRM-protected files are stored encrypted in DCF format. Opening a DRM file involves opening a DCF file. DRM content originally delivered in Forward Lock or Combined Delivery format should first be stored securely using the DRM APIs, which will result in a conversion to DCF format.

Consuming a DRM File ^TOP^

Listing 2.2 shows how to consume the contents of a DRM file.

Listing 2.2  Consuming a DRM file

void PrvDisplayDRMFile(const char *filename) { 
{ 
  AlpDrmMetaInfo info; 
  alp_status_t status; 
  gboolean right = FALSE; 
  char *contentid = NULL, *issuer = NULL; 
  if(alp_drm_is_drm_file(filename)) 
  { 
	as=alp_drm_check_rights_info(filename,AlpDrmPermissionDisplay, 
				&contentid,&issuer); 
	if(as!=ALP_DRM_STATUS_OK) 
	{ 
		right=FALSE; 
	if(as!=ALP_DRM_STATUS_OK) 
	{ 
		right=FALSE; 
		if(issuer==NULL)//malloc fail , then the contentid=null too,exceptions 
		{ 
			dlg=gtk_message_dialog_new(GTK_WINDOW(MianWin), 
GTK_DIALOG_DESTROY_WITH_PARENT|GTK_DIALOG_MODAL,GTK_MESSAGE_WARNING, 
GTK_BUTTONS_OK, "No Right or Right expired."); 
			gtk_dialog_run(GTK_DIALOG(dlg)); 
			gtk_widget_destroy(dlg); 
		} 
		else if(strlen(issuer)==0)//it is a CD or FL DRM File , no need to get any 
rights 
		{ 
			dlg=gtk_message_dialog_new(GTK_WINDOW(MianWin), 
GTK_DIALOG_DESTROY_WITH_PARENT|GTK_DIALOG_MODAL,GTK_MESSAGE_WARNING, 
GTK_BUTTONS_OK, "No Right or Right expired."); 
			gtk_dialog_run(GTK_DIALOG(dlg)); 
			gtk_widget_destroy(dlg); 
		} 
		else //it has rightissuer in, need to try to get the rights  
		{ 
			gint response; 
			dlg=gtk_message_dialog_new(GTK_WINDOW(MianWin), 
GTK_DIALOG_DESTROY_WITH_PARENT|GTK_DIALOG_MODAL,GTK_MESSAGE_QUESTION, 
GTK_BUTTONS_OK_CANCEL, "Do your want to launch Browser to buy a License for 
this file?"); 
			response=gtk_dialog_run(GTK_DIALOG(dlg)); 
			gtk_widget_destroy(dlg); 
			if(response==GTK_RESPONSE_OK) 
			{ 
				
if(ALP_DRM_STATUS_OK==alp_drm_activate_drm_content_block(contentid,issuer,GTK_W
INDOW(MianWin)))//the process dialog closed automaticlly 
				{ 
					//recheck the right for the operation 
			 		
if(ALP_DRM_STATUS_OK==alp_drm_check_rights_info(glFileName,AlpDrmPermissionDisp
lay,NULL,NULL)) 
			 		{ 
			 			right=TRUE; 
			 		} 
				} 
			} 
		} 
	} 
	} 
	//else if the right is OK or we a valid ro came. 
	if(as==ALP_DRM_STATUS_OK||right==TRUE) 
	{ 
		
FILE*f=alp_drm_fopen_with_permission(filename,"rb",AlpDrmPermissionDisplay); 
		if(f) 
		{ 
			memset(&info, 0, sizeof(AlpDrmMetaInfo)); 
			as=alp_drm_get_meta_data(filename,ALP_DRM_META_INFO_CONTENT_TYPE,&info); 
			if(as==ALP_DRM_STATUS_OK) 
			{ 
				//Do things with alp_drm_f... 
				DoDisplayFunction(filename,info.fContentType); 
				//Update the constraints even if the file is a FL one. 
				alp_drm_update_constraints(f,contentid,1); 
			} 
			alp_drm_fclose (f); 
		} 
	} 
	{ 
		//still have no permission,This DRM file can not displayed 
		return error; 
	} 
  } 
  else  
  { 
  	/* Not a drm file */ 
  	... 
  } 
} 

Retrieving DRM File Information ^TOP^

The alp_drm_check_rights_info() and alp_drm_get_meta_data() functions allow you to retrieve a great deal of information about a DRM file other than its contents. The code in Listing 2.3 shows how to use these functions to explore all of this information associated with a given DRM file.

Listing 2.3  Retrieving DRM file info

/* define a struct of info for each AlpDrmPermission type */ 
typedef struct _RightInfo { 
	gboolean has_right; /* Does this file have the right to do
		the operation */ 
	gint count;	 /* How many time left to do the operation */ 
	time_t start_data_time; // Start time for valid operation 
	time_t end_data_time; /* End time for valid operation */ 
	time_t interval_start; /* The first use time */ 
	time_t interval_duration; 
}RightInfo; 
 
void DisplayDRMInfo(const char* filename) { 
	RightInfo Rights[AlpDrmPermissionNum]; 
	AlpDrmMetaInfo info; 
	gint i = 0; 
				 
	/* Following constants are used for Display prefixes*/				 
	const gchar * RightLabel[] = { 
		"AlpDrmPlay:", 
		"AlpDrmDisplay:", 
		"AlpDrmExecute:", 
		"AlpDrmPrint:" 
	}; 
	const gchar * InfoFields[] = { 
		"Content ID:", 
		"Content Version:", 
		"Content Type:", /*origional mime type*/ 
		"Title:", 
		"Description:", 
		"Content Vender:", 
		"Icon URI:", 
		"Right Issuer:", 
		"Delivery Method:", /*see Types*/ 
		NULL 
	};  
	/*types of the drm file*/ 
	const gchar * Types[] = { 
		"ALP_DRM_DELIVERY_FL", 
		"ALP_DRM_DELIVERY_CD", 
		"ALP_DRM_DELIVERY_SD", 
		NULL 
	}; 
	gchar * FieldContent[9]; 
				 
	/*initial value, set all fields to zero*/ 
	memset(Rights, 0x00, AlpDrmPermissionNum * 
		sizeof(RightInfo)); 
	memset(&info, 0, sizeof(AlpDrmMetaInfo)); 
	 
	/* get all info for every AlpDrmPermissionType and 
		display them*/ 
	for (i=0;<AlpDrmPermissionNum;i++) { 
		if(ALP_STATUS_OK == alp_drm_check_rights_info(filename,
			(AlpDrmPermissionType)i, NULL, NULL)) {	 
			Rights[i].has_right = TRUE; 
			alp_drm_get_file_constraints(filename,
				(AlpDrmPermissionType)i, &Rights[i].count,
				&Rights[i].start_data_time,
				&Rights[i].end_data_time,
				&Rights[i].interval_start,
				&Rights[i].interval_duration); 
		} 
 
		PRINT("[%s] %s\n", RightLabel[i],
			Rights[i].has_right?"True":"False"); 
 
		if(Rights[i].right) { 
				/*asctime will be broken if invoke again*/ 
				PRINT("\t[Count] %d\n",Rights[i].count); 
				PRINT("\t[Begin Time] %s\n",
					Rights[i].start_data_time); 
				PRINT("\t[End Time] %s\n",Rights[i].end_data_time); 
				PRINT("\t[Interval Start] %s\n",
					Rights[i].interval_start); 
				PRINT("\t[Interval Duration] %s\n",
					Rights[i].interval_duration); 
				/*PRINT("\t[Count] %d\n\t[Begin Time] %s\n\t[End\
						Time] %s\n\t[Interval Start] %s\n\t[Interval\
						Duration] %s\n",					Rights[i].count, 
						asctime(gmtime(&Rights[i].start_data_time)), 
						asctime(gmtime(&Rights[i].end_data_time)),
						asctime(gmtime(&Rights[i].interval_start)),
						asctime(gmtime(&Rights[i].interval_duration))); 
				*/ 
		} 
	} 
	/*get each field of the DRM file*/ 
	if(ALP_DRM_STATUS_OK == alp_drm_get_meta_data(filename,
		ALP_DRM_META_INFO_MASK, &info) 	{ 
		FieldContent[0] = info.fContentID; 
		FieldContent[1] = info.fContentVersion; 
		FieldContent[2] = info.fContentType; 
		FieldContent[3] = info.fTitle; 
		FieldContent[4] = info.fDescription; 
		FieldContent[5] = info.fContentVender; 
		FieldContent[6] = info.fIconURI; 
		FieldContent[7] = info.fRightsIssuer; 
		FieldContent[8] = Types[info.fDeliveryMethod]; 
	} 
	/*display all the files if it is valid*/ 
	i=0; 
	while(InfoFields[i]!=NULL) { 
		if(FieldContent[i]!=NULL) { 
			PRINT("[%s] %s\n",InfoFields[i],FieldContent[i]); 
		} 
	} 
	/*release the info*/ 
	alp_drm_free_meta_data(&info); 
} 

Getting a pixbuf from a DRM-Protected Image File ^TOP^

Getting a GDK pixbuf (pixel buffer) from a DRM-protected image file is a relatively simple process: you simply obtain a handle to the DRM-protected image file's contents by calling alp_drm_fopen_with_permission(), obtain the image's MIME type by calling alp_drm_get_meta_data(), and pass those to a function like that shown in Listing 2.4.

Listing 2.4  A function that gets a pixbuf for a DRM-protected image file

/* 
 * fp is the handle returned by alp_drm_fopen_with_permission 
 * mimetype the original mimetye returned by calling 
 *   alp_drm_get_meta_data 
 * error the glib error holder, can be null 
 */ 
GdkPixbuf *gdk_pixbuf_new_from_drm_fp(FILE* fp, 
	const char* mimetype, GError** error) { 
	GdkPixbuf *pixbuf; 
	gchar tbuf[1024]; 
 
	/* Create a loader with the mimetype */ 
	GdkPixbufLoader* loader; 
	loader = gdk_pixbuf_loader_new_with_mime_type(mimetype,
		NULL); 
	/* increasly add the buf to the loader */ 
	while(alp_drm_fread(tbuf, 1024, 1, fp) > 0) { 
		if(FALSE == gdk_pixbuf_loader_write(loader, tbuf, 
			1024, NULL)) { 
			gdk_pixbuf_loader_close(loader, NULL); 
			return NULL; 
		} 
	} 
	/* Get the pixbuf from the loader */ 
	pixbuf = gdk_pixbuf_loader_get_pixbuf(loader); 
	gdk_pixbuf_loader_close(loader, NULL); 
	return pixbuf; 
} 

---

1. ACCESS Linux Platform 1.0 only supported OMA DRM v1.0 Forward Lock.