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

NAME

6       pkispawn - Sets up an instance of Certificate Server.
7
8

SYNOPSIS

10       pkispawn -s <subsystem> -f <config_file> [options] [-p <prefix>]
11
12

DESCRIPTION

14       Sets  up a Certificate Server subsystem (CA, KRA, OCSP, TKS, or TPS) in
15       a Tomcat instance.
16
17       Note:  A 389 Directory Server instance must be configured  and  running
18              before  this  script  can be run. Certificate Server requires an
19              internal directory database. The default configuration assumes a
20              Directory  Server  instance  running on the same machine on port
21              389.  For  more  information  on  creating  a  Directory  Server
22              instance, see setup-ds.pl(8).
23
24       An instance can contain multiple subsystems, although it may contain at
25       most one of each type of subsystem on a single machine.  So, for  exam‐
26       ple,  an  instance could contain CA and KRA subsystems,  but not two CA
27       subsystems.  To create an instance with a CA  and  a  KRA,  simply  run
28       pkispawn twice, with values -s CA and -s KRA respectively.
29
30       The  instances are created based on values for configuration parameters
31       in the default configuration (/etc/pki/default.cfg) and  the  user-pro‐
32       vided configuration file.  The user-provided configuration file is read
33       after the default configuration file, so any parameters defined in that
34       file  will  override  parameters in the default configuration file.  In
35       general, most users will store only those parameters which are  differ‐
36       ent from the default configuration in their user-provided configuration
37       file.
38
39       This configuration file contains parameters that are grouped into  sec‐
40       tions.   These sections are stacked, so that parameters defined in ear‐
41       lier sections can be overwritten by parameters defined  in  later  sec‐
42       tions.  The  sections are read in the following order: [DEFAULT], [Tom‐
43       cat], and the subsystem section ([CA], [KRA], [OCSP], [TKS], or [TPS]).
44       This  allows the ability to specify parameters to be shared by all sub‐
45       systems in [DEFAULT] or [Tomcat], and system-specific customization.
46
47
48       Note:  Any non-password related parameter values in  the  configuration
49              file  that  needs  to  contain  a  %  character must be properly
50              escaped.  For example, a value of foo%bar would be specified  as
51              foo%%bar in the configuration file.
52
53       At  a  minimum,  the  user-defined configuration file must provide some
54       passwords needed for the install.  An  example  configuration  file  is
55       provided  in  the  EXAMPLES section below.  For more information on the
56       default configuration file and the parameters it contains (and  can  be
57       customized), see pki_default.cfg(5).
58
59       The  pkispawn run creates several different installation files that can
60       be referenced later, if need be:
61
62              * For Tomcat-based instances, a Tomcat instance  is  created  at
63              /var/lib/pki/<pki_instance_name>,   where  pki_instance_name  is
64              defined in the configuration file.
65
66              *  A  log  file   of   pkispawn   operations   is   written   to
67              /var/log/pki/pki-<subsystem>-spawn.<timestamp>.log.
68
69              *  A .p12 (PKCS #12) file containing a certificate for a subsys‐
70              tem administrator is stored in pki_client_dir.
71
72       When the utility is done running, the CA can be accessed by pointing  a
73       browser to https://<hostname>:<pki_https_port>/. The agent pages can be
74       accessed by importing the CA certificate and administrator  certificate
75       into the browser.
76
77       The Certificate Server instance can also be accessed using the pki com‐
78       mand line interface.  See pki(1). For more extensive  documentation  on
79       how  to  use  Certificate  Server features, see the Red Hat Certificate
80       System      Documentation      at      https://access.redhat.com/knowl
81       edge/docs/Red_Hat_Certificate_System/.
82
83       Instances  created using pkispawn can be removed using pkidestroy.  See
84       pkidestroy(8).
85
86       pkispawn supersedes and combines the  functionality  of  pkicreate  and
87       pkisilent,  which  were  available  in  earlier releases of Certificate
88       Server.  It is now possible to completely create and configure the Cer‐
89       tificate Server subsystem in a single step using pkispawn.
90
91       Note:  Previously,  as  an  alternative to using pkisilent to perform a
92              non-interactive batch configuration, a  PKI  instance  could  be
93              interactively configured by a GUI-based configuration wizard via
94              a Firefox browser.  GUI-based configuration of a PKI instance is
95              unavailable in this version of the product.
96

OPTIONS

98       -s <subsystem>
99              Specifies  the  subsystem  to be installed and configured, where
100              <subsystem> is CA, KRA, OCSP, TKS, or TPS.
101
102       -f <config_file>
103              Specifies the path to the user-defined configuration file.  This
104              file  contains differences between the default configuration and
105              the custom configuration.
106
107       --precheck
108              Execute pre-checks and exit.
109
110       --skip-configuration
111              Run the first  step  of  the  installation  (i.e.  skipping  the
112              instance configuration step).
113
114       --skip-installation
115              Run  the  second  step  of  the  installation (i.e. skipping the
116              instance installation step).
117
118       -h, --help
119              Prints additional help information.
120
121       -v     Displays verbose information about the installation.  This  flag
122              can  be  provided  multiple  times  to  increase verbosity.  See
123              pkispawn -h for details.
124
125

SEPARATE VERSUS SHARED INSTANCES

127   Separate PKI instances:
128
129
130       As described above, this version of  Certificate  System  continues  to
131       support separate PKI instances for all subsystems.
132
133       Separate  PKI  instances  run  as  a  single  Java-based  Apache Tomcat
134       instance, contain a single PKI subsystem (CA, KRA, OCSP, TKS, or  TPS),
135       and  must  utilize  unique  ports  if  co-located  on the same physical
136       machine or virtual machine (VM).
137
138   Shared PKI instances:
139
140
141       Additionally, this version of Certificate System introduces the  notion
142       of a shared PKI instance.
143
144       Shared  PKI  instances  also  run  as a single Java-based Apache Tomcat
145       instance, but may contain any combination of up to one of each type  of
146       PKI subsystem:
147
148              CA
149              TKS
150              CA, KRA
151              CA, OCSP
152              TKS, TPS
153              CA, KRA, TKS, TPS
154              CA, KRA, OCSP, TKS, TPS
155              etc.
156
157       Shared  PKI  instances  allow  all of their subsystems contained within
158       that instance to share the same ports, and must utilize unique ports if
159       more  than  one  shared PKI instance is co-located on the same physical
160       machine or VM.
161
162       Semantically, a shared PKI instance that contains a single PKI  subsys‐
163       tem is identical to a separate PKI instance.
164
165

INTERACTIVE MODE

167       If  no options are specified, pkispawn will provide an interactive menu
168       to collect the parameters needed  to  install  the  Certificate  Server
169       instance.   Note that only the most basic installation options are pro‐
170       vided. This includes root CA, KRA, OCSP, TKS, and TPS connecting to  an
171       existing  directory server. More advanced setups such as cloned subsys‐
172       tems, subordinate or externally signed CA, subsystems that  connect  to
173       the  directory  server  using LDAPS, and subsystems that are customized
174       beyond the options described below require the use of  a  configuration
175       file with the -f option.
176
177
178       The  interactive option is most useful for those users getting familiar
179       with Certificate Server.  The parameters collected are written  to  the
180       installation  file of the subsystem, which can be found at /etc/syscon‐
181       fig/pki/tomcat/<instance name>/<subsystem>/deployment.cfg.
182
183       The following parameters are queried interactively during the installa‐
184       tion process:
185
186       Subsystem Type
187
188       Subsystem (CA/KRA/OCSP/TKS/TPS):
189              the  type  of  subsystem  to  be installed. Prompted when the -s
190              option is not specified.  The default value chosen is CA.
191
192       Instance Specific Parameters
193
194       Instance name:
195              the name of the tomcat instance in which the subsystem is to  be
196              installed. The default value is pki-tomcat.
197              Note:  Only  one  subsystem of a given type (CA, KRA, OCSP, TKS,
198              TPS) can exist within a given instance.
199
200       HTTP port:
201              the HTTP port of the Tomcat instance. The default value is 8080.
202
203       Secure HTTP port:
204              the HTTPS port of the Tomcat  instance.  The  default  value  is
205              8443.
206
207       AJP port:
208              the AJP port of the Tomcat instance. The default value is 8009.
209
210       Management port:
211              the management port of the Tomcat instance. The default value is
212              8005.
213
214       Note: When  deploying  a  new  subsystem  into  an  existing  instance,
215       pkispawn  will  attempt  to  read  the  ports from deployment.cfg files
216       stored for previously installed subsystems for this instance.  If  suc‐
217       cessful, the installer will not prompt for these ports.
218
219       Administrative User Parameters
220
221       Username:
222              the username of the administrator of this subsystem. The default
223              value is <ca/kra/ocsp/tks/tps>admin.
224
225       Password:
226              password for the administrator user.
227
228       Import certificate:
229              An optional parameter that can be  used  to  import  an  already
230              available CA admin certificate into this instance.
231
232       Export certificate:
233              setup  the  path where the admin certificate of this <subsystem>
234              should be stored. The default  value  is  $HOME/.dogtag/pki-tom‐
235              cat/<ca/kra/ocsp/tks/tps>_admin.cert.
236
237       Directory Server Parameters
238
239       Hostname:
240              Hostname of the directory server instance.  The default value is
241              the hostname of the system.
242
243       Use a secure LDAPS connection?
244              Answering yes to this question will  cause  prompts  for  Secure
245              LDAPS  Port:  and  Directory  Server  CA  certificate pem file:.
246              Answering no to this question will cause a prompt for LDAP Port.
247              The initial default value for this question is no.
248
249       Secure LDAPS Port:
250              Secure LDAPS port for the directory server instance. The default
251              value is 636.
252
253       Directory Server CA certificate pem file:
254              The fully-qualified path including  the  filename  of  the  file
255              which  contains  an  exported  copy of the Directory Server's CA
256              certificate (e. g. - $HOME/dscacert.pem).  This file must  exist
257              prior to pkispawn being able to utilize it.  For details on cre‐
258              ation of this file  see  the  EXAMPLES  section  below  entitled
259              Installing  a  CA  connecting securely to a Directory Server via
260              LDAPS.
261
262       LDAP Port:
263              LDAP port for the directory server instance. The  default  value
264              is 389.
265
266       Base DN:
267              the  Base  DN to be used for the internal database for this sub‐
268              system. The default value is o=pki-tomcat-<subsystem>.
269
270       Bind DN:
271              the bind DN required to connect for the directory  server.  This
272              user  must  have  sufficient permissions to install the required
273              schema and database.  The default value is cn=Directory Manager.
274
275       Password:
276              password for the bind DN.
277
278       Security Domain Parameters
279
280       Name:  the name of the security domain. Required only if  installing  a
281              root CA. Default value: <DNS domain name> Security Domain.
282
283       Hostname:
284              the  hostname for the security domain CA. Required only for non-
285              CA subsystems. The default value is the hostname of this system.
286
287       Secure HTTP port:
288              the https port for the security domain. Required only for non-CA
289              subsystems. The default value is 8443.
290
291       Username:
292              the  username  of  the  security domain administrator of the CA.
293              Required only for non-CA subsystems. The default value is  caad‐
294              min.
295
296       Password:
297              password for the security domain administrator. Required for all
298              subsystems that are not root CAs.
299
300

PRE-CHECK MODE

302       This option is only available when pkispawn is invoked in a  non-inter‐
303       active  mode.   When  the --precheck option is provided, a set of basic
304       tests are performed to ensure that the parameters provided to  pkispawn
305       are valid and consistent.
306
307       pkispawn  will  then  exit  with  an exit code of 0 on success, or 1 on
308       failure.  This mode can be used to perform basic tests prior  to  doing
309       any actual installation of the Certificate Server instance.
310
311       Flags are available to disable specific tests.  For instance, one might
312       want to disable validation of the credentials for the internal database
313       user if the directory server instance has not yet been created.
314
315       See  pki_default.cfg(5)  for more details about available flags.
316
317

TWO-STEP INSTALLATION MODE

319       pkispawn  provides  a  number  of  parameters  to customize an instance
320       before it is created. Usually, most other  customization  can  be  done
321       after  the server is created.  However, sometimes certain types of cus‐
322       tomization need to be done before the server is created, but there  are
323       no  parameters  for  that.  For  example,  configuring session timeout,
324       adding CSR extensions, customizing  certificate  profiles,  configuring
325       TLS  ciphers,  etc.  To support such customization, pkispawn provides a
326       two-step installation mode.
327
328       Generally, instance creation happens in one step (except for the exter‐
329       nal  CA  case).   Internally, the process happens in two stages. In the
330       first stage, pkispawn will install the instance files (e.g. CS.cfg, NSS
331       database,  profiles, etc.) in the instance directory and customize them
332       based on pkispawn parameters. In the second stage, pkispawn will  start
333       the  instance and configure the instance based on the instance configu‐
334       ration files (e.g. initializing database, generating certificates, con‐
335       figuring  connectors, etc.). The two-step process allows the process to
336       be stopped after the first stage, allowing further customization to  be
337       done before running the second stage.
338
339       To use two-step installation mode, prepare a normal pkispawn configura‐
340       tion file, then run pkispawn with the  --skip-configuration  parameter.
341       For example:
342
343
344
345              pkispawn -s CA -f myconfig.txt --skip-configuration
346
347
348       Then  customize the files in the instance directory as needed. Finally,
349       finish the installation by running  pkispawn  again  with  the  --skip-
350       installation parameter. For example:
351
352
353
354              pkispawn -s CA -f myconfig.txt --skip-installation
355
356

EXAMPLES

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

BUGS

1587       Report bugs to http://bugzilla.redhat.com.
1588
1589

AUTHORS

1591       Ade  Lee  <alee@redhat.com>.   pkispawn  was written by the Certificate
1592       Server project.
1593
1594
1596       Copyright (c) 2012 Red Hat, Inc. This is licensed under the GNU General
1597       Public  License, version 2 (GPLv2). A copy of this license is available
1598       at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.
1599
1600

SEE ALSO

1602       pkidestroy(8), pki_default.cfg(5), pki(1), setup-ds.pl(8)
1603
1604
1605
1606version 1.0                    December 13, 2012                   pkispawn(8)
Impressum