Using the Xtra packaging kit

Security concerns for distributing Xtras

Installing the Xtra Packaging Kit

Generating a certificate request

Completing the VeriSign enrollment form

Creating an Xtra package

Placing package files on a server

Preparing a movie that requires a downloaded Xtra

Testing a movie with Xtra downloading

Maintaining Xtra version numbers

Using the Movie Packages and Package Files movies

Director downloads and install Xtras using the VeriSign code signing system to protect users and Xtra developers. The Xtra packaging kit includes all the components you need to make an Xtra available for downloading. To make an Xtra downloadable, you need to create a package file that contains the files to be downloaded. The Xtra packaging kit includes a Director movie for making package files, along with utilities for managing packages. It also includes the software you need to register with VeriSign.

VeriSign certifies that an Xtra developer is a responsible party and that the code in the Xtra has not been changed since its download package was signed. Neither Macromedia nor VeriSign can prevent registered Xtra developers from creating malicious Xtras, but VeriSign technology is a proven mechanism for insuring responsibility.

You can only create package files using a private key you receive when you request a certificate. When a user downloads an Xtra, Director checks a signature in the package file against the code that was downloaded and makes sure that nothing has been changed. If anything does not match, Director discards the Xtra.

The general steps for creating an Xtra package are as follows:

	Generate a certificate request, a private key, and a public key using the Cert Request application.
	Using the certificate request, complete and submit the VeriSign enrollment form on the VeriSign web site. Wait for a certificate from VeriSign (usually about a week).
	Run the Xtra Packager Director movie and create package files for Macintosh and Windows using the VeriSign certificate and your private key. The package file contains the Xtra (or Xtras) you want to make available for downloading.
	Copy the package files to an Internet server.
	Prepare a test movie to verify that your downloaded Xtra works properly.

Additionally, if a movie you are distributing requires a downloadable Xtra, you need to edit the file Xtrainfo.txt to add the URL from which the Xtra package can be downloaded, and turn on the Download if Needed option in the Movie Xtras dialog box.

 
Security concerns for distributing Xtras
The Xtra packaging system explained here does not determine the safety of an Xtra. Your good judgment and reputation are all that protects the end user. The VeriSign code signing system makes an Xtra developer accountable for an Xtra, but it does not protect an end user from a destructive Xtra. Several major software companies use the same system for other types of downloaded software. VeriSign attempts to provide known and trusted sources from which software can be downloaded. The user can decide before downloading and executing any code if the source is reliable.

When you use your digital certificate to sign an Xtras package, you are claiming responsibility for the contents of that package. Your name or your company's name appears to users when the package downloads.

You must consider carefully the possible consequences of distributing your product on the Internet. Be sure that there is no potentially destructive or unexpected functionality. Do not sign Xtras from outside your company or Xtras you are not completely familiar with. Do not sign Xtras you did not compile yourself. Do not sign development ("beta") versions of Xtras. Consider the possibility of someone exploiting flaws in your code to compromise an end user's system.

For more information about creating safe Xtras, see Macromedia tech note 13761 "Making an Xtra Safe for Shockwave" at http://www.macromedia.com/support/xtras/ts/nav/ . There are also many other documents available on the Internet discussing code safety.

 
Installing the Xtra Packaging Kit
The Xtra Packaging Kit includes Xtras and Director movies. Before running the Xtra Packager for the first time, you need copy the various components to your Xtras folder. Make sure you are using version 7.02 or later of Director to create a movie with downloaded Xtras or an Xtra package.

To install the Xtra Packaging kit:

1	If Director is running, exit the program.
2	Copy the Windows or Macintosh Packages folder to the Xtra folder in the Director application folder.

 
Generating a certificate request
Use the Certificate Request Generator, (Cert Request.exe (Windows) or Cert Request (Macintosh)) to create a certificate request. The Certificate Request Generator is a console application. The Certificate Request Generator also creates the public and private keys you need to complete the Xtra packaging process. You need only one certificate request, public key, and private key for both the Windows and Macintosh platforms.

To use the Certificate Request Generator:

1	Run the file Cert Request.exe (Windows) or Cert Request (Macintosh).
2	At the first prompt, enter any text and press Enter to generate a random number.
3	At the next prompt, enter the complete name of your company.
4	At the next prompt, enter a file name for the certificate request.
	The program generates the certificate request and saves it using the file name you enter.
5	At the next prompt, enter a file name for the private key.
6	At the next prompt, enter a file name for the public key.
	Cert Request finishes saving the files and posts a Done message.

The private key ensures that no one else can create Xtra package files with your certificate. Keep it in a secure place, ideally on a floppy disk in a locked container. The public key file contains a copy of the public key in the certificate request file. In most cases you won't need to use it. VeriSign uses the public and private keys together to generate a signature for a package file.

 
Completing the VeriSign enrollment form
The VeriSign enrollment form is on a page in the VeriSign web site. Use it to supply information about your company and to pay for the enrollment process. To complete the enrollment form, you need to copy the complete contents of the certificate request into the correct field in the form.

To complete the VeriSign enrollment form:

1	Open the certificate request file you created in the last section in a text editor and copy the complete contents of the file to your system clipboard.
2	Open the page at http://digitalid.verisign.com/developer/class3SWave.htm in your web browser and carefully follow all the directions found there, pasting the certificate request into the appropriate field.
3	Submit the completed enrollment form and wait for a response from a VeriSign.

 
Creating an Xtra package
Once you've received a certificate from VeriSign, use the Xtra Packager Director movie to create the package files. You can create as many package files as necessary with a single certificate and private key.

To use the Xtra Packager movie:

1	Choose Xtras > Packages > Xtras Packager.
	The Xtras Packager movie opens as a movie in a window (MIAW).
2	After clicking continue at the first screen, use the buttons provided to specify the location of the private key file and the certificate file. Click Continue when you're done.
	You can review information extracted from the certificate in the scrolling field.
3	At the next screen, enter a package name and description.
	The package name and description appear in a dialog box after a user downloads the package. You should provide all the information a user needs to make a good decision about allowing the Xtra to be installed. For instance, "This Xtra enables real time 3D Shockwave movies, and has no ability to modify data on your disk."
4	Enter the names of the files to be included in the package file.
	You can include up to 10 files in a single package. You can include any type of file in a package; the files do not have to be Xtras.
5	Enter a name for the output file in the field provided, or click Specify Output File and choose an output file.
	You must use a .w32 suffix for Windows and .ppc for Macintosh. Note that the name of the package is not the same as the file name of the output file.
6	Click Save Package File to create and save the package file.
	You can create additional packages without restarting the movie.

http://www.myserver.com/packs/animgif.ppc

http://www.myserver.com/packs/animgif.w32

 
Preparing a movie that requires a downloaded Xtra
If you are distributing a movie that requires an Xtra from the package file you created, you need to identify the Xtra to be downloaded within the movie and specify a URL in the Xtrainfo.txt file.

If you are distributing Xtras for use by other Director developers, please provide these instructions along with the testing information in the next section so they are able to provide a good experience to their users.

Xtra downloading occurs before a movie starts. This means that a Web page that includes a movie that downloads an Xtra does not respond until the package downloads. If the user chooses not to install the Xtra, Director discards the downloaded package. To improve this experience, create an introductory movie that checks for the existence of required Xtras with the XtraList command. If an Xtra isn't available, the movie should present the user with the choice of proceeding with the download. If the user proceeds, the introduction should run the main movie with goToNetMovie. If a user chooses not to download the Xtra, the movie should proceed without the Xtra, or fail gracefully.

To prepare a movie for use with a downloaded Xtra:

1	Open the file Xtrainfo.txt in any text editor and enter the URL to the package files you created earlier and copied to a server. Exclude the file extension from the name of the packages.
	For example:
	[#namePPC:"Animated GIF Asset", #nameW32:"Animated GIF Asset.X32",#package:"http://www.myserver.com/packs/animgif"]
	#nameW32 and #namePPC specify whether the package is for Windows, Macintosh, or both. You don't have to include a package for both platforms.
2	Open the movie in Director, choose Modify > Movie > Xtras and turn on Download if Needed for the Xtras that should be downloaded.
	If Download if Needed is not enabled for the Xtra, make sure the file name in Xtrainfo.txt matches the actual file name for the Xtra. When you click the checkbox, Director loads information from the package file at the specified URL and adds it to the current movie. There must be an active network connection for this to work.
3	If the movie is playing from a projector, create an introductory movie that starts the main movie with gotoNetMovie.
	Xtra downloading does not work if a movie is playing in a projector unless started from another movie with goToNetMovie.

Note that Xtra downloading does not work if a movie is playing in a projector unless you start it from another movie with goToNetMovie. It's often best to use an introductory movie before starting a movie that requires Xtra downloading. Also, Xtra downloading does not occur if you start a movie with go to movie.

 
Maintaining Xtra version numbers
It's important to properly maintain both internal and external version numbers for an Xtra you are distributing on the Internet.

When you create an Xtra package, the packager includes the file version number for every file in the package. You define a file version number in your Xtra source code or with a resource editor.

When you refer to a package in a movie by turning on the Download if Needed option in the Movie Xtras dialog box, Director adds to the movie the URL for the package and a list of all packaged files and their version numbers. This list includes files for both Windows and Macintosh packages.

When a movie runs with Xtra downloading enabled, Director checks that all the files in the referenced package files are present on the current platform. If a file is present, Director then checks the version number according to these rules:

	Two files with no version are assumed to be the same version.
	A file with no version is assumed to be older than a file with any version.
	Versions read as major.minor.sub. For example: 7.0.1, 5.3, 4, 2.2.1)
	Anything after the sub-version is ignored. For example, 7.0.1d22 is the same as 7.0.1d15)

If a file from the package is not present, or if the file on the current system does not match the version number in the package, then Director downloads the file. If a package has two files, both of which already exist and only one of which is newer, Director only installs the newer file.

Director places downloaded Xtras in a subfolder of the Xtras folder named Download. To isolate each download, Director creates subfolders in the Download folder using the company name and package name. When Director installs a newer version of an Xtra, it deletes the older version, but not until the end of the current session.

Xtras have an internal version number that is used by MOA as well as an external version. Director does not use the internal version in the download process. However, you must increment the internal version when you update an Xtra. Right after Director downloads a new version of an Xtra, there will be two copies of the Xtra registered with MOA until the older copy gets deleted at the end of the current session. In this case, MOA uses the internal version to determine which Xtra to use. See the Xtra Developer's Kit documentation for information on setting the internal Xtra version number.

 
Using the Movie Packages and Package Files movies
Use Movie Packages to see the contents of packages referenced by the current movie. Use Package Files to view the contents of package files.

To use the Movie Packages movie:

1	Open a movie that includes references to Xtra packages.
2	Choose Xtras > Packages > Movie Packages.
3	Click Check Movie.
	Movie Packages displays a list of all the packages referred to in the current movie.
4	Select a package file.
5	Click PPC or W32 to display the platform-specific information. Alt-click (Windows) or Option-click (Macintosh) these buttons to see the file version instead the file name.