1pkispawn(8)              PKI Instance Creation Utility             pkispawn(8)
2
3
4

NAME

6       pkispawn - Sets up a PKI subsystem.
7
8

SYNOPSIS

10       pkispawn -s subsystem -f config_file [-h] [-v]
11
12

DESCRIPTION

14       Sets  up  a  PKI  subsystem  (CA,  KRA,  OCSP, TKS, or TPS) in a Tomcat
15       instance.
16
17
18       Note: A 389 Directory Server instance must be  configured  and  running
19       before  this script can be run.  PKI server requires an internal direc‐
20       tory database.  The default configuration assumes  a  Directory  Server
21       instance running on the same machine on port 389.  For more information
22       on creating a Directory Server instance, see dscreate(8).
23
24
25       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
31
32       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
41
42       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
50
51       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
56
57       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
63
64       The pkispawn run creates several different installation files that  can
65       be referenced later, if need be:
66
67
68              · 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
72              · A   log   file   of   pkispawn   operations   is   written  to
73                /var/log/pki/pki-subsystem-spawn.timestamp.log.
74
75              · A .p12 (PKCS #12) file containing a certificate for a  subsys‐
76                tem  administrator  is stored in pki_client_dir defined in the
77                configuration file.
78
79
80
81       When the utility is done running, the CA can be accessed by pointing  a
82       browser  to  https://hostname:pki_https_port/.   The agent pages can be
83       accessed by importing the CA certificate and administrator  certificate
84       into the browser.
85
86
87       The PKI server instance can also be accessed using the pki command line
88       interface. See pki(1).  For more extensive documentation on how to  use
89       PKI  features,  see  the  Red  Hat  Certificate System Documentation at
90       https://access.redhat.com/knowledge/docs/Red_Hat_Certificate_System.
91
92
93       Instances created using pkispawn can be removed using pkidestroy.   See
94       pkidestroy(8).
95
96
97       pkispawn  supersedes  and  combines  the functionality of pkicreate and
98       pkisilent, which were available  in  earlier  releases  of  Certificate
99       Server.  It is now possible to completely create and configure the Cer‐
100       tificate Server subsystem in a single step using pkispawn.
101
102
103       Note: Previously, as an alternative to using  pkisilent  to  perform  a
104       non-interactive  batch  configuration, a PKI instance could be interac‐
105       tively configured by a GUI-based configuration  wizard  via  a  Firefox
106       browser.   GUI-based  configuration of a PKI instance is unavailable in
107       this version of the product.
108
109

OPTIONS

111       -s subsystem
112           Specifies the subsystem to be installed and configured, where  sub‐
113       system is CA, KRA, OCSP, TKS, or TPS.
114
115
116       -f config_file
117           Specifies the path to the user-defined configuration file.
118           This  file  contains  differences between the default configuration
119       and the custom configuration.
120
121
122       --precheck
123           Execute pre-checks and exit.
124
125
126       --skip-configuration
127           Run the first step of the installation (i.e. skipping the  instance
128       configuration step).
129
130
131       --skip-installation
132           Run the second step of the installation (i.e. skipping the instance
133       installation step).
134
135
136       -h, --help
137           Prints additional help information.
138
139
140       -v
141           Displays verbose information about the installation.
142           This flag can be provided multiple times to increase verbosity.
143           See pkispawn -h for details.
144
145

SEPARATE VERSUS SHARED INSTANCES

147   Separate PKI instances
148       As described above, this version of PKI continues to  support  separate
149       PKI instances for all subsystems.
150
151
152       Separate  PKI  instances  run  as  a  single  Java-based  Apache Tomcat
153       instance, contain a single PKI subsystem (CA, KRA, OCSP, TKS, or  TPS),
154       and must utilize unique ports if co-located on the same machine.
155
156
157   Shared PKI instances
158       Additionally, this version of PKI introduces the notion of a shared PKI
159       instance.
160
161
162       Shared PKI instances also run as  a  single  Java-based  Apache  Tomcat
163       instance,  but may contain any combination of up to one of each type of
164       PKI subsystem:
165
166
167              · CA
168
169              · TKS
170
171              · CA, KRA
172
173              · CA, OCSP
174
175              · TKS, TPS
176
177              · CA, KRA, TKS, TPS
178
179              · CA, KRA, OCSP, TKS, TPS
180
181              · etc.
182
183
184
185       Shared PKI instances allow all of  their  subsystems  contained  within
186       that instance to share the same ports, and must utilize unique ports if
187       more than one shared PKI instance is co-located on the same machine.
188
189
190       Semantically, a shared PKI instance that contains a single PKI  subsys‐
191       tem is identical to a separate PKI instance.
192
193

INTERACTIVE MODE

195       If  no options are specified, pkispawn will provide an interactive menu
196       to collect the parameters needed  to  install  the  Certificate  Server
197       instance.   Note that only the most basic installation options are pro‐
198       vided. This includes root CA, KRA, OCSP, TKS, and TPS connecting to  an
199       existing  directory server. More advanced setups such as cloned subsys‐
200       tems, subordinate or externally signed CA, subsystems that  connect  to
201       the  directory  server  using LDAPS, and subsystems that are customized
202       beyond the options described below require the use of  a  configuration
203       file with the -f option.
204
205
206       The  interactive option is most useful for those users getting familiar
207       with Certificate Server.  The parameters collected are written  to  the
208       installation  file of the subsystem, which can be found at /etc/syscon‐
209       fig/pki/tomcat/instance_name/subsystem/deployment.cfg.
210
211
212       The following parameters are queried interactively during the installa‐
213       tion process.
214
215
216   Subsystem Type
217       Subsystem (CA/KRA/OCSP/TKS/TPS):
218           The type of subsystem to be installed.
219           Prompted when the -s option is not specified.
220           The default value chosen is CA.
221
222
223   Instance Specific Parameters
224       Instance name:
225           The  name  of  the  tomcat instance in which the subsystem is to be
226       installed. The default value is pki-tomcat.
227
228
229       Note: Only one subsystem of a given type (CA, KRA, OCSP, TKS, TPS)  can
230       exist within a given instance.
231
232
233       HTTP port:
234           The HTTP port of the Tomcat instance. The default value is 8080.
235
236
237       Secure HTTP port:
238           The HTTPS port of the Tomcat instance. The default value is 8443.
239
240
241       AJP port:
242           The AJP port of the Tomcat instance. The default value is 8009.
243
244
245       Management port:
246           The  management  port  of the Tomcat instance. The default value is
247       8005.
248
249
250       Note: When  deploying  a  new  subsystem  into  an  existing  instance,
251       pkispawn  will  attempt  to  read  the  ports from deployment.cfg files
252       stored for previously installed subsystems for this instance.  If  suc‐
253       cessful, the installer will not prompt for these ports.
254
255
256   Administrative User Parameters
257       Username:
258           The  username  of  the administrator of this subsystem. The default
259       value is <ca/kra/ocsp/tks/tps>admin.
260
261
262       Password:
263           Password for the administrator user.
264
265
266       Import certificate:
267           An optional parameter that can be used to import an already  avail‐
268       able CA admin certificate into this instance.
269
270
271       Export certificate:
272           Setup  the  path  where  the  admin certificate of this <subsystem>
273       should be stored.
274           The       default       value       is       $HOME/.dogtag/pki-tom‐
275       cat/<ca/kra/ocsp/tks/tps>_admin.cert.
276
277
278   Directory Server Parameters
279       Hostname:
280           Hostname  of  the  directory server instance.  The default value is
281       the hostname of the system.
282
283
284       Use a secure LDAPS connection?
285           Answering yes to this question will cause prompts for Secure  LDAPS
286       Port: and Directory Server CA certificate pem file:.
287           Answering no to this question will cause a prompt for LDAP Port.
288           The initial default value for this question is no.
289
290
291       Secure LDAPS Port:
292           Secure  LDAPS  port  for the directory server instance. The default
293       value is 636.
294
295
296       Directory Server CA certificate PEM file:
297           The fully-qualified path including the filename of the  file  which
298       contains  an  exported  copy  of  the Directory Server's CA certificate
299       (e.g. $HOME/dscacert.pem).
300           This file must exist prior to pkispawn being able to utilize it.
301           For details on creation of this file see the EXAMPLES section below
302       entitled Installing PKI Subsystem with Secure LDAP Connection.
303
304
305       LDAP Port:
306           LDAP  port  for the directory server instance. The default value is
307       389.
308
309
310       Base DN:
311           The Base DN to be used for the internal database for  this  subsys‐
312       tem.
313           The default value is o=pki-tomcat-<subsystem>.
314
315
316       Bind DN:
317           The bind DN required to connect for the directory server.
318           This  user must have sufficient permissions to install the required
319       schema and database.
320           The default value is cn=Directory Manager.
321
322
323       Password:
324           Password for the bind DN.
325
326
327   Security Domain Parameters
328       Name:
329           The name of the security domain. Required only if installing a root
330       CA.
331           Default value: <DNS domain name> Security Domain.
332
333
334       Hostname:
335           The  hostname  for the security domain CA. Required only for non-CA
336       subsystems.
337           The default value is the hostname of this system.
338
339
340       Secure HTTP port:
341           The https port for the security domain. Required  only  for  non-CA
342       subsystems. The default value is 8443.
343
344
345       Username:
346           The username of the security domain administrator of the CA.
347           Required only for non-CA subsystems.
348           The default value is caadmin.
349
350
351       Password:
352           Password  for  the  security domain administrator. Required for all
353       subsystems that are not root CAs.
354
355

PRE-CHECK MODE

357       This option is only available when pkispawn is invoked in a  non-inter‐
358       active  mode.   When  the --precheck option is provided, a set of basic
359       tests are performed to ensure that the parameters provided to  pkispawn
360       are valid and consistent.
361
362
363       pkispawn  will  then  exit  with  an exit code of 0 on success, or 1 on
364       failure.  This mode can be used to perform basic tests prior  to  doing
365       any actual installation of the PKI server instance.
366
367
368       Flags are available to disable specific tests.  For instance, one might
369       want to disable validation of the credentials for the internal database
370       user if the directory server instance has not yet been created.
371
372
373       See pki_default.cfg(5) for more details about available flags.
374
375

TWO-STEP INSTALLATION MODE

377       pkispawn  provides  a  number  of  parameters  to customize an instance
378       before it is created.  Usually, most other customization  can  be  done
379       after  the server is created.  However, sometimes certain types of cus‐
380       tomization need to be done before the server is created, but there  are
381       no  parameters  for  that.  For  example,  configuring session timeout,
382       adding CSR extensions, customizing  certificate  profiles,  configuring
383       TLS  ciphers,  etc.  To support such customization, pkispawn provides a
384       two-step installation mode.
385
386
387       Generally, instance creation happens in one step (except for the exter‐
388       nal  CA  case).  Internally, the process happens in two stages.  In the
389       first stage, pkispawn will install the instance files (e.g. CS.cfg, NSS
390       database, profiles, etc.)  in the instance directory and customize them
391       based on pkispawn parameters.  In the second stage, pkispawn will start
392       the  instance and configure the instance based on the instance configu‐
393       ration files (e.g. initializing database, generating certificates, con‐
394       figuring connectors, etc.).  The two-step process allows the process to
395       be stopped after the first stage, allowing further customization to  be
396       done before running the second stage.
397
398
399       To use two-step installation mode, prepare a normal pkispawn configura‐
400       tion file, then run pkispawn with the  --skip-configuration  parameter.
401       For example:
402
403
404              $ pkispawn -s CA -f myconfig.txt --skip-configuration
405
406
407
408       Then customize the files in the instance directory as needed.  Finally,
409       finish  the  installation  by   running   pkispawn   again   with   the
410       --skip-installation parameter.  For example:
411
412
413              $ pkispawn -s CA -f myconfig.txt --skip-installation
414
415
416

EXAMPLES

418   Installing Root CA
419       To install a root CA in a new instance execute the following command:
420
421
422              $ pkispawn -s CA -f myconfig.txt
423
424
425
426       where myconfig.txt contains the following text:
427
428
429              [DEFAULT]
430              pki_admin_password=Secret.123
431              pki_client_pkcs12_password=Secret.123
432              pki_ds_password=Secret.123
433
434
435
436       Prior  to  running  this command, a Directory Server instance should be
437       created and running.  This command assumes that  the  Directory  Server
438       instance is using its default configuration:
439
440
441              · Installed on the local machine
442
443              · Listening on port 389
444
445              · The  user is cn=Directory Manager, with the password specified
446                in pki_ds_password
447
448
449
450       This invocation of pkispawn creates a Tomcat instance containing  a  CA
451       running  on  the  local machine with secure port 8443 and unsecure port
452       8080.  To access this CA,  simply  point  a  browser  to  https://host‐
453       name:8443.
454
455
456       The  instance name (defined by pki_instance_name) is pki-tomcat, and it
457       is located  at  /var/lib/pki/pki-tomcat.  Logs  for  the  instance  are
458       located  at /var/log/pki/pki-tomcat, and an installation log is written
459       to /var/log/pki/pki-subsystem-spawn.timestamp.log.
460
461
462       A PKCS #12 file containing the administrator certificate is created  in
463       $HOME/.dogtag/pki-tomcat.  This  PKCS #12 file uses the password desig‐
464       nated by pki_client_pkcs12_password in the configuration file.
465
466
467       To access the agent pages, first import the CA certificate by accessing
468       the  CA  End Entity Pages and clicking on the Retrieval Tab. Be sure to
469       trust the CA certificate. Then, import the administrator certificate in
470       the PKCS #12 file.
471
472
473   Installing Root CA using ECC
474       To  install a root CA in a new instance using ECC execute the following
475       command:
476
477
478              $ pkispawn -s CA -f myconfig.txt
479
480
481
482       where myconfig.txt contains the following text:
483
484
485              [DEFAULT]
486              pki_admin_password=Secret.123
487              pki_admin_key_algorithm=SHA256withEC
488              pki_admin_key_size=nistp256
489              pki_admin_key_type=ecc
490              pki_client_pkcs12_password=Secret.123
491              pki_ds_password=Secret.123
492              pki_sslserver_key_algorithm=SHA256withEC
493              pki_sslserver_key_size=nistp256
494              pki_sslserver_key_type=ecc
495              pki_subsystem_key_algorithm=SHA256withEC
496              pki_subsystem_key_size=nistp256
497              pki_subsystem_key_type=ecc
498
499              [CA]
500              pki_ca_signing_key_algorithm=SHA256withEC
501              pki_ca_signing_key_size=nistp256
502              pki_ca_signing_key_type=ecc
503              pki_ca_signing_signing_algorithm=SHA256withEC
504              pki_ocsp_signing_key_algorithm=SHA256withEC
505              pki_ocsp_signing_key_size=nistp256
506              pki_ocsp_signing_key_type=ecc
507              pki_ocsp_signing_signing_algorithm=SHA256withEC
508
509
510
511       In order to utilize ECC, the SSL Server and  Subsystem  key  algorithm,
512       key  size,  and  key  type  should  be  changed  from  SHA256withRSA to
513       SHA256withEC, 2048 to nistp256, and rsa to ecc, respectively.   To  use
514       an  ECC  admin key size and key type, the values should also be changed
515       from 2048 to nistp256, and rsa to ecc.
516
517
518       Additionally, for a CA subsystem, both the  CA  and  OCSP  Signing  key
519       algorithm,  key size, key type, and signing algorithm should be changed
520       from SHA256withRSA to SHA256withEC, 2048 to nistp256, rsa to  ecc,  and
521       SHA256withRSA to SHA256withEC, respectively.
522
523
524       Note: For all PKI subsystems including the CA, ECC is not supported for
525       the corresponding Audit Signing parameters.  Similarly, for KRA subsys‐
526       tems,  ECC  is not supported for either of the corresponding Storage or
527       Transport parameters.
528
529
530   Installing KRA, OCSP, TKS, or TPS in Shared Instance
531       For this example, assume that a new CA instance has been  installed  by
532       executing the following command:
533
534
535              $ pkispawn -s CA -f myconfig.txt
536
537
538
539       where myconfig.txt contains the following text:
540
541
542              [DEFAULT]
543              pki_admin_password=Secret.123
544              pki_client_pkcs12_password=Secret.123
545              pki_ds_password=Secret.123
546              # Optionally keep client databases
547              pki_client_database_purge=False
548
549
550
551       To install a shared KRA in the same instance used by the CA execute the
552       following command:
553
554
555              $ pkispawn -s KRA -f myconfig.txt
556
557
558
559       where myconfig.txt contains the following text:
560
561
562              [DEFAULT]
563              pki_admin_password=Secret.123
564              pki_client_database_password=Secret.123
565              pki_client_pkcs12_password=Secret.123
566              pki_ds_password=Secret.123
567              pki_security_domain_password=Secret.123
568
569
570
571       To install a shared OCSP in the same instance used by  the  CA  execute
572       the following command:
573
574
575              $ pkispawn -s OCSP -f myconfig.txt
576
577
578
579       where myconfig.txt contains the following text:
580
581
582              [DEFAULT]
583              pki_admin_password=Secret.123
584              pki_client_database_password=Secret.123
585              pki_client_pkcs12_password=Secret.123
586              pki_ds_password=Secret.123
587              pki_security_domain_password=Secret.123
588
589
590
591       To install a shared TKS in the same instance used by the CA execute the
592       following command:
593
594
595              $ pkispawn -s TKS -f myconfig.txt
596
597
598
599       where myconfig.txt contains the following text:
600
601
602              [DEFAULT]
603              pki_admin_password=Secret.123
604              pki_client_database_password=Secret.123
605              pki_client_pkcs12_password=Secret.123
606              pki_ds_password=Secret.123
607              pki_security_domain_password=Secret.123
608
609
610
611       To install a shared TPS in the same instance used by the CA execute the
612       following command:
613
614
615              $ pkispawn -s TPS -f myconfig.txt
616
617
618
619       where myconfig.txt contains the following text:
620
621
622              [DEFAULT]
623              pki_admin_password=Secret.123
624              pki_client_database_password=Secret.123
625              pki_client_pkcs12_password=Secret.123
626              pki_ds_password=Secret.123
627              pki_security_domain_password=Secret.123
628
629              [TPS]
630              # Shared TPS instances optionally utilize their shared KRA
631              # for server-side keygen
632              pki_enable_server_side_keygen=True
633              pki_authdb_basedn=dc=example,dc=com
634
635
636
637       Note:  For  this  particular example, the computed default values for a
638       PKI instance name including its ports, URLs, machine names, etc.   were
639       utilized  as  defined  in  /usr/share/pki/server/etc/default.cfg.  Each
640       subsystem in this example will reside under the /var/lib/pki/pki-tomcat
641       instance  housed within their own ca, kra, ocsp, tks, and tps subdirec‐
642       tories, utilizing the same default port values  of  8080  (http),  8443
643       (https),  8009  (ajp),  8005 (tomcat), using the same computed hostname
644       and URL information, and sharing a single common PKI Administrator Cer‐
645       tificate.
646
647
648       The  pki_security_domain_password  is  the  admin  password  of  the CA
649       installed in the same instance. This command should be run after  a  CA
650       is  installed. This installs another subsystem within the same instance
651       using the certificate generated for the CA administrator for  the  sub‐
652       system's administrator. This allows a user to access both subsystems on
653       the browser with a single administrator certificate. To access the  new
654       subsystem's  functionality,  simply  point the browser to https://host‐
655       name:8443 and click the relevant top-level links.
656
657
658       To install TPS in a shared instance the following section must be added
659       to myconfig.txt:
660
661
662              [TPS]
663              pki_authdb_basedn=dc=example,dc=com
664
665
666
667       TPS  requires an authentication database.  The pki_authdb_basedn speci‐
668       fies the base DN of the authentication database.
669
670
671       TPS also requires that a CA and a TKS subsystems are already  installed
672       in  the  same  instance.  Since they are in the same instance, a shared
673       secret key will automatically be generated in  TKS  and  imported  into
674       TPS.
675
676
677       Optionally,  server-side key generation can be enabled in TPS by adding
678       the following parameter in [TPS]:
679
680
681              pki_enable_server_side_keygen=True
682
683
684
685       Enabling server-side key generation requires that a  KRA  subsystem  is
686       already installed in the same instance.
687
688
689   Installing KRA, OCSP, TKS, or TPS in Separate Instance
690       For  this  example, assume that a new CA instance has been installed by
691       executing the following command:
692
693
694              $ pkispawn -s CA -f myconfig.txt
695
696
697
698       where myconfig.txt contains the following text:
699
700
701              [DEFAULT]
702              pki_admin_password=Secret.123
703              pki_client_pkcs12_password=Secret.123
704              pki_ds_password=Secret.123
705              # Optionally keep client databases
706              pki_client_database_purge=False
707              # Separated CA instance name and ports
708              pki_instance_name=pki-ca
709              pki_http_port=18080
710              pki_https_port=18443
711              # This Separated CA instance will be its own security domain
712              pki_security_domain_https_port=18443
713
714              [Tomcat]
715              # Separated CA Tomcat ports
716              pki_ajp_port=18009
717              pki_tomcat_server_port=18005
718
719
720
721       To install a separate KRA which connects to this remote CA execute  the
722       following command:
723
724
725              $ pkispawn -s KRA -f myconfig.txt
726
727
728
729       where myconfig.txt contains the following text:
730
731
732              [DEFAULT]
733              pki_admin_password=Secret.123
734              pki_client_database_password=Secret.123
735              pki_client_pkcs12_password=Secret.123
736              pki_ds_password=Secret.123
737              pki_security_domain_password=Secret.123
738              # Optionally keep client databases
739              pki_client_database_purge=False
740              # Separated KRA instance name and ports
741              pki_instance_name=pki-kra
742              pki_http_port=28080
743              pki_https_port=28443
744              # Separated KRA instance security domain references
745              pki_issuing_ca=https://pki.example.com:18443
746              pki_security_domain_hostname=pki.example.com
747              pki_security_domain_https_port=18443
748              pki_security_domain_user=caadmin
749
750              [Tomcat]
751              # Separated KRA Tomcat ports
752              pki_ajp_port=28009
753              pki_tomcat_server_port=28005
754
755              [KRA]
756              # A Separated KRA instance requires its own
757              # PKI Administrator Certificate
758              pki_import_admin_cert=False
759
760
761
762       To install a separate OCSP which connects to this remote CA execute the
763       following command:
764
765
766              $ pkispawn -s OCSP -f myconfig.txt
767
768
769
770       where myconfig.txt contains the following text:
771
772
773              [DEFAULT]
774              pki_admin_password=Secret.123
775              pki_client_database_password=Secret.123
776              pki_client_pkcs12_password=Secret.123
777              pki_ds_password=Secret.123
778              pki_security_domain_password=Secret.123
779              # Optionally keep client databases
780              pki_client_database_purge=False
781              # Separated OCSP instance name and ports
782              pki_instance_name=pki-ocsp
783              pki_http_port=29080
784              pki_https_port=29443
785              # Separated OCSP instance security domain references
786              pki_issuing_ca=https://pki.example.com:18443
787              pki_security_domain_hostname=pki.example.com
788              pki_security_domain_https_port=18443
789              pki_security_domain_user=caadmin
790
791              [Tomcat]
792              # Separated OCSP Tomcat ports
793              pki_ajp_port=29009
794              pki_tomcat_server_port=29005
795
796              [OCSP]
797              # A Separated OCSP instance requires its own
798              # PKI Administrator Certificate
799              pki_import_admin_cert=False
800
801
802
803       To install a separate TKS which connects to this remote CA execute  the
804       following command:
805
806
807              $ pkispawn -s TKS -f myconfig.txt
808
809
810
811       where myconfig.txt contains the following text:
812
813
814              [DEFAULT]
815              pki_admin_password=Secret.123
816              pki_client_database_password=Secret.123
817              pki_client_pkcs12_password=Secret.123
818              pki_ds_password=Secret.123
819              pki_security_domain_password=Secret.123
820              # Optionally keep client databases
821              pki_client_database_purge=False
822              # Separated TKS instance name and ports
823              pki_instance_name=pki-tks
824              pki_http_port=30080
825              pki_https_port=30443
826              # Separated TKS instance security domain references
827              pki_issuing_ca=https://pki.example.com:18443
828              pki_security_domain_hostname=pki.example.com
829              pki_security_domain_https_port=18443
830              pki_security_domain_user=caadmin
831
832              [Tomcat]
833              # Separated TKS Tomcat ports
834              pki_ajp_port=30009
835              pki_tomcat_server_port=30005
836
837              [TKS]
838              # A Separated TKS instance requires its own
839              # PKI Administrator Certificate
840              pki_import_admin_cert=False
841
842
843
844       To  install a separate TPS which connects to this remote CA execute the
845       following command:
846
847
848              $ pkispawn -s TPS -f myconfig.txt
849
850
851
852       where myconfig.txt contains the following text:
853
854
855              [DEFAULT]
856              pki_admin_password=Secret.123
857              pki_client_database_password=Secret.123
858              pki_client_pkcs12_password=Secret.123
859              pki_ds_password=Secret.123
860              pki_security_domain_password=Secret.123
861              # Optionally keep client databases
862              pki_client_database_purge=False
863              # Separated TPS instance name and ports
864              pki_instance_name=pki-tps
865              pki_http_port=31080
866              pki_https_port=31443
867              # Separated TPS instance security domain references
868              pki_issuing_ca=https://pki.example.com:18443
869              pki_security_domain_hostname=pki.example.com
870              pki_security_domain_https_port=18443
871              pki_security_domain_user=caadmin
872
873              [Tomcat]
874              # Separated TPS Tomcat ports
875              pki_ajp_port=31009
876              pki_tomcat_server_port=31005
877
878              [TPS]
879              # Separated TPS instances require specifying a remote CA
880              pki_ca_uri=https://pki.example.com:18443
881              # Separated TPS instances optionally utilize a remote KRA
882              # for server-side keygen
883              pki_kra_uri=https://pki.example.com:28443
884              pki_enable_server_side_keygen=True
885              pki_authdb_basedn=dc=example,dc=com
886              # Separated TPS instances require specifying a remote TKS
887              pki_tks_uri=https://pki.example.com:30443
888              pki_import_shared_secret=True
889              # A Separated TPS instance requires its own
890              # PKI Administrator Certificate
891              pki_import_admin_cert=False
892
893
894
895       Note: For this particular example,  besides  passwords,  sample  values
896       were  also utilized for PKI instance names, ports, URLs, machine names,
897       etc.  Under no circumstances should these demonstrative values be  con‐
898       strued to be required literal values.
899
900
901       A remote CA is one where the CA resides in another PKI server instance,
902       either on the local machine or a remote machine.  In this case,  mycon‐
903       fig.txt  must  specify the connection information for the remote CA and
904       the information about the security domain (the  trusted  collection  of
905       subsystems within an instance).
906
907
908       The  subsystem section is [KRA], [OCSP], [TKS], or [TPS].  This example
909       assumes that the specified CA hosts the security domain.  The  CA  must
910       be running and accessible.
911
912
913       A  new administrator certificate is generated for the new subsystem and
914       stored in a PKCS #12 file in $HOME/.dogtag/pki_instance_name.
915
916
917       As in a shared instance, to install TPS  in  a  separate  instance  the
918       authentication  database  must  be  specified in the [TPS] section, and
919       optionally the server-side key generation can be enabled.  If  the  CA,
920       KRA, or TKS subsystems required by TPS are running on a remote instance
921       the following parameters must be added into the [TPS] section to  spec‐
922       ify their locations:
923
924
925              pki_ca_uri=https://<ca_hostname>:<ca_https_port>
926              pki_kra_uri=https://<kra_hostname>:<kra_https_port>
927              pki_tks_uri=https://<tks_hostname>:<tks_https_port>
928
929
930
931       If  TPS  and  TKS are installed on separate instances the shared secret
932       key should be imported over the wire between the TKS and TPS  automati‐
933       cally.
934
935
936       If  the automated procedure fails for any unlikely reason the following
937       manual procedure will serve as a fallback. The key needs to be  created
938       on the TKS side and imported into the TPS side in this case.
939
940
941       Generate  the  shared  secret key (if needed) in TKS with the following
942       command:
943
944
945              $ tkstool -T -d /var/lib/pki/pki-tomcat/alias -n sharedSecret
946
947
948
949       Verify the shared secret key in TKS with the following command:
950
951
952              $ tkstool -L -d /var/lib/pki/pki-tomcat/alias
953
954
955
956       Once TPS is installed, shutdown TPS instance, then  import  the  shared
957       secret key into TPS with the following command:
958
959
960              $ tkstool -I -d /var/lib/pki/pki-tomcat/alias -n sharedSecret
961
962
963
964       Verify the shared secret key in TPS with the following command:
965
966
967              $ tkstool -L -d /var/lib/pki/pki-tomcat/alias
968
969
970
971       The  shared secret key nickname should be stored in the following prop‐
972       erty in the TPS's CS.cfg:
973
974
975              conn.tks1.tksSharedSymKeyName=sharedSecret
976
977
978
979       Finally, restart the TPS instance.
980
981
982   Installing CA, KRA, OCSP, TKS, or TPS using HSM
983       This section provides sample myconfig.txt files when a  Hardware  Secu‐
984       rity Module (HSM) is being utilized in a shared PKI instance.
985
986
987       For  this  example, assume that a new CA instance has been installed by
988       executing the following command:
989
990
991              $ pkispawn -s CA -f myconfig.txt
992
993
994
995       where myconfig.txt contains the following text:
996
997
998              [DEFAULT]
999              pki_admin_password=Secret.123
1000              pki_client_pkcs12_password=Secret.123
1001              pki_ds_password=Secret.123
1002              # Optionally keep client databases
1003              pki_client_database_purge=False
1004              # Provide HSM parameters
1005              pki_hsm_enable=True
1006              pki_hsm_libfile=<hsm_libfile>
1007              pki_hsm_modulename=<hsm_modulename>
1008              pki_token_name=<hsm_token_name>
1009              pki_token_password=<pki_token_password>
1010              # Provide PKI-specific HSM token names
1011              pki_audit_signing_token=<hsm_token_name>
1012              pki_sslserver_token=<hsm_token_name>
1013              pki_subsystem_token=<hsm_token_name>
1014
1015              [CA]
1016              # Provide CA-specific HSM token names
1017              pki_ca_signing_token=<hsm_token_name>
1018              pki_ocsp_signing_token=<hsm_token_name>
1019
1020
1021
1022       To install a shared KRA in the same instance used by the CA execute the
1023       following command:
1024
1025
1026              $ pkispawn -s KRA -f myconfig.txt
1027
1028
1029
1030       where myconfig.txt contains the following text:
1031
1032
1033              [DEFAULT]
1034              pki_admin_password=Secret.123
1035              pki_client_database_password=Secret.123
1036              pki_client_pkcs12_password=Secret.123
1037              pki_ds_password=Secret.123
1038              pki_security_domain_password=Secret.123
1039              # Provide HSM parameters
1040              pki_hsm_enable=True
1041              pki_hsm_libfile=<hsm_libfile>
1042              pki_hsm_modulename=<hsm_modulename>
1043              pki_token_name=<hsm_token_name>
1044              pki_token_password=<pki_token_password>
1045              # Provide PKI-specific HSM token names
1046              pki_audit_signing_token=<hsm_token_name>
1047              pki_sslserver_token=<hsm_token_name>
1048              pki_subsystem_token=<hsm_token_name>
1049
1050              [KRA]
1051              # Provide KRA-specific HSM token names
1052              pki_storage_token=<hsm_token_name>
1053              pki_transport_token=<hsm_token_name>
1054
1055
1056
1057       To  install  a  shared OCSP in the same instance used by the CA execute
1058       the following command:
1059
1060
1061              $ pkispawn -s OCSP -f myconfig.txt
1062
1063
1064
1065       where myconfig.txt contains the following text:
1066
1067
1068              [DEFAULT]
1069              pki_admin_password=Secret.123
1070              pki_client_database_password=Secret.123
1071              pki_client_pkcs12_password=Secret.123
1072              pki_ds_password=Secret.123
1073              pki_security_domain_password=Secret.123
1074              # Provide HSM parameters
1075              pki_hsm_enable=True
1076              pki_hsm_libfile=<hsm_libfile>
1077              pki_hsm_modulename=<hsm_modulename>
1078              pki_token_name=<hsm_token_name>
1079              pki_token_password=<pki_token_password>
1080              # Provide PKI-specific HSM token names
1081              pki_audit_signing_token=<hsm_token_name>
1082              pki_sslserver_token=<hsm_token_name>
1083              pki_subsystem_token=<hsm_token_name>
1084
1085              [OCSP]
1086              # Provide OCSP-specific HSM token names
1087              pki_ocsp_signing_token=<hsm_token_name>
1088
1089
1090
1091       To install a shared TKS in the same instance used by the CA execute the
1092       following command:
1093
1094
1095              $ pkispawn -s TKS -f myconfig.txt
1096
1097
1098
1099       where myconfig.txt contains the following text:
1100
1101
1102              [DEFAULT]
1103              pki_admin_password=Secret.123
1104              pki_client_database_password=Secret.123
1105              pki_client_pkcs12_password=Secret.123
1106              pki_ds_password=Secret.123
1107              pki_security_domain_password=Secret.123
1108              # Provide HSM parameters
1109              pki_hsm_enable=True
1110              pki_hsm_libfile=<hsm_libfile>
1111              pki_hsm_modulename=<hsm_modulename>
1112              pki_token_name=<hsm_token_name>
1113              pki_token_password=<pki_token_password>
1114              # Provide PKI-specific HSM token names
1115              pki_audit_signing_token=<hsm_token_name>
1116              pki_sslserver_token=<hsm_token_name>
1117              pki_subsystem_token=<hsm_token_name>
1118
1119
1120
1121       To install a shared TPS in the same instance used by the CA execute the
1122       following command:
1123
1124
1125              $ pkispawn -s TPS -f myconfig.txt
1126
1127
1128
1129       where myconfig.txt contains the following text:
1130
1131
1132              [DEFAULT]
1133              pki_admin_password=Secret.123
1134              pki_client_database_password=Secret.123
1135              pki_client_pkcs12_password=Secret.123
1136              pki_ds_password=Secret.123
1137              pki_security_domain_password=Secret.123
1138              # Provide HSM parameters
1139              pki_hsm_enable=True
1140              pki_hsm_libfile=<hsm_libfile>
1141              pki_hsm_modulename=<hsm_modulename>
1142              pki_token_name=<hsm_token_name>
1143              pki_token_password=<pki_token_password>
1144              # Provide PKI-specific HSM token names
1145              pki_audit_signing_token=<hsm_token_name>
1146              pki_sslserver_token=<hsm_token_name>
1147              pki_subsystem_token=<hsm_token_name>
1148
1149              [TPS]
1150              # Shared TPS instances optionally utilize their shared KRA
1151              # for server-side keygen
1152              pki_enable_server_side_keygen=True
1153              pki_authdb_basedn=dc=example,dc=com
1154
1155
1156
1157       Important: Since HSM keys are stored in the HSM, they cannot be  backed
1158       up,   moved,   or   copied  to  a  PKCS  #12  file.   For  example,  if
1159       pki_hsm_enable is set to True, pki_backup_keys should be set  to  False
1160       and  pki_backup_password  should  be  left unset (the default values in
1161       /usr/share/pki/server/etc/default.cfg).  Similarly,  for  the  case  of
1162       clones  using  an  HSM,  this  means  that  the HSM keys must be shared
1163       between the master and its clones.  Therefore, if pki_hsm_enable is set
1164       to   True,  both  pki_clone_pkcs12_path  and  pki_clone_pkcs12_password
1165       should     be     left     unset     (the     default     values     in
1166       /usr/share/pki/server/etc/default.cfg).   Failure  to comply with these
1167       rules will result in pkispawn reporting an appropriate error and  exit‐
1168       ing.
1169
1170
1171   Installing CA Clone
1172       To install a CA clone execute the following command:
1173
1174
1175              $ pkispawn -s CA -f myconfig.txt
1176
1177
1178
1179       where myconfig.txt contains the following text:
1180
1181
1182              [DEFAULT]
1183              pki_admin_password=Secret.123
1184              pki_client_database_password=Secret.123
1185              pki_client_pkcs12_password=Secret.123
1186              pki_ds_password=Secret.123
1187              pki_security_domain_password=Secret.123
1188              pki_security_domain_hostname=<master_ca_hostname>
1189              pki_security_domain_https_port=<master_ca_https_port>
1190              pki_security_domain_user=caadmin
1191              pki_security_domain_post_login_sleep_seconds=5
1192
1193              [Tomcat]
1194              pki_clone=True
1195              pki_clone_pkcs12_password=Secret.123
1196              pki_clone_pkcs12_path=<path_to_pkcs12_file>
1197              pki_clone_replicate_schema=True
1198              pki_clone_uri=https://<master_ca_hostname>:<master_ca_https_port>
1199
1200
1201
1202       A  cloned  CA  is  a  CA which uses the same signing, OCSP signing, and
1203       audit signing certificates as the master CA,  but  issues  certificates
1204       within  a different serial number range.  It has its own internal data‐
1205       base -- separate from the master CA database -- but using the same base
1206       DN,  that  keeps  in sync with the master CA through replication agree‐
1207       ments between the databases.  This is very useful for load sharing  and
1208       disaster  recovery.  To create a clone, the myconfig.txt uses pkiclone*
1209       parameters in its [Tomcat] section which identify the  original  CA  to
1210       use  as  a master template.  Additionally, it connects to the master CA
1211       as a remote CA and uses its security domain.
1212
1213
1214       Before the clone can be generated, the Directory Server must be created
1215       that  is  separate  from the master CA's Directory Server.  The example
1216       assumes that the master CA and cloned CA are on different machines, and
1217       that their Directory Servers are on port 389.
1218
1219
1220       In  addition,  since this example does not utilize an HSM, the master's
1221       system certs and keys have been stored in  a  PKCS  #12  file  that  is
1222       copied  over  to  the  clone  subsystem  in  the  location specified in
1223       <path_to_pkcs12_file>.  This file needs to be readable by the user  the
1224       Certificate  Server  runs  as  (by  default,  pkiuser) and be given the
1225       SELinux context pki_tomcat_cert_t.
1226
1227
1228       The master's system certificates can be exported to a PKCS#12 file when
1229       the master is installed if the parameter pki_backup_keys is set to True
1230       and the pki_backup_password is set.  The PKCS#12  file  is  then  found
1231       under  /var/lib/pki/<instance_name>/alias.   Alternatively, the PKCS#12
1232       file can be generated at any time post-installation using PKCS12Export.
1233
1234
1235       The pki_security_domain_post_login_sleep_seconds config specifies sleep
1236       duration  after  logging  into a security domain, to allow the security
1237       domain session data to be replicated to subsystems on other hosts.   It
1238       is optional and defaults to 5 seconds.
1239
1240
1241       An example invocation showing the export of the system certificates and
1242       keys, copying the keys to the replica subsystem, and setting the  rele‐
1243       vant  SELinux  and  file  permissions is shown below.  pwfile is a text
1244       file  containing  the  password  for  the  masters  NSS  DB  (found  in
1245       /etc/pki/instance_name/password.conf).   pkcs12_password_file is a text
1246       file containing the password selected for the generated PKCS12 file.
1247
1248
1249              master# PKCS12Export -d /etc/pki/pki-tomcat/alias -p pwfile \
1250                      -w pkcs12_password_file -o backup_keys.p12
1251              master# scp backup_keys.p12 clone:/backup_keys.p12
1252
1253              clone# chown pkiuser: /backup_keys.p12
1254              clone# semanage -a -t pki_tomcat_cert_t /backup_keys.p12
1255
1256
1257
1258       Note: From Dogtag 10.3, a slightly different mechanism  has  been  pro‐
1259       vided to create and specify the required PKCS#12 file to the clone sub‐
1260       system.  This new method is provided in addition to the  method  above,
1261       but will become the preferred method in future releases.
1262
1263
1264       This method can be used if both master and clone are 10.3 or above.
1265
1266
1267       To export the required keys from the master, use the pki-server command
1268       line tool.
1269
1270
1271              master# pki-server ca-clone-prepare -i pki-tomcat \
1272                      --pkcs12-file backup_keys.p12 \
1273                      --pkcs12-password Secret123
1274
1275              master# scp backup_keys.p12 clone:/backup_keys.p12
1276              master# scp /etc/pki/pki-tomcat/external_certs.conf \
1277                       clone:/external_certs.conf
1278
1279
1280
1281       The external_certs.conf file contains  information  about  third  party
1282       certificates that were added to the master's certificate database using
1283       the pki-server command.  The certificates themselves are stored in  the
1284       backup_keys.p12 file. If there are no third-party certifcates that have
1285       been added, then the external_certs.conf file may not exist and  should
1286       be ignored.
1287
1288
1289       The  two  files (backup_keys.p12 and external_certs.conf) are specified
1290       to pkispawn as below.
1291
1292
1293              [DEFAULT]
1294              pki_admin_password=Secret.123
1295              pki_client_database_password=Secret.123
1296              pki_client_pkcs12_password=Secret.123
1297              pki_ds_password=Secret.123
1298              pki_security_domain_password=Secret.123
1299              pki_security_domain_hostname=<master_ca_hostname>
1300              pki_security_domain_https_port=<master_ca_https_port>
1301              pki_security_domain_user=caadmin
1302
1303              [Tomcat]
1304              pki_server_pkcs12_path=<path to pkcs12 file>
1305              pki_server_pkcs12_password=Secret.123
1306              pki_server_external_certs_path=<path to external_certs.conf file>
1307              pki_clone=True
1308              pki_clone_replicate_schema=True
1309              pki_clone_uri=https://<master_ca_hostname>:<master_ca_https_port>
1310
1311
1312
1313       Note that the previous p12 parameters (pki_clonepkcs12*) are no  longer
1314       needed, and will be ignored.
1315
1316
1317       Note: One current cloning anomaly to mention is the following scenario:
1318
1319
1320                1. Create a clone of a CA or of any other subsystem.
1321
1322                2. Remove that just created clone.
1323
1324                3. Immediately attempt the exact same clone again, in place of
1325                   the recently destroyed instance.   Before  recreating  this
1326                   clone,   make  sure  the pki_ds_remove_data=True is used in
1327                   the clone's deployment config file.  This will  remove  the
1328                   old data from the previous clone.
1329
1330
1331
1332       Here  the  Director  Server  instance  may have worked itself in into a
1333       state where it no longer accepts connections, aborting the  clone  con‐
1334       figuration quickly.
1335
1336
1337       The  fix  to  this  is  to simply restart the Directory Server instance
1338       before creating the clone for the second time.   After  restarting  the
1339       Directory  Server  it  should be possible to create the mentioned clone
1340       instance.
1341
1342
1343   Installing KRA or TKS Clone
1344       To install a KRA or TKS (OCSP and TPS unsupported as  of  now)  execute
1345       the following command:
1346
1347
1348              $ pkispawn -s <subsystem> -f myconfig.txt
1349
1350
1351
1352       where  subsystem  is KRA or TKS and myconfig.txt contains the following
1353       text:
1354
1355
1356              [DEFAULT]
1357              pki_admin_password=Secret.123
1358              pki_client_database_password=Secret.123
1359              pki_client_pkcs12_password=Secret.123
1360              pki_ds_password=Secret.123
1361              pki_security_domain_password=Secret.123
1362              pki_security_domain_hostname=<master_ca_hostname>
1363              pki_security_domain_https_port=<master_ca_https_port>
1364              pki_security_domain_user=caadmin
1365
1366              [Tomcat]
1367              pki_clone=True
1368              pki_clone_pkcs12_password=Secret.123
1369              pki_clone_pkcs12_path=<path_to_pkcs12_file>
1370              pki_clone_replicate_schema=True
1371              pki_clone_uri=https://<master_subsystem_host>:<master_subsystem_https_port>
1372              pki_issuing_ca=https://<ca_hostname>:<ca_https_port>
1373
1374
1375
1376       As with a CA clone, a KRA or TKS clone uses the same  certificates  and
1377       basic  configuration  as  the  original  subsystem.   The configuration
1378       points to the original subsystem to copy its configuration.  This exam‐
1379       ple  also  assumes that the CA is on a remote machine and specifies the
1380       CA and security domain information.
1381
1382
1383       The parameter pki_clone_uri should be modified to point to the required
1384       master (KRA or TKS).
1385
1386
1387       As  of 10.3, a slightly different mechanism has been introduced to gen‐
1388       erate and specify the PKCS#12 file and  any  third-party  certificates.
1389       See the Installing CA Clone section for details.
1390
1391
1392   Installing CA Clone on the Same Host
1393       For  testing purposes, it is useful to configure cloned CAs which exist
1394       (with their internal databases) on the same host as the master  CA.  To
1395       configure the cloned CA execute the following command:
1396
1397
1398              $ pkispawn -s CA -f myconfig.txt
1399
1400
1401
1402       where myconfig.txt contains the following text:
1403
1404
1405              [DEFAULT]
1406              pki_admin_password=Secret123
1407              pki_client_database_password=Secret123
1408              pki_client_pkcs12_password=Secret123
1409              pki_ds_password=Secret123
1410              pki_ds_ldap_port=<unique port different from master>
1411              pki_ds_ldaps_port=<unique port different from master>
1412              pki_http_port=<unique port different from master>
1413              pki_https_port=<unique port different from master>
1414              pki_instance_name=<unique name different from master>
1415              pki_security_domain_hostname=<master_ca_hostname>
1416              pki_security_domain_https_port=<master_ca_https_port>
1417              pki_security_domain_password=Secret123
1418
1419              [Tomcat]
1420              pki_ajp_port=<unique port different from master>
1421              pki_clone=True
1422              pki_clone_pkcs12_password=Secret123
1423              pki_clone_pkcs12_path=<path_to_pkcs12_file>
1424              pki_clone_uri=https://<master_ca_hostname>:<master_ca_https_port>
1425              pki_tomcat_server_port=<unique port different from master>
1426
1427              [CA]
1428              pki_ds_base_dn=<identical value as master>
1429              pki_ds_database=<identical value as master>
1430
1431
1432
1433       In  this  case,  because both CA Tomcat instances are on the same host,
1434       they must have distinct ports.  Similarly, each CA must use a  distinct
1435       directory  server  instance for its internal database.  Like the Tomcat
1436       instances, these are distinguished by distinct ports.  The suffix being
1437       replicated (pki_ds_base), however, must be the same for both master and
1438       clone.
1439
1440
1441   Installing Subordinate CA in Existing Security Domain
1442       To install a subordinate CA in an existing security domain execute  the
1443       following command:
1444
1445
1446              $ pkispawn -s CA -f myconfig.txt
1447
1448
1449
1450       where myconfig.txt contains the following text:
1451
1452
1453              [DEFAULT]
1454              pki_admin_password=Secret.123
1455              pki_client_database_password=Secret.123
1456              pki_client_pkcs12_password=Secret.123
1457              pki_ds_password=Secret.123
1458              pki_security_domain_password=Secret.123
1459              pki_security_domain_hostname=<security_domain_ca_hostname>
1460              pki_security_domain_https_port=<security_domain_ca_https_port>
1461              pki_security_domain_user=caadmin
1462
1463              [CA]
1464              pki_subordinate=True
1465              pki_issuing_ca=https://<master_ca_hostname>:<master_ca_https_port>
1466              pki_ca_signing_subject_dn=cn=CA Subordinate Signing,o=example.com
1467
1468
1469
1470       A  sub-CA  derives  its  certificate  configuration  -- such as allowed
1471       extensions and validity periods -- from a superior or root CA.   Other‐
1472       wise,  the configuration of the CA is independent of the root CA, so it
1473       is its own instance rather than a clone.  A sub-CA is configured  using
1474       the  pki_subordinate parameter and a pointer to the CA which issues the
1475       sub-CA's certificates.
1476
1477
1478       Note: The value of pki_ca_signing_subject_dn of a subordinate CA should
1479       be different from the root CA's signing subject DN.
1480
1481
1482   Installing Subordinate CA in New Security Domain
1483       To  install  a subordinate CA in a new security domain execute the fol‐
1484       lowing command:
1485
1486
1487              $ pkispawn -s CA -f myconfig.txt
1488
1489
1490
1491       where myconfig.txt contains the following text:
1492
1493
1494              [DEFAULT]
1495              pki_admin_password=Secret.123
1496              pki_client_database_password=Secret.123
1497              pki_client_pkcs12_password=Secret.123
1498              pki_ds_password=Secret.123
1499              pki_security_domain_password=Secret.123
1500              pki_security_domain_hostname=<master CA security domain hostname>
1501              pki_security_domain_https_port=<master CA security domain https port>
1502              pki_security_domain_user=caadmin
1503
1504              [CA]
1505              pki_subordinate=True
1506              pki_issuing_ca=https://<master_ca_hostname>:<master_ca_https_port>
1507              pki_ca_signing_subject_dn=cn=CA Subordinate Signing,o=example.com
1508              pki_subordinate_create_new_security_domain=True
1509              pki_subordinate_security_domain_name=Subordinate CA Security Domain
1510
1511
1512
1513       In this section, the subordinate CA logs onto and  registers  with  the
1514       security  domain  CA  (using  parameters  pki_security_domain_hostname,
1515       pki_security_domain_user and pki_security_domain_password)  as  in  the
1516       previous section, but also creates and hosts a new security domain.  To
1517       do this,  pki_subordinate_create_new_security_domain  must  be  set  to
1518       True.  The subordinate CA security domain name can also be specified by
1519       specifying a value for pki_subordinate_security_domain_name.
1520
1521
1522       Note: The value of pki_ca_signing_subject_dn of a subordinate CA should
1523       be different from the root CA's signing subject DN.
1524
1525
1526   Installing Externally-Signed CA
1527       To install an externally signed CA execute the following command:
1528
1529
1530              $ pkispawn -s CA -f myconfig.txt
1531
1532
1533
1534       This is a two-step process.
1535
1536
1537       In the first step, a certificate signing request (CSR) is generated for
1538       the signing certificate and myconfig.txt contains the following text:
1539
1540
1541              [DEFAULT]
1542              pki_admin_password=Secret.123
1543              pki_client_database_password=Secret.123
1544              pki_client_pkcs12_password=Secret.123
1545              pki_ds_password=Secret.123
1546              pki_security_domain_password=Secret.123
1547
1548              [CA]
1549              pki_external=True
1550              pki_ca_signing_csr_path=/tmp/ca_signing.csr
1551              pki_ca_signing_subject_dn=cn=CA Signing,ou=External,o=example.com
1552
1553
1554
1555       The CSR is written to pki_ca_signing_csr_path.  The pki_ca_signing_sub‐
1556       ject_dn should be different from the subject DN of the external CA that
1557       is signing the request.  The pki_ca_signing_subject_dn parameter can be
1558       used to specify the signing certificate's subject DN.
1559
1560
1561       The  CSR  is  then submitted to the external CA, and the resulting cer‐
1562       tificate and certificate chain are saved to files on the system.
1563
1564
1565       In the second step, the configuration file has been modified to install
1566       the  issued certificates.  In place of the original CSR, the configura‐
1567       tion file now points to  the  issued  CA  certificate  and  certificate
1568       chain.   There  is  also  a  flag  to  indicate that this completes the
1569       installation process (pki_external_step_two).
1570
1571
1572              [DEFAULT]
1573              pki_admin_password=Secret.123
1574              pki_client_database_password=Secret.123
1575              pki_client_pkcs12_password=Secret.123
1576              pki_ds_password=Secret.123
1577              pki_security_domain_password=Secret.123
1578
1579              [CA]
1580              pki_external=True
1581              pki_external_step_two=True
1582              pki_cert_chain_path=/tmp/ca_cert_chain.cert
1583              pki_ca_signing_cert_path=/tmp/ca_signing.cert
1584              pki_ca_signing_subject_dn=cn=CA Signing Certificate,ou=External,o=example.com
1585
1586
1587
1588       Then, the pkispawn command is run again:
1589
1590
1591              $ pkispawn -s CA -f myconfig.txt
1592
1593
1594
1595   Installing PKI Subsystem with Secure LDAP Connection
1596       There are three scenarios in which a PKI subsystem (e.g. a CA) needs to
1597       communicate securely via LDAPS with a directory server:
1598
1599
1600       Scenario  1:  A  directory server exists which is already running LDAPS
1601       using a CA certificate that has been issued by some other CA.  For this
1602       scenario,  the  CA  certificate  must  be made available via a PEM file
1603       (e.g. $HOME/dscacert.pem) prior to running pkispawn such that  the  new
1604       CA  may  be installed and configured to communicate with this directory
1605       server using LDAPS.
1606
1607
1608       Scenario 2: A directory server exists which is currently running  LDAP.
1609       Once a CA has been created, there is a desire to use its CA certificate
1610       to issue an SSL certificate for this directory server so that  this  CA
1611       and  this  directory  server  can communicate via LDAPS.  For this sce‐
1612       nario, since there is  no  need  to  communicate  securely  during  the
1613       pkispawn installation/configuration, simply use pkispawn to install and
1614       configure the CA using the LDAP port of the directory server, issue  an
1615       SSL  certificate from this CA for the directory server, and then recon‐
1616       figure the CA and directory server to communicate with each  other  via
1617       LDAPS.
1618
1619
1620       Scenario 3: Similar to the previous scenario, a directory server exists
1621       which is currently running LDAP, and the desire is to create a  CA  and
1622       use  it  to  establish  LDAPS  communications  between this CA and this
1623       directory server.  However, for this scenario, there is a need for  the
1624       CA  and  the  directory  server to communicate securely during pkispawn
1625       installation and configuration.  For this  to  succeed,  the  directory
1626       server  must  generate  a  temporary self-signed certificate which then
1627       must be made available via a PEM file (e.g.  $HOME/dscacert.pem)  prior
1628       to  running pkispawn.  Once the CA has been created, swap things out to
1629       reconfigure the CA and directory server to utilize  LDAPS  through  the
1630       desired certificates.
1631
1632
1633       Set  up  a  Directory Server instance with a self-signed CA certificate
1634       (see dscreate(8)), then export the certificate into a PEM file
1635
1636
1637       Once the self-signed CA certificate  is  obtained,  add  the  following
1638       parameters into the [DEFAULT] section in myconfig.txt:
1639
1640
1641              pki_ds_secure_connection=True
1642              pki_ds_secure_connection_ca_pem_file=$HOME/dscacert.pem
1643
1644
1645
1646       Then execute pkispawn to create the CA subsystem.
1647
1648
1649   Managing PKI instance
1650       To start a PKI instance named <pki_instance_name>:
1651
1652
1653              $ systemctl start pki-tomcatd@<pki_instance_name>.service
1654
1655
1656
1657       To stop a PKI instance named <pki_instance_name>:
1658
1659
1660              $ systemctl stop pki-tomcatd@<pki_instance_name>.service
1661
1662
1663
1664       To restart a PKI instance named <pki_instance_name>:
1665
1666
1667              $ systemctl restart pki-tomcatd@<pki_instance_name>.service
1668
1669
1670
1671       To obtain the status of a PKI instance named <pki_instance_name>:
1672
1673
1674              $ systemctl status pki-tomcatd@<pki_instance_name>.service
1675
1676
1677
1678       To   obtain   a   detailed  status  of  a  Tomcat  PKI  instance  named
1679       <pki_instance_name>:
1680
1681
1682              $ pki-server status <pki_instance_name>
1683
1684
1685
1686       To list all available PKI instances installed on a system:
1687
1688
1689              $ pki-server instance-find
1690
1691
1692

SEE ALSO

1694       pkidestroy(8)
1695       pki_default.cfg(5)
1696       pki(1)
1697       dscreate(8)
1698
1699

AUTHORS

1701       Ade Lee <alee@redhat.com> and Dinesh Prasanth M K <dmoluguw@redhat.com>
1702
1703
1705       Copyright (c) 2020 Red Hat, Inc.  This is licensed under the  GNU  Gen‐
1706       eral  Public  License,  version  2  (GPLv2).  A copy of this license is
1707       available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.
1708
1709
1710
1711PKI                           September 30, 2020                   pkispawn(8)
Impressum