1pkispawn(8) PKI Instance Creation Utility pkispawn(8)
2
6 pkispawn - Sets up a PKI subsystem.
7
10 pkispawn -s subsystem -f config_file [-h] [-v]
11
14 Sets up a PKI subsystem (CA, KRA, OCSP, TKS, or TPS) in a Tomcat
15 instance.
16 Note: A 389 Directory Server instance must be configured and running
19 before this script can be run. PKI server requires an internal direc‐
20 tory database. The default configuration assumes a Directory Server
21 instance running on the same machine on port 389. For more information
22 on creating a Directory Server instance, see dscreate(8).
23 An instance can contain multiple subsystems, although it may contain at
26 most one of each type of subsystem on a single machine. So, for exam‐
27 ple, an instance could contain CA and KRA subsystems, but not two CA
28 subsystems. To create an instance with a CA and a KRA, simply run
29 pkispawn twice, with values -s CA and -s KRA respectively.
30 The instances are created based on values for configuration parameters
33 in the default configuration (i.e.
34 /usr/share/pki/server/etc/default.cfg) and the user-provided configura‐
35 tion file. The user-provided configuration file is read after the
36 default configuration file, so any parameters defined in that file will
37 override parameters in the default configuration file. In general,
38 most users will store only those parameters which are different from
39 the default configuration in their user-provided configuration file.
40 This configuration file contains parameters that are grouped into sec‐
43 tions. These sections are stacked, so that parameters defined in ear‐
44 lier sections can be overwritten by parameters defined in later sec‐
45 tions. The sections are read in the following order: [DEFAULT], [Tom‐
46 cat], and the subsystem section ([CA], [KRA], [OCSP], [TKS], or [TPS]).
47 This allows the ability to specify parameters to be shared by all sub‐
48 systems in [DEFAULT] or [Tomcat], and system-specific customization.
49 Note: Any non-password related parameter values in the configuration
52 file that needs to contain a % character must be properly escaped. For
53 example, a value of foo%bar would be specified as foo%%bar in the con‐
54 figuration file.
55 At a minimum, the user-defined configuration file must provide some
58 passwords needed for the install. An example configuration file is
59 provided in the EXAMPLES section below. For more information on the
60 default configuration file and the parameters it contains (and can be
61 customized), see pki_default.cfg(5).
62 The pkispawn run creates several different installation files that can
65 be referenced later, if need be:
66 · For Tomcat-based instances, a Tomcat instance is created at
69 /var/lib/pki/pki_instance_name, where pki_instance_name is
70 defined in the configuration file.
71 · A log file of pkispawn operations is written to
73 /var/log/pki/pki-subsystem-spawn.timestamp.log.
74 · A .p12 (PKCS #12) file containing a certificate for a subsys‐
76 tem administrator is stored in pki_client_dir defined in the
77 configuration file.
78 When the utility is done running, the CA can be accessed by pointing a
82 browser to https://hostname:pki_https_port/. The agent pages can be
83 accessed by importing the CA certificate and administrator certificate
84 into the browser.
85 The PKI server instance can also be accessed using the pki command line
88 interface. See pki(1). For more extensive documentation on how to use
89 PKI features, see the Red Hat Certificate System Documentation at
90 https://access.redhat.com/knowledge/docs/Red_Hat_Certificate_System.
91 Instances created using pkispawn can be removed using pkidestroy. See
94 pkidestroy(8).
95 pkispawn supersedes and combines the functionality of pkicreate and
98 pkisilent, which were available in earlier releases of Certificate
99 Server. It is now possible to completely create and configure the Cer‐
100 tificate Server subsystem in a single step using pkispawn.
101 Note: Previously, as an alternative to using pkisilent to perform a
104 non-interactive batch configuration, a PKI instance could be interac‐
105 tively configured by a GUI-based configuration wizard via a Firefox
106 browser. GUI-based configuration of a PKI instance is unavailable in
107 this version of the product.
108
111 -s subsystem
112 Specifies the subsystem to be installed and configured, where sub‐
113 system is CA, KRA, OCSP, TKS, or TPS.
114 -f config_file
117 Specifies the path to the user-defined configuration file.
118 This file contains differences between the default configuration
119 and the custom configuration.
120 --precheck
123 Execute pre-checks and exit.
124 --skip-configuration
127 Run the first step of the installation (i.e. skipping the instance
128 configuration step).
129 --skip-installation
132 Run the second step of the installation (i.e. skipping the instance
133 installation step).
134 -h, --help
137 Prints additional help information.
138 -v
141 Displays verbose information about the installation.
142 This flag can be provided multiple times to increase verbosity.
143 See pkispawn -h for details.
144
147 Separate PKI instances
148 As described above, this version of PKI continues to support separate
149 PKI instances for all subsystems.
150 Separate PKI instances run as a single Java-based Apache Tomcat
153 instance, contain a single PKI subsystem (CA, KRA, OCSP, TKS, or TPS),
154 and must utilize unique ports if co-located on the same machine.
155 Shared PKI instances
158 Additionally, this version of PKI introduces the notion of a shared PKI
159 instance.
160 Shared PKI instances also run as a single Java-based Apache Tomcat
163 instance, but may contain any combination of up to one of each type of
164 PKI subsystem:
165 · CA
168 · TKS
170 · CA, KRA
172 · CA, OCSP
174 · TKS, TPS
176 · CA, KRA, TKS, TPS
178 · CA, KRA, OCSP, TKS, TPS
180 · etc.
182 Shared PKI instances allow all of their subsystems contained within
186 that instance to share the same ports, and must utilize unique ports if
187 more than one shared PKI instance is co-located on the same machine.
188 Semantically, a shared PKI instance that contains a single PKI subsys‐
191 tem is identical to a separate PKI instance.
192
195 If no options are specified, pkispawn will provide an interactive menu
196 to collect the parameters needed to install the Certificate Server
197 instance. Note that only the most basic installation options are pro‐
198 vided. This includes root CA, KRA, OCSP, TKS, and TPS connecting to an
199 existing directory server. More advanced setups such as cloned subsys‐
200 tems, subordinate or externally signed CA, subsystems that connect to
201 the directory server using LDAPS, and subsystems that are customized
202 beyond the options described below require the use of a configuration
203 file with the -f option.
204 The interactive option is most useful for those users getting familiar
207 with Certificate Server. The parameters collected are written to the
208 installation file of the subsystem, which can be found at /etc/syscon‐
209 fig/pki/tomcat/instance_name/subsystem/deployment.cfg.
210 The following parameters are queried interactively during the installa‐
213 tion process.
214 Subsystem Type
217 Subsystem (CA/KRA/OCSP/TKS/TPS):
218 The type of subsystem to be installed.
219 Prompted when the -s option is not specified.
220 The default value chosen is CA.
221 Instance Specific Parameters
224 Instance name:
225 The name of the tomcat instance in which the subsystem is to be
226 installed. The default value is pki-tomcat.
227 Note: Only one subsystem of a given type (CA, KRA, OCSP, TKS, TPS) can
230 exist within a given instance.
231 HTTP port:
234 The HTTP port of the Tomcat instance. The default value is 8080.
235 Secure HTTP port:
238 The HTTPS port of the Tomcat instance. The default value is 8443.
239 AJP port:
242 The AJP port of the Tomcat instance. The default value is 8009.
243 Management port:
246 The management port of the Tomcat instance. The default value is
247 8005.
248 Note: When deploying a new subsystem into an existing instance,
251 pkispawn will attempt to read the ports from deployment.cfg files
252 stored for previously installed subsystems for this instance. If suc‐
253 cessful, the installer will not prompt for these ports.
254 Administrative User Parameters
257 Username:
258 The username of the administrator of this subsystem. The default
259 value is <ca/kra/ocsp/tks/tps>admin.
260 Password:
263 Password for the administrator user.
264 Import certificate:
267 An optional parameter that can be used to import an already avail‐
268 able CA admin certificate into this instance.
269 Export certificate:
272 Setup the path where the admin certificate of this <subsystem>
273 should be stored.
274 The default value is $HOME/.dogtag/pki-tom‐
275 cat/<ca/kra/ocsp/tks/tps>_admin.cert.
276 Directory Server Parameters
279 Hostname:
280 Hostname of the directory server instance. The default value is
281 the hostname of the system.
282 Use a secure LDAPS connection?
285 Answering yes to this question will cause prompts for Secure LDAPS
286 Port: and Directory Server CA certificate pem file:.
287 Answering no to this question will cause a prompt for LDAP Port.
288 The initial default value for this question is no.
289 Secure LDAPS Port:
292 Secure LDAPS port for the directory server instance. The default
293 value is 636.
294 Directory Server CA certificate PEM file:
297 The fully-qualified path including the filename of the file which
298 contains an exported copy of the Directory Server's CA certificate
299 (e.g. $HOME/dscacert.pem).
300 This file must exist prior to pkispawn being able to utilize it.
301 For details on creation of this file see the EXAMPLES section below
302 entitled Installing PKI Subsystem with Secure LDAP Connection.
303 LDAP Port:
306 LDAP port for the directory server instance. The default value is
307 389.
308 Base DN:
311 The Base DN to be used for the internal database for this subsys‐
312 tem.
313 The default value is o=pki-tomcat-<subsystem>.
314 Bind DN:
317 The bind DN required to connect for the directory server.
318 This user must have sufficient permissions to install the required
319 schema and database.
320 The default value is cn=Directory Manager.
321 Password:
324 Password for the bind DN.
325 Security Domain Parameters
328 Name:
329 The name of the security domain. Required only if installing a root
330 CA.
331 Default value: <DNS domain name> Security Domain.
332 Hostname:
335 The hostname for the security domain CA. Required only for non-CA
336 subsystems.
337 The default value is the hostname of this system.
338 Secure HTTP port:
341 The https port for the security domain. Required only for non-CA
342 subsystems. The default value is 8443.
343 Username:
346 The username of the security domain administrator of the CA.
347 Required only for non-CA subsystems.
348 The default value is caadmin.
349 Password:
352 Password for the security domain administrator. Required for all
353 subsystems that are not root CAs.
354
357 This option is only available when pkispawn is invoked in a non-inter‐
358 active mode. When the --precheck option is provided, a set of basic
359 tests are performed to ensure that the parameters provided to pkispawn
360 are valid and consistent.
361 pkispawn will then exit with an exit code of 0 on success, or 1 on
364 failure. This mode can be used to perform basic tests prior to doing
365 any actual installation of the PKI server instance.
366 Flags are available to disable specific tests. For instance, one might
369 want to disable validation of the credentials for the internal database
370 user if the directory server instance has not yet been created.
371 See pki_default.cfg(5) for more details about available flags.
374
377 pkispawn provides a number of parameters to customize an instance
378 before it is created. Usually, most other customization can be done
379 after the server is created. However, sometimes certain types of cus‐
380 tomization need to be done before the server is created, but there are
381 no parameters for that. For example, configuring session timeout,
382 adding CSR extensions, customizing certificate profiles, configuring
383 TLS ciphers, etc. To support such customization, pkispawn provides a
384 two-step installation mode.
385 Generally, instance creation happens in one step (except for the exter‐
388 nal CA case). Internally, the process happens in two stages. In the
389 first stage, pkispawn will install the instance files (e.g. CS.cfg, NSS
390 database, profiles, etc.) in the instance directory and customize them
391 based on pkispawn parameters. In the second stage, pkispawn will start
392 the instance and configure the instance based on the instance configu‐
393 ration files (e.g. initializing database, generating certificates, con‐
394 figuring connectors, etc.). The two-step process allows the process to
395 be stopped after the first stage, allowing further customization to be
396 done before running the second stage.
397 To use two-step installation mode, prepare a normal pkispawn configura‐
400 tion file, then run pkispawn with the --skip-configuration parameter.
401 For example:
402 $ pkispawn -s CA -f myconfig.txt --skip-configuration
405 Then customize the files in the instance directory as needed. Finally,
409 finish the installation by running pkispawn again with the
410 --skip-installation parameter. For example:
411 $ pkispawn -s CA -f myconfig.txt --skip-installation
414
418 Installing Root CA
419 To install a root CA in a new instance execute the following command:
420 $ pkispawn -s CA -f myconfig.txt
423 where myconfig.txt contains the following text:
427 [DEFAULT]
430 pki_admin_password=Secret.123
431 pki_client_pkcs12_password=Secret.123
432 pki_ds_password=Secret.123
433 Prior to running this command, a Directory Server instance should be
437 created and running. This command assumes that the Directory Server
438 instance is using its default configuration:
439 · Installed on the local machine
442 · Listening on port 389
444 · The user is cn=Directory Manager, with the password specified
446 in pki_ds_password
447 This invocation of pkispawn creates a Tomcat instance containing a CA
451 running on the local machine with secure port 8443 and unsecure port
452 8080. To access this CA, simply point a browser to https://host‐
453 name:8443.
454 The instance name (defined by pki_instance_name) is pki-tomcat, and it
457 is located at /var/lib/pki/pki-tomcat. Logs for the instance are
458 located at /var/log/pki/pki-tomcat, and an installation log is written
459 to /var/log/pki/pki-subsystem-spawn.timestamp.log.
460 A PKCS #12 file containing the administrator certificate is created in
463 $HOME/.dogtag/pki-tomcat. This PKCS #12 file uses the password desig‐
464 nated by pki_client_pkcs12_password in the configuration file.
465 To access the agent pages, first import the CA certificate by accessing
468 the CA End Entity Pages and clicking on the Retrieval Tab. Be sure to
469 trust the CA certificate. Then, import the administrator certificate in
470 the PKCS #12 file.
471 Installing Root CA using ECC
474 To install a root CA in a new instance using ECC execute the following
475 command:
476 $ pkispawn -s CA -f myconfig.txt
479 where myconfig.txt contains the following text:
483 [DEFAULT]
486 pki_admin_password=Secret.123
487 pki_admin_key_algorithm=SHA256withEC
488 pki_admin_key_size=nistp256
489 pki_admin_key_type=ecc
490 pki_client_pkcs12_password=Secret.123
491 pki_ds_password=Secret.123
492 pki_sslserver_key_algorithm=SHA256withEC
493 pki_sslserver_key_size=nistp256
494 pki_sslserver_key_type=ecc
495 pki_subsystem_key_algorithm=SHA256withEC
496 pki_subsystem_key_size=nistp256
497 pki_subsystem_key_type=ecc
498 [CA]
500 pki_ca_signing_key_algorithm=SHA256withEC
501 pki_ca_signing_key_size=nistp256
502 pki_ca_signing_key_type=ecc
503 pki_ca_signing_signing_algorithm=SHA256withEC
504 pki_ocsp_signing_key_algorithm=SHA256withEC
505 pki_ocsp_signing_key_size=nistp256
506 pki_ocsp_signing_key_type=ecc
507 pki_ocsp_signing_signing_algorithm=SHA256withEC
508 In order to utilize ECC, the SSL Server and Subsystem key algorithm,
512 key size, and key type should be changed from SHA256withRSA to
513 SHA256withEC, 2048 to nistp256, and rsa to ecc, respectively. To use
514 an ECC admin key size and key type, the values should also be changed
515 from 2048 to nistp256, and rsa to ecc.
516 Additionally, for a CA subsystem, both the CA and OCSP Signing key
519 algorithm, key size, key type, and signing algorithm should be changed
520 from SHA256withRSA to SHA256withEC, 2048 to nistp256, rsa to ecc, and
521 SHA256withRSA to SHA256withEC, respectively.
522 Note: For all PKI subsystems including the CA, ECC is not supported for
525 the corresponding Audit Signing parameters. Similarly, for KRA subsys‐
526 tems, ECC is not supported for either of the corresponding Storage or
527 Transport parameters.
528 Installing KRA, OCSP, TKS, or TPS in Shared Instance
531 For this example, assume that a new CA instance has been installed by
532 executing the following command:
533 $ pkispawn -s CA -f myconfig.txt
536 where myconfig.txt contains the following text:
540 [DEFAULT]
543 pki_admin_password=Secret.123
544 pki_client_pkcs12_password=Secret.123
545 pki_ds_password=Secret.123
546 # Optionally keep client databases
547 pki_client_database_purge=False
548 To install a shared KRA in the same instance used by the CA execute the
552 following command:
553 $ pkispawn -s KRA -f myconfig.txt
556 where myconfig.txt contains the following text:
560 [DEFAULT]
563 pki_admin_password=Secret.123
564 pki_client_database_password=Secret.123
565 pki_client_pkcs12_password=Secret.123
566 pki_ds_password=Secret.123
567 pki_security_domain_password=Secret.123
568 To install a shared OCSP in the same instance used by the CA execute
572 the following command:
573 $ pkispawn -s OCSP -f myconfig.txt
576 where myconfig.txt contains the following text:
580 [DEFAULT]
583 pki_admin_password=Secret.123
584 pki_client_database_password=Secret.123
585 pki_client_pkcs12_password=Secret.123
586 pki_ds_password=Secret.123
587 pki_security_domain_password=Secret.123
588 To install a shared TKS in the same instance used by the CA execute the
592 following command:
593 $ pkispawn -s TKS -f myconfig.txt
596 where myconfig.txt contains the following text:
600 [DEFAULT]
603 pki_admin_password=Secret.123
604 pki_client_database_password=Secret.123
605 pki_client_pkcs12_password=Secret.123
606 pki_ds_password=Secret.123
607 pki_security_domain_password=Secret.123
608 To install a shared TPS in the same instance used by the CA execute the
612 following command:
613 $ pkispawn -s TPS -f myconfig.txt
616 where myconfig.txt contains the following text:
620 [DEFAULT]
623 pki_admin_password=Secret.123
624 pki_client_database_password=Secret.123
625 pki_client_pkcs12_password=Secret.123
626 pki_ds_password=Secret.123
627 pki_security_domain_password=Secret.123
628 [TPS]
630 # Shared TPS instances optionally utilize their shared KRA
631 # for server-side keygen
632 pki_enable_server_side_keygen=True
633 pki_authdb_basedn=dc=example,dc=com
634 Note: For this particular example, the computed default values for a
638 PKI instance name including its ports, URLs, machine names, etc. were
639 utilized as defined in /usr/share/pki/server/etc/default.cfg. Each
640 subsystem in this example will reside under the /var/lib/pki/pki-tomcat
641 instance housed within their own ca, kra, ocsp, tks, and tps subdirec‐
642 tories, utilizing the same default port values of 8080 (http), 8443
643 (https), 8009 (ajp), 8005 (tomcat), using the same computed hostname
644 and URL information, and sharing a single common PKI Administrator Cer‐
645 tificate.
646 The pki_security_domain_password is the admin password of the CA
649 installed in the same instance. This command should be run after a CA
650 is installed. This installs another subsystem within the same instance
651 using the certificate generated for the CA administrator for the sub‐
652 system's administrator. This allows a user to access both subsystems on
653 the browser with a single administrator certificate. To access the new
654 subsystem's functionality, simply point the browser to https://host‐
655 name:8443 and click the relevant top-level links.
656 To install TPS in a shared instance the following section must be added
659 to myconfig.txt:
660 [TPS]
663 pki_authdb_basedn=dc=example,dc=com
664 TPS requires an authentication database. The pki_authdb_basedn speci‐
668 fies the base DN of the authentication database.
669 TPS also requires that a CA and a TKS subsystems are already installed
672 in the same instance. Since they are in the same instance, a shared
673 secret key will automatically be generated in TKS and imported into
674 TPS.
675 Optionally, server-side key generation can be enabled in TPS by adding
678 the following parameter in [TPS]:
679 pki_enable_server_side_keygen=True
682 Enabling server-side key generation requires that a KRA subsystem is
686 already installed in the same instance.
687 Installing KRA, OCSP, TKS, or TPS in Separate Instance
690 For this example, assume that a new CA instance has been installed by
691 executing the following command:
692 $ pkispawn -s CA -f myconfig.txt
695 where myconfig.txt contains the following text:
699 [DEFAULT]
702 pki_admin_password=Secret.123
703 pki_client_pkcs12_password=Secret.123
704 pki_ds_password=Secret.123
705 # Optionally keep client databases
706 pki_client_database_purge=False
707 # Separated CA instance name and ports
708 pki_instance_name=pki-ca
709 pki_http_port=18080
710 pki_https_port=18443
711 # This Separated CA instance will be its own security domain
712 pki_security_domain_https_port=18443
713 [Tomcat]
715 # Separated CA Tomcat ports
716 pki_ajp_port=18009
717 pki_tomcat_server_port=18005
718 To install a separate KRA which connects to this remote CA execute the
722 following command:
723 $ pkispawn -s KRA -f myconfig.txt
726 where myconfig.txt contains the following text:
730 [DEFAULT]
733 pki_admin_password=Secret.123
734 pki_client_database_password=Secret.123
735 pki_client_pkcs12_password=Secret.123
736 pki_ds_password=Secret.123
737 pki_security_domain_password=Secret.123
738 # Optionally keep client databases
739 pki_client_database_purge=False
740 # Separated KRA instance name and ports
741 pki_instance_name=pki-kra
742 pki_http_port=28080
743 pki_https_port=28443
744 # Separated KRA instance security domain references
745 pki_issuing_ca=https://pki.example.com:18443
746 pki_security_domain_hostname=pki.example.com
747 pki_security_domain_https_port=18443
748 pki_security_domain_user=caadmin
749 [Tomcat]
751 # Separated KRA Tomcat ports
752 pki_ajp_port=28009
753 pki_tomcat_server_port=28005
754 [KRA]
756 # A Separated KRA instance requires its own
757 # PKI Administrator Certificate
758 pki_import_admin_cert=False
759 To install a separate OCSP which connects to this remote CA execute the
763 following command:
764 $ pkispawn -s OCSP -f myconfig.txt
767 where myconfig.txt contains the following text:
771 [DEFAULT]
774 pki_admin_password=Secret.123
775 pki_client_database_password=Secret.123
776 pki_client_pkcs12_password=Secret.123
777 pki_ds_password=Secret.123
778 pki_security_domain_password=Secret.123
779 # Optionally keep client databases
780 pki_client_database_purge=False
781 # Separated OCSP instance name and ports
782 pki_instance_name=pki-ocsp
783 pki_http_port=29080
784 pki_https_port=29443
785 # Separated OCSP instance security domain references
786 pki_issuing_ca=https://pki.example.com:18443
787 pki_security_domain_hostname=pki.example.com
788 pki_security_domain_https_port=18443
789 pki_security_domain_user=caadmin
790 [Tomcat]
792 # Separated OCSP Tomcat ports
793 pki_ajp_port=29009
794 pki_tomcat_server_port=29005
795 [OCSP]
797 # A Separated OCSP instance requires its own
798 # PKI Administrator Certificate
799 pki_import_admin_cert=False
800 To install a separate TKS which connects to this remote CA execute the
804 following command:
805 $ pkispawn -s TKS -f myconfig.txt
808 where myconfig.txt contains the following text:
812 [DEFAULT]
815 pki_admin_password=Secret.123
816 pki_client_database_password=Secret.123
817 pki_client_pkcs12_password=Secret.123
818 pki_ds_password=Secret.123
819 pki_security_domain_password=Secret.123
820 # Optionally keep client databases
821 pki_client_database_purge=False
822 # Separated TKS instance name and ports
823 pki_instance_name=pki-tks
824 pki_http_port=30080
825 pki_https_port=30443
826 # Separated TKS instance security domain references
827 pki_issuing_ca=https://pki.example.com:18443
828 pki_security_domain_hostname=pki.example.com
829 pki_security_domain_https_port=18443
830 pki_security_domain_user=caadmin
831 [Tomcat]
833 # Separated TKS Tomcat ports
834 pki_ajp_port=30009
835 pki_tomcat_server_port=30005
836 [TKS]
838 # A Separated TKS instance requires its own
839 # PKI Administrator Certificate
840 pki_import_admin_cert=False
841 To install a separate TPS which connects to this remote CA execute the
845 following command:
846 $ pkispawn -s TPS -f myconfig.txt
849 where myconfig.txt contains the following text:
853 [DEFAULT]
856 pki_admin_password=Secret.123
857 pki_client_database_password=Secret.123
858 pki_client_pkcs12_password=Secret.123
859 pki_ds_password=Secret.123
860 pki_security_domain_password=Secret.123
861 # Optionally keep client databases
862 pki_client_database_purge=False
863 # Separated TPS instance name and ports
864 pki_instance_name=pki-tps
865 pki_http_port=31080
866 pki_https_port=31443
867 # Separated TPS instance security domain references
868 pki_issuing_ca=https://pki.example.com:18443
869 pki_security_domain_hostname=pki.example.com
870 pki_security_domain_https_port=18443
871 pki_security_domain_user=caadmin
872 [Tomcat]
874 # Separated TPS Tomcat ports
875 pki_ajp_port=31009
876 pki_tomcat_server_port=31005
877 [TPS]
879 # Separated TPS instances require specifying a remote CA
880 pki_ca_uri=https://pki.example.com:18443
881 # Separated TPS instances optionally utilize a remote KRA
882 # for server-side keygen
883 pki_kra_uri=https://pki.example.com:28443
884 pki_enable_server_side_keygen=True
885 pki_authdb_basedn=dc=example,dc=com
886 # Separated TPS instances require specifying a remote TKS
887 pki_tks_uri=https://pki.example.com:30443
888 pki_import_shared_secret=True
889 # A Separated TPS instance requires its own
890 # PKI Administrator Certificate
891 pki_import_admin_cert=False
892 Note: For this particular example, besides passwords, sample values
896 were also utilized for PKI instance names, ports, URLs, machine names,
897 etc. Under no circumstances should these demonstrative values be con‐
898 strued to be required literal values.
899 A remote CA is one where the CA resides in another PKI server instance,
902 either on the local machine or a remote machine. In this case, mycon‐
903 fig.txt must specify the connection information for the remote CA and
904 the information about the security domain (the trusted collection of
905 subsystems within an instance).
906 The subsystem section is [KRA], [OCSP], [TKS], or [TPS]. This example
909 assumes that the specified CA hosts the security domain. The CA must
910 be running and accessible.
911 A new administrator certificate is generated for the new subsystem and
914 stored in a PKCS #12 file in $HOME/.dogtag/pki_instance_name.
915 As in a shared instance, to install TPS in a separate instance the
918 authentication database must be specified in the [TPS] section, and
919 optionally the server-side key generation can be enabled. If the CA,
920 KRA, or TKS subsystems required by TPS are running on a remote instance
921 the following parameters must be added into the [TPS] section to spec‐
922 ify their locations:
923 pki_ca_uri=https://<ca_hostname>:<ca_https_port>
926 pki_kra_uri=https://<kra_hostname>:<kra_https_port>
927 pki_tks_uri=https://<tks_hostname>:<tks_https_port>
928 If TPS and TKS are installed on separate instances the shared secret
932 key should be imported over the wire between the TKS and TPS automati‐
933 cally.
934 If the automated procedure fails for any unlikely reason the following
937 manual procedure will serve as a fallback. The key needs to be created
938 on the TKS side and imported into the TPS side in this case.
939 Generate the shared secret key (if needed) in TKS with the following
942 command:
943 $ tkstool -T -d /var/lib/pki/pki-tomcat/alias -n sharedSecret
946 Verify the shared secret key in TKS with the following command:
950 $ tkstool -L -d /var/lib/pki/pki-tomcat/alias
953 Once TPS is installed, shutdown TPS instance, then import the shared
957 secret key into TPS with the following command:
958 $ tkstool -I -d /var/lib/pki/pki-tomcat/alias -n sharedSecret
961 Verify the shared secret key in TPS with the following command:
965 $ tkstool -L -d /var/lib/pki/pki-tomcat/alias
968 The shared secret key nickname should be stored in the following prop‐
972 erty in the TPS's CS.cfg:
973 conn.tks1.tksSharedSymKeyName=sharedSecret
976 Finally, restart the TPS instance.
980 Installing CA, KRA, OCSP, TKS, or TPS using HSM
983 This section provides sample myconfig.txt files when a Hardware Secu‐
984 rity Module (HSM) is being utilized in a shared PKI instance.
985 For this example, assume that a new CA instance has been installed by
988 executing the following command:
989 $ pkispawn -s CA -f myconfig.txt
992 where myconfig.txt contains the following text:
996 [DEFAULT]
999 pki_admin_password=Secret.123
1000 pki_client_pkcs12_password=Secret.123
1001 pki_ds_password=Secret.123
1002 # Optionally keep client databases
1003 pki_client_database_purge=False
1004 # Provide HSM parameters
1005 pki_hsm_enable=True
1006 pki_hsm_libfile=<hsm_libfile>
1007 pki_hsm_modulename=<hsm_modulename>
1008 pki_token_name=<hsm_token_name>
1009 pki_token_password=<pki_token_password>
1010 # Provide PKI-specific HSM token names
1011 pki_audit_signing_token=<hsm_token_name>
1012 pki_sslserver_token=<hsm_token_name>
1013 pki_subsystem_token=<hsm_token_name>
1014 [CA]
1016 # Provide CA-specific HSM token names
1017 pki_ca_signing_token=<hsm_token_name>
1018 pki_ocsp_signing_token=<hsm_token_name>
1019 To install a shared KRA in the same instance used by the CA execute the
1023 following command:
1024 $ pkispawn -s KRA -f myconfig.txt
1027 where myconfig.txt contains the following text:
1031 [DEFAULT]
1034 pki_admin_password=Secret.123
1035 pki_client_database_password=Secret.123
1036 pki_client_pkcs12_password=Secret.123
1037 pki_ds_password=Secret.123
1038 pki_security_domain_password=Secret.123
1039 # Provide HSM parameters
1040 pki_hsm_enable=True
1041 pki_hsm_libfile=<hsm_libfile>
1042 pki_hsm_modulename=<hsm_modulename>
1043 pki_token_name=<hsm_token_name>
1044 pki_token_password=<pki_token_password>
1045 # Provide PKI-specific HSM token names
1046 pki_audit_signing_token=<hsm_token_name>
1047 pki_sslserver_token=<hsm_token_name>
1048 pki_subsystem_token=<hsm_token_name>
1049 [KRA]
1051 # Provide KRA-specific HSM token names
1052 pki_storage_token=<hsm_token_name>
1053 pki_transport_token=<hsm_token_name>
1054 To install a shared OCSP in the same instance used by the CA execute
1058 the following command:
1059 $ pkispawn -s OCSP -f myconfig.txt
1062 where myconfig.txt contains the following text:
1066 [DEFAULT]
1069 pki_admin_password=Secret.123
1070 pki_client_database_password=Secret.123
1071 pki_client_pkcs12_password=Secret.123
1072 pki_ds_password=Secret.123
1073 pki_security_domain_password=Secret.123
1074 # Provide HSM parameters
1075 pki_hsm_enable=True
1076 pki_hsm_libfile=<hsm_libfile>
1077 pki_hsm_modulename=<hsm_modulename>
1078 pki_token_name=<hsm_token_name>
1079 pki_token_password=<pki_token_password>
1080 # Provide PKI-specific HSM token names
1081 pki_audit_signing_token=<hsm_token_name>
1082 pki_sslserver_token=<hsm_token_name>
1083 pki_subsystem_token=<hsm_token_name>
1084 [OCSP]
1086 # Provide OCSP-specific HSM token names
1087 pki_ocsp_signing_token=<hsm_token_name>
1088 To install a shared TKS in the same instance used by the CA execute the
1092 following command:
1093 $ pkispawn -s TKS -f myconfig.txt
1096 where myconfig.txt contains the following text:
1100 [DEFAULT]
1103 pki_admin_password=Secret.123
1104 pki_client_database_password=Secret.123
1105 pki_client_pkcs12_password=Secret.123
1106 pki_ds_password=Secret.123
1107 pki_security_domain_password=Secret.123
1108 # Provide HSM parameters
1109 pki_hsm_enable=True
1110 pki_hsm_libfile=<hsm_libfile>
1111 pki_hsm_modulename=<hsm_modulename>
1112 pki_token_name=<hsm_token_name>
1113 pki_token_password=<pki_token_password>
1114 # Provide PKI-specific HSM token names
1115 pki_audit_signing_token=<hsm_token_name>
1116 pki_sslserver_token=<hsm_token_name>
1117 pki_subsystem_token=<hsm_token_name>
1118 To install a shared TPS in the same instance used by the CA execute the
1122 following command:
1123 $ pkispawn -s TPS -f myconfig.txt
1126 where myconfig.txt contains the following text:
1130 [DEFAULT]
1133 pki_admin_password=Secret.123
1134 pki_client_database_password=Secret.123
1135 pki_client_pkcs12_password=Secret.123
1136 pki_ds_password=Secret.123
1137 pki_security_domain_password=Secret.123
1138 # Provide HSM parameters
1139 pki_hsm_enable=True
1140 pki_hsm_libfile=<hsm_libfile>
1141 pki_hsm_modulename=<hsm_modulename>
1142 pki_token_name=<hsm_token_name>
1143 pki_token_password=<pki_token_password>
1144 # Provide PKI-specific HSM token names
1145 pki_audit_signing_token=<hsm_token_name>
1146 pki_sslserver_token=<hsm_token_name>
1147 pki_subsystem_token=<hsm_token_name>
1148 [TPS]
1150 # Shared TPS instances optionally utilize their shared KRA
1151 # for server-side keygen
1152 pki_enable_server_side_keygen=True
1153 pki_authdb_basedn=dc=example,dc=com
1154 Important: Since HSM keys are stored in the HSM, they cannot be backed
1158 up, moved, or copied to a PKCS #12 file. For example, if
1159 pki_hsm_enable is set to True, pki_backup_keys should be set to False
1160 and pki_backup_password should be left unset (the default values in
1161 /usr/share/pki/server/etc/default.cfg). Similarly, for the case of
1162 clones using an HSM, this means that the HSM keys must be shared
1163 between the master and its clones. Therefore, if pki_hsm_enable is set
1164 to True, both pki_clone_pkcs12_path and pki_clone_pkcs12_password
1165 should be left unset (the default values in
1166 /usr/share/pki/server/etc/default.cfg). Failure to comply with these
1167 rules will result in pkispawn reporting an appropriate error and exit‐
1168 ing.
1169 Installing CA Clone
1172 To install a CA clone execute the following command:
1173 $ pkispawn -s CA -f myconfig.txt
1176 where myconfig.txt contains the following text:
1180 [DEFAULT]
1183 pki_admin_password=Secret.123
1184 pki_client_database_password=Secret.123
1185 pki_client_pkcs12_password=Secret.123
1186 pki_ds_password=Secret.123
1187 pki_security_domain_password=Secret.123
1188 pki_security_domain_hostname=<master_ca_hostname>
1189 pki_security_domain_https_port=<master_ca_https_port>
1190 pki_security_domain_user=caadmin
1191 pki_security_domain_post_login_sleep_seconds=5
1192 [Tomcat]
1194 pki_clone=True
1195 pki_clone_pkcs12_password=Secret.123
1196 pki_clone_pkcs12_path=<path_to_pkcs12_file>
1197 pki_clone_replicate_schema=True
1198 pki_clone_uri=https://<master_ca_hostname>:<master_ca_https_port>
1199 A cloned CA is a CA which uses the same signing, OCSP signing, and
1203 audit signing certificates as the master CA, but issues certificates
1204 within a different serial number range. It has its own internal data‐
1205 base -- separate from the master CA database -- but using the same base
1206 DN, that keeps in sync with the master CA through replication agree‐
1207 ments between the databases. This is very useful for load sharing and
1208 disaster recovery. To create a clone, the myconfig.txt uses pkiclone*
1209 parameters in its [Tomcat] section which identify the original CA to
1210 use as a master template. Additionally, it connects to the master CA
1211 as a remote CA and uses its security domain.
1212 Before the clone can be generated, the Directory Server must be created
1215 that is separate from the master CA's Directory Server. The example
1216 assumes that the master CA and cloned CA are on different machines, and
1217 that their Directory Servers are on port 389.
1218 In addition, since this example does not utilize an HSM, the master's
1221 system certs and keys have been stored in a PKCS #12 file that is
1222 copied over to the clone subsystem in the location specified in
1223 <path_to_pkcs12_file>. This file needs to be readable by the user the
1224 Certificate Server runs as (by default, pkiuser) and be given the
1225 SELinux context pki_tomcat_cert_t.
1226 The master's system certificates can be exported to a PKCS#12 file when
1229 the master is installed if the parameter pki_backup_keys is set to True
1230 and the pki_backup_password is set. The PKCS#12 file is then found
1231 under /var/lib/pki/<instance_name>/alias. Alternatively, the PKCS#12
1232 file can be generated at any time post-installation using PKCS12Export.
1233 The pki_security_domain_post_login_sleep_seconds config specifies sleep
1236 duration after logging into a security domain, to allow the security
1237 domain session data to be replicated to subsystems on other hosts. It
1238 is optional and defaults to 5 seconds.
1239 An example invocation showing the export of the system certificates and
1242 keys, copying the keys to the replica subsystem, and setting the rele‐
1243 vant SELinux and file permissions is shown below. pwfile is a text
1244 file containing the password for the masters NSS DB (found in
1245 /etc/pki/instance_name/password.conf). pkcs12_password_file is a text
1246 file containing the password selected for the generated PKCS12 file.
1247 master# PKCS12Export -d /etc/pki/pki-tomcat/alias -p pwfile \
1250 -w pkcs12_password_file -o backup_keys.p12
1251 master# scp backup_keys.p12 clone:/backup_keys.p12
1252 clone# chown pkiuser: /backup_keys.p12
1254 clone# semanage -a -t pki_tomcat_cert_t /backup_keys.p12
1255 Note: From Dogtag 10.3, a slightly different mechanism has been pro‐
1259 vided to create and specify the required PKCS#12 file to the clone sub‐
1260 system. This new method is provided in addition to the method above,
1261 but will become the preferred method in future releases.
1262 This method can be used if both master and clone are 10.3 or above.
1265 To export the required keys from the master, use the pki-server command
1268 line tool.
1269 master# pki-server ca-clone-prepare -i pki-tomcat \
1272 --pkcs12-file backup_keys.p12 \
1273 --pkcs12-password Secret123
1274 master# scp backup_keys.p12 clone:/backup_keys.p12
1276 master# scp /etc/pki/pki-tomcat/external_certs.conf \
1277 clone:/external_certs.conf
1278 The external_certs.conf file contains information about third party
1282 certificates that were added to the master's certificate database using
1283 the pki-server command. The certificates themselves are stored in the
1284 backup_keys.p12 file. If there are no third-party certifcates that have
1285 been added, then the external_certs.conf file may not exist and should
1286 be ignored.
1287 The two files (backup_keys.p12 and external_certs.conf) are specified
1290 to pkispawn as below.
1291 [DEFAULT]
1294 pki_admin_password=Secret.123
1295 pki_client_database_password=Secret.123
1296 pki_client_pkcs12_password=Secret.123
1297 pki_ds_password=Secret.123
1298 pki_security_domain_password=Secret.123
1299 pki_security_domain_hostname=<master_ca_hostname>
1300 pki_security_domain_https_port=<master_ca_https_port>
1301 pki_security_domain_user=caadmin
1302 [Tomcat]
1304 pki_server_pkcs12_path=<path to pkcs12 file>
1305 pki_server_pkcs12_password=Secret.123
1306 pki_server_external_certs_path=<path to external_certs.conf file>
1307 pki_clone=True
1308 pki_clone_replicate_schema=True
1309 pki_clone_uri=https://<master_ca_hostname>:<master_ca_https_port>
1310 Note that the previous p12 parameters (pki_clonepkcs12*) are no longer
1314 needed, and will be ignored.
1315 Note: One current cloning anomaly to mention is the following scenario:
1318 1. Create a clone of a CA or of any other subsystem.
1321 2. Remove that just created clone.
1323 3. Immediately attempt the exact same clone again, in place of
1325 the recently destroyed instance. Before recreating this
1326 clone, make sure the pki_ds_remove_data=True is used in
1327 the clone's deployment config file. This will remove the
1328 old data from the previous clone.
1329 Here the Director Server instance may have worked itself in into a
1333 state where it no longer accepts connections, aborting the clone con‐
1334 figuration quickly.
1335 The fix to this is to simply restart the Directory Server instance
1338 before creating the clone for the second time. After restarting the
1339 Directory Server it should be possible to create the mentioned clone
1340 instance.
1341 Installing KRA or TKS Clone
1344 To install a KRA or TKS (OCSP and TPS unsupported as of now) execute
1345 the following command:
1346 $ pkispawn -s <subsystem> -f myconfig.txt
1349 where subsystem is KRA or TKS and myconfig.txt contains the following
1353 text:
1354 [DEFAULT]
1357 pki_admin_password=Secret.123
1358 pki_client_database_password=Secret.123
1359 pki_client_pkcs12_password=Secret.123
1360 pki_ds_password=Secret.123
1361 pki_security_domain_password=Secret.123
1362 pki_security_domain_hostname=<master_ca_hostname>
1363 pki_security_domain_https_port=<master_ca_https_port>
1364 pki_security_domain_user=caadmin
1365 [Tomcat]
1367 pki_clone=True
1368 pki_clone_pkcs12_password=Secret.123
1369 pki_clone_pkcs12_path=<path_to_pkcs12_file>
1370 pki_clone_replicate_schema=True
1371 pki_clone_uri=https://<master_subsystem_host>:<master_subsystem_https_port>
1372 pki_issuing_ca=https://<ca_hostname>:<ca_https_port>
1373 As with a CA clone, a KRA or TKS clone uses the same certificates and
1377 basic configuration as the original subsystem. The configuration
1378 points to the original subsystem to copy its configuration. This exam‐
1379 ple also assumes that the CA is on a remote machine and specifies the
1380 CA and security domain information.
1381 The parameter pki_clone_uri should be modified to point to the required
1384 master (KRA or TKS).
1385 As of 10.3, a slightly different mechanism has been introduced to gen‐
1388 erate and specify the PKCS#12 file and any third-party certificates.
1389 See the Installing CA Clone section for details.
1390 Installing CA Clone on the Same Host
1393 For testing purposes, it is useful to configure cloned CAs which exist
1394 (with their internal databases) on the same host as the master CA. To
1395 configure the cloned CA execute the following command:
1396 $ pkispawn -s CA -f myconfig.txt
1399 where myconfig.txt contains the following text:
1403 [DEFAULT]
1406 pki_admin_password=Secret123
1407 pki_client_database_password=Secret123
1408 pki_client_pkcs12_password=Secret123
1409 pki_ds_password=Secret123
1410 pki_ds_ldap_port=<unique port different from master>
1411 pki_ds_ldaps_port=<unique port different from master>
1412 pki_http_port=<unique port different from master>
1413 pki_https_port=<unique port different from master>
1414 pki_instance_name=<unique name different from master>
1415 pki_security_domain_hostname=<master_ca_hostname>
1416 pki_security_domain_https_port=<master_ca_https_port>
1417 pki_security_domain_password=Secret123
1418 [Tomcat]
1420 pki_ajp_port=<unique port different from master>
1421 pki_clone=True
1422 pki_clone_pkcs12_password=Secret123
1423 pki_clone_pkcs12_path=<path_to_pkcs12_file>
1424 pki_clone_uri=https://<master_ca_hostname>:<master_ca_https_port>
1425 pki_tomcat_server_port=<unique port different from master>
1426 [CA]
1428 pki_ds_base_dn=<identical value as master>
1429 pki_ds_database=<identical value as master>
1430 In this case, because both CA Tomcat instances are on the same host,
1434 they must have distinct ports. Similarly, each CA must use a distinct
1435 directory server instance for its internal database. Like the Tomcat
1436 instances, these are distinguished by distinct ports. The suffix being
1437 replicated (pki_ds_base), however, must be the same for both master and
1438 clone.
1439 Installing Subordinate CA in Existing Security Domain
1442 To install a subordinate CA in an existing security domain execute the
1443 following command:
1444 $ pkispawn -s CA -f myconfig.txt
1447 where myconfig.txt contains the following text:
1451 [DEFAULT]
1454 pki_admin_password=Secret.123
1455 pki_client_database_password=Secret.123
1456 pki_client_pkcs12_password=Secret.123
1457 pki_ds_password=Secret.123
1458 pki_security_domain_password=Secret.123
1459 pki_security_domain_hostname=<security_domain_ca_hostname>
1460 pki_security_domain_https_port=<security_domain_ca_https_port>
1461 pki_security_domain_user=caadmin
1462 [CA]
1464 pki_subordinate=True
1465 pki_issuing_ca=https://<master_ca_hostname>:<master_ca_https_port>
1466 pki_ca_signing_subject_dn=cn=CA Subordinate Signing,o=example.com
1467 A sub-CA derives its certificate configuration -- such as allowed
1471 extensions and validity periods -- from a superior or root CA. Other‐
1472 wise, the configuration of the CA is independent of the root CA, so it
1473 is its own instance rather than a clone. A sub-CA is configured using
1474 the pki_subordinate parameter and a pointer to the CA which issues the
1475 sub-CA's certificates.
1476 Note: The value of pki_ca_signing_subject_dn of a subordinate CA should
1479 be different from the root CA's signing subject DN.
1480 Installing Subordinate CA in New Security Domain
1483 To install a subordinate CA in a new security domain execute the fol‐
1484 lowing command:
1485 $ pkispawn -s CA -f myconfig.txt
1488 where myconfig.txt contains the following text:
1492 [DEFAULT]
1495 pki_admin_password=Secret.123
1496 pki_client_database_password=Secret.123
1497 pki_client_pkcs12_password=Secret.123
1498 pki_ds_password=Secret.123
1499 pki_security_domain_password=Secret.123
1500 pki_security_domain_hostname=<master CA security domain hostname>
1501 pki_security_domain_https_port=<master CA security domain https port>
1502 pki_security_domain_user=caadmin
1503 [CA]
1505 pki_subordinate=True
1506 pki_issuing_ca=https://<master_ca_hostname>:<master_ca_https_port>
1507 pki_ca_signing_subject_dn=cn=CA Subordinate Signing,o=example.com
1508 pki_subordinate_create_new_security_domain=True
1509 pki_subordinate_security_domain_name=Subordinate CA Security Domain
1510 In this section, the subordinate CA logs onto and registers with the
1514 security domain CA (using parameters pki_security_domain_hostname,
1515 pki_security_domain_user and pki_security_domain_password) as in the
1516 previous section, but also creates and hosts a new security domain. To
1517 do this, pki_subordinate_create_new_security_domain must be set to
1518 True. The subordinate CA security domain name can also be specified by
1519 specifying a value for pki_subordinate_security_domain_name.
1520 Note: The value of pki_ca_signing_subject_dn of a subordinate CA should
1523 be different from the root CA's signing subject DN.
1524 Installing Externally-Signed CA
1527 To install an externally signed CA execute the following command:
1528 $ pkispawn -s CA -f myconfig.txt
1531 This is a two-step process.
1535 In the first step, a certificate signing request (CSR) is generated for
1538 the signing certificate and myconfig.txt contains the following text:
1539 [DEFAULT]
1542 pki_admin_password=Secret.123
1543 pki_client_database_password=Secret.123
1544 pki_client_pkcs12_password=Secret.123
1545 pki_ds_password=Secret.123
1546 pki_security_domain_password=Secret.123
1547 [CA]
1549 pki_external=True
1550 pki_ca_signing_csr_path=/tmp/ca_signing.csr
1551 pki_ca_signing_subject_dn=cn=CA Signing,ou=External,o=example.com
1552 The CSR is written to pki_ca_signing_csr_path. The pki_ca_signing_sub‐
1556 ject_dn should be different from the subject DN of the external CA that
1557 is signing the request. The pki_ca_signing_subject_dn parameter can be
1558 used to specify the signing certificate's subject DN.
1559 The CSR is then submitted to the external CA, and the resulting cer‐
1562 tificate and certificate chain are saved to files on the system.
1563 In the second step, the configuration file has been modified to install
1566 the issued certificates. In place of the original CSR, the configura‐
1567 tion file now points to the issued CA certificate and certificate
1568 chain. There is also a flag to indicate that this completes the
1569 installation process (pki_external_step_two).
1570 [DEFAULT]
1573 pki_admin_password=Secret.123
1574 pki_client_database_password=Secret.123
1575 pki_client_pkcs12_password=Secret.123
1576 pki_ds_password=Secret.123
1577 pki_security_domain_password=Secret.123
1578 [CA]
1580 pki_external=True
1581 pki_external_step_two=True
1582 pki_cert_chain_path=/tmp/ca_cert_chain.cert
1583 pki_ca_signing_cert_path=/tmp/ca_signing.cert
1584 pki_ca_signing_subject_dn=cn=CA Signing Certificate,ou=External,o=example.com
1585 Then, the pkispawn command is run again:
1589 $ pkispawn -s CA -f myconfig.txt
1592 Installing PKI Subsystem with Secure LDAP Connection
1596 There are three scenarios in which a PKI subsystem (e.g. a CA) needs to
1597 communicate securely via LDAPS with a directory server:
1598 Scenario 1: A directory server exists which is already running LDAPS
1601 using a CA certificate that has been issued by some other CA. For this
1602 scenario, the CA certificate must be made available via a PEM file
1603 (e.g. $HOME/dscacert.pem) prior to running pkispawn such that the new
1604 CA may be installed and configured to communicate with this directory
1605 server using LDAPS.
1606 Scenario 2: A directory server exists which is currently running LDAP.
1609 Once a CA has been created, there is a desire to use its CA certificate
1610 to issue an SSL certificate for this directory server so that this CA
1611 and this directory server can communicate via LDAPS. For this sce‐
1612 nario, since there is no need to communicate securely during the
1613 pkispawn installation/configuration, simply use pkispawn to install and
1614 configure the CA using the LDAP port of the directory server, issue an
1615 SSL certificate from this CA for the directory server, and then recon‐
1616 figure the CA and directory server to communicate with each other via
1617 LDAPS.
1618 Scenario 3: Similar to the previous scenario, a directory server exists
1621 which is currently running LDAP, and the desire is to create a CA and
1622 use it to establish LDAPS communications between this CA and this
1623 directory server. However, for this scenario, there is a need for the
1624 CA and the directory server to communicate securely during pkispawn
1625 installation and configuration. For this to succeed, the directory
1626 server must generate a temporary self-signed certificate which then
1627 must be made available via a PEM file (e.g. $HOME/dscacert.pem) prior
1628 to running pkispawn. Once the CA has been created, swap things out to
1629 reconfigure the CA and directory server to utilize LDAPS through the
1630 desired certificates.
1631 Set up a Directory Server instance with a self-signed CA certificate
1634 (see dscreate(8)), then export the certificate into a PEM file
1635 Once the self-signed CA certificate is obtained, add the following
1638 parameters into the [DEFAULT] section in myconfig.txt:
1639 pki_ds_secure_connection=True
1642 pki_ds_secure_connection_ca_pem_file=$HOME/dscacert.pem
1643 Then execute pkispawn to create the CA subsystem.
1647 Managing PKI instance
1650 To start a PKI instance named <pki_instance_name>:
1651 $ systemctl start pki-tomcatd@<pki_instance_name>.service
1654 To stop a PKI instance named <pki_instance_name>:
1658 $ systemctl stop pki-tomcatd@<pki_instance_name>.service
1661 To restart a PKI instance named <pki_instance_name>:
1665 $ systemctl restart pki-tomcatd@<pki_instance_name>.service
1668 To obtain the status of a PKI instance named <pki_instance_name>:
1672 $ systemctl status pki-tomcatd@<pki_instance_name>.service
1675 To obtain a detailed status of a Tomcat PKI instance named
1679 <pki_instance_name>:
1680 $ pki-server status <pki_instance_name>
1683 To list all available PKI instances installed on a system:
1687 $ pki-server instance-find
1690
1694 pkidestroy(8)
1695 pki_default.cfg(5)
1696 pki(1)
1697 dscreate(8)
1698
1701 Ade Lee <alee@redhat.com> and Dinesh Prasanth M K <dmoluguw@redhat.com>
1702
1705 Copyright (c) 2020 Red Hat, Inc. This is licensed under the GNU Gen‐
1706 eral Public License, version 2 (GPLv2). A copy of this license is
1707 available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.
1708PKI September 30, 2020 pkispawn(8)