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 setup-ds.pl(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.
77 When the utility is done running, the CA can be accessed by pointing a
81 browser to https://hostname:pki_https_port/. The agent pages can be
82 accessed by importing the CA certificate and administrator certificate
83 into the browser.
84 The PKI server instance can also be accessed using the pki command line
87 interface. See pki(1). For more extensive documentation on how to use
88 PKI features, see the Red Hat Certificate System Documentation at
89 ⟨https://access.redhat.com/knowledge/docs/Red_Hat_Certificate_System⟩.
90 Instances created using pkispawn can be removed using pkidestroy. See
93 pkidestroy(8).
94 pkispawn supersedes and combines the functionality of pkicreate and
97 pkisilent, which were available in earlier releases of Certificate
98 Server. It is now possible to completely create and configure the Cer‐
99 tificate Server subsystem in a single step using pkispawn.
100 Note: Previously, as an alternative to using pkisilent to perform a
103 non-interactive batch configuration, a PKI instance could be interac‐
104 tively configured by a GUI-based configuration wizard via a Firefox
105 browser. GUI-based configuration of a PKI instance is unavailable in
106 this version of the product.
107
110 -s subsystem
111 Specifies the subsystem to be installed and configured, where sub‐
112 system is CA, KRA, OCSP, TKS, or TPS.
113 -f config_file
116 Specifies the path to the user-defined configuration file.
117 This file contains differences between the default configuration
118 and the custom configuration.
119 --precheck
122 Execute pre-checks and exit.
123 --skip-configuration
126 Run the first step of the installation (i.e. skipping the instance
127 configuration step).
128 --skip-installation
131 Run the second step of the installation (i.e. skipping the instance
132 installation step).
133 -h, --help
136 Prints additional help information.
137 -v
140 Displays verbose information about the installation.
141 This flag can be provided multiple times to increase verbosity.
142 See pkispawn -h for details.
143
146 Separate PKI instances
147 As described above, this version of PKI continues to support separate
148 PKI instances for all subsystems.
149 Separate PKI instances run as a single Java-based Apache Tomcat
152 instance, contain a single PKI subsystem (CA, KRA, OCSP, TKS, or TPS),
153 and must utilize unique ports if co-located on the same machine.
154 Shared PKI instances
157 Additionally, this version of PKI introduces the notion of a shared PKI
158 instance.
159 Shared PKI instances also run as a single Java-based Apache Tomcat
162 instance, but may contain any combination of up to one of each type of
163 PKI subsystem:
164 · CA
167 · TKS
169 · CA, KRA
171 · CA, OCSP
173 · TKS, TPS
175 · CA, KRA, TKS, TPS
177 · CA, KRA, OCSP, TKS, TPS
179 · etc.
181 Shared PKI instances allow all of their subsystems contained within
185 that instance to share the same ports, and must utilize unique ports if
186 more than one shared PKI instance is co-located on the same machine.
187 Semantically, a shared PKI instance that contains a single PKI subsys‐
190 tem is identical to a separate PKI instance.
191
194 If no options are specified, pkispawn will provide an interactive menu
195 to collect the parameters needed to install the Certificate Server
196 instance. Note that only the most basic installation options are pro‐
197 vided. This includes root CA, KRA, OCSP, TKS, and TPS connecting to an
198 existing directory server. More advanced setups such as cloned subsys‐
199 tems, subordinate or externally signed CA, subsystems that connect to
200 the directory server using LDAPS, and subsystems that are customized
201 beyond the options described below require the use of a configuration
202 file with the -f option.
203 The interactive option is most useful for those users getting familiar
206 with Certificate Server. The parameters collected are written to the
207 installation file of the subsystem, which can be found at /etc/syscon‐
208 fig/pki/tomcat/instance_name/subsystem/deployment.cfg.
209 The following parameters are queried interactively during the installa‐
212 tion process.
213 Subsystem Type
216 Subsystem (CA/KRA/OCSP/TKS/TPS):
217 The type of subsystem to be installed.
218 Prompted when the -s option is not specified.
219 The default value chosen is CA.
220 Instance Specific Parameters
223 Instance name:
224 The name of the tomcat instance in which the subsystem is to be
225 installed. The default value is pki-tomcat.
226 Note: Only one subsystem of a given type (CA, KRA, OCSP, TKS, TPS) can
229 exist within a given instance.
230 HTTP port:
233 The HTTP port of the Tomcat instance. The default value is 8080.
234 Secure HTTP port:
237 The HTTPS port of the Tomcat instance. The default value is 8443.
238 AJP port:
241 The AJP port of the Tomcat instance. The default value is 8009.
242 Management port:
245 The management port of the Tomcat instance. The default value is
246 8005.
247 Note: When deploying a new subsystem into an existing instance,
250 pkispawn will attempt to read the ports from deployment.cfg files
251 stored for previously installed subsystems for this instance. If suc‐
252 cessful, the installer will not prompt for these ports.
253 Administrative User Parameters
256 Username:
257 The username of the administrator of this subsystem. The default
258 value is <ca/kra/ocsp/tks/tps>admin.
259 Password:
262 Password for the administrator user.
263 Import certificate:
266 An optional parameter that can be used to import an already avail‐
267 able CA admin certificate into this instance.
268 Export certificate:
271 Setup the path where the admin certificate of this <subsystem>
272 should be stored.
273 The default value is $HOME/.dogtag/pki-tom‐
274 cat/<ca/kra/ocsp/tks/tps>_admin.cert.
275 Directory Server Parameters
278 Hostname:
279 Hostname of the directory server instance. The default value is
280 the hostname of the system.
281 Use a secure LDAPS connection?
284 Answering yes to this question will cause prompts for Secure LDAPS
285 Port: and Directory Server CA certificate pem file:.
286 Answering no to this question will cause a prompt for LDAP Port.
287 The initial default value for this question is no.
288 Secure LDAPS Port:
291 Secure LDAPS port for the directory server instance. The default
292 value is 636.
293 Directory Server CA certificate PEM file:
296 The fully-qualified path including the filename of the file which
297 contains an exported copy of the Directory Server's CA certificate
298 (e.g. $HOME/dscacert.pem).
299 This file must exist prior to pkispawn being able to utilize it.
300 For details on creation of this file see the EXAMPLES section below
301 entitled Installing PKI Subsystem with Secure LDAP Connection.
302 LDAP Port:
305 LDAP port for the directory server instance. The default value is
306 389.
307 Base DN:
310 The Base DN to be used for the internal database for this subsys‐
311 tem.
312 The default value is o=pki-tomcat-<subsystem>.
313 Bind DN:
316 The bind DN required to connect for the directory server.
317 This user must have sufficient permissions to install the required
318 schema and database.
319 The default value is cn=Directory Manager.
320 Password:
323 Password for the bind DN.
324 Security Domain Parameters
327 Name:
328 The name of the security domain. Required only if installing a root
329 CA.
330 Default value: <DNS domain name> Security Domain.
331 Hostname:
334 The hostname for the security domain CA. Required only for non-CA
335 subsystems.
336 The default value is the hostname of this system.
337 Secure HTTP port:
340 The https port for the security domain. Required only for non-CA
341 subsystems. The default value is 8443.
342 Username:
345 The username of the security domain administrator of the CA.
346 Required only for non-CA subsystems.
347 The default value is caadmin.
348 Password:
351 Password for the security domain administrator. Required for all
352 subsystems that are not root CAs.
353
356 This option is only available when pkispawn is invoked in a non-inter‐
357 active mode. When the --precheck option is provided, a set of basic
358 tests are performed to ensure that the parameters provided to pkispawn
359 are valid and consistent.
360 pkispawn will then exit with an exit code of 0 on success, or 1 on
363 failure. This mode can be used to perform basic tests prior to doing
364 any actual installation of the PKI server instance.
365 Flags are available to disable specific tests. For instance, one might
368 want to disable validation of the credentials for the internal database
369 user if the directory server instance has not yet been created.
370 See pki_default.cfg(5) for more details about available flags.
373
376 pkispawn provides a number of parameters to customize an instance
377 before it is created. Usually, most other customization can be done
378 after the server is created. However, sometimes certain types of cus‐
379 tomization need to be done before the server is created, but there are
380 no parameters for that. For example, configuring session timeout,
381 adding CSR extensions, customizing certificate profiles, configuring
382 TLS ciphers, etc. To support such customization, pkispawn provides a
383 two-step installation mode.
384 Generally, instance creation happens in one step (except for the exter‐
387 nal CA case). Internally, the process happens in two stages. In the
388 first stage, pkispawn will install the instance files (e.g. CS.cfg, NSS
389 database, profiles, etc.) in the instance directory and customize them
390 based on pkispawn parameters. In the second stage, pkispawn will start
391 the instance and configure the instance based on the instance configu‐
392 ration files (e.g. initializing database, generating certificates, con‐
393 figuring connectors, etc.). The two-step process allows the process to
394 be stopped after the first stage, allowing further customization to be
395 done before running the second stage.
396 To use two-step installation mode, prepare a normal pkispawn configura‐
399 tion file, then run pkispawn with the --skip-configuration parameter.
400 For example:
401 $ pkispawn -s CA -f myconfig.txt --skip-configuration
404 Then customize the files in the instance directory as needed. Finally,
408 finish the installation by running pkispawn again with the
409 --skip-installation parameter. For example:
410 $ pkispawn -s CA -f myconfig.txt --skip-installation
413
417 Installing Root CA
418 To install a root CA in a new instance execute the following command:
419 $ pkispawn -s CA -f myconfig.txt
422 where myconfig.txt contains the following text:
426 [DEFAULT]
429 pki_admin_password=Secret.123
430 pki_client_pkcs12_password=Secret.123
431 pki_ds_password=Secret.123
432 Prior to running this command, a Directory Server instance should be
436 created and running. This command assumes that the Directory Server
437 instance is using its default configuration:
438 · Installed on the local machine
441 · Listening on port 389
443 · The user is cn=Directory Manager, with the password specified
445 in pki_ds_password
446 This invocation of pkispawn creates a Tomcat instance containing a CA
450 running on the local machine with secure port 8443 and unsecure port
451 8080. To access this CA, simply point a browser to https://host‐
452 name:8443.
453 The instance name (defined by pki_instance_name) is pki-tomcat, and it
456 is located at /var/lib/pki/pki-tomcat. Logs for the instance are
457 located at /var/log/pki/pki-tomcat, and an installation log is written
458 to /var/log/pki/pki-subsystem-spawn.timestamp.log.
459 A PKCS #12 file containing the administrator certificate is created in
462 $HOME/.dogtag/pki-tomcat. This PKCS #12 file uses the password desig‐
463 nated by pki_client_pkcs12_password in the configuration file.
464 To access the agent pages, first import the CA certificate by accessing
467 the CA End Entity Pages and clicking on the Retrieval Tab. Be sure to
468 trust the CA certificate. Then, import the administrator certificate in
469 the PKCS #12 file.
470 Installing Root CA using ECC
473 To install a root CA in a new instance using ECC execute the following
474 command:
475 $ pkispawn -s CA -f myconfig.txt
478 where myconfig.txt contains the following text:
482 [DEFAULT]
485 pki_admin_password=Secret.123
486 pki_admin_key_algorithm=SHA256withEC
487 pki_admin_key_size=nistp256
488 pki_admin_key_type=ecc
489 pki_client_pkcs12_password=Secret.123
490 pki_ds_password=Secret.123
491 pki_sslserver_key_algorithm=SHA256withEC
492 pki_sslserver_key_size=nistp256
493 pki_sslserver_key_type=ecc
494 pki_subsystem_key_algorithm=SHA256withEC
495 pki_subsystem_key_size=nistp256
496 pki_subsystem_key_type=ecc
497 [CA]
499 pki_ca_signing_key_algorithm=SHA256withEC
500 pki_ca_signing_key_size=nistp256
501 pki_ca_signing_key_type=ecc
502 pki_ca_signing_signing_algorithm=SHA256withEC
503 pki_ocsp_signing_key_algorithm=SHA256withEC
504 pki_ocsp_signing_key_size=nistp256
505 pki_ocsp_signing_key_type=ecc
506 pki_ocsp_signing_signing_algorithm=SHA256withEC
507 In order to utilize ECC, the SSL Server and Subsystem key algorithm,
511 key size, and key type should be changed from SHA256withRSA to
512 SHA256withEC, 2048 to nistp256, and rsa to ecc, respectively. To use
513 an ECC admin key size and key type, the values should also be changed
514 from 2048 to nistp256, and rsa to ecc.
515 Additionally, for a CA subsystem, both the CA and OCSP Signing key
518 algorithm, key size, key type, and signing algorithm should be changed
519 from SHA256withRSA to SHA256withEC, 2048 to nistp256, rsa to ecc, and
520 SHA256withRSA to SHA256withEC, respectively.
521 Note: For all PKI subsystems including the CA, ECC is not supported for
524 the corresponding Audit Signing parameters. Similarly, for KRA subsys‐
525 tems, ECC is not supported for either of the corresponding Storage or
526 Transport parameters.
527 Installing KRA, OCSP, TKS, or TPS in Shared Instance
530 For this example, assume that a new CA instance has been installed by
531 executing the following command:
532 $ pkispawn -s CA -f myconfig.txt
535 where myconfig.txt contains the following text:
539 [DEFAULT]
542 pki_admin_password=Secret.123
543 pki_client_pkcs12_password=Secret.123
544 pki_ds_password=Secret.123
545 # Optionally keep client databases
546 pki_client_database_purge=False
547 To install a shared KRA in the same instance used by the CA execute the
551 following command:
552 $ pkispawn -s KRA -f myconfig.txt
555 where myconfig.txt contains the following text:
559 [DEFAULT]
562 pki_admin_password=Secret.123
563 pki_client_database_password=Secret.123
564 pki_client_pkcs12_password=Secret.123
565 pki_ds_password=Secret.123
566 pki_security_domain_password=Secret.123
567 To install a shared OCSP in the same instance used by the CA execute
571 the following command:
572 $ pkispawn -s OCSP -f myconfig.txt
575 where myconfig.txt contains the following text:
579 [DEFAULT]
582 pki_admin_password=Secret.123
583 pki_client_database_password=Secret.123
584 pki_client_pkcs12_password=Secret.123
585 pki_ds_password=Secret.123
586 pki_security_domain_password=Secret.123
587 To install a shared TKS in the same instance used by the CA execute the
591 following command:
592 $ pkispawn -s TKS -f myconfig.txt
595 where myconfig.txt contains the following text:
599 [DEFAULT]
602 pki_admin_password=Secret.123
603 pki_client_database_password=Secret.123
604 pki_client_pkcs12_password=Secret.123
605 pki_ds_password=Secret.123
606 pki_security_domain_password=Secret.123
607 To install a shared TPS in the same instance used by the CA execute the
611 following command:
612 $ pkispawn -s TPS -f myconfig.txt
615 where myconfig.txt contains the following text:
619 [DEFAULT]
622 pki_admin_password=Secret.123
623 pki_client_database_password=Secret.123
624 pki_client_pkcs12_password=Secret.123
625 pki_ds_password=Secret.123
626 pki_security_domain_password=Secret.123
627 [TPS]
629 # Shared TPS instances optionally utilize their shared KRA
630 # for server-side keygen
631 pki_enable_server_side_keygen=True
632 pki_authdb_basedn=dc=example,dc=com
633 Note: For this particular example, the computed default values for a
637 PKI instance name including its ports, URLs, machine names, etc. were
638 utilized as defined in /usr/share/pki/server/etc/default.cfg. Each
639 subsystem in this example will reside under the /var/lib/pki/pki-tomcat
640 instance housed within their own ca, kra, ocsp, tks, and tps subdirec‐
641 tories, utilizing the same default port values of 8080 (http), 8443
642 (https), 8009 (ajp), 8005 (tomcat), using the same computed hostname
643 and URL information, and sharing a single common PKI Administrator Cer‐
644 tificate.
645 The pki_security_domain_password is the admin password of the CA
648 installed in the same instance. This command should be run after a CA
649 is installed. This installs another subsystem within the same instance
650 using the certificate generated for the CA administrator for the sub‐
651 system's administrator. This allows a user to access both subsystems on
652 the browser with a single administrator certificate. To access the new
653 subsystem's functionality, simply point the browser to https://host‐
654 name:8443 and click the relevant top-level links.
655 To install TPS in a shared instance the following section must be added
658 to myconfig.txt:
659 [TPS]
662 pki_authdb_basedn=dc=example,dc=com
663 TPS requires an authentication database. The pki_authdb_basedn speci‐
667 fies the base DN of the authentication database.
668 TPS also requires that a CA and a TKS subsystems are already installed
671 in the same instance. Since they are in the same instance, a shared
672 secret key will automatically be generated in TKS and imported into
673 TPS.
674 Optionally, server-side key generation can be enabled in TPS by adding
677 the following parameter in [TPS]:
678 pki_enable_server_side_keygen=True
681 Enabling server-side key generation requires that a KRA subsystem is
685 already installed in the same instance.
686 Installing KRA, OCSP, TKS, or TPS in Separate Instance
689 For this example, assume that a new CA instance has been installed by
690 executing the following command:
691 $ pkispawn -s CA -f myconfig.txt
694 where myconfig.txt contains the following text:
698 [DEFAULT]
701 pki_admin_password=Secret.123
702 pki_client_pkcs12_password=Secret.123
703 pki_ds_password=Secret.123
704 # Optionally keep client databases
705 pki_client_database_purge=False
706 # Separated CA instance name and ports
707 pki_instance_name=pki-ca
708 pki_http_port=18080
709 pki_https_port=18443
710 # This Separated CA instance will be its own security domain
711 pki_security_domain_https_port=18443
712 [Tomcat]
714 # Separated CA Tomcat ports
715 pki_ajp_port=18009
716 pki_tomcat_server_port=18005
717 To install a separate KRA which connects to this remote CA execute the
721 following command:
722 $ pkispawn -s KRA -f myconfig.txt
725 where myconfig.txt contains the following text:
729 [DEFAULT]
732 pki_admin_password=Secret.123
733 pki_client_database_password=Secret.123
734 pki_client_pkcs12_password=Secret.123
735 pki_ds_password=Secret.123
736 pki_security_domain_password=Secret.123
737 # Optionally keep client databases
738 pki_client_database_purge=False
739 # Separated KRA instance name and ports
740 pki_instance_name=pki-kra
741 pki_http_port=28080
742 pki_https_port=28443
743 # Separated KRA instance security domain references
744 pki_issuing_ca=https://pki.example.com:18443
745 pki_security_domain_hostname=pki.example.com
746 pki_security_domain_https_port=18443
747 pki_security_domain_user=caadmin
748 [Tomcat]
750 # Separated KRA Tomcat ports
751 pki_ajp_port=28009
752 pki_tomcat_server_port=28005
753 [KRA]
755 # A Separated KRA instance requires its own
756 # PKI Administrator Certificate
757 pki_import_admin_cert=False
758 To install a separate OCSP which connects to this remote CA execute the
762 following command:
763 $ pkispawn -s OCSP -f myconfig.txt
766 where myconfig.txt contains the following text:
770 [DEFAULT]
773 pki_admin_password=Secret.123
774 pki_client_database_password=Secret.123
775 pki_client_pkcs12_password=Secret.123
776 pki_ds_password=Secret.123
777 pki_security_domain_password=Secret.123
778 # Optionally keep client databases
779 pki_client_database_purge=False
780 # Separated OCSP instance name and ports
781 pki_instance_name=pki-ocsp
782 pki_http_port=29080
783 pki_https_port=29443
784 # Separated OCSP instance security domain references
785 pki_issuing_ca=https://pki.example.com:18443
786 pki_security_domain_hostname=pki.example.com
787 pki_security_domain_https_port=18443
788 pki_security_domain_user=caadmin
789 [Tomcat]
791 # Separated OCSP Tomcat ports
792 pki_ajp_port=29009
793 pki_tomcat_server_port=29005
794 [OCSP]
796 # A Separated OCSP instance requires its own
797 # PKI Administrator Certificate
798 pki_import_admin_cert=False
799 To install a separate TKS which connects to this remote CA execute the
803 following command:
804 $ pkispawn -s TKS -f myconfig.txt
807 where myconfig.txt contains the following text:
811 [DEFAULT]
814 pki_admin_password=Secret.123
815 pki_client_database_password=Secret.123
816 pki_client_pkcs12_password=Secret.123
817 pki_ds_password=Secret.123
818 pki_security_domain_password=Secret.123
819 # Optionally keep client databases
820 pki_client_database_purge=False
821 # Separated TKS instance name and ports
822 pki_instance_name=pki-tks
823 pki_http_port=30080
824 pki_https_port=30443
825 # Separated TKS instance security domain references
826 pki_issuing_ca=https://pki.example.com:18443
827 pki_security_domain_hostname=pki.example.com
828 pki_security_domain_https_port=18443
829 pki_security_domain_user=caadmin
830 [Tomcat]
832 # Separated TKS Tomcat ports
833 pki_ajp_port=30009
834 pki_tomcat_server_port=30005
835 [TKS]
837 # A Separated TKS instance requires its own
838 # PKI Administrator Certificate
839 pki_import_admin_cert=False
840 To install a separate TPS which connects to this remote CA execute the
844 following command:
845 $ pkispawn -s TPS -f myconfig.txt
848 where myconfig.txt contains the following text:
852 [DEFAULT]
855 pki_admin_password=Secret.123
856 pki_client_database_password=Secret.123
857 pki_client_pkcs12_password=Secret.123
858 pki_ds_password=Secret.123
859 pki_security_domain_password=Secret.123
860 # Optionally keep client databases
861 pki_client_database_purge=False
862 # Separated TPS instance name and ports
863 pki_instance_name=pki-tps
864 pki_http_port=31080
865 pki_https_port=31443
866 # Separated TPS instance security domain references
867 pki_issuing_ca=https://pki.example.com:18443
868 pki_security_domain_hostname=pki.example.com
869 pki_security_domain_https_port=18443
870 pki_security_domain_user=caadmin
871 [Tomcat]
873 # Separated TPS Tomcat ports
874 pki_ajp_port=31009
875 pki_tomcat_server_port=31005
876 [TPS]
878 # Separated TPS instances require specifying a remote CA
879 pki_ca_uri=https://pki.example.com:18443
880 # Separated TPS instances optionally utilize a remote KRA
881 # for server-side keygen
882 pki_kra_uri=https://pki.example.com:28443
883 pki_enable_server_side_keygen=True
884 pki_authdb_basedn=dc=example,dc=com
885 # Separated TPS instances require specifying a remote TKS
886 pki_tks_uri=https://pki.example.com:30443
887 pki_import_shared_secret=True
888 # A Separated TPS instance requires its own
889 # PKI Administrator Certificate
890 pki_import_admin_cert=False
891 Note: For this particular example, besides passwords, sample values
895 were also utilized for PKI instance names, ports, URLs, machine names,
896 etc. Under no circumstances should these demonstrative values be con‐
897 strued to be required literal values.
898 A remote CA is one where the CA resides in another PKI server instance,
901 either on the local machine or a remote machine. In this case, mycon‐
902 fig.txt must specify the connection information for the remote CA and
903 the information about the security domain (the trusted collection of
904 subsystems within an instance).
905 The subsystem section is [KRA], [OCSP], [TKS], or [TPS]. This example
908 assumes that the specified CA hosts the security domain. The CA must
909 be running and accessible.
910 A new administrator certificate is generated for the new subsystem and
913 stored in a PKCS #12 file in $HOME/.dogtag/pki_instance_name.
914 As in a shared instance, to install TPS in a separate instance the
917 authentication database must be specified in the [TPS] section, and
918 optionally the server-side key generation can be enabled. If the CA,
919 KRA, or TKS subsystems required by TPS are running on a remote instance
920 the following parameters must be added into the [TPS] section to spec‐
921 ify their locations:
922 pki_ca_uri=https://<ca_hostname>:<ca_https_port>
925 pki_kra_uri=https://<kra_hostname>:<kra_https_port>
926 pki_tks_uri=https://<tks_hostname>:<tks_https_port>
927 If TPS and TKS are installed on separate instances the shared secret
931 key should be imported over the wire between the TKS and TPS automati‐
932 cally.
933 If the automated procedure fails for any unlikely reason the following
936 manual procedure will serve as a fallback. The key needs to be created
937 on the TKS side and imported into the TPS side in this case.
938 Generate the shared secret key (if needed) in TKS with the following
941 command:
942 $ tkstool -T -d /var/lib/pki/pki-tomcat/alias -n sharedSecret
945 Verify the shared secret key in TKS with the following command:
949 $ tkstool -L -d /var/lib/pki/pki-tomcat/alias
952 Once TPS is installed, shutdown TPS instance, then import the shared
956 secret key into TPS with the following command:
957 $ tkstool -I -d /var/lib/pki/pki-tomcat/alias -n sharedSecret
960 Verify the shared secret key in TPS with the following command:
964 $ tkstool -L -d /var/lib/pki/pki-tomcat/alias
967 The shared secret key nickname should be stored in the following prop‐
971 erty in the TPS's CS.cfg:
972 conn.tks1.tksSharedSymKeyName=sharedSecret
975 Finally, restart the TPS instance.
979 Installing CA, KRA, OCSP, TKS, or TPS using HSM
982 This section provides sample myconfig.txt files when a Hardware Secu‐
983 rity Module (HSM) is being utilized in a shared PKI instance.
984 For this example, assume that a new CA instance has been installed by
987 executing the following command:
988 $ pkispawn -s CA -f myconfig.txt
991 where myconfig.txt contains the following text:
995 [DEFAULT]
998 pki_admin_password=Secret.123
999 pki_client_pkcs12_password=Secret.123
1000 pki_ds_password=Secret.123
1001 # Optionally keep client databases
1002 pki_client_database_purge=False
1003 # Provide HSM parameters
1004 pki_hsm_enable=True
1005 pki_hsm_libfile=<hsm_libfile>
1006 pki_hsm_modulename=<hsm_modulename>
1007 pki_token_name=<hsm_token_name>
1008 pki_token_password=<pki_token_password>
1009 # Provide PKI-specific HSM token names
1010 pki_audit_signing_token=<hsm_token_name>
1011 pki_sslserver_token=<hsm_token_name>
1012 pki_subsystem_token=<hsm_token_name>
1013 [CA]
1015 # Provide CA-specific HSM token names
1016 pki_ca_signing_token=<hsm_token_name>
1017 pki_ocsp_signing_token=<hsm_token_name>
1018 To install a shared KRA in the same instance used by the CA execute the
1022 following command:
1023 $ pkispawn -s KRA -f myconfig.txt
1026 where myconfig.txt contains the following text:
1030 [DEFAULT]
1033 pki_admin_password=Secret.123
1034 pki_client_database_password=Secret.123
1035 pki_client_pkcs12_password=Secret.123
1036 pki_ds_password=Secret.123
1037 pki_security_domain_password=Secret.123
1038 # Provide HSM parameters
1039 pki_hsm_enable=True
1040 pki_hsm_libfile=<hsm_libfile>
1041 pki_hsm_modulename=<hsm_modulename>
1042 pki_token_name=<hsm_token_name>
1043 pki_token_password=<pki_token_password>
1044 # Provide PKI-specific HSM token names
1045 pki_audit_signing_token=<hsm_token_name>
1046 pki_sslserver_token=<hsm_token_name>
1047 pki_subsystem_token=<hsm_token_name>
1048 [KRA]
1050 # Provide KRA-specific HSM token names
1051 pki_storage_token=<hsm_token_name>
1052 pki_transport_token=<hsm_token_name>
1053 To install a shared OCSP in the same instance used by the CA execute
1057 the following command:
1058 $ pkispawn -s OCSP -f myconfig.txt
1061 where myconfig.txt contains the following text:
1065 [DEFAULT]
1068 pki_admin_password=Secret.123
1069 pki_client_database_password=Secret.123
1070 pki_client_pkcs12_password=Secret.123
1071 pki_ds_password=Secret.123
1072 pki_security_domain_password=Secret.123
1073 # Provide HSM parameters
1074 pki_hsm_enable=True
1075 pki_hsm_libfile=<hsm_libfile>
1076 pki_hsm_modulename=<hsm_modulename>
1077 pki_token_name=<hsm_token_name>
1078 pki_token_password=<pki_token_password>
1079 # Provide PKI-specific HSM token names
1080 pki_audit_signing_token=<hsm_token_name>
1081 pki_sslserver_token=<hsm_token_name>
1082 pki_subsystem_token=<hsm_token_name>
1083 [OCSP]
1085 # Provide OCSP-specific HSM token names
1086 pki_ocsp_signing_token=<hsm_token_name>
1087 To install a shared TKS in the same instance used by the CA execute the
1091 following command:
1092 $ pkispawn -s TKS -f myconfig.txt
1095 where myconfig.txt contains the following text:
1099 [DEFAULT]
1102 pki_admin_password=Secret.123
1103 pki_client_database_password=Secret.123
1104 pki_client_pkcs12_password=Secret.123
1105 pki_ds_password=Secret.123
1106 pki_security_domain_password=Secret.123
1107 # Provide HSM parameters
1108 pki_hsm_enable=True
1109 pki_hsm_libfile=<hsm_libfile>
1110 pki_hsm_modulename=<hsm_modulename>
1111 pki_token_name=<hsm_token_name>
1112 pki_token_password=<pki_token_password>
1113 # Provide PKI-specific HSM token names
1114 pki_audit_signing_token=<hsm_token_name>
1115 pki_sslserver_token=<hsm_token_name>
1116 pki_subsystem_token=<hsm_token_name>
1117 To install a shared TPS in the same instance used by the CA execute the
1121 following command:
1122 $ pkispawn -s TPS -f myconfig.txt
1125 where myconfig.txt contains the following text:
1129 [DEFAULT]
1132 pki_admin_password=Secret.123
1133 pki_client_database_password=Secret.123
1134 pki_client_pkcs12_password=Secret.123
1135 pki_ds_password=Secret.123
1136 pki_security_domain_password=Secret.123
1137 # Provide HSM parameters
1138 pki_hsm_enable=True
1139 pki_hsm_libfile=<hsm_libfile>
1140 pki_hsm_modulename=<hsm_modulename>
1141 pki_token_name=<hsm_token_name>
1142 pki_token_password=<pki_token_password>
1143 # Provide PKI-specific HSM token names
1144 pki_audit_signing_token=<hsm_token_name>
1145 pki_sslserver_token=<hsm_token_name>
1146 pki_subsystem_token=<hsm_token_name>
1147 [TPS]
1149 # Shared TPS instances optionally utilize their shared KRA
1150 # for server-side keygen
1151 pki_enable_server_side_keygen=True
1152 pki_authdb_basedn=dc=example,dc=com
1153 Important: Since HSM keys are stored in the HSM, they cannot be backed
1157 up, moved, or copied to a PKCS #12 file. For example, if
1158 pki_hsm_enable is set to True, pki_backup_keys should be set to False
1159 and pki_backup_password should be left unset (the default values in
1160 /usr/share/pki/server/etc/default.cfg). Similarly, for the case of
1161 clones using an HSM, this means that the HSM keys must be shared
1162 between the master and its clones. Therefore, if pki_hsm_enable is set
1163 to True, both pki_clone_pkcs12_path and pki_clone_pkcs12_password
1164 should be left unset (the default values in
1165 /usr/share/pki/server/etc/default.cfg). Failure to comply with these
1166 rules will result in pkispawn reporting an appropriate error and exit‐
1167 ing.
1168 Installing CA Clone
1171 To install a CA clone execute the following command:
1172 $ pkispawn -s CA -f myconfig.txt
1175 where myconfig.txt contains the following text:
1179 [DEFAULT]
1182 pki_admin_password=Secret.123
1183 pki_client_database_password=Secret.123
1184 pki_client_pkcs12_password=Secret.123
1185 pki_ds_password=Secret.123
1186 pki_security_domain_password=Secret.123
1187 pki_security_domain_hostname=<master_ca_hostname>
1188 pki_security_domain_https_port=<master_ca_https_port>
1189 pki_security_domain_user=caadmin
1190 pki_security_domain_post_login_sleep_seconds=5
1191 [Tomcat]
1193 pki_clone=True
1194 pki_clone_pkcs12_password=Secret.123
1195 pki_clone_pkcs12_path=<path_to_pkcs12_file>
1196 pki_clone_replicate_schema=True
1197 pki_clone_uri=https://<master_ca_hostname>:<master_ca_https_port>
1198 A cloned CA is a CA which uses the same signing, OCSP signing, and
1202 audit signing certificates as the master CA, but issues certificates
1203 within a different serial number range. It has its own internal data‐
1204 base -- separate from the master CA database -- but using the same base
1205 DN, that keeps in sync with the master CA through replication agree‐
1206 ments between the databases. This is very useful for load sharing and
1207 disaster recovery. To create a clone, the myconfig.txt uses pkiclone*
1208 parameters in its [Tomcat] section which identify the original CA to
1209 use as a master template. Additionally, it connects to the master CA
1210 as a remote CA and uses its security domain.
1211 Before the clone can be generated, the Directory Server must be created
1214 that is separate from the master CA's Directory Server. The example
1215 assumes that the master CA and cloned CA are on different machines, and
1216 that their Directory Servers are on port 389.
1217 In addition, since this example does not utilize an HSM, the master's
1220 system certs and keys have been stored in a PKCS #12 file that is
1221 copied over to the clone subsystem in the location specified in
1222 <path_to_pkcs12_file>. This file needs to be readable by the user the
1223 Certificate Server runs as (by default, pkiuser) and be given the
1224 SELinux context pki_tomcat_cert_t.
1225 The master's system certificates can be exported to a PKCS#12 file when
1228 the master is installed if the parameter pki_backup_keys is set to True
1229 and the pki_backup_password is set. The PKCS#12 file is then found
1230 under /var/lib/pki/<instance_name>/alias. Alternatively, the PKCS#12
1231 file can be generated at any time post-installation using PKCS12Export.
1232 The pki_security_domain_post_login_sleep_seconds config specifies sleep
1235 duration after logging into a security domain, to allow the security
1236 domain session data to be replicated to subsystems on other hosts. It
1237 is optional and defaults to 5 seconds.
1238 An example invocation showing the export of the system certificates and
1241 keys, copying the keys to the replica subsystem, and setting the rele‐
1242 vant SELinux and file permissions is shown below. pwfile is a text
1243 file containing the password for the masters NSS DB (found in
1244 /etc/pki/instance_name/password.conf). pkcs12_password_file is a text
1245 file containing the password selected for the generated PKCS12 file.
1246 master# PKCS12Export -d /etc/pki/pki-tomcat/alias -p pwfile \
1249 -w pkcs12_password_file -o backup_keys.p12
1250 master# scp backup_keys.p12 clone:/backup_keys.p12
1251 clone# chown pkiuser: /backup_keys.p12
1253 clone# semanage -a -t pki_tomcat_cert_t /backup_keys.p12
1254 Note: From Dogtag 10.3, a slightly different mechanism has been pro‐
1258 vided to create and specify the required PKCS#12 file to the clone sub‐
1259 system. This new method is provided in addition to the method above,
1260 but will become the preferred method in future releases.
1261 This method can be used if both master and clone are 10.3 or above.
1264 To export the required keys from the master, use the pki-server command
1267 line tool.
1268 master# pki-server ca-clone-prepare -i pki-tomcat \
1271 --pkcs12-file backup_keys.p12 \
1272 --pkcs12-password Secret123
1273 master# scp backup_keys.p12 clone:/backup_keys.p12
1275 master# scp /etc/pki/pki-tomcat/external_certs.conf \
1276 clone:/external_certs.conf
1277 The external_certs.conf file contains information about third party
1281 certificates that were added to the master's certificate database using
1282 the pki-server command. The certificates themselves are stored in the
1283 backup_keys.p12 file. If there are no third-party certifcates that have
1284 been added, then the external_certs.conf file may not exist and should
1285 be ignored.
1286 The two files (backup_keys.p12 and external_certs.conf) are specified
1289 to pkispawn as below.
1290 [DEFAULT]
1293 pki_admin_password=Secret.123
1294 pki_client_database_password=Secret.123
1295 pki_client_pkcs12_password=Secret.123
1296 pki_ds_password=Secret.123
1297 pki_security_domain_password=Secret.123
1298 pki_security_domain_hostname=<master_ca_hostname>
1299 pki_security_domain_https_port=<master_ca_https_port>
1300 pki_security_domain_user=caadmin
1301 [Tomcat]
1303 pki_server_pkcs12_path=<path to pkcs12 file>
1304 pki_server_pkcs12_password=Secret.123
1305 pki_server_external_certs_path=<path to external_certs.conf file>
1306 pki_clone=True
1307 pki_clone_replicate_schema=True
1308 pki_clone_uri=https://<master_ca_hostname>:<master_ca_https_port>
1309 Note that the previous p12 parameters (pki_clonepkcs12*) are no longer
1313 needed, and will be ignored.
1314 Note: One current cloning anomaly to mention is the following scenario:
1317 1. Create a clone of a CA or of any other subsystem.
1320 2. Remove that just created clone.
1322 3. Immediately attempt the exact same clone again, in place of
1324 the recently destroyed instance. Before recreating this
1325 clone, make sure the pki_ds_remove_data=True is used in
1326 the clone's deployment config file. This will remove the
1327 old data from the previous clone.
1328 Here the Director Server instance may have worked itself in into a
1332 state where it no longer accepts connections, aborting the clone con‐
1333 figuration quickly.
1334 The fix to this is to simply restart the Directory Server instance
1337 before creating the clone for the second time. After restarting the
1338 Directory Server it should be possible to create the mentioned clone
1339 instance.
1340 Installing KRA or TKS Clone
1343 To install a KRA or TKS (OCSP and TPS unsupported as of now) execute
1344 the following command:
1345 $ pkispawn -s <subsystem> -f myconfig.txt
1348 where subsystem is KRA or TKS and myconfig.txt contains the following
1352 text:
1353 [DEFAULT]
1356 pki_admin_password=Secret.123
1357 pki_client_database_password=Secret.123
1358 pki_client_pkcs12_password=Secret.123
1359 pki_ds_password=Secret.123
1360 pki_security_domain_password=Secret.123
1361 pki_security_domain_hostname=<master_ca_hostname>
1362 pki_security_domain_https_port=<master_ca_https_port>
1363 pki_security_domain_user=caadmin
1364 [Tomcat]
1366 pki_clone=True
1367 pki_clone_pkcs12_password=Secret.123
1368 pki_clone_pkcs12_path=<path_to_pkcs12_file>
1369 pki_clone_replicate_schema=True
1370 pki_clone_uri=https://<master_subsystem_host>:<master_subsystem_https_port>
1371 pki_issuing_ca=https://<ca_hostname>:<ca_https_port>
1372 As with a CA clone, a KRA or TKS clone uses the same certificates and
1376 basic configuration as the original subsystem. The configuration
1377 points to the original subsystem to copy its configuration. This exam‐
1378 ple also assumes that the CA is on a remote machine and specifies the
1379 CA and security domain information.
1380 The parameter pki_clone_uri should be modified to point to the required
1383 master (KRA or TKS).
1384 As of 10.3, a slightly different mechanism has been introduced to gen‐
1387 erate and specify the PKCS#12 file and any third-party certificates.
1388 See the Installing CA Clone section for details.
1389 Installing CA Clone on the Same Host
1392 For testing purposes, it is useful to configure cloned CAs which exist
1393 (with their internal databases) on the same host as the master CA. To
1394 configure the cloned CA execute the following command:
1395 $ pkispawn -s CA -f myconfig.txt
1398 where myconfig.txt contains the following text:
1402 [DEFAULT]
1405 pki_admin_password=Secret123
1406 pki_client_database_password=Secret123
1407 pki_client_pkcs12_password=Secret123
1408 pki_ds_password=Secret123
1409 pki_ds_ldap_port=<unique port different from master>
1410 pki_ds_ldaps_port=<unique port different from master>
1411 pki_http_port=<unique port different from master>
1412 pki_https_port=<unique port different from master>
1413 pki_instance_name=<unique name different from master>
1414 pki_security_domain_hostname=<master_ca_hostname>
1415 pki_security_domain_https_port=<master_ca_https_port>
1416 pki_security_domain_password=Secret123
1417 [Tomcat]
1419 pki_ajp_port=<unique port different from master>
1420 pki_clone=True
1421 pki_clone_pkcs12_password=Secret123
1422 pki_clone_pkcs12_path=<path_to_pkcs12_file>
1423 pki_clone_uri=https://<master_ca_hostname>:<master_ca_https_port>
1424 pki_tomcat_server_port=<unique port different from master>
1425 [CA]
1427 pki_ds_base_dn=<identical value as master>
1428 pki_ds_database=<identical value as master>
1429 In this case, because both CA Tomcat instances are on the same host,
1433 they must have distinct ports. Similarly, each CA must use a distinct
1434 directory server instance for its internal database. Like the Tomcat
1435 instances, these are distinguished by distinct ports. The suffix being
1436 replicated (pki_ds_base), however, must be the same for both master and
1437 clone.
1438 Installing Subordinate CA in Existing Security Domain
1441 To install a subordinate CA in an existing security domain execute the
1442 following command:
1443 $ pkispawn -s CA -f myconfig.txt
1446 where myconfig.txt contains the following text:
1450 [DEFAULT]
1453 pki_admin_password=Secret.123
1454 pki_client_database_password=Secret.123
1455 pki_client_pkcs12_password=Secret.123
1456 pki_ds_password=Secret.123
1457 pki_security_domain_password=Secret.123
1458 pki_security_domain_hostname=<security_domain_ca_hostname>
1459 pki_security_domain_https_port=<security_domain_ca_https_port>
1460 pki_security_domain_user=caadmin
1461 [CA]
1463 pki_subordinate=True
1464 pki_issuing_ca=https://<master_ca_hostname>:<master_ca_https_port>
1465 pki_ca_signing_subject_dn=cn=CA Subordinate Signing,o=example.com
1466 A sub-CA derives its certificate configuration -- such as allowed
1470 extensions and validity periods -- from a superior or root CA. Other‐
1471 wise, the configuration of the CA is independent of the root CA, so it
1472 is its own instance rather than a clone. A sub-CA is configured using
1473 the pki_subordinate parameter and a pointer to the CA which issues the
1474 sub-CA's certificates.
1475 Note: The value of pki_ca_signing_subject_dn of a subordinate CA should
1478 be different from the root CA's signing subject DN.
1479 Installing Subordinate CA in New Security Domain
1482 To install a subordinate CA in a new security domain execute the fol‐
1483 lowing command:
1484 $ pkispawn -s CA -f myconfig.txt
1487 where myconfig.txt contains the following text:
1491 [DEFAULT]
1494 pki_admin_password=Secret.123
1495 pki_client_database_password=Secret.123
1496 pki_client_pkcs12_password=Secret.123
1497 pki_ds_password=Secret.123
1498 pki_security_domain_password=Secret.123
1499 pki_security_domain_hostname=<master CA security domain hostname>
1500 pki_security_domain_https_port=<master CA security domain https port>
1501 pki_security_domain_user=caadmin
1502 [CA]
1504 pki_subordinate=True
1505 pki_issuing_ca=https://<master_ca_hostname>:<master_ca_https_port>
1506 pki_ca_signing_subject_dn=cn=CA Subordinate Signing,o=example.com
1507 pki_subordinate_create_new_security_domain=True
1508 pki_subordinate_security_domain_name=Subordinate CA Security Domain
1509 In this section, the subordinate CA logs onto and registers with the
1513 security domain CA (using parameters pki_security_domain_hostname,
1514 pki_security_domain_user and pki_security_domain_password) as in the
1515 previous section, but also creates and hosts a new security domain. To
1516 do this, pki_subordinate_create_new_security_domain must be set to
1517 True. The subordinate CA security domain name can also be specified by
1518 specifying a value for pki_subordinate_security_domain_name.
1519 Note: The value of pki_ca_signing_subject_dn of a subordinate CA should
1522 be different from the root CA's signing subject DN.
1523 Installing Externally-Signed CA
1526 To install an externally signed CA execute the following command:
1527 $ pkispawn -s CA -f myconfig.txt
1530 This is a two-step process.
1534 In the first step, a certificate signing request (CSR) is generated for
1537 the signing certificate and myconfig.txt contains the following text:
1538 [DEFAULT]
1541 pki_admin_password=Secret.123
1542 pki_client_database_password=Secret.123
1543 pki_client_pkcs12_password=Secret.123
1544 pki_ds_password=Secret.123
1545 pki_security_domain_password=Secret.123
1546 [CA]
1548 pki_external=True
1549 pki_ca_signing_csr_path=/tmp/ca_signing.csr
1550 pki_ca_signing_subject_dn=cn=CA Signing,ou=External,o=example.com
1551 The CSR is written to pki_ca_signing_csr_path. The pki_ca_signing_sub‐
1555 ject_dn should be different from the subject DN of the external CA that
1556 is signing the request. The pki_ca_signing_subject_dn parameter can be
1557 used to specify the signing certificate's subject DN.
1558 The CSR is then submitted to the external CA, and the resulting cer‐
1561 tificate and certificate chain are saved to files on the system.
1562 In the second step, the configuration file has been modified to install
1565 the issued certificates. In place of the original CSR, the configura‐
1566 tion file now points to the issued CA certificate and certificate
1567 chain. There is also a flag to indicate that this completes the
1568 installation process (pki_external_step_two).
1569 [DEFAULT]
1572 pki_admin_password=Secret.123
1573 pki_client_database_password=Secret.123
1574 pki_client_pkcs12_password=Secret.123
1575 pki_ds_password=Secret.123
1576 pki_security_domain_password=Secret.123
1577 [CA]
1579 pki_external=True
1580 pki_external_step_two=True
1581 pki_cert_chain_path=/tmp/ca_cert_chain.cert
1582 pki_ca_signing_cert_path=/tmp/ca_signing.cert
1583 pki_ca_signing_subject_dn=cn=CA Signing Certificate,ou=External,o=example.com
1584 Then, the pkispawn command is run again:
1588 $ pkispawn -s CA -f myconfig.txt
1591 Installing PKI Subsystem with Secure LDAP Connection
1595 There are three scenarios in which a PKI subsystem (e.g. a CA) needs to
1596 communicate securely via LDAPS with a directory server:
1597 Scenario 1: A directory server exists which is already running LDAPS
1600 using a CA certificate that has been issued by some other CA. For this
1601 scenario, the CA certificate must be made available via a PEM file
1602 (e.g. $HOME/dscacert.pem) prior to running pkispawn such that the new
1603 CA may be installed and configured to communicate with this directory
1604 server using LDAPS.
1605 Scenario 2: A directory server exists which is currently running LDAP.
1608 Once a CA has been created, there is a desire to use its CA certificate
1609 to issue an SSL certificate for this directory server so that this CA
1610 and this directory server can communicate via LDAPS. For this sce‐
1611 nario, since there is no need to communicate securely during the
1612 pkispawn installation/configuration, simply use pkispawn to install and
1613 configure the CA using the LDAP port of the directory server, issue an
1614 SSL certificate from this CA for the directory server, and then recon‐
1615 figure the CA and directory server to communicate with each other via
1616 LDAPS.
1617 Scenario 3: Similar to the previous scenario, a directory server exists
1620 which is currently running LDAP, and the desire is to create a CA and
1621 use it to establish LDAPS communications between this CA and this
1622 directory server. However, for this scenario, there is a need for the
1623 CA and the directory server to communicate securely during pkispawn
1624 installation and configuration. For this to succeed, the directory
1625 server must generate a temporary self-signed certificate which then
1626 must be made available via a PEM file (e.g. $HOME/dscacert.pem) prior
1627 to running pkispawn. Once the CA has been created, swap things out to
1628 reconfigure the CA and directory server to utilize LDAPS through the
1629 desired certificates.
1630 The following example demonstrates the steps to generate a temporary
1633 self-signed certificate in the Directory Server which requires an Admin
1634 Server. Directory Server and Admin Server instances can be created
1635 with the following command:
1636 $ setup-ds.pl
1639 Enable LDAPS in the Directory Server with the following command:
1643 $ /usr/sbin/setupssl2.sh /etc/dirsrv/slapd-pki 389 636 Secret.123
1646 Note: The setupssl2.sh script may be downloaded from
1650 ⟨https://raw.githubusercontent.com/richm/scripts/master/setupssl2.sh⟩.
1651 Restart the Directory Server with the following command:
1654 $ systemctl restart dirsrv.target
1657 Verify that a client can connect securely over LDAPS with the following
1661 command:
1662 $ /usr/lib64/mozldap/ldapsearch -Z -h pki.example.com -p 636 \
1665 -D "cn=Directory Manager" -w Secret.123 -b "dc=example, dc=com" "objectclass=*"
1666 Note: The mozldap ldapsearch utility is available from the mozl‐
1670 dap-tools package.
1671 Export the self-signed CA certificate with the following command:
1674 $ certutil -L -d /etc/dirsrv/slapd-pki -n "CA certificate" -a > $HOME/dscacert.pem
1677 Once the self-signed CA certificate is obtained, add the following
1681 parameters into the [DEFAULT] section in myconfig.txt:
1682 pki_ds_secure_connection=True
1685 pki_ds_secure_connection_ca_pem_file=$HOME/dscacert.pem
1686 Then execute pkispawn to create the CA subsystem.
1690 Managing PKI instance
1693 To start all 389 instances (local PKI databases):
1694 $ systemctl start dirsrv.target
1697 To stop all 389 instances (local PKI databases):
1701 $ systemctl stop dirsrv.target
1704 To restart all 389 instances (local PKI databases):
1708 $ systemctl restart dirsrv.target
1711 To obtain the status of all 389 instances (local PKI databases):
1715 $ systemctl status dirsrv.target
1718 To start a PKI instance named <pki_instance_name>:
1722 $ systemctl start pki-tomcatd@<pki_instance_name>.service
1725 To stop a PKI instance named <pki_instance_name>:
1729 $ systemctl stop pki-tomcatd@<pki_instance_name>.service
1732 To restart a PKI instance named <pki_instance_name>:
1736 $ systemctl restart pki-tomcatd@<pki_instance_name>.service
1739 To obtain the status of a PKI instance named <pki_instance_name>:
1743 $ systemctl status pki-tomcatd@<pki_instance_name>.service
1746 To obtain a detailed status of a Tomcat PKI instance named
1750 <pki_instance_name>:
1751 $ pkidaemon status tomcat <pki_instance_name>
1754 To obtain a detailed status of all Tomcat PKI instances:
1758 $ pkidaemon status tomcat
1761
1765 pkidestroy(8)
1766 pki_default.cfg(5)
1767 pki(1)
1768 setup-ds.pl(8)
1769
1772 Ade Lee ⟨alee@redhat.com⟩.
1773
1776 Copyright (c) 2012 Red Hat, Inc. This is licensed under the GNU Gen‐
1777 eral Public License, version 2 (GPLv2). A copy of this license is
1778 available at ⟨http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt⟩.
1779PKI December 13, 2012 pkispawn(8)