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
2585N/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
2585N/AThe ``signature`` actions form a tree that includes the delivered binaries
2585N/Asuch that complete verification of the installed software is possible.
2585N/AThere are other uses for manifest signing beyond validation; signatures
2585N/Acan also be used to indicate approval by other organizations or parties.
2585N/AFor example, the internal QA organization could sign manifests of packages
2585N/Aonce it was determined the packages were qualified for production use.
2585N/APolicy could mandate such approvals prior to installation.
2525N/AAs a result, a useful characteristic for signatures is to be
2585N/Aindependent of other signatures in a manifest. Signatures can be
2585N/Aadded or removed without invalidating the other signatures
2525N/Athat might be present. This feature also facilitates production
2585N/Ahand offs, with signatures used along the path to indicate completion
2585N/Aalong the way. Subsequent steps can optionally remove previous
2585N/Asignatures at any time without ill effect.
2585N/A``signature`` actions look like this::
2573N/A signature <hash of certificate> algorithm=<signature algorithm> \
2585N/A chain="<hashes of certs needed to validate primary certificate>" \
2585N/A version=<pkg version of signature>
2585N/AThe payload and ``chain`` attributes represent the packaging
2585N/Ahash of the PEM (Privacy Enhanced Mail) files, containing the
2585N/Ax.509 certificates downloadable from the originating repository.
2585N/AThe value is the signed hash of the manifest's message text, prepared
2585N/Aas discussed below. The payload certificate is the certificate which
2585N/Averifies the value in ``value``.
2585N/AThe other certificates presented needs to form a
2525N/Acertificate path that leads from the payload certificate to the trust
2585N/Aanchors that were established as part of the publisher configuration.
2525N/ATwo types of signature algorithms are currently supported. The first
2585N/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
2585N/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::
2585N/A signature algorithm=<hash algorithm> value=<hash> \
2585N/A version=<pkg version of signature>
2525N/AAdditional metadata can be added to a signature if desired, as with
2585N/Aany other action. Such metadata is protected by that signature.
2585N/APolicies can 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
2585N/Aseen in the chain of trust. Other policies might be added in the
2585N/APublishing a signed manifest is a two step process:
2585N/A1. Publish the package unsigned to a repository.
2585N/A2. Update the package in place, using |pkgsign| to append
2585N/A a signature action to the manifest in the repository.
2585N/AThis process leaves the package intact, including its timestamp.
2585N/AThis process enables 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
2585N/Amight want to sign all packages that are installed internally to
2525N/Aindicate they have been approved for use, but not republish the
2585N/Apackages, which would create a new timestamp and invalidate the
2525N/Asignature of the original publisher.
2585N/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
2585N/Asignature is removed and a warning is emitted. The |pkgsign| man page
2585N/Acontains examples of how to use |pkgsign|.
2585N/AOne current restriction to be aware of is that signature actions with variants
2585N/Aare ignored. That means that doing a |pkgmerge| on a pair of manifests will
2585N/Ainvalidate any signatures which were previously applied. Signing the package
2585N/Ashould be the last step of the package development before the package is tested.
2585N/A|pkgsign| does not perform all the possible checks for its inputs when signing
2585N/Apackages. This means it's important to check signed packages to ensure 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.
2585N/AErrors Involving Signed Packages
2585N/A~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2585N/AA signed package can fail to install or update for reasons that are unique to
2585N/Asigned packages. For example, if a package's signature fails to verify, or if
2585N/Aits chain of trust can't be verified or anchored to a trusted certificate, the
2585N/Apackage will fail to install.
2585N/AWhen installing signed packages, certain image properties will influence the
2585N/Achecks that are performed on packages. These properties are:
2585N/A * ``signature-required-names``
2585N/A * ``trust-anchor-directory``
2585N/ASee the |pkg| man page for further information about these properties, and their
2585N/AWhat follows are some examples of different failure paths and what can
2585N/AExample 1: Chain Certificate Not Found
2585N/A``````````````````````````````````````
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
2585N/Amissing or otherwise erroneous.
2585N/AIn this case, there were three certificates in the chain of trust when the
2585N/Apackage was signed. It was rooted in the trust anchor, a certificate named
2585N/A``ta3``. ``ta3`` signed a chain cert named ``ch1_ta3``.
2585N/A``ch1_ta3`` signed a code signing certificate named ``cs1_ch1_ta3``. When |pkg|
2585N/Atried to install the package, it was able to locate the code signing
2585N/Acertificate, ``cs1_ch1_ta3``, but it couldn't locate the chain certificate,
2585N/A``ch1_ta3``, so the chain of trust could not be established.
2585N/AThe most common cause of this problem is failing to provide the right
2585N/Acertificate(s) to the ``-i`` option of |pkgsign|.
2585N/AExample 2: Authorized Certificate Not Found
2585N/A```````````````````````````````````````````
2573N/A pkg install: The certificate which issued this certificate:
2573N/A could not be found. The issuer is:
2585N/AThe error shown above is similar to the error in *Example 1* but has a different
2585N/AIn this case, the package was signed using the ``cs1_cs8_ch1_ta3``
2585N/Acertificate, which was signed by the ``cs8_ch1_ta3`` certificate.
2585N/AThe problem is that the ``cs8_ch1_ta3`` certificate wasn't authorized to sign
2585N/Aother certificates. (To be specific, the ``cs8_ch1_ta3`` certificate had the
2585N/A``basicConstraints`` extension set to ``CA:false`` and marked critical.)
2585N/AWhen |pkg| verifies the chain of trust, it doesn't find a certificate which was
2585N/Aallowed to sign the ``cs1_cs8_ch1_ta3`` certificate. Since the chain of trust
2585N/Acan't be verified from the leaf to the root, |pkg| prevents the package from
2585N/AExample 3: Untrusted Self-Signed Certificate
2585N/A````````````````````````````````````````````
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
2585N/Acertificate which isn't trusted by the system.
2585N/AWhen a developer creates a chain of certificates using ``openssl`` for testing,
2585N/Athe root certificate is usually self-signed, since there's little reason to have
2585N/Aan outside company verify a certificate only used for testing.
2585N/AIn a test situation, there are two solutions.
2585N/AThe first is to add the self-signed certificate which is the root of the chain
2585N/AThis mirrors the likely situation customers will encounter where a production
2585N/Apackage is signed with a certificate that's ultimately rooted in a certificate
2585N/Athat's delivered with the operating system as a trust anchor.
2585N/AThe second solution is to approve the self-signed certificate for the publisher
2585N/Awhich offers the package for testing by using the ``--approve-ca-cert``
2585N/Aoption for the ``set-publisher`` subcommand to |pkg|.
2585N/AExample 4: Signature Value Does Not Match Expected Value
2585N/A````````````````````````````````````````````````````````
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
2585N/Akey used to sign the package.
2585N/AThere are two possible causes for an error like this.
2585N/AThe first is that the package has been changed since it was signed. This
2585N/Ais unlikely to happen since |pkgsend| will strip existing signature actions
2585N/Aduring publication (since the new timestamp the package will get will invalidate
2585N/Athe old signature) but is possible if the package's manifest has been hand
2585N/AThe second, and most likely cause, is that the key and certificate used to the
2585N/Asign the package weren't a matched pair. If the certificate given to the
2585N/A``-c`` option of |pkgsign| wasn't created with the key given to the
2585N/A``-k`` option of |pkgsign|, the package is signed, but its signature won't
2585N/AExample 5: Unknown Critical Extension
2585N/A`````````````````````````````````````
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
2585N/Aextension which |pkg| doesn't understand.
2585N/AUntil |pkg| learns how to process that critical extension, the only solution is
2585N/Ato regenerate the certificate without the problematic critical extension.
2585N/AExample 6: Unknown Extension Value
2585N/A``````````````````````````````````
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
2585N/AThe error above is similar to the error in *Example 5* except that the problem is
2585N/Anot with an unfamiliar critical extension but with a value that |pkg| doesn't
2585N/Aunderstand for an extension which |pkg| does understand.
2585N/AIn this case, |pkg| understands the ``keyUsage`` extension, but doesn't
2585N/Aunderstand the value ‘``Encipher Only``.’ The error will look the same whether
2585N/Athe extension in question is critical or not.
2585N/AThe solution, until |pkg| learns about the value in question, is to remove the
2585N/Avalue from the extension, or remove the extension entirely.
2585N/AExample 7: Unauthorized Use of Certificate
2585N/A``````````````````````````````````````````
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'.
2585N/AThe error above occurs when a certificate has been used for a purpose for which
2585N/AIn this case, the certificate ``ch1_ta3`` has been used to sign the package.
2585N/AIt's ``keyUsage`` extension means that it's only valid to use that certificate
2585N/Ato sign other certificates and CRL's.
2585N/AExample 8: Unexpected Hash Value
2585N/A````````````````````````````````
2573N/A has been modified on disk. Its hash value is not what was expected.
2585N/AThe error above means what it says.
2585N/AThe certificate at the provided path is used to verify the package being
2585N/Ainstalled but the hash of the contents on disk don't match what the signature
2585N/Aaction thought they should be.
2585N/AThis indicates that the certificate has been changed since it was last retrieved
2585N/AThe simple solution is to remove the certificate and allow |pkg| to download
2585N/AExample 9: Revoked Certificate
2585N/A``````````````````````````````
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