1pkispawn(8) PKI Instance Creation Utility pkispawn(8)
2
6 pkispawn - Sets up an instance of Certificate Server.
7
10 pkispawn -s <subsystem> -f <config_file> [options] [-p <prefix>]
11
14 Sets up a Certificate Server subsystem (CA, KRA, OCSP, TKS, or TPS) in
15 a Tomcat instance.
16 Note: A 389 Directory Server instance must be configured and running
18 before this script can be run. Certificate Server requires an
19 internal directory database. The default configuration assumes a
20 Directory Server instance running on the same machine on port
21 389. For more information on creating a Directory Server
22 instance, see setup-ds.pl(8).
23 An instance can contain multiple subsystems, although it may contain at
25 most one of each type of subsystem on a single machine. So, for exam‐
26 ple, an instance could contain CA and KRA subsystems, but not two CA
27 subsystems. To create an instance with a CA and a KRA, simply run
28 pkispawn twice, with values -s CA and -s KRA respectively.
29 The instances are created based on values for configuration parameters
31 in the default configuration (/etc/pki/default.cfg) and the user-pro‐
32 vided configuration file. The user-provided configuration file is read
33 after the default configuration file, so any parameters defined in that
34 file will override parameters in the default configuration file. In
35 general, most users will store only those parameters which are differ‐
36 ent from the default configuration in their user-provided configuration
37 file.
38 This configuration file contains parameters that are grouped into sec‐
40 tions. These sections are stacked, so that parameters defined in ear‐
41 lier sections can be overwritten by parameters defined in later sec‐
42 tions. The sections are read in the following order: [DEFAULT], [Tom‐
43 cat], and the subsystem section ([CA], [KRA], [OCSP], [TKS], or [TPS]).
44 This allows the ability to specify parameters to be shared by all sub‐
45 systems in [DEFAULT] or [Tomcat], and system-specific customization.
46 Note: Any non-password related parameter values in the configuration
49 file that needs to contain a % character must be properly
50 escaped. For example, a value of foo%bar would be specified as
51 foo%%bar in the configuration file.
52 At a minimum, the user-defined configuration file must provide some
54 passwords needed for the install. An example configuration file is
55 provided in the EXAMPLES section below. For more information on the
56 default configuration file and the parameters it contains (and can be
57 customized), see pki_default.cfg(5).
58 The pkispawn run creates several different installation files that can
60 be referenced later, if need be:
61 * For Tomcat-based instances, a Tomcat instance is created at
63 /var/lib/pki/<pki_instance_name>, where pki_instance_name is
64 defined in the configuration file.
65 * A log file of pkispawn operations is written to
67 /var/log/pki/pki-<subsystem>-spawn.<timestamp>.log.
68 * A .p12 (PKCS #12) file containing a certificate for a subsys‐
70 tem administrator is stored in pki_client_dir.
71 When the utility is done running, the CA can be accessed by pointing a
73 browser to https://<hostname>:<pki_https_port>/. The agent pages can be
74 accessed by importing the CA certificate and administrator certificate
75 into the browser.
76 The Certificate Server instance can also be accessed using the pki com‐
78 mand line interface. See pki(1). For more extensive documentation on
79 how to use Certificate Server features, see the Red Hat Certificate
80 System Documentation at https://access.redhat.com/knowl‐
81 edge/docs/Red_Hat_Certificate_System/.
82 Instances created using pkispawn can be removed using pkidestroy. See
84 pkidestroy(8).
85 pkispawn supersedes and combines the functionality of pkicreate and
87 pkisilent, which were available in earlier releases of Certificate
88 Server. It is now possible to completely create and configure the Cer‐
89 tificate Server subsystem in a single step using pkispawn.
90 Note: Previously, as an alternative to using pkisilent to perform a
92 non-interactive batch configuration, a PKI instance could be
93 interactively configured by a GUI-based configuration wizard via
94 a Firefox browser. GUI-based configuration of a PKI instance is
95 unavailable in this version of the product.
96
98 -s <subsystem>
99 Specifies the subsystem to be installed and configured, where
100 <subsystem> is CA, KRA, OCSP, TKS, or TPS.
101 -f <config_file>
103 Specifies the path to the user-defined configuration file. This
104 file contains differences between the default configuration and
105 the custom configuration.
106 --precheck
108 Execute pre-checks and exit.
109 --skip-configuration
111 Run the first step of the installation (i.e. skipping the
112 instance configuration step).
113 --skip-installation
115 Run the second step of the installation (i.e. skipping the
116 instance installation step).
117 -h, --help
119 Prints additional help information.
120 -v Displays verbose information about the installation. This flag
122 can be provided multiple times to increase verbosity. See
123 pkispawn -h for details.
124
127 Separate PKI instances:
128 As described above, this version of Certificate System continues to
131 support separate PKI instances for all subsystems.
132 Separate PKI instances run as a single Java-based Apache Tomcat
134 instance, contain a single PKI subsystem (CA, KRA, OCSP, TKS, or TPS),
135 and must utilize unique ports if co-located on the same physical
136 machine or virtual machine (VM).
137 Shared PKI instances:
139 Additionally, this version of Certificate System introduces the notion
142 of a shared PKI instance.
143 Shared PKI instances also run as a single Java-based Apache Tomcat
145 instance, but may contain any combination of up to one of each type of
146 PKI subsystem:
147 CA
149 TKS
150 CA, KRA
151 CA, OCSP
152 TKS, TPS
153 CA, KRA, TKS, TPS
154 CA, KRA, OCSP, TKS, TPS
155 etc.
156 Shared PKI instances allow all of their subsystems contained within
158 that instance to share the same ports, and must utilize unique ports if
159 more than one shared PKI instance is co-located on the same physical
160 machine or VM.
161 Semantically, a shared PKI instance that contains a single PKI subsys‐
163 tem is identical to a separate PKI instance.
164
167 If no options are specified, pkispawn will provide an interactive menu
168 to collect the parameters needed to install the Certificate Server
169 instance. Note that only the most basic installation options are pro‐
170 vided. This includes root CA, KRA, OCSP, TKS, and TPS connecting to an
171 existing directory server. More advanced setups such as cloned subsys‐
172 tems, subordinate or externally signed CA, subsystems that connect to
173 the directory server using LDAPS, and subsystems that are customized
174 beyond the options described below require the use of a configuration
175 file with the -f option.
176 The interactive option is most useful for those users getting familiar
179 with Certificate Server. The parameters collected are written to the
180 installation file of the subsystem, which can be found at /etc/syscon‐
181 fig/pki/tomcat/<instance name>/<subsystem>/deployment.cfg.
182 The following parameters are queried interactively during the installa‐
184 tion process:
185 Subsystem Type
187 Subsystem (CA/KRA/OCSP/TKS/TPS):
189 the type of subsystem to be installed. Prompted when the -s
190 option is not specified. The default value chosen is CA.
191 Instance Specific Parameters
193 Instance name:
195 the name of the tomcat instance in which the subsystem is to be
196 installed. The default value is pki-tomcat.
197 Note: Only one subsystem of a given type (CA, KRA, OCSP, TKS,
198 TPS) can exist within a given instance.
199 HTTP port:
201 the HTTP port of the Tomcat instance. The default value is 8080.
202 Secure HTTP port:
204 the HTTPS port of the Tomcat instance. The default value is
205 8443.
206 AJP port:
208 the AJP port of the Tomcat instance. The default value is 8009.
209 Management port:
211 the management port of the Tomcat instance. The default value is
212 8005.
213 Note: When deploying a new subsystem into an existing instance,
215 pkispawn will attempt to read the ports from deployment.cfg files
216 stored for previously installed subsystems for this instance. If suc‐
217 cessful, the installer will not prompt for these ports.
218 Administrative User Parameters
220 Username:
222 the username of the administrator of this subsystem. The default
223 value is <ca/kra/ocsp/tks/tps>admin.
224 Password:
226 password for the administrator user.
227 Import certificate:
229 An optional parameter that can be used to import an already
230 available CA admin certificate into this instance.
231 Export certificate:
233 setup the path where the admin certificate of this <subsystem>
234 should be stored. The default value is $HOME/.dogtag/pki-tom‐
235 cat/<ca/kra/ocsp/tks/tps>_admin.cert.
236 Directory Server Parameters
238 Hostname:
240 Hostname of the directory server instance. The default value is
241 the hostname of the system.
242 Use a secure LDAPS connection?
244 Answering yes to this question will cause prompts for Secure
245 LDAPS Port: and Directory Server CA certificate pem file:.
246 Answering no to this question will cause a prompt for LDAP Port.
247 The initial default value for this question is no.
248 Secure LDAPS Port:
250 Secure LDAPS port for the directory server instance. The default
251 value is 636.
252 Directory Server CA certificate pem file:
254 The fully-qualified path including the filename of the file
255 which contains an exported copy of the Directory Server's CA
256 certificate (e. g. - $HOME/dscacert.pem). This file must exist
257 prior to pkispawn being able to utilize it. For details on cre‐
258 ation of this file see the EXAMPLES section below entitled
259 Installing a CA connecting securely to a Directory Server via
260 LDAPS.
261 LDAP Port:
263 LDAP port for the directory server instance. The default value
264 is 389.
265 Base DN:
267 the Base DN to be used for the internal database for this sub‐
268 system. The default value is o=pki-tomcat-<subsystem>.
269 Bind DN:
271 the bind DN required to connect for the directory server. This
272 user must have sufficient permissions to install the required
273 schema and database. The default value is cn=Directory Manager.
274 Password:
276 password for the bind DN.
277 Security Domain Parameters
279 Name: the name of the security domain. Required only if installing a
281 root CA. Default value: <DNS domain name> Security Domain.
282 Hostname:
284 the hostname for the security domain CA. Required only for non-
285 CA subsystems. The default value is the hostname of this system.
286 Secure HTTP port:
288 the https port for the security domain. Required only for non-CA
289 subsystems. The default value is 8443.
290 Username:
292 the username of the security domain administrator of the CA.
293 Required only for non-CA subsystems. The default value is caad‐
294 min.
295 Password:
297 password for the security domain administrator. Required for all
298 subsystems that are not root CAs.
299
302 This option is only available when pkispawn is invoked in a non-inter‐
303 active mode. When the --precheck option is provided, a set of basic
304 tests are performed to ensure that the parameters provided to pkispawn
305 are valid and consistent.
306 pkispawn will then exit with an exit code of 0 on success, or 1 on
308 failure. This mode can be used to perform basic tests prior to doing
309 any actual installation of the Certificate Server instance.
310 Flags are available to disable specific tests. For instance, one might
312 want to disable validation of the credentials for the internal database
313 user if the directory server instance has not yet been created.
314 See pki_default.cfg(5) for more details about available flags.
316
319 pkispawn provides a number of parameters to customize an instance
320 before it is created. Usually, most other customization can be done
321 after the server is created. However, sometimes certain types of cus‐
322 tomization need to be done before the server is created, but there are
323 no parameters for that. For example, configuring session timeout,
324 adding CSR extensions, customizing certificate profiles, configuring
325 TLS ciphers, etc. To support such customization, pkispawn provides a
326 two-step installation mode.
327 Generally, instance creation happens in one step (except for the exter‐
329 nal CA case). Internally, the process happens in two stages. In the
330 first stage, pkispawn will install the instance files (e.g. CS.cfg, NSS
331 database, profiles, etc.) in the instance directory and customize them
332 based on pkispawn parameters. In the second stage, pkispawn will start
333 the instance and configure the instance based on the instance configu‐
334 ration files (e.g. initializing database, generating certificates, con‐
335 figuring connectors, etc.). The two-step process allows the process to
336 be stopped after the first stage, allowing further customization to be
337 done before running the second stage.
338 To use two-step installation mode, prepare a normal pkispawn configura‐
340 tion file, then run pkispawn with the --skip-configuration parameter.
341 For example:
342 pkispawn -s CA -f myconfig.txt --skip-configuration
346 Then customize the files in the instance directory as needed. Finally,
349 finish the installation by running pkispawn again with the --skip-
350 installation parameter. For example:
351 pkispawn -s CA -f myconfig.txt --skip-installation
355
358 Installing a root CA
359 To install a root CA in a new instance execute the following command:
362 pkispawn -s CA -f myconfig.txt
366 where myconfig.txt contains the following text:
369 [DEFAULT]
372 pki_admin_password=Secret123
373 pki_client_pkcs12_password=Secret123
374 pki_ds_password=Secret123
375 Prior to running this command, a Directory Server instance should be
378 created and running. This command assumes that the Directory Server
379 instance is using its default configuration:
380 * Installed on the local machine
383 * Listening on port 389
386 * The user is cn=Directory Manager, with the password specified
389 in pki_ds_password
390 This invocation of pkispawn creates a Tomcat instance containing a CA
393 running on the local machine with secure port 8443 and unsecure port
394 8080. To access this CA, simply point a browser to https://<host‐
395 name>:8443.
396 The instance name (defined by pki_instance_name) is pki-tomcat, and it
399 is located at /var/lib/pki/pki-tomcat. Logs for the instance are
400 located at /var/log/pki/pki-tomcat, and an installation log is written
401 to /var/log/pki/pki-<subsystem>-spawn.<timestamp>.log.
402 A PKCS #12 file containing the administrator certificate is created in
405 $HOME/.dogtag/pki-tomcat. This PKCS #12 file uses the password desig‐
406 nated by pki_client_pkcs12_password in the configuration file.
407 To access the agent pages, first import the CA certificate by accessing
410 the CA End Entity Pages and clicking on the Retrieval Tab. Be sure to
411 trust the CA certificate. Then, import the administrator certificate in
412 the PKCS #12 file.
413 Installing a root CA using ECC
416 To install a root CA in a new instance using ECC execute the following
419 command:
420 pkispawn -s CA -f myconfig.txt
424 where myconfig.txt contains the following text:
427 [DEFAULT]
430 pki_admin_password=Secret123
431 pki_admin_key_algorithm=SHA256withEC
432 pki_admin_key_size=nistp256
433 pki_admin_key_type=ecc
434 pki_client_pkcs12_password=Secret123
435 pki_ds_password=Secret123
436 pki_sslserver_key_algorithm=SHA256withEC
437 pki_sslserver_key_size=nistp256
438 pki_sslserver_key_type=ecc
439 pki_subsystem_key_algorithm=SHA256withEC
440 pki_subsystem_key_size=nistp256
441 pki_subsystem_key_type=ecc
442 [CA]
444 pki_ca_signing_key_algorithm=SHA256withEC
445 pki_ca_signing_key_size=nistp256
446 pki_ca_signing_key_type=ecc
447 pki_ca_signing_signing_algorithm=SHA256withEC
448 pki_ocsp_signing_key_algorithm=SHA256withEC
449 pki_ocsp_signing_key_size=nistp256
450 pki_ocsp_signing_key_type=ecc
451 pki_ocsp_signing_signing_algorithm=SHA256withEC
452 In order to utilize ECC, the SSL Server and Subsystem key algorithm,
455 key size, and key type should be changed from SHA256withRSA -->
456 SHA256withEC, 2048 --> nistp256, and rsa --> ecc, respectively. To use
457 an ECC admin key size and key type, the values should also be changed
458 from 2048 --> nistp256, and rsa --> ecc.
459 Additionally, for a CA subsystem, both the CA and OCSP Signing key
462 algorithm, key size, key type, and signing algorithm should be changed
463 from SHA256withRSA --> SHA256withEC, 2048 --> nistp256, rsa --> ecc,
464 and SHA256withRSA --> SHA256withEC,respectively.
465 Note: For all PKI subsystems including the CA, ECC is not supported
468 for the corresponding Audit Signing parameters. Similarly, for
469 KRA subsystems, ECC is not supported for either of the corre‐
470 sponding Storage or Transport parameters.
471 Installing a KRA, OCSP, TKS, or TPS in a shared instance
474 For this example, assume that a new CA instance has been installed by
477 executing the following command:
478 pkispawn -s CA -f myconfig.txt
481 where myconfig.txt contains the following text:
483 [DEFAULT]
485 pki_admin_password=Secret123
486 pki_client_pkcs12_password=Secret123
487 pki_ds_password=Secret123
488 # Optionally keep client databases
489 pki_client_database_purge=False
490 To install a shared KRA in the same instance used by the CA execute
492 the following command:
493 pkispawn -s KRA -f myconfig.txt
496 where myconfig.txt contains the following text:
498 [DEFAULT]
500 pki_admin_password=Secret123
501 pki_client_database_password=Secret123
502 pki_client_pkcs12_password=Secret123
503 pki_ds_password=Secret123
504 pki_security_domain_password=Secret123
505 To install a shared OCSP in the same instance used by the CA execute
507 the following command:
508 pkispawn -s OCSP -f myconfig.txt
511 where myconfig.txt contains the following text:
513 [DEFAULT]
515 pki_admin_password=Secret123
516 pki_client_database_password=Secret123
517 pki_client_pkcs12_password=Secret123
518 pki_ds_password=Secret123
519 pki_security_domain_password=Secret123
520 To install a shared TKS in the same instance used by the CA execute
522 the following command:
523 pkispawn -s TKS -f myconfig.txt
526 where myconfig.txt contains the following text:
528 [DEFAULT]
530 pki_admin_password=Secret123
531 pki_client_database_password=Secret123
532 pki_client_pkcs12_password=Secret123
533 pki_ds_password=Secret123
534 pki_security_domain_password=Secret123
535 To install a shared TPS in the same instance used by the CA execute
537 the following command:
538 pkispawn -s TPS -f myconfig.txt
541 where myconfig.txt contains the following text:
543 [DEFAULT]
545 pki_admin_password=Secret123
546 pki_client_database_password=Secret123
547 pki_client_pkcs12_password=Secret123
548 pki_ds_password=Secret123
549 pki_security_domain_password=Secret123
550 [TPS]
551 # Shared TPS instances optionally utilize their shared KRA
552 # for server-side keygen
553 pki_enable_server_side_keygen=True
554 pki_authdb_basedn=dc=example,dc=com
555 Note: For this particular example, the computed default values for a
557 PKI instance name including its ports, URLs, machine names, etc.
558 were utilized as defined in /etc/pki/default.cfg. Each
559 subsystem in this example will reside under the
560 /var/lib/pki/pki-tomcat instance housed within their own
561 ca, kra, ocsp, tks, and tps
562 subdirectories, utilizing the same default port values of
563 8080 (http), 8443 (https), 8009 (ajp), 8005 (tomcat), using the
564 same computed hostname and URL information, and sharing a single
565 common PKI Administrator Certificate.
566 The pki_security_domain_password is the admin password of the
569 CA installed in the same instance. This command should be run after
570 a CA is installed. This installs another subsystem within the same
571 instance using the certificate generated for the CA administrator
572 for the subsystem's administrator. This allows a user to access
573 both subsystems on the browser with a single administrator
574 certificate. To access the new subsystem's functionality, simply
575 point the browser to https://<hostname>:8443 and click the
576 relevant top-level links.
577 To install TPS in a shared instance the following section must be
580 added to myconfig.txt:
581 [TPS]
584 pki_authdb_basedn=dc=example,dc=com
585 TPS requires an authentication database. The pki_authdb_basedn speci‐
588 fies the base DN of the authentication database.
589 TPS also requires that a CA and a TKS subsystems are already installed
592 in the same instance. Since they are in the same instance, a shared
593 secret key will automatically be generated in TKS and imported into
594 TPS.
595 Optionally, server-side key generation can be enabled in TPS by adding
598 the following parameter in [TPS]:
599 pki_enable_server_side_keygen=True
602 Enabling server-side key generation requires that a KRA subsystem is
605 already installed in the same instance.
606 Installing a KRA, OCSP, TKS, or TPS in a separate instance
609 For this example, assume that a new CA instance has been installed by
612 executing the following command:
613 pkispawn -s CA -f myconfig.txt
616 where myconfig.txt contains the following text:
618 [DEFAULT]
620 pki_admin_password=Secret123
621 pki_client_pkcs12_password=Secret123
622 pki_ds_password=Secret123
623 # Optionally keep client databases
624 pki_client_database_purge=False
625 # Separated CA instance name and ports
626 pki_instance_name=pki-ca
627 pki_http_port=18080
628 pki_https_port=18443
629 # This Separated CA instance will be its own security domain
630 pki_security_domain_https_port=18443
631 [Tomcat]
632 # Separated CA Tomcat ports
633 pki_ajp_port=18009
634 pki_tomcat_server_port=18005
635 To install a separate KRA which connects to this remote CA execute
637 the following command:
638 pkispawn -s KRA -f myconfig.txt
641 where myconfig.txt contains the following text:
643 [DEFAULT]
645 pki_admin_password=Secret123
646 pki_client_database_password=Secret123
647 pki_client_pkcs12_password=Secret123
648 pki_ds_password=Secret123
649 pki_security_domain_password=Secret123
650 # Optionally keep client databases
651 pki_client_database_purge=False
652 # Separated KRA instance name and ports
653 pki_instance_name=pki-kra
654 pki_http_port=28080
655 pki_https_port=28443
656 # Separated KRA instance security domain references
657 pki_issuing_ca=https://pki.example.com:18443
658 pki_security_domain_hostname=pki.example.com
659 pki_security_domain_https_port=18443
660 pki_security_domain_user=caadmin
661 [Tomcat]
662 # Separated KRA Tomcat ports
663 pki_ajp_port=28009
664 pki_tomcat_server_port=28005
665 [KRA]
666 # A Separated KRA instance requires its own
667 # PKI Administrator Certificate
668 pki_import_admin_cert=False
669 To install a separate OCSP which connects to this remote CA execute
671 the following command:
672 pkispawn -s OCSP -f myconfig.txt
675 where myconfig.txt contains the following text:
677 [DEFAULT]
679 pki_admin_password=Secret123
680 pki_client_database_password=Secret123
681 pki_client_pkcs12_password=Secret123
682 pki_ds_password=Secret123
683 pki_security_domain_password=Secret123
684 # Optionally keep client databases
685 pki_client_database_purge=False
686 # Separated OCSP instance name and ports
687 pki_instance_name=pki-ocsp
688 pki_http_port=29080
689 pki_https_port=29443
690 # Separated OCSP instance security domain references
691 pki_issuing_ca=https://pki.example.com:18443
692 pki_security_domain_hostname=pki.example.com
693 pki_security_domain_https_port=18443
694 pki_security_domain_user=caadmin
695 [Tomcat]
696 # Separated OCSP Tomcat ports
697 pki_ajp_port=29009
698 pki_tomcat_server_port=29005
699 [OCSP]
700 # A Separated OCSP instance requires its own
701 # PKI Administrator Certificate
702 pki_import_admin_cert=False
703 To install a separate TKS which connects to this remote CA execute
705 the following command:
706 pkispawn -s TKS -f myconfig.txt
709 where myconfig.txt contains the following text:
711 [DEFAULT]
713 pki_admin_password=Secret123
714 pki_client_database_password=Secret123
715 pki_client_pkcs12_password=Secret123
716 pki_ds_password=Secret123
717 pki_security_domain_password=Secret123
718 # Optionally keep client databases
719 pki_client_database_purge=False
720 # Separated TKS instance name and ports
721 pki_instance_name=pki-tks
722 pki_http_port=30080
723 pki_https_port=30443
724 # Separated TKS instance security domain references
725 pki_issuing_ca=https://pki.example.com:18443
726 pki_security_domain_hostname=pki.example.com
727 pki_security_domain_https_port=18443
728 pki_security_domain_user=caadmin
729 [Tomcat]
730 # Separated TKS Tomcat ports
731 pki_ajp_port=30009
732 pki_tomcat_server_port=30005
733 [TKS]
734 # A Separated TKS instance requires its own
735 # PKI Administrator Certificate
736 pki_import_admin_cert=False
737 To install a separate TPS which connects to this remote CA execute
739 the following command:
740 pkispawn -s TPS -f myconfig.txt
743 where myconfig.txt contains the following text:
745 [DEFAULT]
747 pki_admin_password=Secret123
748 pki_client_database_password=Secret123
749 pki_client_pkcs12_password=Secret123
750 pki_ds_password=Secret123
751 pki_security_domain_password=Secret123
752 # Optionally keep client databases
753 pki_client_database_purge=False
754 # Separated TPS instance name and ports
755 pki_instance_name=pki-tps
756 pki_http_port=31080
757 pki_https_port=31443
758 # Separated TPS instance security domain references
759 pki_issuing_ca=https://pki.example.com:18443
760 pki_security_domain_hostname=pki.example.com
761 pki_security_domain_https_port=18443
762 pki_security_domain_user=caadmin
763 [Tomcat]
764 # Separated TPS Tomcat ports
765 pki_ajp_port=31009
766 pki_tomcat_server_port=31005
767 [TPS]
768 # Separated TPS instances require specifying a remote CA
769 pki_ca_uri=https://pki.example.com:18443
770 # Separated TPS instances optionally utilize a remote KRA
771 # for server-side keygen
772 pki_kra_uri=https://pki.example.com:28443
773 pki_enable_server_side_keygen=True
774 pki_authdb_basedn=dc=example,dc=com
775 # Separated TPS instances require specifying a remote TKS
776 pki_tks_uri=https://pki.example.com:30443
777 pki_import_shared_secret=True
778 # A Separated TPS instance requires its own
779 # PKI Administrator Certificate
780 pki_import_admin_cert=False
781 Note: For this particular example, besides passwords, sample
783 values were also utilized for PKI instance names, ports,
784 URLs, machine names, etc. Under no circumstances should
785 these demonstrative values be construed to be required
786 literal values.
787 A remote CA is one where the CA resides in another
790 Certificate Server instance, either on the local machine
791 or a remote machine. In this case, myconfig.txt must
792 specify the connection information for the remote CA and the
793 information about the security domain (the trusted collection
794 of subsystems within an instance).
795 The subsystem section is [KRA], [OCSP], [TKS], or [TPS].
798 This example assumes that the specified CA hosts the security
799 domain. The CA must be running and accessible.
800 A new administrator certificate is generated for the new
803 subsystem and stored in a PKCS #12 file
804 in $HOME/.dogtag/<pki_instance_name>.
805 As in a shared instance, to install TPS in a separate instance
808 the authentication database must be specified in the [TPS] section,
809 and optionally the server-side key generation can be enabled.
810 If the CA, KRA, or TKS subsystems required by TPS are running
811 on a remote instance the following parameters must be added into
812 the [TPS] section to specify their locations:
813 pki_ca_uri=https://<ca_hostname>:<ca_https_port>
816 pki_kra_uri=https://<kra_hostname>:<kra_https_port>
817 pki_tks_uri=https://<tks_hostname>:<tks_https_port>
818 If TPS and TKS are installed on separate instances the shared secret
821 key should be imported over the wire between the TKS and TPS automati‐
822 cally.
823 If the automated procedure fails for any unlikely reason the following
825 manual procedure will serve as a fallback. The key needs to be created
826 on the TKS side and imported into the TPS side in this case.
827 Generate the shared secret key (if needed) in TKS with the following
830 command:
831 tkstool -T -d /var/lib/pki/pki-tomcat/alias -n sharedSecret
834 Verify the shared secret key in TKS with the following command:
837 tkstool -L -d /var/lib/pki/pki-tomcat/alias
840 Once TPS is installed, shutdown TPS instance, then import the shared
843 secret key into TPS with the following command:
844 tkstool -I -d /var/lib/pki/pki-tomcat/alias -n sharedSecret
847 Verify the shared secret key in TPS with the following command:
850 tkstool -L -d /var/lib/pki/pki-tomcat/alias
853 The shared secret key nickname should be stored in the following prop‐
856 erty in the TPS's CS.cfg:
857 conn.tks1.tksSharedSymKeyName=sharedSecret
860 Finally, restart the TPS instance.
863 Installing a CA, KRA, OCSP, TKS, or TPS using a Hardware Security Module
866 (HSM)
867 This section provides sample myconfig.txt files when an HSM is being
870 utilized in a shared PKI instance.
871 For this example, assume that a new CA instance has been installed by
874 executing the following command:
875 pkispawn -s CA -f myconfig.txt
878 where myconfig.txt contains the following text:
880 [DEFAULT]
882 pki_admin_password=Secret123
883 pki_client_pkcs12_password=Secret123
884 pki_ds_password=Secret123
885 # Optionally keep client databases
886 pki_client_database_purge=False
887 # Provide HSM parameters
888 pki_hsm_enable=True
889 pki_hsm_libfile=<hsm_libfile>
890 pki_hsm_modulename=<hsm_modulename>
891 pki_token_name=<hsm_token_name>
892 pki_token_password=<pki_token_password>
893 # Provide PKI-specific HSM token names
894 pki_audit_signing_token=<hsm_token_name>
895 pki_sslserver_token=<hsm_token_name>
896 pki_subsystem_token=<hsm_token_name>
897 [CA]
898 # Provide CA-specific HSM token names
899 pki_ca_signing_token=<hsm_token_name>
900 pki_ocsp_signing_token=<hsm_token_name>
901 To install a shared KRA in the same instance used by the CA execute
903 the following command:
904 pkispawn -s KRA -f myconfig.txt
907 where myconfig.txt contains the following text:
909 [DEFAULT]
911 pki_admin_password=Secret123
912 pki_client_database_password=Secret123
913 pki_client_pkcs12_password=Secret123
914 pki_ds_password=Secret123
915 pki_security_domain_password=Secret123
916 # Provide HSM parameters
917 pki_hsm_enable=True
918 pki_hsm_libfile=<hsm_libfile>
919 pki_hsm_modulename=<hsm_modulename>
920 pki_token_name=<hsm_token_name>
921 pki_token_password=<pki_token_password>
922 # Provide PKI-specific HSM token names
923 pki_audit_signing_token=<hsm_token_name>
924 pki_sslserver_token=<hsm_token_name>
925 pki_subsystem_token=<hsm_token_name>
926 [KRA]
927 # Provide KRA-specific HSM token names
928 pki_storage_token=<hsm_token_name>
929 pki_transport_token=<hsm_token_name>
930 To install a shared OCSP in the same instance used by the CA execute
932 the following command:
933 pkispawn -s OCSP -f myconfig.txt
936 where myconfig.txt contains the following text:
938 [DEFAULT]
940 pki_admin_password=Secret123
941 pki_client_database_password=Secret123
942 pki_client_pkcs12_password=Secret123
943 pki_ds_password=Secret123
944 pki_security_domain_password=Secret123
945 # Provide HSM parameters
946 pki_hsm_enable=True
947 pki_hsm_libfile=<hsm_libfile>
948 pki_hsm_modulename=<hsm_modulename>
949 pki_token_name=<hsm_token_name>
950 pki_token_password=<pki_token_password>
951 # Provide PKI-specific HSM token names
952 pki_audit_signing_token=<hsm_token_name>
953 pki_sslserver_token=<hsm_token_name>
954 pki_subsystem_token=<hsm_token_name>
955 [OCSP]
956 # Provide OCSP-specific HSM token names
957 pki_ocsp_signing_token=<hsm_token_name>
958 To install a shared TKS in the same instance used by the CA execute
960 the following command:
961 pkispawn -s TKS -f myconfig.txt
964 where myconfig.txt contains the following text:
966 [DEFAULT]
968 pki_admin_password=Secret123
969 pki_client_database_password=Secret123
970 pki_client_pkcs12_password=Secret123
971 pki_ds_password=Secret123
972 pki_security_domain_password=Secret123
973 # Provide HSM parameters
974 pki_hsm_enable=True
975 pki_hsm_libfile=<hsm_libfile>
976 pki_hsm_modulename=<hsm_modulename>
977 pki_token_name=<hsm_token_name>
978 pki_token_password=<pki_token_password>
979 # Provide PKI-specific HSM token names
980 pki_audit_signing_token=<hsm_token_name>
981 pki_sslserver_token=<hsm_token_name>
982 pki_subsystem_token=<hsm_token_name>
983 To install a shared TPS in the same instance used by the CA execute
985 the following command:
986 pkispawn -s TPS -f myconfig.txt
989 where myconfig.txt contains the following text:
991 [DEFAULT]
993 pki_admin_password=Secret123
994 pki_client_database_password=Secret123
995 pki_client_pkcs12_password=Secret123
996 pki_ds_password=Secret123
997 pki_security_domain_password=Secret123
998 # Provide HSM parameters
999 pki_hsm_enable=True
1000 pki_hsm_libfile=<hsm_libfile>
1001 pki_hsm_modulename=<hsm_modulename>
1002 pki_token_name=<hsm_token_name>
1003 pki_token_password=<pki_token_password>
1004 # Provide PKI-specific HSM token names
1005 pki_audit_signing_token=<hsm_token_name>
1006 pki_sslserver_token=<hsm_token_name>
1007 pki_subsystem_token=<hsm_token_name>
1008 [TPS]
1009 # Shared TPS instances optionally utilize their shared KRA
1010 # for server-side keygen
1011 pki_enable_server_side_keygen=True
1012 pki_authdb_basedn=dc=example,dc=com
1013 Important:
1015 Since HSM keys are stored in the HSM (hardware), they cannot be
1016 backed up, moved, or copied to a PKCS #12 file (software).
1017 For example, if pki_hsm_enable is set to True,
1018 pki_backup_keys should be set to False and
1019 pki_backup_password should be left unset (the default
1020 values in /etc/pki/default.cfg). Similarly, for the case
1021 of clones using an HSM, this means that the HSM keys must be
1022 shared between the master and its clones. Therefore, if
1023 pki_hsm_enable is set to True, both
1024 pki_clone_pkcs12_path and pki_clone_pkcs12_password
1025 should be left unset (the default values in
1026 /etc/pki/default.cfg). Failure to comply with these rules
1027 will result in pkispawn reporting an appropriate error and
1028 exiting.
1029 Installing a CA clone
1032 To install a CA clone execute the following command:
1035 pkispawn -s CA -f myconfig.txt
1039 where myconfig.txt contains the following text:
1042 [DEFAULT]
1045 pki_admin_password=Secret123
1046 pki_client_database_password=Secret123
1047 pki_client_pkcs12_password=Secret123
1048 pki_ds_password=Secret123
1049 pki_security_domain_password=Secret123
1050 pki_security_domain_hostname=<master_ca_hostname>
1051 pki_security_domain_https_port=<master_ca_https_port>
1052 pki_security_domain_user=caadmin
1053 pki_security_domain_post_login_sleep_seconds=5
1054 [Tomcat]
1056 pki_clone=True
1057 pki_clone_pkcs12_password=Secret123
1058 pki_clone_pkcs12_path=<path_to_pkcs12_file>
1059 pki_clone_replicate_schema=True
1060 pki_clone_uri=https://<master_ca_hostname>:<master_ca_https_port>
1061 A cloned CA is a CA which uses the same signing, OCSP signing, and
1064 audit signing certificates as the master CA, but issues certificates
1065 within a different serial number range. It has its own internal data‐
1066 base -- separate from the master CA database -- but using the same base
1067 DN, that keeps in sync with the master CA through replication agree‐
1068 ments between the databases. This is very useful for load sharing and
1069 disaster recovery. To create a clone, the myconfig.txt uses pki_clone-*
1070 parameters in its [Tomcat] section which identify the original CA to
1071 use as a master template. Additionally, it connects to the master CA as
1072 a remote CA and uses its security domain.
1073 Before the clone can be generated, the Directory Server must be created
1076 that is separate from the master CA's Directory Server. The example
1077 assumes that the master CA and cloned CA are on different machines, and
1078 that their Directory Servers are on port 389.
1079 In addition, since this example does not utilize an HSM, the master's
1082 system certs and keys have been stored in a PKCS #12 file that is
1083 copied over to the clone subsystem in the location specified in
1084 <path_to_pkcs12_file>. This file needs to be readable by the user the
1085 Certificate Server runs as (by default, pkiuser) and be given the
1086 SELinux context pki_tomcat_cert_t.
1087 The master's system certificates can be exported to a PKCS#12 file when
1090 the master is installed if the parameter pki_backup_keys is set to True
1091 and the pki_backup_password is set. The PKCS#12 file is then found
1092 under /var/lib/pki/<instance_name>/alias. Alternatively, the PKCS#12
1093 file can be generated at any time post-installation using PKCS12Export.
1094 The pki_security_domain_post_login_sleep_seconds config specifies sleep
1097 duration after logging into a security domain, to allow the security
1098 domain session data to be replicated to subsystems on other hosts. It
1099 is optional and defaults to 5 seconds.
1100 An example invocation showing the export of the system certificates and
1103 keys, copying the keys to the replica subsystem, and setting the rele‐
1104 vant SELinux and file permissions is shown below. pwfile is a text
1105 file containing the password for the master NSS DB (found in
1106 /etc/pki/<instance_name>/password.conf).
1107 pkcs12_password_file is a text file containing the password selected
1108 for the generated PKCS12 file.
1109 master# PKCS12Export -d /etc/pki/pki-tomcat/alias -p pwfile \
1112 -w pkcs12_password_file -o backup_keys.p12
1113 master# scp backup_keys.p12 clone:/backup_keys.p12
1114 clone# chown pkiuser: /backup_keys.p12
1116 clone# semanage -a -t pki_tomcat_cert_t /backup_keys.p12
1117 Note: From Dogtag 10.3, a slightly different mechanism has been pro‐
1120 vided to create and specify the required PKCS#12 file to the clone sub‐
1121 system. This new method is provided in addition to the method above,
1122 but will become the preferred method in future releases.
1123 This method can be used if both master and clone are 10.3 or above.
1125 To export the required keys from the master, use the pki-server command
1128 line tool.
1129 master# pki-server ca-clone-prepare -i pki-tomcat \
1132 --pkcs12-file backup_keys.p12 \
1133 --pkcs12-password Secret123
1134 master# scp backup_keys.p12 clone:/backup_keys.p12
1136 master# scp /etc/pki/pki-tomcat/external_certs.conf \
1137 clone:/external_certs.conf
1138 The external_certs.conf file contains information about third party
1141 certificates that were added to the master's certificate database using
1142 the pki-server command. The certificates themselves are stored in the
1143 backup_keys.p12 file. If there are no third-party certifcates that have
1144 been added, then the external_certs.conf file may not exist and should
1145 be ignored.
1146 The two files (backup_keys.p12 and external_certs.conf) are specified
1148 to pkispawn as below.
1149 [DEFAULT]
1152 pki_admin_password=Secret123
1153 pki_client_database_password=Secret123
1154 pki_client_pkcs12_password=Secret123
1155 pki_ds_password=Secret123
1156 pki_security_domain_password=Secret123
1157 pki_security_domain_hostname=<master_ca_hostname>
1158 pki_security_domain_https_port=<master_ca_https_port>
1159 pki_security_domain_user=caadmin
1160 [Tomcat]
1162 pki_server_pkcs12_path=<path to pkcs12 file>
1163 pki_server_pkcs12_password=Secret123
1164 pki_server_external_certs_path=<path to external_certs.conf file>
1165 pki_clone=True
1166 pki_clone_replicate_schema=True
1167 pki_clone_uri=https://<master_ca_hostname>:<master_ca_https_port>
1168 Note that the previous p12 parameters (pki_clone_pkcs12_*) are no
1171 longer needed, and will be ignored.
1172 Note: One current cloning anomaly to mention is the following scenario:
1174 1. Create a clone of a CA or of any other subsystem.
1176 2. Remove that just created clone.
1177 3. Immediately attempt the exact same clone again, in place of
1178 the recently destroyed instance. Before recreating this clone,
1179 make sure the "pki_ds_remove_data=True" is used in the clone's
1180 deployment config file. This will remove the old data from the previous
1181 clone.
1182 Here the Director Server instance may have worked itself in into a state
1184 where it no longer accepts connections, aborting the clone configuration quickly.
1185 The fix to this is to simply restart the Directory Server instance before
1187 creating the clone for the second time. After restarting the Directory Server
1188 it should be possible to create the mentioned clone instance.
1189 Installing a KRA or TKS clone
1192 To install a KRA or TKS (OCSP and TPS unsupported as of now) execute
1195 the following command:
1196 pkispawn -s <subsystem> -f myconfig.txt
1200 where subsystem is KRA or TKS and myconfig.txt contains the following
1203 text:
1204 [DEFAULT]
1207 pki_admin_password=Secret123
1208 pki_client_database_password=Secret123
1209 pki_client_pkcs12_password=Secret123
1210 pki_ds_password=Secret123
1211 pki_security_domain_password=Secret123
1212 pki_security_domain_hostname=<master_ca_hostname>
1213 pki_security_domain_https_port=<master_ca_https_port>
1214 pki_security_domain_user=caadmin
1215 [Tomcat]
1217 pki_clone=True
1218 pki_clone_pkcs12_password=Secret123
1219 pki_clone_pkcs12_path=<path_to_pkcs12_file>
1220 pki_clone_replicate_schema=True
1221 pki_clone_uri=https://<master_subsystem_host>:<master_subsystem_https_port>
1222 pki_issuing_ca=https://<ca_hostname>:<ca_https_port>
1223 As with a CA clone, a KRA or TKS clone uses the same certificates and
1226 basic configuration as the original subsystem. The configuration points
1227 to the original subsystem to copy its configuration. This example also
1228 assumes that the CA is on a remote machine and specifies the CA and
1229 security domain information.
1230 The parameter pki_clone_uri should be modified to point to the required
1233 master (KRA or TKS).
1234 As of 10.3, a slightly different mechanism has been introduced to gen‐
1236 erate and specify the PKCS#12 file and any third-party certificates.
1237 See the Installing a CA clone section for details.
1238 Installing a CA clone on the same host
1241 For testing purposes, it is useful to configure cloned CAs which exist
1244 (with their internal databases) on the same host as the master CA. To
1245 configure the cloned CA execute the following command:
1246 pkispawn -s CA -f myconfig.txt
1250 where myconfig.txt contains the following text:
1253 [DEFAULT]
1256 pki_admin_password=Secret123
1257 pki_client_database_password=Secret123
1258 pki_client_pkcs12_password=Secret123
1259 pki_ds_password=Secret123
1260 pki_ds_ldap_port=<unique port different from master>
1261 pki_ds_ldaps_port=<unique port different from master>
1262 pki_http_port=<unique port different from master>
1263 pki_https_port=<unique port different from master>
1264 pki_instance_name=<unique name different from master>
1265 pki_security_domain_hostname=<master_ca_hostname>
1266 pki_security_domain_https_port=<master_ca_https_port>
1267 pki_security_domain_password=Secret123
1268 [Tomcat]
1270 pki_ajp_port=<unique port different from master>
1271 pki_clone=True
1272 pki_clone_pkcs12_password=Secret123
1273 pki_clone_pkcs12_path=<path_to_pkcs12_file>
1274 pki_clone_uri=https://<master_ca_hostname>:<master_ca_https_port>
1275 pki_tomcat_server_port=<unique port different from master>
1276 [CA]
1278 pki_ds_base_dn=<identical value as master>
1279 pki_ds_database=<identical value as master>
1280 In this case, because both CA Tomcat instances are on the same host,
1283 they must have distinct ports. Similarly, each CA must use a distinct
1284 directory server instance for its internal database. Like the Tomcat
1285 instances, these are distinguished by distinct ports. The suffix being
1286 replicated (pki_ds_base), however, must be the same for both master and
1287 clone.
1288 Installing a subordinate CA in existing security domain
1291 To install a subordinate CA in an existing security domain execute the
1294 following command:
1295 pkispawn -s CA -f myconfig.txt
1299 where myconfig.txt contains the following text:
1302 [DEFAULT]
1305 pki_admin_password=Secret123
1306 pki_client_database_password=Secret123
1307 pki_client_pkcs12_password=Secret123
1308 pki_ds_password=Secret123
1309 pki_security_domain_password=Secret123
1310 pki_security_domain_hostname=<security_domain_ca_hostname>
1311 pki_security_domain_https_port=<security_domain_ca_https_port>
1312 pki_security_domain_user=caadmin
1313 [CA]
1315 pki_subordinate=True
1316 pki_issuing_ca=https://<master_ca_hostname>:<master_ca_https_port>
1317 pki_ca_signing_subject_dn=cn=CA Subordinate Signing,o=example.com
1318 A sub-CA derives its certificate configuration -- such as allowed
1321 extensions and validity periods -- from a superior or root CA. Other‐
1322 wise, the configuration of the CA is independent of the root CA, so it
1323 is its own instance rather than a clone. A sub-CA is configured using
1324 the pki_subordinate parameter and a pointer to the CA which issues the
1325 sub-CA's certificates.
1326 Note: The value of pki_ca_signing_subject_dn of a subordinate CA should
1329 be different from the root CA's signing subject DN.
1330 Installing a subordinate CA in new security domain
1333 To install a subordinate CA in a new security domain execute the fol‐
1336 lowing command:
1337 pkispawn -s CA -f myconfig.txt
1341 where myconfig.txt contains the following text:
1344 [DEFAULT]
1347 pki_admin_password=Secret123
1348 pki_client_database_password=Secret123
1349 pki_client_pkcs12_password=Secret123
1350 pki_ds_password=Secret123
1351 pki_security_domain_password=Secret123
1352 pki_security_domain_hostname=<master CA security domain hostname>
1353 pki_security_domain_https_port=<master CA security domain https port>
1354 pki_security_domain_user=caadmin
1355 [CA]
1357 pki_subordinate=True
1358 pki_issuing_ca=https://<master_ca_hostname>:<master_ca_https_port>
1359 pki_ca_signing_subject_dn=cn=CA Subordinate Signing,o=example.com
1360 pki_subordinate_create_new_security_domain=True
1361 pki_subordinate_security_domain_name=Subordinate CA Security Domain
1362 In this section, the subordinate CA logs onto and registers with the
1365 security domain CA (using parameters pki_security_domain_hostname,
1366 pki_security_domain_user and pki_security_domain_password) as in the
1367 previous section, but also creates and hosts a new security domain. To
1368 do this, pki_subordinate_create_new_security_domain must be set to
1369 True. The subordinate CA security domain name can also be specified by
1370 specifying a value for pki_subordinate_security_domain_name.
1371 Note: The value of pki_ca_signing_subject_dn of a subordinate CA should
1374 be different from the root CA's signing subject DN.
1375 Installing an externally signed CA
1378 To install an externally signed CA execute the following command:
1381 pkispawn -s CA -f myconfig.txt
1385 This is a two step process.
1388 In the first step, a certificate signing request (CSR) is generated for
1391 the signing certificate and myconfig.txt contains the following text:
1392 [DEFAULT]
1395 pki_admin_password=Secret123
1396 pki_client_database_password=Secret123
1397 pki_client_pkcs12_password=Secret123
1398 pki_ds_password=Secret123
1399 pki_security_domain_password=Secret123
1400 [CA]
1402 pki_external=True
1403 pki_ca_signing_csr_path=/tmp/ca_signing.csr
1404 pki_ca_signing_subject_dn=cn=CA Signing,ou=External,o=example.com
1405 The CSR is written to pki_ca_signing_csr_path. The pki_ca_signing_sub‐
1408 ject_dn should be different from the subject DN of the external CA that
1409 is signing the request. The pki_ca_signing_subject_dn parameter can be
1410 used to specify the signing certificate's subject DN.
1411 The CSR is then submitted to the external CA, and the resulting cer‐
1414 tificate and certificate chain are saved to files on the system.
1415 In the second step, the configuration file has been modified to install
1418 the issued certificates. In place of the original CSR, the configura‐
1419 tion file now points to the issued CA certificate and certificate
1420 chain. There is also a flag to indicate that this completes the instal‐
1421 lation process (pki_external_step_two).
1422 [DEFAULT]
1425 pki_admin_password=Secret123
1426 pki_client_database_password=Secret123
1427 pki_client_pkcs12_password=Secret123
1428 pki_ds_password=Secret123
1429 pki_security_domain_password=Secret123
1430 [CA]
1432 pki_external=True
1433 pki_external_step_two=True
1434 pki_cert_chain_path=/tmp/ca_cert_chain.cert
1435 pki_ca_signing_cert_path=/tmp/ca_signing.cert
1436 pki_ca_signing_subject_dn=cn=CA Signing Certificate,ou=External,o=example.com
1437 Then, the pkispawn command is run again:
1440 pkispawn -s CA -f myconfig.txt
1443 Installing a PKI subsystem with a secure LDAP connection
1446 There are three scenarios in which a PKI subsystem (e.g. a CA) needs to
1449 communicate securely via LDAPS with a directory server:
1450 * A directory server exists which is already running LDAPS using
1453 a CA certificate that has been issued by some other CA. For this
1454 scenario, the CA certificate must be made available via a PEM
1455 file (e.g. $HOME/dscacert.pem) prior to running pkispawn such
1456 that the new CA may be installed and configured to communicate
1457 with this directory server using LDAPS.
1458 * A directory server exists which is currently running LDAP.
1461 Once a CA has been created, there is a desire to use its CA cer‐
1462 tificate to issue an SSL certificate for this directory server
1463 so that this CA and this directory server can communicate via
1464 LDAPS. For this scenario, since there is no need to communicate
1465 securely during the pkispawn installation/configuration, simply
1466 use pkispawn to install and configure the CA using the LDAP port
1467 of the directory server, issue an SSL certificate from this CA
1468 for the directory server, and then reconfigure the CA and direc‐
1469 tory server to communicate with each other via LDAPS.
1470 * Similar to the previous scenario, a directory server exists
1473 which is currently running LDAP, and the desire is to create a
1474 CA and use it to establish LDAPS communications between this CA
1475 and this directory server. However, for this scenario, there is
1476 a need for the CA and the directory server to communicate
1477 securely during pkispawn installation and configuration. For
1478 this to succeed, the directory server must generate a temporary
1479 self-signed certificate which then must be made available via a
1480 PEM file (e.g. $HOME/dscacert.pem) prior to running pkispawn.
1481 Once the CA has been created, swap things out to reconfigure the
1482 CA and directory server to utilize LDAPS through the desired
1483 certificates.
1484 The following example demonstrates the steps to generate a temporary
1487 self-signed certificate in the Directory Server which requires an Admin
1488 Server. Directory Server and Admin Server instances can be created
1489 with the following command:
1490 setup-ds.pl
1493 Enable LDAPS in the Directory Server with the following command:
1496 /usr/sbin/setupssl2.sh /etc/dirsrv/slapd-pki 389 636 Secret123
1499 Note: The setupssl2.sh script may be downloaded from
1502 https://raw.githubusercontent.com/richm/scripts/master/setupssl2.sh.
1503 Restart the Directory Server with the following command:
1505 systemctl restart dirsrv.target
1508 Verify that a client can connect securely over LDAPS with the following
1511 command:
1512 /usr/lib64/mozldap/ldapsearch -Z -h pki.example.com -p 636 -D
1515 'cn=Directory Manager' -w Secret123 -b "dc=example, dc=com"
1516 "objectclass=*"
1517 Note: The mozldap ldapsearch utility is available from the mozldap-
1520 tools package.
1521 Export the self-signed CA certificate with the following command:
1524 certutil -L -d /etc/dirsrv/slapd-pki -n "CA certificate" -a >
1527 $HOME/dscacert.pem
1528 Once the self-signed CA certificate is obtained, add the following
1531 parameters into the [DEFAULT] section in myconfig.txt:
1532 pki_ds_secure_connection=True
1535 pki_ds_secure_connection_ca_pem_file=$HOME/dscacert.pem
1536 Then execute pkispawn to create the CA subsystem.
1539 Managing PKI instance
1542 To start all 389 instances (local PKI databases):
1545 systemctl start dirsrv.target
1547 To stop all 389 instances (local PKI databases):
1549 systemctl stop dirsrv.target
1551 To restart all 389 instances (local PKI databases):
1553 systemctl restart dirsrv.target
1555 To obtain the status of all 389 instances (local PKI databases):
1557 systemctl status dirsrv.target
1559 To start a PKI instance named <pki_instance_name>:
1561 systemctl start pki-tomcatd@<pki_instance_name>.service
1563 To stop a PKI instance named <pki_instance_name>:
1565 systemctl stop pki-tomcatd@<pki_instance_name>.service
1567 To restart a PKI instance named <pki_instance_name>:
1569 systemctl restart pki-tomcatd@<pki_instance_name>.service
1571 To obtain the status of a PKI instance named <pki_instance_name>:
1573 systemctl status pki-tomcatd@<pki_instance_name>.service
1575 To obtain a detailed status of a Tomcat PKI instance named
1577 <pki_instance_name>:
1578 pkidaemon status tomcat <pki_instance_name>
1580 To obtain a detailed status of all Tomcat PKI instances:
1582 pkidaemon status tomcat
1584
1587 Report bugs to http://bugzilla.redhat.com.
1588
1591 Ade Lee <alee@redhat.com>. pkispawn was written by the Certificate
1592 Server project.
1593
1596 Copyright (c) 2012 Red Hat, Inc. This is licensed under the GNU General
1597 Public License, version 2 (GPLv2). A copy of this license is available
1598 at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.
1599
1602 pkidestroy(8), pki_default.cfg(5), pki(1), setup-ds.pl(8)
1603version 1.0 December 13, 2012 pkispawn(8)