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 setup-ds.pl(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.
77
78
79
80       When  the utility is done running, the CA can be accessed by pointing a
81       browser to https://hostname:pki_https_port/.  The agent  pages  can  be
82       accessed  by importing the CA certificate and administrator certificate
83       into the browser.
84
85
86       The PKI server instance can also be accessed using the pki command line
87       interface.  See pki(1).  For more extensive documentation on how to use
88       PKI features, see the  Red  Hat  Certificate  System  Documentation  at
89https://access.redhat.com/knowledge/docs/Red_Hat_Certificate_System⟩.
90
91
92       Instances  created using pkispawn can be removed using pkidestroy.  See
93       pkidestroy(8).
94
95
96       pkispawn supersedes and combines the  functionality  of  pkicreate  and
97       pkisilent,  which  were  available  in  earlier releases of Certificate
98       Server.  It is now possible to completely create and configure the Cer‐
99       tificate Server subsystem in a single step using pkispawn.
100
101
102       Note:  Previously,  as  an  alternative to using pkisilent to perform a
103       non-interactive batch configuration, a PKI instance could  be  interac‐
104       tively  configured  by  a  GUI-based configuration wizard via a Firefox
105       browser.  GUI-based configuration of a PKI instance is  unavailable  in
106       this version of the product.
107
108

OPTIONS

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

SEPARATE VERSUS SHARED INSTANCES

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

INTERACTIVE MODE

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

PRE-CHECK MODE

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

TWO-STEP INSTALLATION MODE

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

EXAMPLES

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

SEE ALSO

1765       pkidestroy(8)
1766       pki_default.cfg(5)
1767       pki(1)
1768       setup-ds.pl(8)
1769
1770

AUTHORS

1772       Ade Lee ⟨alee@redhat.com⟩.
1773
1774
1776       Copyright (c) 2012 Red Hat, Inc.  This is licensed under the  GNU  Gen‐
1777       eral  Public  License,  version  2  (GPLv2).  A copy of this license is
1778       available at ⟨http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt⟩.
1779
1780
1781
1782PKI                            December 13, 2012                   pkispawn(8)
Impressum