Creating Signed Packages

The process of creating signed packages involves a number of steps and requires some comprehension of new concepts and terminology. This section provides information about signed packages, its terminology, and information about certificate management. This section also provides step-by-step procedures about how to create a signed package.

Signed Packages

A signed package is a normal stream-format package that has a digital signature (PEM-encoded PKCS7 digital signature which is defined below) that verifies the following:

The package came from the entity who signed it
The entity indeed signed it
The package has not been modified since the entity signed it
The entity who signed it is a trusted entity

A signed package is identical to an unsigned package, except for the signature. A signed package is binary-compatible with an unsigned package. Therefore, a signed package can be used with older versions of the packaging tools. However, the signature is ignored in this case.

The signed packaging technology introduces some new terminology and abbreviations, which are described in the following table.

Term	Definition
ASN.1	Abstract Syntax Notation 1 - A way of expressing abstract objects. For example, ASN.1 defines a public key certificate, all of the objects that make up the certificate, and the order in which the objects are collected. However, ASN.1 does not specify how the objects are serialized for storage or transmission.
X.509	ITU-T Recommendation X.509 - Specifies the widely-adopted X.509 public key certificate syntax.
DER	Distinguished Encoding Rules - A binary representation of an ASN.1 object and defines how an ASN.1 object is serialized for storage or transmission in computing environments.
PEM	Privacy Enhanced Message - A way to encode a file (in DER or another binary format) using base 64 encoding and some optional headers. PEM was initially used for encoding MIME-type email messages. PEM is also used extensively for encoding certificates and private keys into a file that exists on a file system or in an email message.
PKCS7	Public Key Cryptography Standard #7 - This standard describes a general syntax for data that may have cryptography applied to it, such as digital signatures and digital envelopes. A signed package contains an embedded PKCS7 signature. This signature contains at a minimum the encrypted digest of the package, along with the signer's X.509 public key certificate. The signed package can also contain chain certificates. Chain certificates can be used when forming a chain of trust from the signer's certificate to a locally-stored trusted certificate.
PKCS12	Public Key Cryptography Standard #12 - This standard describes a syntax for storing cryptographic objects on disk. The package keystore is maintained in this format.
Package keystore	A repository of certificates and keys that can be queried by the package tools.

Certificate Management

Before creating a signed package, you must have a package keystore. This package keystore contains certificates in the form of objects. Two types of objects exist in a package keystore:

Trusted certificate

A trusted certificate contains a single public key certificate that belongs to another entity. The trusted certificate is named as such because the keystore owner trusts that the public key in the certificate indeed belongs to the identity indicated by the “subject” (owner) of the certificate. The issuer of the certificate vouches for this trust by signing the certificate.

Trusted certificates are used when verifying signatures and when initiating a connection to a secure (SSL) server.

User key

A user key holds sensitive cryptographic key information. This information is stored in a protected format to prevent unauthorized access. A user key consists of both the user's private key and the public key certificate that corresponds to the private key.

User keys are used when creating a signed package.

By default, the package keystore is stored in the /var/sadm/security directory. Individual users can also have their own keystore stored by default in the $HOME/.pkg/security directory.

On disk, a package keystore can be in two formats: a multiple-file format and a single-file format. A multiple-file format stores its objects in multiple files. Each type of object is stored in a separate file. All of these files must be encrypted using the same passphrase. A single-file keystore stores all of its objects in a single file on the file system.

The primary utility used to manage the certificates and the package keystore is the pkgadm command. The following subsections describe the more common tasks used for managing the package keystore.

Adding Trusted Certificates to the Package Keystore

A trusted certificate can be added to the package keystore using the pkgadm command. The certificate can be in PEM or DER format. For example:

$ pkgadm addcert -t /tmp/mytrustedcert.pem

In this example, the PEM format certificate called mytrustedcert.pem is added to the package keystore.

Adding a User Certificate and Private Key to the Package Keystore

The pkgadm command does not generate user certificates or private keys. User certificates and private keys are normally obtained from a Certificate Authority, such as Verisign. Or, they are generated locally as a self-signed certificate. Once the key and certificate are obtained, they can be imported into the package keystore using the pkgadm command. For example:

pkgadm addcert -n myname -e /tmp/myprivkey.pem /tmp/mypubcert.pem

In this example, the following options are used:

`-n` myname	Identifies the entity (myname) in the package keystore on which you wish to operate. The myname entity becomes the alias under which the objects are stored.
`-e` `/tmp/`myprivkey.pem	Specifies the file that contains the private key. In this case, the file is myprivkey.pem, which is located in the `/tmp` directory.
`/tmp/`mypubcert.pem	Specifies the PEM format certificate file called mypubcert.pem.

Verifying the Contents in the Package Keystore

The pkgadm command is also used to view the contents of the package keystore. For example:

$ pkgadm listcert

This command displays the trusted certificates and private keys in the package keystore.

Deleting Trusted Certificates and Private Keys From the Package Keystore

The pkgadm command can be used to delete trusted certificates and private keys from the package keystore.

When you delete user certificates, the alias of the certificate/key pair must be specified. For example:

$ pkgadm removecert -n myname

The alias of the certificate is the common name of the certificate, which can be identified using the pkgadm listcert command. For example, this command deletes a trusted certificate entitled Trusted CA Cert 1:

$ pkgadm removecert -n "Trusted CA Cert 1"

Note - If you have both a trusted certificate and a user certificate stored using the same alias, they are both deleted when you specify the -n option.

Signed Packages Creation

The process of creating signed packages involves three basic steps:

Creating an unsigned, directory-format package.
Importing the signing certificate, CA certificates, and private key into the package keystore.
Signing the package from Step 1 with the certificates from Step 2.

Note - The packaging tools do not create certificates. These certificates must be obtained from a Certificate Authority, such as Verisign or Thawte.

Each step for creating signed packages is described in the following procedures.

How to Create an Unsigned, Directory-Format Package

The procedure for creating an unsigned, directory-format package is the same as the procedure for creating a normal package, as previously described in this manual. The following procedure describes the process of creating this unsigned, directory-format package. If you need more information, refer to the previous sections about building packages.

Create the pkginfo file.

The pkginfo file should have the following basic content:

PKG=SUNWfoo
BASEDIR=/
NAME=My Test Package
ARCH=sparc
VERSION=1.0.0
CATEGORY=application

Create the prototype file.

The prototye file should have the following basic content:

$cat prototype
i pkginfo
d none usr 0755 root sys
d none usr/bin 0755 root bin
f none usr/bin/myapp=/tmp/myroot/usr/bin/myapp 0644 root bin

List the contents of the object source directory.

For example:

$ ls -lR /tmp/myroot

The output would appear similar to the following:

/tmp/myroot:
total 16
drwxr-xr-x   3 abc      other        177 Jun  2 16:19 usr

/tmp/myroot/usr:
total 16
drwxr-xr-x   2 abc      other        179 Jun  2 16:19 bin

/tmp/myroot/usr/bin:
total 16
-rw-------   1 abc      other       1024 Jun  2 16:19 myapp

Create the unsigned package.

pkgmk -d `pwd`

The output would appear similar to the following:

## Building pkgmap from package prototype file.
## Processing pkginfo file.
WARNING: parameter <PSTAMP> set to "syrinx20030605115507"
WARNING: parameter <CLASSES> set to "none"
## Attempting to volumize 3 entries in pkgmap.
part  1 -- 84 blocks, 7 entries
## Packaging one part.
/tmp/SUNWfoo/pkgmap
/tmp/SUNWfoo/pkginfo
/tmp/SUNWfoo/reloc/usr/bin/myapp
## Validating control scripts.
## Packaging complete.

The package now exists in the current directory.

How to Import the Certificates Into the Package Keystore

The certificate and private key to be imported must exist as a PEM- or DER-encoded X.509 certificate and private key. In addition, any intermediate or “chain” certificates linking your signing certificate to the Certificate Authority certificate must be imported into the package keystore before a package can be signed.

Note - Each Certificate Authority can issue certificates in various formats. To extract the certificates and private key out of the PKCS12 file and into a PEM-encoded X.509 file (suitable for importing into the package keystore), use a freeware conversion utility such as OpenSSL.

If your private key is encrypted (which should usually be the case), you are prompted for the passphrase. Also, you are prompted for a password to protect the resulting package keystore. You can optionally not supply any password, but doing so results in an unencrypted package keystore.

The following procedure describes how to import the certificates using the pkgadm command once the certificate is in the proper format.

Import all the Certificate Authority certificates found in your PEM- or DER-encoded X.509 certificate file.

For example, to import all the Certificate Authority certificates found in the file ca.pem, you would type the following:

$ pkgadm addcert -k ~/mykeystore -ty ca.pem

The output would appear similar to the following:

Trusting certificate <VeriSign Class 1 CA Individual \
Subscriber-Persona Not Validated>
Trusting certificate </C=US/O=VeriSign, Inc./OU=Class 1 Public \
Primary Certification Authority
Type a Keystore protection Password.
Press ENTER for no protection password (not recommended): 
For Verification: Type a Keystore protection Password.
Press ENTER for no protection password (not recommended): 
Certificate(s) from <ca.pem> are now trusted

In order to import your signing key into the package keystore, you must supply an alias that is used later when signing the package. This alias can also be used if you want to delete the key from the package keystore.

For example, to import your signing key from the file sign.pem, you would type the following:

$ pkgadm addcert -k ~/mykeystore -n mycert sign.pem

The output would appear similar to the following:

Enter PEM passphrase:
Enter Keystore Password: 
Successfully added Certificate <sign.pem> with alias <mycert>

Verify that the certificates are in the package keystore.
For example, to view the certificates in the keystore created in the previous step, you would type the following:
```
$ pkgadm listcert -k ~/mykeystore
```

How to Sign the Package

Once the certificates are imported into the package keystore, you can now sign the package. The actual signing of the package is done using the pkgtrans command.

Sign the package using the pkgtrans command. Supply the location of the unsigned package and the alias of the key to sign the package.
For example, using the examples from the previous procedures, you would type the following to create a signed package called SUNWfoo.signed:
```
$ pkgtrans -g -k ~/mykeystore -n mycert . ./SUNWfoo.signed SUNWfoo
```
The output of this command would appear similar to the following:
```
Retrieving signing certificates from keystore </home/user/mykeystore>
Enter keystore password:
Generating digital signature for signer <Test User>
Transferring <SUNWfoot> package instance
```
The signed package is created in the file SUNWfoo.signed and is in the package-stream format. This signed package is suitable for copying to a web site and being installed using the pkgadd command and a URL.