2573N/A.. The contents of this file are subject to the terms of the
2573N/A Common Development and Distribution License (the "License").
2573N/A You may not use this file except in compliance with the License.
2573N/A See the License for the specific language governing permissions
2573N/A and limitations under the License.
2573N/A.. When distributing Covered Code, include this CDDL HEADER in each
2573N/A If applicable, add the following below this CDDL HEADER, with the
2573N/A fields enclosed by brackets "[]" replaced with your own identifying
2573N/A information: Portions Copyright [yyyy] [name of copyright owner]
2573N/A.. Copyright (c) 2011, Oracle
and/or its affiliates. All rights reserved.
2525N/AOne important consideration in the design of IPS was being able to
2525N/Avalidate that the software installed on the customer's machine was
2525N/Aactually as originally specified by the publisher. This ability to
2525N/Avalidate the installed system is key for both the customer and the
2525N/ATo support this validation, manifests can be signed in IPS with the
2525N/Asignatures becoming part of the manifest. Signatures are represented
2525N/Aas actions like all other manifest content. Since manifests contain
2525N/Aall the package metadata - file permissions, ownership, content
2525N/Ahashes, etc, a signature action that validates that the manifest has
2525N/Anot be altered since it was published is an important part of system
2525N/Avalidation, and insures that the package has not be altered.
2525N/AThe signature actions form a Merkle, or hash, tree that includes the
2525N/Adelivered binaries such that complete verification of the installed
2525N/Asoftware is possible. There are other uses for manifest signing
2525N/Abeyond validation; signatures can also be used to indicate approval by
2525N/Aother organizations or parties. For example, the internal QA
2525N/Aorganization could sign manifests of Solaris packages once they had be
2525N/Adetermined to be qualified for production use; policy settings could
2525N/Amandate such approvals prior to installation.
2525N/AAs a result, a useful characteristic for signatures is to be
2525N/Aindependent of other signatures in a manifest; it was decided
2525N/Anecessary to support the addition (or removal) of signatures (but not
2525N/Aother actions) in a manifest without invalidating the other signatures
2525N/Athat might be present. This feature also facilitates production
2525N/Ahandoffs, with signatures used along the path to indicate completion
2525N/Aalong the way; subsequent steps can optionally remove previous
2525N/Asignatures at any time without ill-effect.
2573N/ASignature actions look like this::
2573N/A signature <hash of certificate> algorithm=<signature algorithm> \
2573N/A value=<signature value> \ chain="<hashes of certs needed to
2573N/A validate primary certificate>" \ version=<pkg version of
2525N/Ahash of the pem file(s) containing the x.509 certificate(s)
2525N/Adownloadable from the originating repository; the value is the signed
2525N/Ahash of the manifest's message text, prepared as discussed below. The
2525N/Apayload certificate is the certificate which verifies the value in
2525N/Acertificate path that leads from the payload certificate to the trust
2525N/Aanchor(s) that was established as part of the publisher configuration.
2525N/ATwo types of signature algorithms are currently supported. The first
2525N/Ais the rsa group of signature algorithms; an example is "rsa-sha256".
2525N/AThe bit after the dash specifies the hash algorithm to use to change
2525N/Athe message text into a single value the rsa algorithm can use.
2525N/AThe second type of signature algorithm is compute the hash only. This
2525N/Atype of algorithm exists primarily for testing and process
2525N/Averification purposes and presents the hash as the signature value. A
2525N/Asignature action of this type is indicated by the lack of a payload
2525N/Acertificate hash. This type of signature action is verified if the
2525N/Aimage is configured to check signatures. Its presence however does
2573N/Anot count as a signature if signatures are required::
2573N/A signature algorithm=<hash algorithm> value=<hash> \ version=<pkg
2525N/AAdditional signature types (pgp, for example) may be added in the
2525N/AAdditional metadata can be added to a signature if desired, as with
2525N/Aany other action; such metadata is protected by that signature.
2525N/APolicies may be set for the image or for specific publishers. The
2525N/Apolicies include ignoring signatures, verifying existing signatures,
2525N/Arequiring signatures, and requiring that specific common names must be
2525N/Aseen in the chain of trust. Other policies may be added in the
2525N/APublishing a signed manifest is a two step process. First, the
2525N/Apackage is published unsigned, to a repository. The package is then
2525N/Aupdated in place, using pkgsign, appending a signature action to the
2525N/Amanifest in the repository but leaving the package, including its
2525N/Atimestamp, intact. This process allows a signature action to be added
2525N/Aby someone other than the publisher without invalidating the original
2525N/Apublisher's signature. For example, the QA department of a company
2525N/Amay want to sign all packages that are installed internally to
2525N/Aindicate they have been approved for use, but not republish the
2525N/Apackages which would create a new timestamp and invalidate the
2525N/Asignature of the original publisher.
2525N/ANote that pkgsign is the only way to publish a signed package. If one
2525N/Aattempts to publish a package already containing a signature, that
2525N/Asignature is removed with a warning. The pkgsign man page contains
2525N/Aexamples of how to use pkgsign.
2562N/AOne current restriction to be aware of is that varianted signatures are ignored.
2562N/AThat means that doing a pkgmerge on a pair of manifests will invalidate any
2562N/Asignatures which were previously applied. It's safest if signing the package is
2562N/Athe last thing done to the package before it's made available to users.
2562N/APkgsign does not perform all the possible checks for its inputs when signing
2562N/Apackages. This means it's important to check signed packages to insure that
2562N/Athey can be properly installed after being signed. What follows are some of the
2562N/Aerrors that can appear when attempting to install or update a signed package
2562N/Aalong with explanations of what the errors mean and how to solve the problem.
2562N/AErrors involving signed packages
2562N/AA signed package can fail to install or update for reasons that are unique. For
2562N/Aexample, if a package's signature fails to verify, or if it's chain of trust
2562N/Acan't be verified or anchored to a trusted certificate, the package will fail to
2562N/Ainstall. What follows are some examples of different failure paths and what can
2573N/A pkg install: The certificate which issued this certificate:
2573N/A could not be found. The issuer is:
2562N/AThe error shown above happens when a certificate in the chain of trust is
2562N/Amissing or otherwise erroneous. In this case, there were three certificates in
2562N/Athe chain of trust when the package was signed. It was rooted in the trust
2562N/Aanchor, a certificate named ta3. Ta3 signed a chain cert named ch1_ta3.
2562N/ACh1_ta3 signed a code signing certificate named cs1_ch1_ta3. When pkg tried to
2562N/Ainstall the package, it was able to locate the code signing certificate,
2562N/Acs1_ch1_ta3, but it couldn't locate the chain certificate, ch1_ta3, so the chain
2562N/Aof trust could not be established. The most common cause of this problem is
2562N/Afailing to provide the right certificate(s) to the -i option of pkgsign.
2573N/A pkg install: The certificate which issued this certificate:
2573N/A could not be found. The issuer is:
2562N/AThe error shown above is similar to the error in example 1 but has a different
2562N/Acause. In this case, the package was signed using the cs1_cs8_ch1_ta3
2562N/Acertificate which was signed by the cs8_ch1_ta3 certificate. The problem is
2562N/Athat the cs8_ch1_ta3 certificate wasn't authorized to sign other certificates.
2562N/A(To be specific, the cs8_ch1_ta3 certificate had the basicConstraints extension
2562N/Aset to CA:false and marked critical.) When pkg verifies the chain of trust, it
2562N/Adoesn't find a certificate which was allowed to sign the cs1_cs8_ch1_ta3
2562N/Acertificate. Since the chain of trust can't be verified from the leaf to the
2562N/Aroot, pkg prevents the package from being installed.
2573N/A pkg install: Chain was rooted in an untrusted self-signed certificate.
2562N/AThe error shown above happens when a chain of trust ends in a self-signed
2562N/Acertificate which isn't trusted by the system. When a developer creates a chain
2562N/Aof certificates using openssl for testing, the root certificate is often
2562N/Aself-signed since there's little reason to have an outside company verify a
2562N/Acertificate only used for testing. In a test situation, there are two
2562N/Asolutions. The first is to add the self-signed certificate which is the root of
2562N/Aservice. This mirrors the likely situation customers will encounter where a
2562N/Aproduction package is signed with a certificate that's ultimately rooted in a
2562N/Acertificate that's delivered with the operating system as a trust anchor. The
2562N/Asecond solution is to approve the self-signed certificate for the publisher
2562N/Awhich offers the package for testing by using the --approve-ca-cert option for
2562N/Athe set-publisher subcommand to pkg.
2573N/A could not be verified for this reason:
2573N/A The signature value did not match the expected value. Res: 0
2573N/A The signature's hash is 0ce15c572961b7a0413b8390c90b7cac18ee9010
2562N/AThe error shown above happens when the value on the signature action could not
2562N/Abe verified using the certificate which the action claims was paired with the
2562N/Akey used to sign the package. There are three possible causes for an error like
2562N/Athis. The first is that the package has been changed since it was signed. This
2562N/Ais unlikely to happen since pkgsend will strip existing signature actions during
2562N/Apublication (since the new timestamp the package will get will invalidate the
2562N/Aold signature) but is possible if the package's manifest has been hand edited
2562N/Asince signing. The second is that there's a bug in pkg. The third, and most
2562N/Alikely cause, is that the key and certificate used to the sign the package
2562N/Aweren't a matched pair. If the certificate given to the -c option of pkgsign
2562N/Awasn't created with the key given to the -k option of pkgsign, pkgsign will sign
2562N/Athe package but the package's signature won't be verified.
2573N/A pkg install: The certificate whose subject is
2573N/A could not be verified because it uses a critical extension that pkg5 cannot
2573N/A handle yet. Extension name:issuerAltName
2562N/AThe error above happens when a certificate in the chain of trust uses a critical
2562N/Aextension which pkg doesn't understand. Until pkg learns how to process that
2562N/Acritical extension, the only solution is to regenerate the certificate without
2562N/Athe problematic critical extension.
2573N/A pkg install: The certificate whose subject is
2573N/A could not be verified because it has an extension with a value that pkg(5)
2573N/A Extension value:Encipher Only
2562N/AThe error above is similar to the error in example except that the problem is
2562N/Anot with an unfamiliar critical extension but with a value that pkg doesn't
2562N/Aunderstand for an extension which pkg does understand. In this case, pkg
2562N/Aunderstands the keyUsage extension, but doesn't understand the value "Encipher
2562N/AOnly." The error will look the same whether the extension in question is
2562N/Acritical or not. The solution until pkg learns about the value in question is
2562N/Ato remove the value from the extension or remove the extension entirely.
2573N/A pkg install: The certificate whose subject is
2573N/A could not be verified because it has been used inappropriately.
2573N/A The way it is used means that the value for extension keyUsage must include
2573N/A 'DIGITAL SIGNATURE' but the value was 'Certificate Sign, CRL Sign'.
2562N/AThe error above happens when a certificate has been used for a purpose for which
2573N/Ait was not authorized. In this case, the certificate ch1_ta3 has been used to
2562N/Asign the package. It's keyUsage extension means that it's only valid to use
2562N/Athat certificate to sign other certificates and CRL's.
2573N/A has been modified on disk. Its hash value is not what was expected.
2562N/AThe error above means what it says. The certificate at the provided path is
2562N/Aused to verify the package being installed but the hash of the contents on disk
2562N/Adon't match what the signature action thought they should be. This indicates
2562N/Athat the certificate has been changed since it was last retrieved from the
2562N/Apublisher. The simple solution is to remove the certificate and allow pkg to
2573N/A pkg install: This certificate was revoked:
2562N/AThe error above indicates the certificate in question, which was in the chain of
2562N/Atrust for the package to be installed, was revoked by the issuer of the