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.
