Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

7    Securing a Palm OS Application

Palm OS® Resource Tools Guide

Palm OS® Developer Suite

This chapter describes how to use PRCCert and PRCSign to create and embed a digital signature and associated certificates in a Palm OS application (PRC file).

For a general description of the security and encryption features of Palm OS Cobalt, see Exploring Palm OS: Security and Cryptography.

Introducing PRCCert ^TOP^

PRCCert is a command line tool that you can use to create your own RSA key pairs and digital certificates. You may create self-signed certificates for testing, or certificates that are signed by other private keys.

PRCCert creates RSA public/private key pairs at 1024-bit length in PEM format. PRCCert also generates a public certificate file in DER format.

The output files from PRCCert are used as input files to PRCSign, as described in "Introducing PRCSign."

Figure 7.1  PRCCert Overview

Using the PRCCert Command Line Tool ^TOP^

There are two modes for PRCCert:

  • Key Generation
  • Certificate Generation

Specifying Key Generation Mode ^TOP^

The command syntax for PRCCert's key generation mode is:

PRCCert [options] -keygen -passphrase password 
-keygen
Tells PRCCert to process in key generation mode.
-passphrase password
Specifies the pass phrase that was used to encrypt the private keyfile.
options
Additional command line options as described in the following section "Specifying PRCCert Command Line Options."

Specifying Certificate Generation Mode ^TOP^

The command syntax for PRCCert's certificate generation mode is:

PrcCert [options] -certgen 
-configfile filepath
-keyfile filepath
-passphrase password
-certgen
Tells PRCCert to process in certificate generation mode.
-configfile filepath
filepath specifies the full path and filename for the configuration file. The configuration file specifies the information that is embedded in the certificate (owner, date, location, and other information). See the provided sample file PRCCert.conf for more information (included in the developer tools package).
-keyfile filepath
filepath specifies the full path and filename for the private key file (a PEM format key file).
-passphrase password
Specifies the pass phrase that was used to encrypt the private keyfile.
options
Additional command line options as described in the following section "Specifying PRCCert Command Line Options."

Specifying PRCCert Command Line Options ^TOP^

-basename name
Specifies the base name for the output files.
-help
Tells PRCCert to display usage description without doing any processing.
-outputdir path
Specifies the directory for the output files.
-quiet
Suppresses the tool description (tool name and version number) and copyright information.

Examples

Creating a Key Pair

To create a key pair, you run PRCCert with the following command line options:

PRCCert -keygen -passphrase "myPassPhrase"

The output is two files: a public key PEM file and a private key PEM file.

Creating a Self-Signed Certificate

To create a self-signed certificate, you first need to do the following:

  • Create a key pair (a public key PEM file and a private key PEM file), as described in the example above.
  • Edit the configuration file, PRCCert.conf (provided in the developer tools kit), updating the security file information, and changing the company name and location as appropriate.
  • Run PRCCert with the following command line options:
PRCCert -certgen 
-passphrase "myPassPhrase" 
-configfile c:\DirName\EditedPRCCert.conf 
-keyfile private_key_filename 

The output is a DER-encoded x509 certificate that can be used with PRCSign.

Introducing PRCSign ^TOP^

PRCSign is a command line tool that you use to digitally sign your applications or to embed digital signature certificates in your applications.

Figure 7.2  PRCSign Overview

PRCSign creates a digital signature for a particular PRC using an asymmetric key cipher, storing the signature into the PRC as a resource of type 'sign'. The signature can be verified as authentic by using your public key to decipher the signature resource. Each application has at most one 'sign' resource with a resource ID of 1000.

PRCSign takes your private key and signs a SHA1 hash of all of the static (unchanging) resources in the PRC along the signature attributes. PRCSign then adds the resulting output as the 'sign' resource to your application PRC file.

PRCSign also takes a digital signature and adds it to the PRC as a 'cert' resource in such a way that the Palm OS Security Manager can retrieve it for application certification.

PRCSign takes your certificate and adds it to the PRC as a 'cert' resource with the certificate ID being a digest (SHA1) of the certificate itself. The certificates need to be in X.509 format and they need to be ASN.1 DER-encoded files. These certificates can be created by any certificate creation tool that generates this format. (For example, OpenSSL has such a tool).

Using the PRCSign Command Line Tool ^TOP^

The command syntax for PRCSign is:

PRCSign inputFile1 [options] [opt_file]
inputFile
One PRC input file must be specified as input to PRCSign, of the following type:
TRC
PRC
BPRC
OPRC
options
Additional command line options as described in the following section "Specifying PRCSign Command Line Options."
opt_file
You can place the options in a text file rather than specifying them on the command line.

Specifying PRCSign Command Line Options ^TOP^

Informational Options
-help
Tells PRCSign to display usage description without doing any processing.
-helpVersion
Tells PRCSign to display tool version information without doing any processing.
-quiet
Suppresses the tool description (tool name and version number) and copyright information.
Required Options
-keyfile private_key_file
Specifies the private key file.
private_key_file
The full path and filename to the PEM private key file. private_key_file is your private key file. The keyfile must be in PEM-encoded format (the format that PRCCert generates).
-passphrase pass_phrase
Specifies the pass phrase for the private key file.
pass_phrase
The pass phrase for the private key file. PEM files are encrypted with a pass phrase, so you must specify it so that PRCSign can access the private key. This is the same pass phrase you passed into PRCCert when the key file was generated.
-cert certificate_file
This option is used both when you sign a PRC and when you add a certificate to a PRC. When you are signing a PRC, the certificate is used to verify the signature. When you are adding a certificate to a PRC, certificate_file specifies the data that you want embedded in the 'cert' resource.
certificate_file
The full path and filename to the public key certificate file (a DER-encoded digital certificate file).
Other Options
-addcert
Specifies that PRCSign should add the certificate (specified with the -cert option) to the PRC. You may only add one certificate at a time. If you need to embed multiple certificates, you need to run the tool once for each certificate.
-o prcFile
Specifies the output PRC filename. The output filename can be the same as the input filename.
-ocert certificate_file
For overlay certification, tells PRCSign to add an ID for the certificate specified by certificate_file. (You must have specified a certificate to add to this list with the -cert option.) Certificate IDs are used to validate signed overlay resources.
To add multiple certificate IDs, specify this parameter once for each certificate_file. You must set the list of multiple certificate IDs at the time of signing; this list may not be modified after the first signature is applied to the application.
-omit resSpec
Tells PRCSign to exclude the resource specified by resSpec from the signature. This option can be useful if a resource is expected to change at runtime.
-remove_sign
Removes the 'sign' resource from the input PRC file.
-remove_cert cert_id
Removes the 'cert' resource with the ID cert_id from the input PRC file.
-scert certificate_file
For shared library verification, tells PRCSign to add an ID for the certificate specified by certificate_file. (You must have specified a certificate to add to this list with the -cert option.)
To add multiple certificate IDs, specify this parameter once for each certificate_file. You must set the list of multiple certificate IDs at the time of signing; this list may not be modified after the first signature is applied to the application.
-smartcard provider opts
Specify a provider to use with a smart card and additional options (specified by opts) that may be necessary for the provider. The only smart card provider supported is the WinCrypt with GemPlus reader.
Note: If you use this option, you do not need the -key or the -pass parameters.
-verbose
Outputs extensive diagnostic information about what data is being processed.