PKI Registry Design

From Dogtag
Jump to: navigation, search

CS/IPA Design for Separating Default PKI Instance Creation from PKI Subsystem Packaging

Responsible Engineer: Matthew Harmsen

Changes to this design are documented in the "discussion" tab of this Wiki page!

NOTE:   While porting Dogtag from using tomcat5 (Dogtag 1.3) to tomcat6 (Dogtag 9.0), numerous changes were made to the registry model defined below. These changes are discussed in Bugzilla Bug #632425 - Port to tomcat6.

Requirements

Per John Dennis on meeting Fedora Packaging requirements:

   An RPM must own (e.g. list in it's %files) every file it installs, otherwise
   you end up with orphaned files and the inability of rpm to validate the set of
   installed files. Orphaned files can create numerous other problems.
   
   Generating files during install is generally frowned upon, however it's
   sometimes necessary, in most circumstances those files must still be listed in
   the %files using a %ghost directive. If you don't do this the files are neither
   removed during an uninstall nor can they be validated after installation. There
   are rare cases where a %post generated file will need to be removed in the
   %preun stage.
   
   Init scripts must be reviewable and verifiable, as such an init script must be
   contained in the package. rpm -V must be able to validate all init scripts. It
   is extremely doubtful a post install machine generated init script would ever
   get approved for Fedora or RHEL.
   
   It is never permissible to modify the file permissions of an installed file
   from what it is in the %files section, especially to add execute permissions.
   
   It is never permissible for a rpm install to prompt the user for input.
   
   It is generally undesirable when installing an rpm to start any service as a
   consequence of installation, especially one like pki which has numerous cross
   dependencies and complex configuration.
   
   Most of what occurs in /usr/share/pki/ca/setup/postinstall and
   /usr/bin/pkicreate should never occur during an rpm install.
   
   Setting special environment variables prior to an rpm install is not permitted.
   It must be possible to install, uninstall, and install again using exclusively
   the defined rpm commands "rpm -i" and "rpm -e" respectively.
   
   An rpm install is only about laying files down in the file system and possibly
   registering those files if necessary. An rpm install generally does not involve
   the execution of any of the packages components. Running pkicreate
   unconditionally in the %post section is not correct, it doesn't even check for
   the install vs. upgrade case (testing $1) which is the defined way to handle
   the situation you're trying to compensate for with DONT_RUN_PKICREATE. Please
   see https://fedoraproject.org/wiki/Packaging:ScriptletSnippets.
   
   Irrespective of when pkicreate is executed an rpm uninstall operation cannot
   leave the system in a state where a subsequent install will fail.
   
   The spec file is not following the init script guidelines found here:
   https://fedoraproject.org/wiki/Packaging/SysVInitScript
   
   Some of what pkicreate is doing is supposed to be done in the spec file, not an
   external script (this is compounded by calling pkicreate at the wrong time,
   e.g. during upgrade). Some of the execution logic in pkicreate is supposed to
   be in the spec file and explicitly controlled by the scriplet $1 argument (e.g.
   calling chkconfig, etc.). Some of what pkicreate is doing is supposed to be
   postponed to a manual step performed by the user *after* installing the
   package. Finally the problems are exacerbated by not properly tracking the
   files belonging to the package.

Associated Bugs

Detailed Design

Design Considerations

To address the numerous issues brought forth by John Dennis, the PKI team would like to propose an over-all solution heavily based upon what the Directory Server team has already implemented.

PKI Packages

This design requires changes to the following PKI instance package containing "pkicreate" and "pkiremove":

  • pki-setup

Additionally, this design requires changes to the following top-level PKI subsystem packages:

  • pki-ca
  • pki-kra
  • pki-ocsp
  • pki-ra
  • pki-tks
  • pki-tps

Finally, this design requires minimal changes to the following additional PKI packages:

  • pki-common
  • pki-silent

PKI Subsystems

This design should be applied to ALL instances of the following PKI subsystems:

  • Certificate Authority (CA)
  • Data Recovery Manager (DRM)
  • Online Certificate Status Protocol Manager (OCSP)
  • Registration Authority (RA)
  • Token Key Service (TKS)
  • Token Processing System (TPS)

High-Level Design

  • PKI Instance Package
    • The pki-setup package will require administrators to create an initial default instance (as well as any additional instances) of all PKI subsystems.
      • The new naming scheme will consist of a subsystem prefix as a part of each instance name (e. g. - "pki-ca-default").
      • References to individual instances of each PKI subsystem will need to be stored as subsystem prefixed names under the "/etc/sysconfig/" directory.
      • The "-pki_instance_name=<pki_instance_id>" option to "pkicreate" and "pkiremove" will be changed to exclude this new subsystem prefix (e. g. - "-pki_instance_name=pki-ca" will become "-pki_instance_name=default").
      NOTE:  For IPA, this will require changing PKI_INSTANCE_NAME="pki-ca" to PKI_INSTANCE_NAME="default"
             in https://fedorahosted.org/freeipa/browser/ipaserver/install/cainstance.py
             to avoid calling the instance "pki-ca-pki-ca".  Additionally, this may require changing other areas
             of the code to refer to the new instance name, "pki-ca-default" rather than "pki-ca".
    • Installation, upgrading, or removing the pki-setup package will do nothing to existing PKI instances.
  • PKI Subsystem Packages
    • Top-level PKI subsystem packages will no longer invoke a call to the "pkicreate" program.
    • Top-level PKI subsystem packages will now own a single startup/shutdown/status service script (e. g. - pki-ca will own a file called "/etc/init.d/pki-ca").
      • Each startup/shutdown/status service script will loop over all instances of a particular PKI subsystem (e. g. - "/etc/init.d/pki-ca" will operate on the specified "/etc/syconfig/pki-ca-*" instance(s)).
    • Installation of a top-level PKI subsystem package will:
      • register the startup/shutdown/status service script with chkconfig
      • startup any and all associated PKI instances of that PKI subsystem type
    • Upgrading a top-level PKI subsystem package will:
      • conditionally restart any and all associated pre-existing PKI instances of that PKI subsystem type
    • Removing a top-level PKI subsystem package will:
      • shutdown any and all associated PKI instances of that PKI subsystem type
      • de-register the startup/shutdown/status service script from chkconfig

Low-Level Design

  • PKI Instance Package
    • Modify the "pkicreate" script option "-pki_instance_name=<pki_instance_id>" to prepend a new subsystem prefix based upon the required "-subsystem_type=<subsystem_type> option
    • Modify the "pkicreate" script to create the appropriate start/stop logic under the "/etc/sysconfig/" directory
    • Modify the "pkicreate" script such that it no longer creates a start/stop script under the "/etc/init.d" directory
    • Modify the "pkicreate" script USAGE to include "default" examples for "pki-ca", "pki-kra", "pki-ocsp", "pki-ra", "pki-tks", and "pki-tps"
    • Modify the "pkiremove" script to require the "-subsystem_type=<subsystem_type> option
    • Modify the "pkiremove" script option "-pki_instance_name=<pki_instance_id>" to prepend a new subsystem prefix based upon the required "-subsystem_type=<subsystem_type> option
    • Modify the "pkiremove" script to remove the appropriate start/stop logic under the "/etc/sysconfig/" directory
    • Modify the "pkiremove" script such that it no longer attempts to remove a start/stop script from under the "/etc/init.d" directory
    • Modify the "pkiremove" script USAGE to require the "-subsystem_type=<subsystem_type> option
    • Modify the "pkiremove" script USAGE to include "default" examples for "pki-ca", "pki-kra", "pki-ocsp", "pki-ra", "pki-tks", and "pki-tps"
  • PKI Subsystem Packages
    • Modify each PKI subsystem "httpd" file to loop over CA instances located in the "/etc/sysconfig" directory
    • Modify each PKI subsystem to include this "httpd" file in its "%files" section as "/etc/init.d/pki-<subsystem>"
    • Modify each PKI subsystem to contain the appropriate "%postinstall" and "%preuninstall" logic for chkconfig registration and PKI instance startup and shutdown
  • Additional PKI Packages
    • Modify pki-common to require a runtime dependency of pki-silent.
    • Modify pki-silent templates to use the new subsystem prefix default instance names (e. g. - "pki-ca" becomes "pki-ca-default").