diff --git a/base/server/CMakeLists.txt b/base/server/CMakeLists.txt index ec2d37b1773..b72eaff64dd 100644 --- a/base/server/CMakeLists.txt +++ b/base/server/CMakeLists.txt @@ -164,6 +164,13 @@ install( ${DATA_INSTALL_DIR}/server/webapps/pki/WEB-INF/lib ) +install( + DIRECTORY + docs/ + DESTINATION + ${DATA_INSTALL_DIR}/server/docs +) + install( DIRECTORY man/ diff --git a/base/server/docs/installation/Installing_CA_with_Custom_CA_Signing_Key.md b/base/server/docs/installation/Installing_CA_with_Custom_CA_Signing_Key.md new file mode 100644 index 00000000000..5cdf786b961 --- /dev/null +++ b/base/server/docs/installation/Installing_CA_with_Custom_CA_Signing_Key.md @@ -0,0 +1,169 @@ +Installing CA with Custom CA Signing Key +======================================== + +Overview +-------- + +This page describes the process to install a CA subsystem with a custom CA signing key, CSR, and certificate. + +Starting CA Subsystem Installation +---------------------------------- + +Prepare a file (e.g. ca-step1.cfg) that contains the deployment configuration step 1, for example: + +``` +[DEFAULT] +pki_server_database_password=Secret.123 + +[CA] +pki_admin_email=caadmin@example.com +pki_admin_name=caadmin +pki_admin_nickname=caadmin +pki_admin_password=Secret.123 +pki_admin_uid=caadmin + +pki_client_database_password=Secret.123 +pki_client_database_purge=False +pki_client_pkcs12_password=Secret.123 + +pki_ds_base_dn=dc=ca,dc=pki,dc=example,dc=com +pki_ds_database=ca +pki_ds_password=Secret.123 + +pki_security_domain_name=EXAMPLE + +pki_ca_signing_nickname=ca_signing +pki_ocsp_signing_nickname=ca_ocsp_signing +pki_audit_signing_nickname=ca_audit_signing +pki_sslserver_nickname=sslserver +pki_subsystem_nickname=subsystem + +pki_external=True +pki_external_step_two=False +``` + +Then execute the following command: + +``` +$ pkispawn -f ca-step1.cfg -s CA +``` + +It will install CA subsystem in a Tomcat instance (default is pki-tomcat) and create the following NSS databases: +* server NSS database: /etc/pki/pki-tomcat/alias +* admin NSS database: ~/.dogtag/pki-tomcat/ca/alias + +Since there is no CSR path parameter specified, it will not generate the CA signing key by default. + +Generating CA Signing Key, CSR, and Certificate +----------------------------------------------- + +Generate a custom CA signing key in the server NSS database, then generate a CSR and store it in a file (e.g. ca_signing.csr). + +Use the CSR to issue the CA signing certificate: +* for root CA installation, generate a self-signed CA signing certificate +* for subordinate CA installation, submit the CSR to an external CA to issue the CA signing certificate + +Store the CA signing certificate in a file (e.g. ca_signing.crt). The CA signing certificate can be specified as a single certificate or a PKCS #7 certificate chain in PEM format. + +If the CA signing certificate was issued by an external CA, store the external CA certificate chain in a file (e.g. external.crt). The certificate chain can be specified as a single certificate or a PKCS #7 certificate chain in PEM format. The certificate chain should include all CA certificates from the root CA to the external CA that issued the CA signing certificate, but it should not include the CA signing certificate itself. + +See also: +* [Generating CA Signing Certificate](http://www.dogtagpki.org/wiki/Generating_CA_Signing_Certificate) + +Finishing CA Subsystem Installation +----------------------------------- + +Prepare another file (e.g. ca-step2.cfg) that contains the deployment configuration step 2. The file can be copied from step 1 (i.e. ca-step1.cfg) with additional changes below. + +Specify step 2 with the following parameter: + +``` +pki_external_step_two=True +``` + +Specify the custom CA signing CSR with the following parameter: + +``` +pki_ca_signing_csr_path=ca_signing.csr +``` + +Specify the custom CA signing certificate with the following parameter: + +``` +pki_ca_signing_cert_path=ca_signing.crt +``` + +If the CA signing certificate was issued by an external CA, specify the external CA certificate chain with the following parameters: + +``` +pki_cert_chain_nickname=external +pki_cert_chain_path=external.crt +``` + +Finally, execute the following command: + +``` +$ pkispawn -f ca-step2.cfg -s CA +``` + +Verifying System Certificates +----------------------------- + +Verify that the server NSS database contains the following certificates: + +``` +$ certutil -L -d /etc/pki/pki-tomcat/alias + +Certificate Nickname Trust Attributes + SSL,S/MIME,JAR/XPI + +external CT,C,C +ca_signing CTu,Cu,Cu +ca_ocsp_signing u,u,u +subsystem u,u,u +ca_audit_signing u,u,Pu +sslserver u,u,u +``` + +Verifying Admin Certificate +--------------------------- + +Prepare a client NSS database (e.g. ~/.dogtag/nssdb): + +``` +$ pki -c Secret.123 client-init +``` + +Import the external CA certificate chain: + +``` +$ pki -c Secret.123 client-cert-import --ca-cert external.crt +``` + +Import the CA signing certificate: + +``` +$ pki -c Secret.123 client-cert-import ca_signing --ca-cert ca_signing.crt +``` + +Import admin key and certificate: + +``` +$ pki -c Secret.123 client-cert-import \ + --pkcs12 ~/.dogtag/pki-tomcat/ca_admin_cert.p12 \ + --pkcs12-password-file ~/.dogtag/pki-tomcat/ca/pkcs12_password.conf +``` + +Verify that the admin certificate can be used to access the CA subsystem by executing the following command: + +``` +$ pki -c Secret.123 -n caadmin ca-user-show caadmin +-------------- +User "caadmin" +-------------- + User ID: caadmin + Full name: caadmin + Email: caadmin@example.com + Type: adminType + State: 1 +``` diff --git a/base/server/docs/installation/Installing_KRA_with_Custom_Keys.md b/base/server/docs/installation/Installing_KRA_with_Custom_Keys.md new file mode 100644 index 00000000000..e555363e708 --- /dev/null +++ b/base/server/docs/installation/Installing_KRA_with_Custom_Keys.md @@ -0,0 +1,190 @@ +Installing KRA with Custom Keys +=============================== + +Overview +-------- + +This page describes the process to install a KRA subsystem with custom KRA system and admin keys, CSRs, and certificates. + +Starting KRA Subsystem Installation +----------------------------------- + +Prepare a file (e.g. kra-step1.cfg) that contains the deployment configuration step 1, for example: + +``` +[DEFAULT] +pki_server_database_password=Secret.123 + +[KRA] +pki_admin_email=kraadmin@example.com +pki_admin_name=kraadmin +pki_admin_nickname=kraadmin +pki_admin_password=Secret.123 +pki_admin_uid=kraadmin + +pki_client_database_password=Secret.123 +pki_client_database_purge=False +pki_client_pkcs12_password=Secret.123 + +pki_ds_base_dn=dc=kra,dc=pki,dc=example,dc=com +pki_ds_database=kra +pki_ds_password=Secret.123 + +pki_security_domain_name=EXAMPLE +pki_security_domain_user=caadmin +pki_security_domain_password=Secret.123 + +pki_storage_nickname=kra_storage +pki_transport_nickname=kra_transport +pki_subsystem_nickname=subsystem +pki_sslserver_nickname=sslserver +pki_audit_signing_nickname=kra_audit_signing + +pki_external=True +pki_external_step_two=False +``` + +Then execute the following command: + +``` +$ pkispawn -f kra-step1.cfg -s KRA +``` + +It will install KRA subsystem in a Tomcat instance (default is pki-tomcat) and create the following NSS databases: +* server NSS database: /etc/pki/pki-tomcat/alias +* admin NSS database: ~/dogtag/pki-tomcat/kra/alias + +Since there are no CSR path parameters specified, it will not generate KRA system and admin keys. + +Generating KRA Keys, CSRs, and Certificates +------------------------------------------- + +Generate custom KRA system keys in the server NSS database and admin key in the admin NSS database, then generate the CSRs and store them in files, for example: +* kra_storage.csr +* kra_transport.csr +* subsystem.csr +* sslserver.csr +* kra_audit_signing.csr +* kra_admin.csr + +Submit the CSRs to an external CA to issue the certificates, then store the certificates in files, for example: +* kra_storage.crt +* kra_transport.crt +* subsystem.crt +* sslserver.crt +* kra_audit_signing.crt +* kra_admin.crt + +The certificates can be specified as single certificates or PKCS #7 certificate chains in PEM format. + +Store the external CA certificate chain in a file (e.g. ca_signing.crt). The certificate chain can be specified as a single certificate or PKCS #7 certificate chain in PEM format. The certificate chain should include all CA certificates from the root CA to the external CA that issued the KRA system and admin certificates. + +See also: +* [Generating KRA Storage Certificate](http://www.dogtagpki.org/wiki/Generating_KRA_Storage_Certificate) +* [Generating KRA Transport Certificate](http://www.dogtagpki.org/wiki/Generating_KRA_Transport_Certificate) +* [Generating Subsystem Certificate](http://www.dogtagpki.org/wiki/Generating_Subsystem_Certificate) +* [Generating SSL Server Certificate](http://www.dogtagpki.org/wiki/Generating_SSL_Server_Certificate) +* [Generating Audit Signing Certificate](http://www.dogtagpki.org/wiki/Generating_Audit_Signing_Certificate) +* [Generating Admin Certificate](http://www.dogtagpki.org/wiki/Generating_Admin_Certificate) + +Finishing KRA Subsystem Installation +------------------------------------ + +Prepare another file (e.g. kra-step2.cfg) that contains the deployment configuration step 2. The file can be copied from step 1 (i.e. kra-step1.cfg) with additional changes below. + +Specify step 2 with the following parameter: + +``` +pki_external_step_two=True +``` + +Specify the custom CSRs with the following parameters: + +``` +pki_storage_csr_path=kra_storage.csr +pki_transport_csr_path=kra_transport.csr +pki_subsystem_csr_path=subsystem.csr +pki_sslserver_csr_path=sslserver.csr +pki_audit_signing_csr_path=kra_audit_signing.csr +pki_admin_csr_path=kra_admin.csr +``` + +Specify the custom certificates with the following parameters: + +``` +pki_storage_cert_path=kra_storage.crt +pki_transport_cert_path=kra_transport.crt +pki_subsystem_cert_path=subsystem.crt +pki_sslserver_cert_path=sslserver.crt +pki_audit_signing_cert_path=kra_audit_signing.crt +pki_admin_cert_path=kra_admin.crt +``` + +Specify the external CA certificate chain with the following parameters: + +``` +pki_cert_chain_nickname=ca_signing +pki_cert_chain_path=ca_signing.crt +``` + +Finally, execute the following command: + +``` +$ pkispawn -f kra-step2.cfg -s KRA +``` + +Verifying System Certificates +----------------------------- + +Verify that the server NSS database contains the following certificates: + +``` +$ certutil -L -d /etc/pki/pki-tomcat/alias + +Certificate Nickname Trust Attributes + SSL,S/MIME,JAR/XPI + +ca_signing CT,C,C +kra_storage CTu,Cu,Cu +kra_transport u,u,u +subsystem u,u,u +kra_audit_signing u,u,Pu +sslserver u,u,u +``` + +Verifying Admin Certificate +--------------------------- + +Prepare a client NSS database (e.g. ~/.dogtag/nssdb): + +``` +$ pki -c Secret.123 client-init +``` + +Import the external CA certificate chain: + +``` +$ pki -c Secret.123 client-cert-import --ca-cert ca_signing.crt +``` + +Import the admin key and certificate: + +``` +$ pki -c Secret.123 client-cert-import \ + --pkcs12 ~/.dogtag/pki-tomcat/kra_admin_cert.p12 \ + --pkcs12-password-file ~/.dogtag/pki-tomcat/ca/pkcs12_password.conf +``` + +Verify that the admin certificate can be used to access KRA by executing the following command: + +``` +$ pki -c Secret.123 -n kraadmin kra-user-show kraadmin +--------------- +User "kraadmin" +--------------- + User ID: kraadmin + Full name: kraadmin + Email: kraadmin@example.com + Type: adminType + State: 1 +``` diff --git a/base/server/docs/installation/Installing_OCSP_with_Custom_Keys.md b/base/server/docs/installation/Installing_OCSP_with_Custom_Keys.md new file mode 100644 index 00000000000..dca4f791574 --- /dev/null +++ b/base/server/docs/installation/Installing_OCSP_with_Custom_Keys.md @@ -0,0 +1,183 @@ +Installing OCSP with Custom Keys +================================ + +Overview +-------- + +This page describes the process to install a OCSP subsystem with custom OCSP system and admin keys, CSRs, and certificates. + +Starting OCSP Subsystem Installation +------------------------------------ + +Prepare a file (e.g. ocsp-step1.cfg) that contains the deployment configuration step 1, for example: + +``` +[DEFAULT] +pki_server_database_password=Secret.123 + +[OCSP] +pki_admin_email=ocspadmin@example.com +pki_admin_name=ocspadmin +pki_admin_nickname=ocspadmin +pki_admin_password=Secret.123 +pki_admin_uid=ocspadmin + +pki_client_database_password=Secret.123 +pki_client_database_purge=False +pki_client_pkcs12_password=Secret.123 + +pki_ds_base_dn=dc=ocsp,dc=pki,dc=example,dc=com +pki_ds_database=ocsp +pki_ds_password=Secret.123 + +pki_security_domain_name=EXAMPLE +pki_security_domain_user=caadmin +pki_security_domain_password=Secret.123 + +pki_ocsp_signing_nickname=ocsp_signing +pki_subsystem_nickname=subsystem +pki_sslserver_nickname=sslserver +pki_audit_signing_nickname=ocsp_audit_signing + +pki_external=True +pki_external_step_two=False +``` + +Then execute the following command: + +``` +$ pkispawn -f ocsp-step1.cfg -s OCSP +``` + +It will install OCSP subsystem in a Tomcat instance (default is pki-tomcat) and create the following NSS databases: +* server NSS database: /etc/pki/pki-tomcat/alias +* admin NSS database: ~/.dogtag/pki-tomcat/ocsp/alias + +Since there are no CSR path parameters specified, it will not generate the OCSP system and admin keys. + +Generating OCSP Keys, CSRs, and Certificates +-------------------------------------------- + +Generate custom OCSP system keys in the server NSS database and admin key in the admin NSS database, then generate the CSRs and store them in files, for example: +* ocsp_signing.csr +* subsystem.csr +* sslserver.csr +* ocsp_audit_signing.csr +* ocsp_admin.csr + +Submit the CSRs to an external CA to issue the certificates, then store the certificates in files, for example: +* ocsp_signing.crt +* subsystem.crt +* sslserver.crt +* ocsp_audit_signing.crt +* ocsp_admin.crt + +The certificates can be specified as single certificates or PKCS #7 certificate chains in PEM format. + +Store the external CA certificate chain in a file (e.g. ca_signing.crt). The certificate chain can be specified as a single certificate or PKCS #7 certificate chain in PEM format. The certificate chain should include all CA certificates from the root CA to the external CA that issued the OCSP system and admin certificates. + +See also: +* [Generating OCSP Signing Certificate](http://www.dogtagpki.org/wiki/Generating_OCSP_Signing_Certificate) +* [Generating Subsystem Certificate](http://www.dogtagpki.org/wiki/Generating_Subsystem_Certificate) +* [Generating SSL Server Certificate](http://www.dogtagpki.org/wiki/Generating_SSL_Server_Certificate) +* [Generating Audit Signing Certificate](http://www.dogtagpki.org/wiki/Generating_Audit_Signing_Certificate) +* [Generating Admin Certificate](http://www.dogtagpki.org/wiki/Generating_Admin_Certificate) + +Finishing OCSP Subsystem Installation +------------------------------------- + +Prepare another file (e.g. ocsp-step2.cfg) that contains the deployment configuration step 2. The file can be copied from step 1 (i.e. ocsp-step1.cfg) with additional changes below. + +Specify step 2 with the following parameter: + +``` +pki_external_step_two=True +``` + +Specify the custom CSRs with the following parameters: + +``` +pki_ocsp_signing_csr_path=ocsp_signing.csr +pki_subsystem_csr_path=subsystem.csr +pki_sslserver_csr_path=sslserver.csr +pki_audit_signing_csr_path=ocsp_audit_signing.csr +pki_admin_csr_path=ocsp_admin.csr +``` + +Specify the custom certificates with the following parameters: + +``` +pki_ocsp_signing_cert_path=ocsp_signing.crt +pki_subsystem_cert_path=subsystem.crt +pki_sslserver_cert_path=sslserver.crt +pki_audit_signing_cert_path=ocsp_audit_signing.crt +pki_admin_cert_path=ocsp_admin.crt +``` + +Specify the external CA certificate chain with the following parameters: + +``` +pki_cert_chain_nickname=ca_signing +pki_cert_chain_path=ca_signing.crt +``` + +Finally, execute the following command: + +``` +$ pkispawn -f ocsp-step2.cfg -s OCSP +``` + +Verifying System Certificates +----------------------------- + +Verify that the server NSS database contains the following certificates: + +``` +$ certutil -L -d /etc/pki/pki-tomcat/alias + +Certificate Nickname Trust Attributes + SSL,S/MIME,JAR/XPI + +ca_signing CT,C,C +ocsp_signing CTu,Cu,Cu +subsystem u,u,u +ocsp_audit_signing u,u,Pu +sslserver u,u,u +``` + +Verifying Admin Certificate +--------------------------- + +Prepare a client NSS database (e.g. ~/.dogtag/nssdb): + +``` +$ pki -c Secret.123 client-init +``` + +Import the external CA certificate chain: + +``` +$ pki -c Secret.123 client-cert-import --ca-cert ca_signing.crt +``` + +Import the admin key and certificate: + +``` +$ pki -c Secret.123 client-cert-import \ + --pkcs12 ~/.dogtag/pki-tomcat/ocsp_admin_cert.p12 \ + --pkcs12-password-file ~/.dogtag/pki-tomcat/ca/pkcs12_password.conf +``` + +Verify that the admin certificate can be used to access the OCSP subsystem by executing the following command: + +``` +$ pki -c Secret.123 -n ocspadmin ocsp-user-show ocspadmin +---------------- +User "ocspadmin" +---------------- + User ID: ocspadmin + Full name: ocspadmin + Email: ocspadmin@example.com + Type: adminType + State: 1 +```