Transcription
HELIX SECURITY MANAGER DEPLOYMENT GUIDEVersion 11.1Revision Date: August 22, 2006
Helix Security Manager Deployment GuideRealNetworks, Inc.PO Box 91123Seattle, WA networks.com 2006 RealNetworks, Inc. All rights reserved.Information in this document is subject to change without notice. No part of this documentmay be reproduced or transmitted in any form or by any means, electronic or mechanical, forany purpose, without the express written permission of RealNetworks, Inc.Printed in the United States of America.Helix, the Helix Logo, Real, the Real "bubble" (logo), RealJukebox, RealOne, Real-rTV,RealArcade, RealAudio, RealDownload, RealNetworks, RealPix, RealPlayer, RealPresenter,RealProducer, RealProducer Plus, RealPoducer Pro, RealProxy, RealPublisher, RealSites,RealSystem, RealText, RealVideo, Rhapsody, SureStream, The Future is Real, TurboPlay, andXing are trademarks or registered trademarks of RealNetworks, Inc.Other product and corporate names may be trademarks or registered trademarks of theirrespective companies.ii
CONTENTSINTRODUCTION1Conventions Used in This Book . 1Technical Support . 21SECURITY MANAGER OVERVIEW3Security Manager Components . 3Web Portal. 3URL Processor. 3Allowance Plug-ins . 4Licensing. 5Secure URLs . 5URL Timeout. 6Security Key. 6Tokens. 6Optional Security System Features. 7IP Address Verification . 7Media Streaming Lifetime . 7External Reallowance. 7Allowance Bypass . 8SMIL Presentations. 82INSTALLING URL PROCESSOR9Setting Up the Java Environment . 9Installing URL Processor Files .10Setting up Log4j for URL Processor .11Configuring URL Processor .12Defining the License File Location.13Setting Basic URL Processor Values .13Abbreviating Query String Parameter Names.16Replacing URL Keywords .19Defining URL Processor Tokens.20Starting and Stopping URL Processor .21Starting JBoss and URL Processor.21Stopping URL Processor .22Changing the JBoss Port .22iii
Helix Security Manager Deployment Guide3SETTING UP HELIX SERVERS AND HELIX PROXIES23Installing the Allowance Plug-in.23Installing and Verifying the Allowance Plug-in License.23Installing the Allowance Plug-in .24Creating a Token File for the Allowance Plug-In.24Configuring the Streaming Server Allowance Plug-in .25Testing the Allowance Plug-in .26Setting Basic Allowance Plug-in Parameters .27Enabling the Allowance Plug-in .28Defining Token Handling.28Configuring Allowance Logs.29Enabling Error Handling .31Setting Allowance Bypass Operation .31Selecting the IP Address Source .31Defining URL Parameter Keywords .324SETTING UP DOWNLOAD SERVERS AND PROXIES33Installing the Download Server Allowance Plug-in .33Installing the Download Server Allowance Plug-in .33Configuring the Download Server Allowance Plug-in .34Creating a Token File for the Download Server .385CONFIGURING ADVANCED AUTHORIZATION FEATURES41Error Handling for Allowance Plug-ins .41Error Types and Default Messages.41Defining Error Handlers .42Creating Error Handlers on Helix Server or Helix Proxy.42Creating Error Handlers on a Download Server and Proxy.43Creating a Customized Error Message .44Redirecting a URL on an Error.45Redirecting a URL on Helix Server or Helix Proxy .45Redirecting a URL on a Download Server and Proxy .45Contacting an External Allowance Server .46Defining External Allowance Error Handling for Streaming Servers .46Setting Up External Allowance Error Handling for Download Servers.47Configuring Error Web Service Attribute Values.47Posting Information to the External Allowance Server .48Responding to a Reallowance Request .50Response Code 1 – Use Default Error .50Response Code 2 – Allow Access .50Response Code 3 – Custom Error Message .50Response Code 4 – URL Redirect.51iv
ContentsModifying Parameters on URL Redirection.52Resubmitting General Parameter Values .52Setting Up Allowance Bypass .55Allowance Bypass Syntax .56Setting the Expression Mask .57Defining Match Expressions .58Using Regular Expressions.596GENERATING SECURE URLS61Submitting URLs to URL Processor.61Adding Query String Parameters to the Unsecured URL .62Encoding URLs for Submission to URL Processor .63Passing Arguments to URL Processor.64Secured URL Returned by URL Processor .65Setting Basic Security Features.67Setting a Clip Lifetime.67Specifying the URL Timeout .69Overriding the Default Encryption .69Verifying Client IP Addresses.70Supplying the Client’s Address .70Applying a Netmask.71Implicit IP Address Validation .71Explicit IP Address Validation .72Selecting the IP Address Source .73Using the URL Processor Servlet .73Encoding Query String Parameters .73Passing Arguments Using the Servlet.74Testing the URL Processor.75AAUTHORIZATION LOGS79Authorization Log Format.79Authorization Log Fields .80Log Type .80Access Time .80URL .80Response Code .80Client IP Address .81Client Identification.81Streaming Times.81Play and Pause Times .81Allowance Codes.82Reallowance Codes .83v
Helix Security Manager Deployment GuideBTERMINATION REPORTS85Termination Codes.85Termination Reports .87Sample Report Using Helix Administrator .87Sample Report Syntax in the Configuration File.89Sample Report Output .89INDEXvi91
INTRODUCTIONWelcome to the Helix Security Manager Deployment Guide fromRealNetworks . This document explains the installation andconfiguration of Helix Security Manager, a set of softwarecomponents that provides security for streaming and downloadedmedia.Conventions Used in This BookThe following table explains the typographic conventions used in this book.Notational ConventionsConventionMeaningemphasisBold text is used for in-line headings, user-interfaceelements, URLs, and e-mail addresses.terminologyItalic text is used for technical terms being introduced ina given manual or other document, and to lend emphasisto generic English words or phrases.syntaxThis font is used for file names, directory names, codeexamples (excerpted or in whole), or command-lineinstructions.syntax emphasisBold syntax character formatting is used for programnames and to emphasize specific syntax elements.variablesItalic text denotes variables. Substitute values appropriatefor your system.[]Square brackets indicate optional values. As a rule, whenyou use these optional values, you do not include thebrackets themselves.choice 1 choice 2 Vertical pipes separate values you can choose between.(Table Page 1 of 2)1
Helix Security Manager Deployment GuideNotational Conventions (continued)ConventionMeaning.Ellipses indicate nonessential information omitted fromexamples.“ ”Curly (“smart”) quotation marks are used for directquotations, to call out words or phrases that are beingused to mean something other than what they mean ineveryday English, and to enclose chapter titles and sectionheadings in cross-references.(Table Page 2 of 2)Technical SupportTo reach RealNetworks Technical Support, please fill out the form s/contact techservice.aspThe information you provide in this form will help Technical Supportpersonnel respond promptly. For general information about RealNetworksTechnical Support, visit this Web page:http://service.real.com/help/call.html2
CHAPTERChapter 1:SECURITY MANAGER OVERVIEW1This chapter provides an overview of Helix Security Manager. Itdescribes the system components and explains how the systemcreates and authenticates secure URLs. It also covers some of theadvanced features that you can implement using Helix SecurityManager.Security Manager ComponentsThe Helix Security Manager allows you to generate tamper-proof URLs thatgrant media access to authorized users. This security system consists of threemain components: a Web portal, the URL Processor, and an allowance plug-infor each media server. You configure Security Manager components usingXML-based configuration files. The system does not include graphical userinterfaces. Rather, it provides interfaces that allow you to integrate SecurityManager features into an existing Web portal.Web PortalHelix Security Manager integrates with any Web portal running on anyoperating system and Web server software. The portal verifies the identity ofeach user, determining if the user should receive access to the requestedcontent. For allowed accesses, it transmits the unsecure URL path to URLProcessor, receiving back a secure URL that it forwards to the user.URL ProcessorThe URL Processor application runs under the JBoss application server, whichis included with Helix Security Manager. It implements security features byattaching query string parameters to the URL submitted by the Web portal.Secure URLs are invalidated if they are altered, and have a timeout feature thatguards against URL forwarding and bookmarking.3
Helix Security Manager Deployment GuideURL Processor RequirementsThe following table lists minimum requirements for the machine running theJBoss application server along with URL Processor.URL Processor RequirementsComponentRequirementsComputerSun v210Intel or compatible 2.0GHz or greaterOperating SystemsSolaris 8, Solaris 9 (SPARC only)RedHat Enterprise Linux 4 AS or ESWindows Server 2003 SP1RAM1 GBDisk Storage100 GB (logging disk)Network Interface Card100 Mbit/sec (minimum)Java Environment (J2SE)Sun Java 1.4.2 available lication ServerJBoss Application Server 4.0.22 (included with HelixSecurity Manager)Allowance Plug-insEach Helix Server, Helix Proxy, download server, or download proxy that hostsyour content uses an allowance plug-in. This plug-in evaluates the securityparameters of each URL request, allowing the access only if the URL has notbeen tampered with and has not timed out. The plug-in keeps a log file of theactions it took on each URL request.For More Information: Chapter 3 and Chapter 4 provideallowance plug-in configuration instructions for streamingand download servers, respectively. See also Chapter 5 forinformation about advanced allowance features.4
CHAPTER 1: Security Manager OverviewAllowance Plug-in RequirementsAllowance plug-ins are installed on your existing streaming and downloadservers. The following table lists server software versions compatible withHelix Security Manager allowance plug-ins.Streaming and Download Server VersionsServerSupported VersionStreaming ServerHelix Server 11 or laterStreaming ProxyHelix Proxy 11 or laterDownload ServerApache v2.0 (earlier and later versions not supported);Covalent Enterprise Ready ServerDownload ProxyApache v2.0 (earlier and later versions not supported);Covalent Enterprise Ready ServerLicensingA valid license file is required to activate URL Processor and the allowanceplug-ins. The license uses the file extension of .lic . The default license filenameis secmgr-license.lic , and is used for all Helix Security Manager components.The license file is not included with the program files. It is available separatelyfrom your RealNetworks representative.Secure URLsURL Processor secures URLs by means of query string parameters. Thefollowing example illustrates the essential security parameters in a URL forstreaming media (line breaks have been added for eo.rm?tokenttl 120>ime 1052261021&tokenname key5&key D832AC16CC54615E313723538AF6F278For More Information: Chapter 6 explains how to use all of theURL Processor security features, options, and overrides.5
Helix Security Manager Deployment GuideURL TimeoutSecure URLs include a lifetime such as 120 seconds. If a user accesses the URLafter this lifetime expires, the server’s allowance plug-in denies the accessattempt. The tokenttl value sets the URL lifetime in seconds. (Allowance plugins are also configured with a default lifetime value in case tokenttl is notpresent.) The gtime value indicates the time when URL Processor generatedthe URL. The allowance plug-in evaluating the access uses the gtime value todetermine the start of the lifetime.Note: To ensure that URL timeout works as expected, the URLProcessor machine and all content servers should use a timesynchronizing program.Security KeyThe key parameter secures the URL against tampering. URL processorgenerates the key value by hashing a private token value with everything in theURL that precedes the key parameter. When evaluating the secure URL, anallowance plug-in regenerates the key value from the requested URL and thesame token value. If the regenerated key value does not match the key value inthe requested URL exactly, the allowance plug-in rejects the request.Note: In generating the key value, URL Processor can use theMD5 or SHA-1 hash algorithm.TokensURL Processor generates the security hash key using a token, which consists ofa user-defined name, such as key5 , along with a user-defined value similar to apassword, such as rt238yg9 . The security system can use a single, default tokenvalue defined in the configuration files for URL Processor and each allowanceplug-in. In this case, a token name is not needed and the tokenname parameteris omitted from the secure URL.Optionally, you can define a set of tokens for URL Processor and each plug-in.When generating the secure URL, the Web portal instructs URL Processor touse one of the token values. URL Processor then includes the token name asthe value of the tokenname parameter. When it evaluates an access request, anallowance plug-in looks up the value associated with the token name and usesthe associated value to regenerate the secure URL.6
CHAPTER 1: Security Manager OverviewOptional Security System FeaturesThe following sections describe optional features that you can use with HelixSecurity Manager.IP Address VerificationURL Processor can include the client’s IPv4 address (with or without anetmask) as a value when generating the URL’s secure hash key. Allowanceplug-ins then verify that the media player requesting the media from astreaming or download server uses the same IP address as the browser clientthat requested the media URL from the Web portal.For More Information: Refer to “Verifying Client IP Addresses”on page 70 for details.Media Streaming LifetimeURL Processor can set a time limit for viewing streaming media. It might set athree-minute total viewing time for a clip, for instance. This allows you tostream a preview or implement a pay-per-view service without encodingseparate clips. Once the viewer’s time limit has expired, the allowance plug-interminates access to the stream.For More Information: See the section “Setting a Clip Lifetime”on page 67.External ReallowanceHelix Security Manager allows you to configure the actions that occur on theURL timeout and stream timeout conditions. You can, for example, have theallowance plug-in forward the URL to an external allowance server. This is anyWeb-based portal that has access to the user information. The portal can theninstruct the allowance plug-in to allow access, deny access, or redirect the userto different content.For More Information: For information about allowance errorconditions and external reallowance, see “Error Handling forAllowance Plug-ins” on page 41.7
Helix Security Manager Deployment GuideAllowance BypassIn most content delivery systems, access to the content is secured. However,you may also want to host some unsecured content for general access. Freecontent might include movie trailers or video introductions to how yoursubscription system works. Helix Security Manager allows you to define whichcontent is available without security restrictions. You can do this on a generallevel, such as any content in a specific directory, or with fine granularity, suchas URL-by-URL.For More Information: For an explanation of using this feature,refer to “Setting Up Allowance Bypass” on page 55.SMIL PresentationsSecurity Manager supports the use of SMIL (Synchronized MultimediaIntegration Language) to create secure, multimedia presentations. The SMILfile can contain unsecure URLs to any number of clips. You use URL Processorto generate a secure key for the SMIL file (extension .smil ). Once the allowanceplug-in on Helix Server or Helix Proxy validates access to the SMIL file, itgrants access to the additional streams that make up the SMIL presentation.It rejects any direct request for an unsecure clip contained within the SMILpresentation.Only the SMIL file validation appears in the allowance plug-in log describedin Appendix A. The main Helix Server or Helix Proxy log file records allstreams, however. Within the server or proxy log, the presentation ID field listsa number used by all clips in the same SMIL presentation. For example, if thelog entries for a SMIL file, a video clip, and a JPEG image all list presentationID 437, you can conclude that the SMIL presentation consisted of that videoand image.For More Information: For more on the presentation ID field,refer to the basic logging chapter of Helix Server AdministrationGuide or Helix Proxy Administration Guide.8
CHAPTERChapter 2:INSTALLING URL PROCESSOR2This chapter explains how to install and configure the URLProcessor Component of Security Manager. The URL Processor runsas an application under the JBoss application server.For More Information: Chapter 6 explains URL Processorfeatures.Setting Up the Java EnvironmentThe JBoss application server requires a Java environment. You can install aJ2SE Runtime Environment (JRE) or a full Java Development Kit (JDK).Security Manager supports version 1.4.2 of the JRE or JDK from SunMicrosystems.Note: Other Java environments may work with SecurityManager, but are not supported by RealNetworks. To install a Java Environment:1. Download the Sun JRE or JDK from the following Web . Install the JRE or JDK files.a. On Windows, double-click the installation file to launch the installer.Follow the installer prompts to perform a typical installation.b. On UNIX, run the self-extracting binary file (.bin ), or run the RPMfile as the root user.For More Information: Detailed installation instructions for theJRE are available at http://java.sun.com/j2se/1.4.2/jre/install.html. For JDK installation instructions, refer tohttp://java.sun.com/j2se/1.4.2/install.html.9
Helix Security Manager Deployment Guide3. Add the JAVA HOME environmental variable to your environment.a. On UNIX, edit the shell profile, such as .bash profile , of the userrunning the Java environment. Include the following line:JAVA HOME Java locationexport JAVA HOMEFor example:JAVA HOME /usr/local/java/j2sdk1.4.2 11export JAVA HOMEb. On Windows, set the JAVA HOME variable to the directory where youinstalled the Java Environment. You add variables using the commandStart Settings Control Panel System Advanced EnvironmentVariables. For example:Variable name:JAVA HOMEVariable value:C:\Program Files\Java\j2re1.4.2 11Installing URL Processor FilesThe following procedure explains how to install JBoss and Security Managerfiles. The installation procedure is similar on Windows and UNIX computers.All files are contained within a compressed archive. Security Manager does notuse an installation application.Note: On Windows, you need an application capable of readingTar archives that have been compressed using Gzip (.tar.gz ).Many Zip utilities on Windows can read these formats. To install URL Processor:1. Uncompress the Security Manager URL Processor package until you reachthe jboss-version folder.2. Move the jboss-version folder to the location where you want to run theURL Processor. For s-4.0.23. Add the JBOSS HOME environmental variable to your environment.10
CHAPTER 2: Installing URL Processora. On UNIX, edit the shell profile, such as .bash profile , of the userrunning URL Processor. Include the following line:JBOSS HOME JBOSS locationexport JBOSS HOMEFor example:JBOSS HOME /usr/local/jboss-4.0.2export JBOSS HOMEb. On Windows, set the JBOSS HOME variable to the directory where youinstalled JBoss. You add variables using the commandStart Settings Control Panel System Advanced EnvironmentVariables. For example:Variable name:JBOSS HOMEVariable value:C:\jboss-4.0.24. Copy the Security Manager license file, typically named secmgr-license.lic ,to the secmgr subdirectory under the JBoss installation directory.Setting up Log4j for URL ProcessorYou can set up Log4j logging to capture information useful for monitoringURL Processor performance and troubleshooting problems. URL Processoruses the Log4j Java API, an open source logging API for Java applications thatenables monitoring and debugging. This logging information is entirelyseparate from the authorization, access, and error logs created by the SecurityManager security system.For More Information: For background on Log4j, refer tohttp://logging.apache.org/log4j/docs/index.html. To use Log4j with URL Processor:1. Using any text editor, open the file secmgr-log4j.properties located in thesecmgr subdirectory under the JBoss installation directory.2. In the file secmgr-log4j.properties , change every sample path to the pathrelevant to your environment.3. Save and close the file secmgr-log4j.properties.Note: The script used to start JBoss must refer to the locationof the Log4j properties file. The scripts secmgrstart.sh and11
Helix Security Manager Deployment Guidesecmgrstart.bat , which the section “Starting JBoss and URLProcessor” on page 21 describes, are preconfigured to point tothe default location of the properties file.Configuring URL ProcessorTo configure URL Processor, you use any text editor to edit the file secmgrconfig.xml located in the secmgr subdirectory under the JBoss installationdirectory. The values in this file allow you to define basic URL Processoroperation: ?xml version "1.0" encoding "utf-8" ? SDSConfig xmlns:xs "http://www.w3.org/2001/XMLSchema"xmlns:xsi "http://www.w3.org/2001/XMLSchema-instance" License LicenseFileName "./secmgr/secmgr-license.lic" / URLProcessor UseDefaultToken "true" UseFullURL "false" UseBase64 "false"MACAddress "address" DefaultToken "default token value"EncryptionType "0" URLKeywords .Keywords for query string parameters passed to URL Processor. /URLKeywords ReplaceKeywordsInURL .Keywords to replace in a requested URL for authorizing the access. /ReplaceKeywordsInURL Keys Key Name "tokenname1" Value "tokenvalue1" / Key Name "tokenname2" Value "tokenvalue2" / .additional name and value pairs. /Keys URlProcessorEncryptionType "0 1"/ /URLPr
This chapter provides an overview of Helix Security Manager. It describes the system components and explains how the system creates and authenticates secure URLs. It also covers some of the advanced features that you can implement using Helix Security Manager. Security Manager Components The Helix Security Manager allows you to generate tamper .
