Using
the Xtra packaging kit
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. Note that xtra "package files" have no relationship to the "packages" that were added as a feature of the Macintosh OS X operating system. 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 Adobe nor VeriSign can prevent registered Xtra developers from creating malicious Xtras, but VeriSign technology is a proven mechanism for insuring responsibility. The VeriSign certificate is good for just one year - you will need to renew and get a new certificate if you want to create additional packages in the future. You can only create package files using a private key you generate 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 modified since the package was created. If anything does not match, Director discards the package file and all its contents. Xtra downloading functions in all Director playback environments: Shockwave, Projectors and Authoring. The "download security dialog" never appears in authoring, but it does appear in other situations. Note that xtras packaged by Adobe, Inc. no longer display the security dialog when they are downloaded. The general steps for creating an Xtra package are as follows:
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. This file is stored in the same folder as the Director application. You will also need to turn on the Download if Needed option in the Movie Xtras dialog box for any movies that require files in the package. 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 Adobe tech note 13761 "Making an Xtra Safe for Shockwave" at http://www.adobe .com/support/xtras/ts/nav/. There are also many other documents available on the Internet discussing code safety. 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 directory. 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:
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. For Macintosh, there is an OS 9 version of this application as well as an OS X version. To use the Certificate Request Generator:
If you were successful, you should see the files for the certificate request, the private key, and the public key in the same folder as the Certificate Request Generator. 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 or copied onto a CD stored 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. The VeriSign enrollment form is on a page that is part of 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:
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 you wish with a single certificate and private key. Note that you have to create Windows packages on a Windows system and Macintosh packages on a Macintosh system. This is necessary because OS specific version information is retrieved for each file included in the package. With Director 11, Macintosh Xtras have have a new format. They are "bundles" - essentially folders that contain the executable code along with other data. The packager xtra has been updated to support this format. To use the Xtra Packager movie:
Use your own scripting to make a package: You can use the scripting interface for the packager xtra to create package files. This may be more convenent than the MIAW tool if you are repeatedly creating package files. Using script control can also can help ensure you use the same description and package name for each platform. Here's the sequence of commands you need to use. Return values from the scripting xtra methods are zero when there is no error.
Once you've created package files for each platform you support, you need to put them all in a single directory on a server. For example:
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 To prepare a movie for use with a downloaded Xtra:
Testing a movie with Xtra downloading Make sure the Xtra to be downloaded is not installed already. Run the movie(s) you created in the previous section in a browser or as a projector. After you choose to proceed from the introductory movie, Director should download the Xtra package from the specified location and present a Download Security dialog box. Note that Xtra downloading does
not work if a movie is playing in a projector unless you start it from another movie with 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:
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 attempts to download the file. Note that Director only checks for the package file if the correct version of the xtra is not available according to the version info stored in the movie. Director never downloads package files just to check version numbers and determine if the contents of the package file have been updated. 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 on the user's machine in a sub folder of the Xtras folder named Download. To isolate each download, Director creates sub folders 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. Use Package Files to view the
contents of package files.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Changes to this document and files
Revision: 2007, August