From 71629d019235d2b618fd7a5521d125af62cf533b Mon Sep 17 00:00:00 2001 From: Mathieu Jourdan Date: Tue, 18 Mar 2025 17:15:18 +0100 Subject: [PATCH 1/7] update index and getting started to make room for pkiaas --- ...ng-started.rst => getting-started-with-opensc.rst} | 0 source/components/nitrokeys/hsm/index.rst | 11 ++++++++--- 2 files changed, 8 insertions(+), 3 deletions(-) rename source/components/nitrokeys/hsm/{getting-started.rst => getting-started-with-opensc.rst} (100%) diff --git a/source/components/nitrokeys/hsm/getting-started.rst b/source/components/nitrokeys/hsm/getting-started-with-opensc.rst similarity index 100% rename from source/components/nitrokeys/hsm/getting-started.rst rename to source/components/nitrokeys/hsm/getting-started-with-opensc.rst diff --git a/source/components/nitrokeys/hsm/index.rst b/source/components/nitrokeys/hsm/index.rst index 865b3a7b6e..df5a8176ab 100644 --- a/source/components/nitrokeys/hsm/index.rst +++ b/source/components/nitrokeys/hsm/index.rst @@ -3,15 +3,20 @@ Nitrokey HSM 2 .. contents:: :local: -First check the: +This documentations describes how to use Nitrokey HSM2 devices. Nitrokey HSM 2 can be used to keep an offline root CA secure. + +For building a Public Key Infrastructure (PKI), you might want to protect the use of your root CA with m-of-n authentication. If so, interacting with your Nitrokeys requires the use of graphical components called SmartCard Shell and PKIAAS. Please refer to this guide: `Getting Started `__ + +If m-of-n authentication is not mandatory for you, then your devices can be used through command line tools provided by the OpenSC project. Please refer to this page `Getting Started `__ .. toctree:: :maxdepth: 1 :glob: - Getting Started + Getting Started with PKIAAS + Getting Started with OpenSC Frequently Asked Questions or check out the features: -* `HSM <../features/hsm/index.html>`_ \ No newline at end of file +* `HSM <../features/hsm/index.html>`_ From 037c6b998e9df63e9aaffacf4124e96937a4129c Mon Sep 17 00:00:00 2001 From: Mathieu Jourdan Date: Wed, 19 Mar 2025 14:38:23 +0100 Subject: [PATCH 2/7] describe how to set m-of-n authentication with scshell and pkiaas --- .../hsm/getting-started-with-pkiaas.md | 49 +++ source/components/nitrokeys/hsm/pkiaas.md | 376 ++++++++++++++++++ .../nitrokeys/hsm/smart-card-shell.md | 160 ++++++++ 3 files changed, 585 insertions(+) create mode 100644 source/components/nitrokeys/hsm/getting-started-with-pkiaas.md create mode 100644 source/components/nitrokeys/hsm/pkiaas.md create mode 100644 source/components/nitrokeys/hsm/smart-card-shell.md diff --git a/source/components/nitrokeys/hsm/getting-started-with-pkiaas.md b/source/components/nitrokeys/hsm/getting-started-with-pkiaas.md new file mode 100644 index 0000000000..ec45d81d5d --- /dev/null +++ b/source/components/nitrokeys/hsm/getting-started-with-pkiaas.md @@ -0,0 +1,49 @@ +Getting started with PKIAAS +=========================== + +This guide describes how to set up a PKI made of : + +- an offline root CA, used only to sign intermediate CAs and revocation list. It is kept secure on a HSM. +- intermediate CAs, used for automatic certificate delivery through online services (like ADCS, EJBCA, OpenBao, and so on). Those have a higher risk of compromission as they are not kept secure on a HSM. + + +Security considerations +----------------------- + +In order to keep access to our CA in case the HSM is lost or faulty, we will backup the material to a secondary HSM. We will protect ourselves from unauthorized copying, by using shared control over key replication, with an m-of-n scheme. A secret will be split and shared between key custodians. + +We also want to have shared control over the use of the CA, so we will also rely upon a m-of-n scheme, with pubkeys authentication. Pubkey authentication will be possible by the mean of personnal HSM devices distributed to key custodians. + +One thing to do is to define how many people will be involved in those m-of-n schemes, and what is the quorum to reach. We suggest the number of required parts to be greater than the number to additional parts. A quorum of 3 people needed out of 5 key custodians is a common ration. + + +Requirements +------------ + +The following devices will be involved: + +- two Nitrokey HSM 2 for the root CA and its backup +- five Nitrokey HSM 2 for personnal authentication +- we also suggest to keep one spare device, just in case + +Our setup will involve: + +- the certificate operator personnal machine, to run + - SmartCard Shell, a java based graphical user interface to initialize the devices + - OCF, to connect your HSM devices to the remote CA web app +- a docker server, on which will be deployed + - PKIAAS, a java based web app to sign the root CA and deliver intermediate certificates + +Both SmartCard Shell and PKIAAS are developped by CardContact, the company that makes the chip embedded in Nitrokey HSM 2. Details on how to install this software will be given later in this guide. + + +Procedure +--------- + +From now on, we will speak of "personnal HSM" and "CA HSM" because of their distinct purposes. + +The following guide will involve a `certificate operator`, in charge of doing the technical steps, and `key custodians`, whom will have to enter their PIN when required. + +[Prepare your HSM with Smart Card Shell](smart-card-shell) + +[Build your PKI with PKIAAS](pkiaas) diff --git a/source/components/nitrokeys/hsm/pkiaas.md b/source/components/nitrokeys/hsm/pkiaas.md new file mode 100644 index 0000000000..a518f0e036 --- /dev/null +++ b/source/components/nitrokeys/hsm/pkiaas.md @@ -0,0 +1,376 @@ +PKIAAS +====== + +For a description of PKIAAS, please see the [release announcement](https://www.smartcard-hsm.com/2018/02/13/pki-as-a-service.html). + +A middleware will also be needed to connect your HSM plugged in your local computer to the remote PKIAAS server, see this [OpenCard Framework description](https://www.openscdp.org/ocf/index.html). + +Installation +------------ + +### client configuration + +We will need: + +- a web browser to access the PKIAAS interface +- a jar file of the Open Card Framework (OCF) + +Download ocf-cc.jar from the [OpenSCDP website](https://www.openscdp.org/ocf/ocf-cc.jar). + + +### PKIAAS server + +We will be using the [docker installation](https://github.com/CardContact/deploy-pki-as-a-service). + +On a Debian 12 host: + +``` +sudo apt install git +sudo apt install docker.io +sudo apt install iptables-legacy +sudo update-alternatives --config iptables +sudo service docker start +``` + +Fetch the docker deployment resources: + +``` +git clone https://github.com/CardContact/deploy-pki-as-a-service.git +cd deploy-pki-as-a-service +``` + +By the time of writing this guide, PKIAAS doesn't support setting arbitrary CRL endpoint, and doesn't handle OCSP at all. At most, we can set in a configuration file the Fully Qualified Domain Name (FQDN) behind which the crl will later be found. + +Copy the application configuration file, and edit it to change de "serverURL" - amongs other settings - according to your needs: + +``` +cp pkiaas/etc/template/configuration.js env/etc/configuration.js +vim env/etc/configuration.js +``` +``` +Config.global = { + serverURL: "{{ pkiaas_global_server_url }}", + allowResetDB: false, + allowDevHSM: false +} +``` + +Edit docker-compose.yml so that: + +- the configuration file is loaded read-only as a volume, instead of building additional layers at each configuration change +- container is linked to two ports of our host + - port 80 is needed for the CRL endpoint to look like http:///se/crl/1 + - port 8080 is needed for OCF to successfully connect personnal HSM to http://localhost:8080/rt + +``` +vim docker-compose.yml +``` +``` + volumes: + - logs:/usr/share/pkiaas/logs + - ./pkiaas/etc/configuration.js:/usr/share/pkiaas/etc/configuration.js:ro + pkiaas-test: + ports: + - 80:8080 + - 8080:8080 +``` + +We're good to go + +``` +docker-compose up +``` + + +Usage +----- + +### Access to the portal + +Open your web browser to http:// + +### Listing devices + +As before we will be dealing with to kind of HSM: + +- CA HSM to protect the root CA +- personnal HSM to perform authentication + +Use `-l` option of ocf-cc.jar to list the HSM plugged in your computer: + +``` +> java -jar ocf-cc.jar -l +SLF4J: No SLF4J providers were found. +SLF4J: Defaulting to no-operation (NOP) logger implementation +SLF4J: See https://www.slf4j.org/codes.html#noProviders for further details. +OCF1.2;IBM Reference Implementation with OpenSCDP extensions 2.0.2.0.35 +Available card terminals: + Nitrokey Nitrokey HSM 0 +``` + +TrustCenter preparation +----------------------- + +### Account activation + +This step is required only the first time we connect to PKIAAS. + +For now, we will only plug in the PKIAAS admin's personnal HSM. + +``` +java -jar ocf-cc.jar -r "Nitrokey Nitrokey HSM 0" -v +``` + +In the web browser, reload the page. A java window appears asking for the PIN of the HSM. Type it in and confirm. + +An e-mail adress is asked. Give yours, and you should receive and activation code. You might as well check out your docker logs to find the same code. + +Enter the activation code when asked, tick the checkboxes you woul'd like for your notification preferences, and click "Submit". + +Now we see the home page. + +### TrustCenter creation + +Before we are able to actually manage our CA, we have to create a "TrustCenter". In the navigation bar, click on Home / Create Trust Center Subject. + +The different roles available in PKIAAS are described. Here is an excerpt: + +> When creating a TrustCenter three roles are created and initially assigned to the person creating the TrustCenter: +> +> -TrustCenter Manager - responsible for managing roles. +> -TrustCenter Operator - responsible for operating the TrustCenter +> -Registration Officer - responsible for processing certification requests. +> -Certification Officer - responsible for managing keys and issuing certificates. +> +> As part of this service request you can assign a SmartCard-HSM token to the TrustCenter. Assigning a SmartCard-HSM is important to establish a link between the HSM's identity and the TrustCenter, so that when the SmartCard-HSM is remotely connected, it can be correctly allocated to the entity. Multiple HSMs can be assigned and assigments can be withdrawn by opening the service request again. + +For our use cases, all roles will be given to the same person. + +Click on "Start Request", then fill in the form: + +``` +Unique Name : +Operation Mode : Private +``` + +Click on "Save", then on "Submit". + +### CA device registration + +We have to tell to PKIAAS which device to use for our CA. + +- stop the ocf client +- unplug the personnal HSM +- plug the CA HSM +- connect the CA HSM with the following command: `java -jar ocf-cc.jar -r "Nitrokey Nitrokey HSM 0" -v` + +On the home page: + +- click on "Create TrustCenter Subjet ()" +- keep "operation mode" set to "private" +- click on "Add Token" + +Do the same with the second HSM you have to backup your CA! + +Now you can stop the OCF, as we will have to use a different URL to connect the CA HSM to PKIAAS. + + +Using the CA HSM +---------------- + +This steps will allow key custodians to authenticate against the CA HSM, wich will be necessary to do anything useful with the device. + +### Connecting HSM + +From now on, We'll keep the CA HSM plugged most of the time, while we will have to frequently plug and unplugg personnal HSM. In order to avoid confusion and connectivity issues, we recommend the run two sessions of OCF in parallel. + +Always connect your CA device first: + +- make sure no HSM is currently plugged in +- plug your CA HSM, so it will be detected as "Nitrokey Nitrokey HSM 0" +- connect your CA HSM with `java -jar ocf-cc.jar -r "Nitrokey Nitrokey HSM 0" http:///rt/hsm` + +When you'll have to perform authentication, do like so: + +- plug the personnal HSM that will be used for authentication, so it will be detected as "Nitrokey Nitrokey HSM 1" +- connect the deivce with `java -jar ocf-cc.jar -r "Nitrokey Nitrokey HSM 1" -v` + +### M-of-n authentication + +In the navigation bar, go to Views / Subjects. In the table, dind your TrustCenter and click on its ID at the beggining of the line. + +If necessary, reload the page. There is a line showing your CA device, with the numbers of public keys currently authenticated. + +Click on "Authenticate", then +- plug one of the personnal HSM +- reload the page +- if the CA HSM is shown instead of the personnal HSM, click on "Enumerate key" +- pick the key used for authentication (it is recognizable by its label) +- click on "Authenticate" +- ask the key custodian to enter their PIN in the java windows +- unplug the personnal HSM. + +Reiterate until the quorum is reached. There, the "Authenticate" button will be replaced by a "Logout" button. Do not click on it! + + +Root CA creation +---------------- + +### Root CA request and signature + +In the navigation bar, go to Views / Subjects, then click on your TrustCenter ID. + +In the navigation bar, a new section appears. Click on CA / Create Signer, then on "Start Request". Fill in the form: + +``` +Issuing CA: Self-signed Root CA (this value can't be changed) +Trust Center: (this value can't be changed) +``` +``` +### CA Certificate Definitions +Expires after (days): 4380 (root CA will be valid for 12 years) +Subordinate CAs: 1 (one level of intermediate CA will be allowed) + +### Certification Authority Data +Distinguished Name: C = , ST = , L = , O = , OU = , CN = + +### Key Specification +Key Specification: EC secp384r1 SHA-256 + +### Subject certificate Definitions +Key Specification: EC secp384r1 SHA-256 +Expires after (days): 1825 (intermediate CA will be valid for 5 years) +Subject DN Rule: c=${issuer.c},st=${issuer.st},l=${issuer.l},o=${issuer.o},cn=${servicerequest.commonName} +upported Profiles: SubCA / TLSServer / TLSClient / EmailAndTLSClient + +### CRL Definitions +Expires after: 365 (key custodians will meet at least once a year to sign a new certificate revocation list) +``` + +If the CA HSM is plugged in and pubkeys authentication went well, then we can: + +- click on "Save" +- click on "Submit" +- click on "Create Signer" + +The HSM lights up and a first entry appears in the list of certificates on screen. Congratulations, your root CA has just been created! + +### Root CA certificate export + +In the navigation bar, go to Subjects / TrustCenter. + +The root CA should be visible here. Click on it. Certificate details are shown. At the bottom of the page, click on "Download Certificate". + +This is the file your machines will have to trust to verify the certificates delivered by your external intermediate CA. + + +Sharing access to PKIAAS +------------------------ + +### Allow additionnal personnal HSM to access the CA + +The first personnal HSM you used to connect to PKIAAS has been registered with the TrustCenter. To avoid the risk of being locked out, it's best to give access to a second key custodian. + +In the navigation bar, go to Views / Subjects, and click on the ID of the TrustCenter. + +In the navigation bar, a "CA" menu appears. Click it, then "Enroll person". + +On the new page, click on "Start Request", then fill in the form: + +``` +Name: +email: +CA: +``` + +- click on "Create" +- replace the device currently plugged in with the device to register +- click on "Identify token" +- a HSM ID should appear, looking similar to /DESRCACC1/DEDINK01/DENK0105102 +- if this device is not authenticated, restart the OCF client and reload the web page +- click on "Save" + +### Associate the personnal HSM with the relevant roles + +Now, the device must be given the right permissions to actually being able to sign the certificates. + +In the navigation bar, click on View / Subjects, then click on the ID right before the newly registered custodian. + +In the navigation bar, a "Subject" menu appears. Click on it, then "Manage role". On the new page: + +- click on "Start Request" +- select all roles +- click on "Save" +- click on "Apply". + +Note: authentication relies upon a certificate flashed right on the device. It is independant of the key pairs we generated earlier with `Smart Card Shell`. Those certificates will still be present on the device even in case of a renitialization, but flashing the device will erase them. + + +Signing with the root CA +------------------------ + +There are basically three things you might want to do with this root CA: + +- signing intermediate CA +- revoking intermediate CA +- updating the revocation list + +Before anything, make sure your HSM arer connected and authenticated as described earlier at section "Using the CA HSM". + +### Sign an intermediate CA + +This requires you already have a `.csr` for the intermediate CA you intend to sign. + +In the navigation bar, go to Home / Request Certificate (PKCS #10). Then: + +- pick the root CA and click on "Start Request" +- click on "Browse", pick the `.csr` file +- click on "Upload" +- review the settings. Name can be changed but that's no obligation. +- click on "Save", then on "Submit" +- as a "registration officer", approve your own request + +In the navigation bar, go to Views / Service Requests. Then: + +- as a "certification officer", click the ID matching the line with "PKCS10ServiceRequest" et "Produce" +- review the request +- click on "Issue Certificate" +- click on "Accept Certificate" + +### Intermediate CA certificate export + +In the certificate list, click on the intermediate authority name. At the bottom of the page, use the "Download Certificate" button. + +And voilà! You can return this certificate to the person in charge of this intermediate CA. + +### Revoke an intermediate CA + +From the home page, find the line "Request Certificate" matching the intermediate CA to revoke. Click on it. + +Verify the certificate description, and if you are sure confirm by clicking "Revoke Certificate". + +### Update certificate revocation list + +Each time a certificate is revoked, or when the CRL reaches its end of life, a new CRL must be signed. + +In the navigation bar, go to Views / Subjects, then click on your TrustCenter ID. + +In the navigation bar, click on CA / Issue CRL, then: + +- click on "Start Request" +- select your root CA +- click on "Select" +- click on "Issue" + +The new crl can be fetched by clicking "Download CRL", or through the command line: + +``` +wget http:///sr/crl/1 -O root-ca.crl +``` + +CRL content can be displayed with openssl: + +``` +openssl crl -in root-ca.crl -text -noout +``` + diff --git a/source/components/nitrokeys/hsm/smart-card-shell.md b/source/components/nitrokeys/hsm/smart-card-shell.md new file mode 100644 index 0000000000..15c643a5f7 --- /dev/null +++ b/source/components/nitrokeys/hsm/smart-card-shell.md @@ -0,0 +1,160 @@ +Smart Card Shell +================ + +Installation +------------ + +Install dependencies on your computer. For a host running Debian 12, you'll need: + +- a desktop environment (like `gnome-shell`) +- a java runtime `openjdk-17-jre` + +Visit the [Smart Card Shell project page](https://www.openscdp.org/scsh3/download.html) and grab the file archive. + +Extract it wherever you want. + +Launch `scsh3gui`. + + +Prepare personnal HSM +--------------------- + +Personnal HSM will be used for authentication. + +### Initialize the personnal HSM + +Plug the device in. In Smart Card Shell, click on File / Key Manager. + +Our HSM should appear in the left pane, as well as in the text shell in the middle of the windows. + +Note: if you encounter a "GPError" instead of seeing the HSM, restart the program. + +Right click on the device, then left click on "Initialize Device". Fill in the following: + +``` +Enter Initialization Code (SO-PIN): +Define a label: hsm_ +Define a provisioning URL (Optional): + +Select authentication mechanism: User PIN +Allow RESET RETRY COUNTER: Resetting and unblocking PIN with SO-PIN not allowed +Enter new User_PIN (leave empty to generate random PIN): +``` +``` +Select Device Key Encryption scheme: No DKEK +``` +``` +keep a profile on disk to save the PINs ?: No +``` + +### Generate and export authentication keys + +Now that our device has been initialized, we can generate the key pair that will be used to authenticate the key custodian. + +In the left pane, right click on the HSM, then left click on "Generate ECC key". Fill in the following: + +``` +Curve: brainpoolP256r1 (beware! signature must not exceed 256 bits or authentication will fail) +key label: key_ +possible algorithms for ECC key: +``` + +Once the key pair has been generated, find the left pane again and : + +- unfold the key object +- right click on the certificate and "export publick key" + +We obtain a file whose extension is `.pka`. We will later upload it to the CA HSM as part of our authorized keys for our m-of-n authentication. + +### Repeat + +Unplug the device and repeat operations until all public keys have been exported. + + +Prepare CA HSM +-------------- + +CA HSM will have very different settings than personnal HSM. + +### Initialize the CA HSM + +Plug in the device that will host your CA. In Smart Card Shell, click on File / Key Manager. + +In the left pane, right click on the HSM, then left click on "initialize device". Fill in the following: + +``` +Initialization Code (SO-PIN): +label: hsm_ +provisioning URL: + +authentication mechanism: Public Key Authentication +total number of public keys: 5 +number of public keys required: 3 +allow replacing registered public keys: Yes + +device key encryption scheme: DKEK Shares ( No DKEK | Randomly generated DKEK | DKEK Shares | Key domains ) +number of DKEK shares: 1 +keep a profile on disk to save the PINs ?: No +``` + +Our HSM has been initialized. + +### Register authorized keys + +In the left pane, right click on the number of missing keys, then left click on "register public key". + +Click on "Browse", set the filter to "all file types", then pick one of the `.pka` files. Click on "yes" to confirm. + +Reiterate until all pubkeys have been added to the authorized keys. + +Our HSM will now require 3 out of 5 key custodians to sign in before letting us use our root CA. + +### Pubkey authentication + +Beware not to unplug the CA HSM during this procedure. It is ok (and probably necessary, unless you have many USB ports) to un/plug personnal HSM one after the other. + +While the CA HSM is still plugged in, plug one personnal HSM in a free port. + +In the left pane, right click on the number of public keys authenticated, then left click on "Authenticate with Public Key". + +A list of card readers is shown. Pick the one with position "01 00". The program will ask us for a key, and we should find it in the list under the label "key_". Ask the key custodian to enter their PIN. + +Once this is done, the counter is incremented by 1. Reiterate the procedure until quorum is reached. + +### Generate DKEK + +Device Key Encryption Key (DKEK) will allow us to backup our CA to a second HSM, in order to avoid Single Point of Failures (SPOF). As it is very sensitive, the DKEK will be protected by Shamirs's Secret Sharing. For convenience, we will split the DKEK with the same m-of-n scheme, and distribute a part of the secret to each custodian. You might distribute the secrets to very different people than the key custodians though, as no personnal HSM will not be involved here. + +Left pane, right click on the HSM, left click on "Create DKEK share". Then fill in: + +``` +DKEK Share Format: Create DKEK Share as File (n-of-m) +File name for DKEK Share: hsm__dkek.pbe +total number of shares: 5 +number of shares required: 3 +``` + +For each part, take care to write down the exact content and distribute it to its custodian. + +### Import DKEK + +The `.pbe` file we just obtained MUST be imported on all devices that will contain the root CA, including the device used to generate the file! + +In the left pane, right click on "DKEK set-up in progress", then left click on "Import DKEK Share". Fill in the following: + +``` +DKEK Share Format: Import DKEK Share from File (n-of-m) +file name containing DKEK share: _dkek.pbe> +number of shares to enter: 5 +enter prime: +``` + +Thanks to this, we will later be able to export our CA key pair in an encrypted container, and reimport it on other HSM which share the same DKEK. + + +Generate CA +----------- + +Smart Card Shell does allow to generate key pair, but this step must be done through PKIAAS. + +[Build your PKI with PKIAAS](pkiaas) From 190b513ba805f3c25bda31b15cbcd017fa72b986 Mon Sep 17 00:00:00 2001 From: Mathieu Jourdan Date: Wed, 19 Mar 2025 14:42:44 +0100 Subject: [PATCH 3/7] export from markdown to rst --- .../hsm/getting-started-with-pkiaas.rst | 69 +++ source/components/nitrokeys/hsm/pkiaas.rst | 457 ++++++++++++++++++ .../nitrokeys/hsm/smart-card-shell.rst | 203 ++++++++ 3 files changed, 729 insertions(+) create mode 100644 source/components/nitrokeys/hsm/getting-started-with-pkiaas.rst create mode 100644 source/components/nitrokeys/hsm/pkiaas.rst create mode 100644 source/components/nitrokeys/hsm/smart-card-shell.rst diff --git a/source/components/nitrokeys/hsm/getting-started-with-pkiaas.rst b/source/components/nitrokeys/hsm/getting-started-with-pkiaas.rst new file mode 100644 index 0000000000..716005f332 --- /dev/null +++ b/source/components/nitrokeys/hsm/getting-started-with-pkiaas.rst @@ -0,0 +1,69 @@ +Getting started with PKIAAS +=========================== + +This guide describes how to set up a PKI made of : + +- an offline root CA, used only to sign intermediate CAs and revocation + list. It is kept secure on a HSM. +- intermediate CAs, used for automatic certificate delivery through + online services (like ADCS, EJBCA, OpenBao, and so on). Those have a + higher risk of compromission as they are not kept secure on a HSM. + +Security considerations +----------------------- + +In order to keep access to our CA in case the HSM is lost or faulty, we +will backup the material to a secondary HSM. We will protect ourselves +from unauthorized copying, by using shared control over key replication, +with an m-of-n scheme. A secret will be split and shared between key +custodians. + +We also want to have shared control over the use of the CA, so we will +also rely upon a m-of-n scheme, with pubkeys authentication. Pubkey +authentication will be possible by the mean of personnal HSM devices +distributed to key custodians. + +One thing to do is to define how many people will be involved in those +m-of-n schemes, and what is the quorum to reach. We suggest the number +of required parts to be greater than the number to additional parts. A +quorum of 3 people needed out of 5 key custodians is a common ration. + +Requirements +------------ + +The following devices will be involved: + +- two Nitrokey HSM 2 for the root CA and its backup +- five Nitrokey HSM 2 for personnal authentication +- we also suggest to keep one spare device, just in case + +Our setup will involve: + +- the certificate operator personnal machine, to run + + - SmartCard Shell, a java based graphical user interface to + initialize the devices + - OCF, to connect your HSM devices to the remote CA web app + +- a docker server, on which will be deployed + + - PKIAAS, a java based web app to sign the root CA and deliver + intermediate certificates + +Both SmartCard Shell and PKIAAS are developped by CardContact, the +company that makes the chip embedded in Nitrokey HSM 2. Details on how +to install this software will be given later in this guide. + +Procedure +--------- + +From now on, we will speak of “personnal HSM” and “CA HSM” because of +their distinct purposes. + +The following guide will involve a ``certificate operator``, in charge +of doing the technical steps, and ``key custodians``, whom will have to +enter their PIN when required. + +`Prepare your HSM with Smart Card Shell `__ + +`Build your PKI with PKIAAS `__ diff --git a/source/components/nitrokeys/hsm/pkiaas.rst b/source/components/nitrokeys/hsm/pkiaas.rst new file mode 100644 index 0000000000..258b3673bd --- /dev/null +++ b/source/components/nitrokeys/hsm/pkiaas.rst @@ -0,0 +1,457 @@ +PKIAAS +====== + +For a description of PKIAAS, please see the `release +announcement `__. + +A middleware will also be needed to connect your HSM plugged in your +local computer to the remote PKIAAS server, see this `OpenCard Framework +description `__. + +Installation +------------ + +client configuration +~~~~~~~~~~~~~~~~~~~~ + +We will need: + +- a web browser to access the PKIAAS interface +- a jar file of the Open Card Framework (OCF) + +Download ocf-cc.jar from the `OpenSCDP +website `__. + +PKIAAS server +~~~~~~~~~~~~~ + +We will be using the `docker +installation `__. + +On a Debian 12 host: + +:: + + sudo apt install git + sudo apt install docker.io + sudo apt install iptables-legacy + sudo update-alternatives --config iptables + sudo service docker start + +Fetch the docker deployment resources: + +:: + + git clone https://github.com/CardContact/deploy-pki-as-a-service.git + cd deploy-pki-as-a-service + +By the time of writing this guide, PKIAAS doesn’t support setting +arbitrary CRL endpoint, and doesn’t handle OCSP at all. At most, we can +set in a configuration file the Fully Qualified Domain Name (FQDN) +behind which the crl will later be found. + +Copy the application configuration file, and edit it to change de +“serverURL” - amongs other settings - according to your needs: + +:: + + cp pkiaas/etc/template/configuration.js env/etc/configuration.js + vim env/etc/configuration.js + +:: + + Config.global = { + serverURL: "{{ pkiaas_global_server_url }}", + allowResetDB: false, + allowDevHSM: false + } + +Edit docker-compose.yml so that: + +- the configuration file is loaded read-only as a volume, instead of + building additional layers at each configuration change +- container is linked to two ports of our host + + - port 80 is needed for the CRL endpoint to look like + http:///se/crl/1 + - port 8080 is needed for OCF to successfully connect personnal HSM + to http://localhost:8080/rt + +:: + + vim docker-compose.yml + +:: + + volumes: + - logs:/usr/share/pkiaas/logs + - ./pkiaas/etc/configuration.js:/usr/share/pkiaas/etc/configuration.js:ro + pkiaas-test: + ports: + - 80:8080 + - 8080:8080 + +We’re good to go + +:: + + docker-compose up + +Usage +----- + +Access to the portal +~~~~~~~~~~~~~~~~~~~~ + +Open your web browser to http:// + +Listing devices +~~~~~~~~~~~~~~~ + +As before we will be dealing with to kind of HSM: + +- CA HSM to protect the root CA +- personnal HSM to perform authentication + +Use ``-l`` option of ocf-cc.jar to list the HSM plugged in your +computer: + +:: + + > java -jar ocf-cc.jar -l + SLF4J: No SLF4J providers were found. + SLF4J: Defaulting to no-operation (NOP) logger implementation + SLF4J: See https://www.slf4j.org/codes.html#noProviders for further details. + OCF1.2;IBM Reference Implementation with OpenSCDP extensions 2.0.2.0.35 + Available card terminals: + Nitrokey Nitrokey HSM 0 + +TrustCenter preparation +----------------------- + +Account activation +~~~~~~~~~~~~~~~~~~ + +This step is required only the first time we connect to PKIAAS. + +For now, we will only plug in the PKIAAS admin’s personnal HSM. + +:: + + java -jar ocf-cc.jar -r "Nitrokey Nitrokey HSM 0" -v + +In the web browser, reload the page. A java window appears asking for +the PIN of the HSM. Type it in and confirm. + +An e-mail adress is asked. Give yours, and you should receive and +activation code. You might as well check out your docker logs to find +the same code. + +Enter the activation code when asked, tick the checkboxes you woul’d +like for your notification preferences, and click “Submit”. + +Now we see the home page. + +TrustCenter creation +~~~~~~~~~~~~~~~~~~~~ + +Before we are able to actually manage our CA, we have to create a +“TrustCenter”. In the navigation bar, click on Home / Create Trust +Center Subject. + +The different roles available in PKIAAS are described. Here is an +excerpt: + + When creating a TrustCenter three roles are created and initially + assigned to the person creating the TrustCenter: + + -TrustCenter Manager - responsible for managing roles. -TrustCenter + Operator - responsible for operating the TrustCenter -Registration + Officer - responsible for processing certification requests. + -Certification Officer - responsible for managing keys and issuing + certificates. + + As part of this service request you can assign a SmartCard-HSM token + to the TrustCenter. Assigning a SmartCard-HSM is important to + establish a link between the HSM’s identity and the TrustCenter, so + that when the SmartCard-HSM is remotely connected, it can be + correctly allocated to the entity. Multiple HSMs can be assigned and + assigments can be withdrawn by opening the service request again. + +For our use cases, all roles will be given to the same person. + +Click on “Start Request”, then fill in the form: + +:: + + Unique Name : + Operation Mode : Private + +Click on “Save”, then on “Submit”. + +CA device registration +~~~~~~~~~~~~~~~~~~~~~~ + +We have to tell to PKIAAS which device to use for our CA. + +- stop the ocf client +- unplug the personnal HSM +- plug the CA HSM +- connect the CA HSM with the following command: + ``java -jar ocf-cc.jar -r "Nitrokey Nitrokey HSM 0" -v`` + +On the home page: + +- click on “Create TrustCenter Subjet ()” +- keep “operation mode” set to “private” +- click on “Add Token” + +Do the same with the second HSM you have to backup your CA! + +Now you can stop the OCF, as we will have to use a different URL to +connect the CA HSM to PKIAAS. + +Using the CA HSM +---------------- + +This steps will allow key custodians to authenticate against the CA HSM, +wich will be necessary to do anything useful with the device. + +Connecting HSM +~~~~~~~~~~~~~~ + +From now on, We’ll keep the CA HSM plugged most of the time, while we +will have to frequently plug and unplugg personnal HSM. In order to +avoid confusion and connectivity issues, we recommend the run two +sessions of OCF in parallel. + +Always connect your CA device first: + +- make sure no HSM is currently plugged in +- plug your CA HSM, so it will be detected as “Nitrokey Nitrokey HSM 0” +- connect your CA HSM with + ``java -jar ocf-cc.jar -r "Nitrokey Nitrokey HSM 0" http:///rt/hsm`` + +When you’ll have to perform authentication, do like so: + +- plug the personnal HSM that will be used for authentication, so it + will be detected as “Nitrokey Nitrokey HSM 1” +- connect the deivce with + ``java -jar ocf-cc.jar -r "Nitrokey Nitrokey HSM 1" -v`` + +M-of-n authentication +~~~~~~~~~~~~~~~~~~~~~ + +In the navigation bar, go to Views / Subjects. In the table, dind your +TrustCenter and click on its ID at the beggining of the line. + +If necessary, reload the page. There is a line showing your CA device, +with the numbers of public keys currently authenticated. + +Click on “Authenticate”, then - plug one of the personnal HSM - reload +the page - if the CA HSM is shown instead of the personnal HSM, click on +“Enumerate key” - pick the key used for authentication (it is +recognizable by its label) - click on “Authenticate” - ask the key +custodian to enter their PIN in the java windows - unplug the personnal +HSM. + +Reiterate until the quorum is reached. There, the “Authenticate” button +will be replaced by a “Logout” button. Do not click on it! + +Root CA creation +---------------- + +Root CA request and signature +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the navigation bar, go to Views / Subjects, then click on your +TrustCenter ID. + +In the navigation bar, a new section appears. Click on CA / Create +Signer, then on “Start Request”. Fill in the form: + +:: + + Issuing CA: Self-signed Root CA (this value can't be changed) + Trust Center: (this value can't be changed) + +:: + + ### CA Certificate Definitions + Expires after (days): 4380 (root CA will be valid for 12 years) + Subordinate CAs: 1 (one level of intermediate CA will be allowed) + + ### Certification Authority Data + Distinguished Name: C = , ST = , L = , O = , OU = , CN = + + ### Key Specification + Key Specification: EC secp384r1 SHA-256 + + ### Subject certificate Definitions + Key Specification: EC secp384r1 SHA-256 + Expires after (days): 1825 (intermediate CA will be valid for 5 years) + Subject DN Rule: c=${issuer.c},st=${issuer.st},l=${issuer.l},o=${issuer.o},cn=${servicerequest.commonName} + upported Profiles: SubCA / TLSServer / TLSClient / EmailAndTLSClient + + ### CRL Definitions + Expires after: 365 (key custodians will meet at least once a year to sign a new certificate revocation list) + +If the CA HSM is plugged in and pubkeys authentication went well, then +we can: + +- click on “Save” +- click on “Submit” +- click on “Create Signer” + +The HSM lights up and a first entry appears in the list of certificates +on screen. Congratulations, your root CA has just been created! + +Root CA certificate export +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the navigation bar, go to Subjects / TrustCenter. + +The root CA should be visible here. Click on it. Certificate details are +shown. At the bottom of the page, click on “Download Certificate”. + +This is the file your machines will have to trust to verify the +certificates delivered by your external intermediate CA. + +Sharing access to PKIAAS +------------------------ + +Allow additionnal personnal HSM to access the CA +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The first personnal HSM you used to connect to PKIAAS has been +registered with the TrustCenter. To avoid the risk of being locked out, +it’s best to give access to a second key custodian. + +In the navigation bar, go to Views / Subjects, and click on the ID of +the TrustCenter. + +In the navigation bar, a “CA” menu appears. Click it, then “Enroll +person”. + +On the new page, click on “Start Request”, then fill in the form: + +:: + + Name: + email: + CA: + +- click on “Create” +- replace the device currently plugged in with the device to register +- click on “Identify token” +- a HSM ID should appear, looking similar to + /DESRCACC1/DEDINK01/DENK0105102 +- if this device is not authenticated, restart the OCF client and + reload the web page +- click on “Save” + +Associate the personnal HSM with the relevant roles +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Now, the device must be given the right permissions to actually being +able to sign the certificates. + +In the navigation bar, click on View / Subjects, then click on the ID +right before the newly registered custodian. + +In the navigation bar, a “Subject” menu appears. Click on it, then +“Manage role”. On the new page: + +- click on “Start Request” +- select all roles +- click on “Save” +- click on “Apply”. + +Note: authentication relies upon a certificate flashed right on the +device. It is independant of the key pairs we generated earlier with +``Smart Card Shell``. Those certificates will still be present on the +device even in case of a renitialization, but flashing the device will +erase them. + +Signing with the root CA +------------------------ + +There are basically three things you might want to do with this root CA: + +- signing intermediate CA +- revoking intermediate CA +- updating the revocation list + +Before anything, make sure your HSM arer connected and authenticated as +described earlier at section “Using the CA HSM”. + +Sign an intermediate CA +~~~~~~~~~~~~~~~~~~~~~~~ + +This requires you already have a ``.csr`` for the intermediate CA you +intend to sign. + +In the navigation bar, go to Home / Request Certificate (PKCS #10). +Then: + +- pick the root CA and click on “Start Request” +- click on “Browse”, pick the ``.csr`` file +- click on “Upload” +- review the settings. Name can be changed but that’s no obligation. +- click on “Save”, then on “Submit” +- as a “registration officer”, approve your own request + +In the navigation bar, go to Views / Service Requests. Then: + +- as a “certification officer”, click the ID matching the line with + “PKCS10ServiceRequest” et “Produce” +- review the request +- click on “Issue Certificate” +- click on “Accept Certificate” + +Intermediate CA certificate export +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the certificate list, click on the intermediate authority name. At +the bottom of the page, use the “Download Certificate” button. + +And voilà! You can return this certificate to the person in charge of +this intermediate CA. + +Revoke an intermediate CA +~~~~~~~~~~~~~~~~~~~~~~~~~ + +From the home page, find the line “Request Certificate” matching the +intermediate CA to revoke. Click on it. + +Verify the certificate description, and if you are sure confirm by +clicking “Revoke Certificate”. + +Update certificate revocation list +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each time a certificate is revoked, or when the CRL reaches its end of +life, a new CRL must be signed. + +In the navigation bar, go to Views / Subjects, then click on your +TrustCenter ID. + +In the navigation bar, click on CA / Issue CRL, then: + +- click on “Start Request” +- select your root CA +- click on “Select” +- click on “Issue” + +The new crl can be fetched by clicking “Download CRL”, or through the +command line: + +:: + + wget http:///sr/crl/1 -O root-ca.crl + +CRL content can be displayed with openssl: + +:: + + openssl crl -in root-ca.crl -text -noout diff --git a/source/components/nitrokeys/hsm/smart-card-shell.rst b/source/components/nitrokeys/hsm/smart-card-shell.rst new file mode 100644 index 0000000000..4015ce1a20 --- /dev/null +++ b/source/components/nitrokeys/hsm/smart-card-shell.rst @@ -0,0 +1,203 @@ +Smart Card Shell +================ + +Installation +------------ + +Install dependencies on your computer. For a host running Debian 12, +you’ll need: + +- a desktop environment (like ``gnome-shell``) +- a java runtime ``openjdk-17-jre`` + +Visit the `Smart Card Shell project +page `__ and grab the file +archive. + +Extract it wherever you want. + +Launch ``scsh3gui``. + +Prepare personnal HSM +--------------------- + +Personnal HSM will be used for authentication. + +Initialize the personnal HSM +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Plug the device in. In Smart Card Shell, click on File / Key Manager. + +Our HSM should appear in the left pane, as well as in the text shell in +the middle of the windows. + +Note: if you encounter a “GPError” instead of seeing the HSM, restart +the program. + +Right click on the device, then left click on “Initialize Device”. Fill +in the following: + +:: + + Enter Initialization Code (SO-PIN): + Define a label: hsm_ + Define a provisioning URL (Optional): + + Select authentication mechanism: User PIN + Allow RESET RETRY COUNTER: Resetting and unblocking PIN with SO-PIN not allowed + Enter new User_PIN (leave empty to generate random PIN): + +:: + + Select Device Key Encryption scheme: No DKEK + +:: + + keep a profile on disk to save the PINs ?: No + +Generate and export authentication keys +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Now that our device has been initialized, we can generate the key pair +that will be used to authenticate the key custodian. + +In the left pane, right click on the HSM, then left click on “Generate +ECC key”. Fill in the following: + +:: + + Curve: brainpoolP256r1 (beware! signature must not exceed 256 bits or authentication will fail) + key label: key_ + possible algorithms for ECC key: + +Once the key pair has been generated, find the left pane again and : + +- unfold the key object +- right click on the certificate and “export publick key” + +We obtain a file whose extension is ``.pka``. We will later upload it to +the CA HSM as part of our authorized keys for our m-of-n authentication. + +Repeat +~~~~~~ + +Unplug the device and repeat operations until all public keys have been +exported. + +Prepare CA HSM +-------------- + +CA HSM will have very different settings than personnal HSM. + +Initialize the CA HSM +~~~~~~~~~~~~~~~~~~~~~ + +Plug in the device that will host your CA. In Smart Card Shell, click on +File / Key Manager. + +In the left pane, right click on the HSM, then left click on “initialize +device”. Fill in the following: + +:: + + Initialization Code (SO-PIN): + label: hsm_ + provisioning URL: + + authentication mechanism: Public Key Authentication + total number of public keys: 5 + number of public keys required: 3 + allow replacing registered public keys: Yes + + device key encryption scheme: DKEK Shares ( No DKEK | Randomly generated DKEK | DKEK Shares | Key domains ) + number of DKEK shares: 1 + keep a profile on disk to save the PINs ?: No + +Our HSM has been initialized. + +Register authorized keys +~~~~~~~~~~~~~~~~~~~~~~~~ + +In the left pane, right click on the number of missing keys, then left +click on “register public key”. + +Click on “Browse”, set the filter to “all file types”, then pick one of +the ``.pka`` files. Click on “yes” to confirm. + +Reiterate until all pubkeys have been added to the authorized keys. + +Our HSM will now require 3 out of 5 key custodians to sign in before +letting us use our root CA. + +Pubkey authentication +~~~~~~~~~~~~~~~~~~~~~ + +Beware not to unplug the CA HSM during this procedure. It is ok (and +probably necessary, unless you have many USB ports) to un/plug personnal +HSM one after the other. + +While the CA HSM is still plugged in, plug one personnal HSM in a free +port. + +In the left pane, right click on the number of public keys +authenticated, then left click on “Authenticate with Public Key”. + +A list of card readers is shown. Pick the one with position “01 00”. The +program will ask us for a key, and we should find it in the list under +the label “key\_”. Ask the key custodian to enter their PIN. + +Once this is done, the counter is incremented by 1. Reiterate the +procedure until quorum is reached. + +Generate DKEK +~~~~~~~~~~~~~ + +Device Key Encryption Key (DKEK) will allow us to backup our CA to a +second HSM, in order to avoid Single Point of Failures (SPOF). As it is +very sensitive, the DKEK will be protected by Shamirs’s Secret Sharing. +For convenience, we will split the DKEK with the same m-of-n scheme, and +distribute a part of the secret to each custodian. You might distribute +the secrets to very different people than the key custodians though, as +no personnal HSM will not be involved here. + +Left pane, right click on the HSM, left click on “Create DKEK share”. +Then fill in: + +:: + + DKEK Share Format: Create DKEK Share as File (n-of-m) + File name for DKEK Share: hsm__dkek.pbe + total number of shares: 5 + number of shares required: 3 + +For each part, take care to write down the exact content and distribute +it to its custodian. + +Import DKEK +~~~~~~~~~~~ + +The ``.pbe`` file we just obtained MUST be imported on all devices that +will contain the root CA, including the device used to generate the +file! + +In the left pane, right click on “DKEK set-up in progress”, then left +click on “Import DKEK Share”. Fill in the following: + +:: + + DKEK Share Format: Import DKEK Share from File (n-of-m) + file name containing DKEK share: _dkek.pbe> + number of shares to enter: 5 + enter prime: + +Thanks to this, we will later be able to export our CA key pair in an +encrypted container, and reimport it on other HSM which share the same +DKEK. + +Generate CA +----------- + +Smart Card Shell does allow to generate key pair, but this step must be +done through PKIAAS. + +`Build your PKI with PKIAAS `__ From 059382bbd43f19fb4e6120cf66b27792a092f76c Mon Sep 17 00:00:00 2001 From: Mathieu Jourdan Date: Wed, 19 Mar 2025 15:42:31 +0100 Subject: [PATCH 4/7] delete markdown files --- .../hsm/getting-started-with-pkiaas.md | 49 --- source/components/nitrokeys/hsm/pkiaas.md | 376 ------------------ .../nitrokeys/hsm/smart-card-shell.md | 160 -------- 3 files changed, 585 deletions(-) delete mode 100644 source/components/nitrokeys/hsm/getting-started-with-pkiaas.md delete mode 100644 source/components/nitrokeys/hsm/pkiaas.md delete mode 100644 source/components/nitrokeys/hsm/smart-card-shell.md diff --git a/source/components/nitrokeys/hsm/getting-started-with-pkiaas.md b/source/components/nitrokeys/hsm/getting-started-with-pkiaas.md deleted file mode 100644 index ec45d81d5d..0000000000 --- a/source/components/nitrokeys/hsm/getting-started-with-pkiaas.md +++ /dev/null @@ -1,49 +0,0 @@ -Getting started with PKIAAS -=========================== - -This guide describes how to set up a PKI made of : - -- an offline root CA, used only to sign intermediate CAs and revocation list. It is kept secure on a HSM. -- intermediate CAs, used for automatic certificate delivery through online services (like ADCS, EJBCA, OpenBao, and so on). Those have a higher risk of compromission as they are not kept secure on a HSM. - - -Security considerations ------------------------ - -In order to keep access to our CA in case the HSM is lost or faulty, we will backup the material to a secondary HSM. We will protect ourselves from unauthorized copying, by using shared control over key replication, with an m-of-n scheme. A secret will be split and shared between key custodians. - -We also want to have shared control over the use of the CA, so we will also rely upon a m-of-n scheme, with pubkeys authentication. Pubkey authentication will be possible by the mean of personnal HSM devices distributed to key custodians. - -One thing to do is to define how many people will be involved in those m-of-n schemes, and what is the quorum to reach. We suggest the number of required parts to be greater than the number to additional parts. A quorum of 3 people needed out of 5 key custodians is a common ration. - - -Requirements ------------- - -The following devices will be involved: - -- two Nitrokey HSM 2 for the root CA and its backup -- five Nitrokey HSM 2 for personnal authentication -- we also suggest to keep one spare device, just in case - -Our setup will involve: - -- the certificate operator personnal machine, to run - - SmartCard Shell, a java based graphical user interface to initialize the devices - - OCF, to connect your HSM devices to the remote CA web app -- a docker server, on which will be deployed - - PKIAAS, a java based web app to sign the root CA and deliver intermediate certificates - -Both SmartCard Shell and PKIAAS are developped by CardContact, the company that makes the chip embedded in Nitrokey HSM 2. Details on how to install this software will be given later in this guide. - - -Procedure ---------- - -From now on, we will speak of "personnal HSM" and "CA HSM" because of their distinct purposes. - -The following guide will involve a `certificate operator`, in charge of doing the technical steps, and `key custodians`, whom will have to enter their PIN when required. - -[Prepare your HSM with Smart Card Shell](smart-card-shell) - -[Build your PKI with PKIAAS](pkiaas) diff --git a/source/components/nitrokeys/hsm/pkiaas.md b/source/components/nitrokeys/hsm/pkiaas.md deleted file mode 100644 index a518f0e036..0000000000 --- a/source/components/nitrokeys/hsm/pkiaas.md +++ /dev/null @@ -1,376 +0,0 @@ -PKIAAS -====== - -For a description of PKIAAS, please see the [release announcement](https://www.smartcard-hsm.com/2018/02/13/pki-as-a-service.html). - -A middleware will also be needed to connect your HSM plugged in your local computer to the remote PKIAAS server, see this [OpenCard Framework description](https://www.openscdp.org/ocf/index.html). - -Installation ------------- - -### client configuration - -We will need: - -- a web browser to access the PKIAAS interface -- a jar file of the Open Card Framework (OCF) - -Download ocf-cc.jar from the [OpenSCDP website](https://www.openscdp.org/ocf/ocf-cc.jar). - - -### PKIAAS server - -We will be using the [docker installation](https://github.com/CardContact/deploy-pki-as-a-service). - -On a Debian 12 host: - -``` -sudo apt install git -sudo apt install docker.io -sudo apt install iptables-legacy -sudo update-alternatives --config iptables -sudo service docker start -``` - -Fetch the docker deployment resources: - -``` -git clone https://github.com/CardContact/deploy-pki-as-a-service.git -cd deploy-pki-as-a-service -``` - -By the time of writing this guide, PKIAAS doesn't support setting arbitrary CRL endpoint, and doesn't handle OCSP at all. At most, we can set in a configuration file the Fully Qualified Domain Name (FQDN) behind which the crl will later be found. - -Copy the application configuration file, and edit it to change de "serverURL" - amongs other settings - according to your needs: - -``` -cp pkiaas/etc/template/configuration.js env/etc/configuration.js -vim env/etc/configuration.js -``` -``` -Config.global = { - serverURL: "{{ pkiaas_global_server_url }}", - allowResetDB: false, - allowDevHSM: false -} -``` - -Edit docker-compose.yml so that: - -- the configuration file is loaded read-only as a volume, instead of building additional layers at each configuration change -- container is linked to two ports of our host - - port 80 is needed for the CRL endpoint to look like http:///se/crl/1 - - port 8080 is needed for OCF to successfully connect personnal HSM to http://localhost:8080/rt - -``` -vim docker-compose.yml -``` -``` - volumes: - - logs:/usr/share/pkiaas/logs - - ./pkiaas/etc/configuration.js:/usr/share/pkiaas/etc/configuration.js:ro - pkiaas-test: - ports: - - 80:8080 - - 8080:8080 -``` - -We're good to go - -``` -docker-compose up -``` - - -Usage ------ - -### Access to the portal - -Open your web browser to http:// - -### Listing devices - -As before we will be dealing with to kind of HSM: - -- CA HSM to protect the root CA -- personnal HSM to perform authentication - -Use `-l` option of ocf-cc.jar to list the HSM plugged in your computer: - -``` -> java -jar ocf-cc.jar -l -SLF4J: No SLF4J providers were found. -SLF4J: Defaulting to no-operation (NOP) logger implementation -SLF4J: See https://www.slf4j.org/codes.html#noProviders for further details. -OCF1.2;IBM Reference Implementation with OpenSCDP extensions 2.0.2.0.35 -Available card terminals: - Nitrokey Nitrokey HSM 0 -``` - -TrustCenter preparation ------------------------ - -### Account activation - -This step is required only the first time we connect to PKIAAS. - -For now, we will only plug in the PKIAAS admin's personnal HSM. - -``` -java -jar ocf-cc.jar -r "Nitrokey Nitrokey HSM 0" -v -``` - -In the web browser, reload the page. A java window appears asking for the PIN of the HSM. Type it in and confirm. - -An e-mail adress is asked. Give yours, and you should receive and activation code. You might as well check out your docker logs to find the same code. - -Enter the activation code when asked, tick the checkboxes you woul'd like for your notification preferences, and click "Submit". - -Now we see the home page. - -### TrustCenter creation - -Before we are able to actually manage our CA, we have to create a "TrustCenter". In the navigation bar, click on Home / Create Trust Center Subject. - -The different roles available in PKIAAS are described. Here is an excerpt: - -> When creating a TrustCenter three roles are created and initially assigned to the person creating the TrustCenter: -> -> -TrustCenter Manager - responsible for managing roles. -> -TrustCenter Operator - responsible for operating the TrustCenter -> -Registration Officer - responsible for processing certification requests. -> -Certification Officer - responsible for managing keys and issuing certificates. -> -> As part of this service request you can assign a SmartCard-HSM token to the TrustCenter. Assigning a SmartCard-HSM is important to establish a link between the HSM's identity and the TrustCenter, so that when the SmartCard-HSM is remotely connected, it can be correctly allocated to the entity. Multiple HSMs can be assigned and assigments can be withdrawn by opening the service request again. - -For our use cases, all roles will be given to the same person. - -Click on "Start Request", then fill in the form: - -``` -Unique Name : -Operation Mode : Private -``` - -Click on "Save", then on "Submit". - -### CA device registration - -We have to tell to PKIAAS which device to use for our CA. - -- stop the ocf client -- unplug the personnal HSM -- plug the CA HSM -- connect the CA HSM with the following command: `java -jar ocf-cc.jar -r "Nitrokey Nitrokey HSM 0" -v` - -On the home page: - -- click on "Create TrustCenter Subjet ()" -- keep "operation mode" set to "private" -- click on "Add Token" - -Do the same with the second HSM you have to backup your CA! - -Now you can stop the OCF, as we will have to use a different URL to connect the CA HSM to PKIAAS. - - -Using the CA HSM ----------------- - -This steps will allow key custodians to authenticate against the CA HSM, wich will be necessary to do anything useful with the device. - -### Connecting HSM - -From now on, We'll keep the CA HSM plugged most of the time, while we will have to frequently plug and unplugg personnal HSM. In order to avoid confusion and connectivity issues, we recommend the run two sessions of OCF in parallel. - -Always connect your CA device first: - -- make sure no HSM is currently plugged in -- plug your CA HSM, so it will be detected as "Nitrokey Nitrokey HSM 0" -- connect your CA HSM with `java -jar ocf-cc.jar -r "Nitrokey Nitrokey HSM 0" http:///rt/hsm` - -When you'll have to perform authentication, do like so: - -- plug the personnal HSM that will be used for authentication, so it will be detected as "Nitrokey Nitrokey HSM 1" -- connect the deivce with `java -jar ocf-cc.jar -r "Nitrokey Nitrokey HSM 1" -v` - -### M-of-n authentication - -In the navigation bar, go to Views / Subjects. In the table, dind your TrustCenter and click on its ID at the beggining of the line. - -If necessary, reload the page. There is a line showing your CA device, with the numbers of public keys currently authenticated. - -Click on "Authenticate", then -- plug one of the personnal HSM -- reload the page -- if the CA HSM is shown instead of the personnal HSM, click on "Enumerate key" -- pick the key used for authentication (it is recognizable by its label) -- click on "Authenticate" -- ask the key custodian to enter their PIN in the java windows -- unplug the personnal HSM. - -Reiterate until the quorum is reached. There, the "Authenticate" button will be replaced by a "Logout" button. Do not click on it! - - -Root CA creation ----------------- - -### Root CA request and signature - -In the navigation bar, go to Views / Subjects, then click on your TrustCenter ID. - -In the navigation bar, a new section appears. Click on CA / Create Signer, then on "Start Request". Fill in the form: - -``` -Issuing CA: Self-signed Root CA (this value can't be changed) -Trust Center: (this value can't be changed) -``` -``` -### CA Certificate Definitions -Expires after (days): 4380 (root CA will be valid for 12 years) -Subordinate CAs: 1 (one level of intermediate CA will be allowed) - -### Certification Authority Data -Distinguished Name: C = , ST = , L = , O = , OU = , CN = - -### Key Specification -Key Specification: EC secp384r1 SHA-256 - -### Subject certificate Definitions -Key Specification: EC secp384r1 SHA-256 -Expires after (days): 1825 (intermediate CA will be valid for 5 years) -Subject DN Rule: c=${issuer.c},st=${issuer.st},l=${issuer.l},o=${issuer.o},cn=${servicerequest.commonName} -upported Profiles: SubCA / TLSServer / TLSClient / EmailAndTLSClient - -### CRL Definitions -Expires after: 365 (key custodians will meet at least once a year to sign a new certificate revocation list) -``` - -If the CA HSM is plugged in and pubkeys authentication went well, then we can: - -- click on "Save" -- click on "Submit" -- click on "Create Signer" - -The HSM lights up and a first entry appears in the list of certificates on screen. Congratulations, your root CA has just been created! - -### Root CA certificate export - -In the navigation bar, go to Subjects / TrustCenter. - -The root CA should be visible here. Click on it. Certificate details are shown. At the bottom of the page, click on "Download Certificate". - -This is the file your machines will have to trust to verify the certificates delivered by your external intermediate CA. - - -Sharing access to PKIAAS ------------------------- - -### Allow additionnal personnal HSM to access the CA - -The first personnal HSM you used to connect to PKIAAS has been registered with the TrustCenter. To avoid the risk of being locked out, it's best to give access to a second key custodian. - -In the navigation bar, go to Views / Subjects, and click on the ID of the TrustCenter. - -In the navigation bar, a "CA" menu appears. Click it, then "Enroll person". - -On the new page, click on "Start Request", then fill in the form: - -``` -Name: -email: -CA: -``` - -- click on "Create" -- replace the device currently plugged in with the device to register -- click on "Identify token" -- a HSM ID should appear, looking similar to /DESRCACC1/DEDINK01/DENK0105102 -- if this device is not authenticated, restart the OCF client and reload the web page -- click on "Save" - -### Associate the personnal HSM with the relevant roles - -Now, the device must be given the right permissions to actually being able to sign the certificates. - -In the navigation bar, click on View / Subjects, then click on the ID right before the newly registered custodian. - -In the navigation bar, a "Subject" menu appears. Click on it, then "Manage role". On the new page: - -- click on "Start Request" -- select all roles -- click on "Save" -- click on "Apply". - -Note: authentication relies upon a certificate flashed right on the device. It is independant of the key pairs we generated earlier with `Smart Card Shell`. Those certificates will still be present on the device even in case of a renitialization, but flashing the device will erase them. - - -Signing with the root CA ------------------------- - -There are basically three things you might want to do with this root CA: - -- signing intermediate CA -- revoking intermediate CA -- updating the revocation list - -Before anything, make sure your HSM arer connected and authenticated as described earlier at section "Using the CA HSM". - -### Sign an intermediate CA - -This requires you already have a `.csr` for the intermediate CA you intend to sign. - -In the navigation bar, go to Home / Request Certificate (PKCS #10). Then: - -- pick the root CA and click on "Start Request" -- click on "Browse", pick the `.csr` file -- click on "Upload" -- review the settings. Name can be changed but that's no obligation. -- click on "Save", then on "Submit" -- as a "registration officer", approve your own request - -In the navigation bar, go to Views / Service Requests. Then: - -- as a "certification officer", click the ID matching the line with "PKCS10ServiceRequest" et "Produce" -- review the request -- click on "Issue Certificate" -- click on "Accept Certificate" - -### Intermediate CA certificate export - -In the certificate list, click on the intermediate authority name. At the bottom of the page, use the "Download Certificate" button. - -And voilà! You can return this certificate to the person in charge of this intermediate CA. - -### Revoke an intermediate CA - -From the home page, find the line "Request Certificate" matching the intermediate CA to revoke. Click on it. - -Verify the certificate description, and if you are sure confirm by clicking "Revoke Certificate". - -### Update certificate revocation list - -Each time a certificate is revoked, or when the CRL reaches its end of life, a new CRL must be signed. - -In the navigation bar, go to Views / Subjects, then click on your TrustCenter ID. - -In the navigation bar, click on CA / Issue CRL, then: - -- click on "Start Request" -- select your root CA -- click on "Select" -- click on "Issue" - -The new crl can be fetched by clicking "Download CRL", or through the command line: - -``` -wget http:///sr/crl/1 -O root-ca.crl -``` - -CRL content can be displayed with openssl: - -``` -openssl crl -in root-ca.crl -text -noout -``` - diff --git a/source/components/nitrokeys/hsm/smart-card-shell.md b/source/components/nitrokeys/hsm/smart-card-shell.md deleted file mode 100644 index 15c643a5f7..0000000000 --- a/source/components/nitrokeys/hsm/smart-card-shell.md +++ /dev/null @@ -1,160 +0,0 @@ -Smart Card Shell -================ - -Installation ------------- - -Install dependencies on your computer. For a host running Debian 12, you'll need: - -- a desktop environment (like `gnome-shell`) -- a java runtime `openjdk-17-jre` - -Visit the [Smart Card Shell project page](https://www.openscdp.org/scsh3/download.html) and grab the file archive. - -Extract it wherever you want. - -Launch `scsh3gui`. - - -Prepare personnal HSM ---------------------- - -Personnal HSM will be used for authentication. - -### Initialize the personnal HSM - -Plug the device in. In Smart Card Shell, click on File / Key Manager. - -Our HSM should appear in the left pane, as well as in the text shell in the middle of the windows. - -Note: if you encounter a "GPError" instead of seeing the HSM, restart the program. - -Right click on the device, then left click on "Initialize Device". Fill in the following: - -``` -Enter Initialization Code (SO-PIN): -Define a label: hsm_ -Define a provisioning URL (Optional): - -Select authentication mechanism: User PIN -Allow RESET RETRY COUNTER: Resetting and unblocking PIN with SO-PIN not allowed -Enter new User_PIN (leave empty to generate random PIN): -``` -``` -Select Device Key Encryption scheme: No DKEK -``` -``` -keep a profile on disk to save the PINs ?: No -``` - -### Generate and export authentication keys - -Now that our device has been initialized, we can generate the key pair that will be used to authenticate the key custodian. - -In the left pane, right click on the HSM, then left click on "Generate ECC key". Fill in the following: - -``` -Curve: brainpoolP256r1 (beware! signature must not exceed 256 bits or authentication will fail) -key label: key_ -possible algorithms for ECC key: -``` - -Once the key pair has been generated, find the left pane again and : - -- unfold the key object -- right click on the certificate and "export publick key" - -We obtain a file whose extension is `.pka`. We will later upload it to the CA HSM as part of our authorized keys for our m-of-n authentication. - -### Repeat - -Unplug the device and repeat operations until all public keys have been exported. - - -Prepare CA HSM --------------- - -CA HSM will have very different settings than personnal HSM. - -### Initialize the CA HSM - -Plug in the device that will host your CA. In Smart Card Shell, click on File / Key Manager. - -In the left pane, right click on the HSM, then left click on "initialize device". Fill in the following: - -``` -Initialization Code (SO-PIN): -label: hsm_ -provisioning URL: - -authentication mechanism: Public Key Authentication -total number of public keys: 5 -number of public keys required: 3 -allow replacing registered public keys: Yes - -device key encryption scheme: DKEK Shares ( No DKEK | Randomly generated DKEK | DKEK Shares | Key domains ) -number of DKEK shares: 1 -keep a profile on disk to save the PINs ?: No -``` - -Our HSM has been initialized. - -### Register authorized keys - -In the left pane, right click on the number of missing keys, then left click on "register public key". - -Click on "Browse", set the filter to "all file types", then pick one of the `.pka` files. Click on "yes" to confirm. - -Reiterate until all pubkeys have been added to the authorized keys. - -Our HSM will now require 3 out of 5 key custodians to sign in before letting us use our root CA. - -### Pubkey authentication - -Beware not to unplug the CA HSM during this procedure. It is ok (and probably necessary, unless you have many USB ports) to un/plug personnal HSM one after the other. - -While the CA HSM is still plugged in, plug one personnal HSM in a free port. - -In the left pane, right click on the number of public keys authenticated, then left click on "Authenticate with Public Key". - -A list of card readers is shown. Pick the one with position "01 00". The program will ask us for a key, and we should find it in the list under the label "key_". Ask the key custodian to enter their PIN. - -Once this is done, the counter is incremented by 1. Reiterate the procedure until quorum is reached. - -### Generate DKEK - -Device Key Encryption Key (DKEK) will allow us to backup our CA to a second HSM, in order to avoid Single Point of Failures (SPOF). As it is very sensitive, the DKEK will be protected by Shamirs's Secret Sharing. For convenience, we will split the DKEK with the same m-of-n scheme, and distribute a part of the secret to each custodian. You might distribute the secrets to very different people than the key custodians though, as no personnal HSM will not be involved here. - -Left pane, right click on the HSM, left click on "Create DKEK share". Then fill in: - -``` -DKEK Share Format: Create DKEK Share as File (n-of-m) -File name for DKEK Share: hsm__dkek.pbe -total number of shares: 5 -number of shares required: 3 -``` - -For each part, take care to write down the exact content and distribute it to its custodian. - -### Import DKEK - -The `.pbe` file we just obtained MUST be imported on all devices that will contain the root CA, including the device used to generate the file! - -In the left pane, right click on "DKEK set-up in progress", then left click on "Import DKEK Share". Fill in the following: - -``` -DKEK Share Format: Import DKEK Share from File (n-of-m) -file name containing DKEK share: _dkek.pbe> -number of shares to enter: 5 -enter prime: -``` - -Thanks to this, we will later be able to export our CA key pair in an encrypted container, and reimport it on other HSM which share the same DKEK. - - -Generate CA ------------ - -Smart Card Shell does allow to generate key pair, but this step must be done through PKIAAS. - -[Build your PKI with PKIAAS](pkiaas) From d90368cdf23b9fa02a93ecea0a55738e6cf86ca3 Mon Sep 17 00:00:00 2001 From: jans23 Date: Wed, 19 Mar 2025 18:43:40 +0100 Subject: [PATCH 5/7] Update smart-card-shell.rst --- .../nitrokeys/hsm/smart-card-shell.rst | 52 +++++++++---------- 1 file changed, 24 insertions(+), 28 deletions(-) diff --git a/source/components/nitrokeys/hsm/smart-card-shell.rst b/source/components/nitrokeys/hsm/smart-card-shell.rst index 4015ce1a20..636099beef 100644 --- a/source/components/nitrokeys/hsm/smart-card-shell.rst +++ b/source/components/nitrokeys/hsm/smart-card-shell.rst @@ -7,29 +7,25 @@ Installation Install dependencies on your computer. For a host running Debian 12, you’ll need: -- a desktop environment (like ``gnome-shell``) -- a java runtime ``openjdk-17-jre`` +* A desktop environment (like ``gnome-shell``) +* A Java runtime ``openjdk-17-jre`` -Visit the `Smart Card Shell project -page `__ and grab the file -archive. +#. Visit the `Smart Card Shell project page `__ and grab the file archive. +#. Extract it wherever you want. +#. Launch ``scsh3gui``. -Extract it wherever you want. +Prepare Personal HSM +-------------------- -Launch ``scsh3gui``. +Personal HSM will be used for authentication. -Prepare personnal HSM ---------------------- +Initialize the Personal HSM +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Personnal HSM will be used for authentication. - -Initialize the personnal HSM -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Plug the device in. In Smart Card Shell, click on File / Key Manager. +Plug the device in. In the Smart Card Shell, click on File / Key Manager. Our HSM should appear in the left pane, as well as in the text shell in -the middle of the windows. +the middle of the window. Note: if you encounter a “GPError” instead of seeing the HSM, restart the program. @@ -40,7 +36,7 @@ in the following: :: Enter Initialization Code (SO-PIN): - Define a label: hsm_ + Define a label: hsm_ Define a provisioning URL (Optional): Select authentication mechanism: User PIN @@ -55,7 +51,7 @@ in the following: keep a profile on disk to save the PINs ?: No -Generate and export authentication keys +Generate and Export Authentication Keys ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Now that our device has been initialized, we can generate the key pair @@ -67,13 +63,13 @@ ECC key”. Fill in the following: :: Curve: brainpoolP256r1 (beware! signature must not exceed 256 bits or authentication will fail) - key label: key_ + key label: key_ possible algorithms for ECC key: -Once the key pair has been generated, find the left pane again and : +Once the key pair has been generated, find the left pane again and: -- unfold the key object -- right click on the certificate and “export publick key” +#. Unfold the key object +#. Right click on the certificate and “export publick key” We obtain a file whose extension is ``.pka``. We will later upload it to the CA HSM as part of our authorized keys for our m-of-n authentication. @@ -87,7 +83,7 @@ exported. Prepare CA HSM -------------- -CA HSM will have very different settings than personnal HSM. +CA HSM will have very different settings than personal HSM. Initialize the CA HSM ~~~~~~~~~~~~~~~~~~~~~ @@ -115,7 +111,7 @@ device”. Fill in the following: Our HSM has been initialized. -Register authorized keys +Register Authorized Keys ~~~~~~~~~~~~~~~~~~~~~~~~ In the left pane, right click on the number of missing keys, then left @@ -129,14 +125,14 @@ Reiterate until all pubkeys have been added to the authorized keys. Our HSM will now require 3 out of 5 key custodians to sign in before letting us use our root CA. -Pubkey authentication +Pubkey Authentication ~~~~~~~~~~~~~~~~~~~~~ Beware not to unplug the CA HSM during this procedure. It is ok (and -probably necessary, unless you have many USB ports) to un/plug personnal +probably necessary, unless you have many USB ports) to un/plug personal HSM one after the other. -While the CA HSM is still plugged in, plug one personnal HSM in a free +While the CA HSM is still plugged in, plug one personal HSM in a free port. In the left pane, right click on the number of public keys @@ -158,7 +154,7 @@ very sensitive, the DKEK will be protected by Shamirs’s Secret Sharing. For convenience, we will split the DKEK with the same m-of-n scheme, and distribute a part of the secret to each custodian. You might distribute the secrets to very different people than the key custodians though, as -no personnal HSM will not be involved here. +no personal HSM will not be involved here. Left pane, right click on the HSM, left click on “Create DKEK share”. Then fill in: From 453adc46a4031d0a219e1bf22a4ee762f8857a08 Mon Sep 17 00:00:00 2001 From: jans23 Date: Wed, 19 Mar 2025 18:44:03 +0100 Subject: [PATCH 6/7] Update getting-started-with-pkiaas.rst --- .../hsm/getting-started-with-pkiaas.rst | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/source/components/nitrokeys/hsm/getting-started-with-pkiaas.rst b/source/components/nitrokeys/hsm/getting-started-with-pkiaas.rst index 716005f332..a8f262b6be 100644 --- a/source/components/nitrokeys/hsm/getting-started-with-pkiaas.rst +++ b/source/components/nitrokeys/hsm/getting-started-with-pkiaas.rst @@ -1,15 +1,15 @@ -Getting started with PKIAAS -=========================== +Getting started with PKI-as-a-Service +===================================== This guide describes how to set up a PKI made of : -- an offline root CA, used only to sign intermediate CAs and revocation - list. It is kept secure on a HSM. -- intermediate CAs, used for automatic certificate delivery through - online services (like ADCS, EJBCA, OpenBao, and so on). Those have a - higher risk of compromission as they are not kept secure on a HSM. +* An offline root CA, used only to sign intermediate CAs and revocation + list. It is kept secure on a HSM. +* intermediate CAs, used for automatic certificate delivery through + online services (like ADCS, EJBCA, OpenBao, and so on). Those have a + higher risk of compromission as they are not kept secure on a HSM. -Security considerations +Security Considerations ----------------------- In order to keep access to our CA in case the HSM is lost or faulty, we @@ -20,7 +20,7 @@ custodians. We also want to have shared control over the use of the CA, so we will also rely upon a m-of-n scheme, with pubkeys authentication. Pubkey -authentication will be possible by the mean of personnal HSM devices +authentication will be possible by the mean of personal HSM devices distributed to key custodians. One thing to do is to define how many people will be involved in those @@ -34,30 +34,30 @@ Requirements The following devices will be involved: - two Nitrokey HSM 2 for the root CA and its backup -- five Nitrokey HSM 2 for personnal authentication +- five Nitrokey HSM 2 for personal authentication - we also suggest to keep one spare device, just in case Our setup will involve: -- the certificate operator personnal machine, to run +- the certificate operator personal machine, to run - - SmartCard Shell, a java based graphical user interface to + - SmartCard Shell, a Java based graphical user interface to initialize the devices - OCF, to connect your HSM devices to the remote CA web app -- a docker server, on which will be deployed +- a Docker server, on which will be deployed - - PKIAAS, a java based web app to sign the root CA and deliver + - PKIAAS, a Java based web app to sign the root CA and deliver intermediate certificates -Both SmartCard Shell and PKIAAS are developped by CardContact, the +Both SmartCard Shell and PKIAAS are developed by CardContact, the company that makes the chip embedded in Nitrokey HSM 2. Details on how to install this software will be given later in this guide. Procedure --------- -From now on, we will speak of “personnal HSM” and “CA HSM” because of +From now on, we will speak of “personal HSM” and “CA HSM” because of their distinct purposes. The following guide will involve a ``certificate operator``, in charge From b5f91d60da2ba7de6dd8285dfca900eec212ef2a Mon Sep 17 00:00:00 2001 From: jans23 Date: Wed, 19 Mar 2025 18:44:40 +0100 Subject: [PATCH 7/7] Update pkiaas.rst --- source/components/nitrokeys/hsm/pkiaas.rst | 217 ++++++++++----------- 1 file changed, 104 insertions(+), 113 deletions(-) diff --git a/source/components/nitrokeys/hsm/pkiaas.rst b/source/components/nitrokeys/hsm/pkiaas.rst index 258b3673bd..54010a993e 100644 --- a/source/components/nitrokeys/hsm/pkiaas.rst +++ b/source/components/nitrokeys/hsm/pkiaas.rst @@ -1,7 +1,7 @@ -PKIAAS -====== +PKI-as-a-Service +================ -For a description of PKIAAS, please see the `release +For a description of PKI-as-a-Service (PKIAAS), please see the `release announcement `__. A middleware will also be needed to connect your HSM plugged in your @@ -11,34 +11,32 @@ description `__. Installation ------------ -client configuration +Client Configuration ~~~~~~~~~~~~~~~~~~~~ We will need: -- a web browser to access the PKIAAS interface -- a jar file of the Open Card Framework (OCF) +* A web browser to access the PKIAAS interface +* A jar file of the Open Card Framework (OCF) Download ocf-cc.jar from the `OpenSCDP website `__. -PKIAAS server +PKIAAS Server ~~~~~~~~~~~~~ -We will be using the `docker +We will be using the `Docker installation `__. On a Debian 12 host: :: - sudo apt install git - sudo apt install docker.io - sudo apt install iptables-legacy + sudo apt install git docker.io iptables-legacy sudo update-alternatives --config iptables sudo service docker start -Fetch the docker deployment resources: +Fetch the Docker deployment resources: :: @@ -48,15 +46,15 @@ Fetch the docker deployment resources: By the time of writing this guide, PKIAAS doesn’t support setting arbitrary CRL endpoint, and doesn’t handle OCSP at all. At most, we can set in a configuration file the Fully Qualified Domain Name (FQDN) -behind which the crl will later be found. +behind which the CRL will later be found. -Copy the application configuration file, and edit it to change de +Copy the application configuration file, and edit it to change the “serverURL” - amongs other settings - according to your needs: :: cp pkiaas/etc/template/configuration.js env/etc/configuration.js - vim env/etc/configuration.js + editor env/etc/configuration.js :: @@ -68,18 +66,15 @@ Copy the application configuration file, and edit it to change de Edit docker-compose.yml so that: -- the configuration file is loaded read-only as a volume, instead of - building additional layers at each configuration change -- container is linked to two ports of our host +* The configuration file is loaded read-only as a volume, instead of building additional layers at each configuration change +* Container is linked to two ports of our host - - port 80 is needed for the CRL endpoint to look like - http:///se/crl/1 - - port 8080 is needed for OCF to successfully connect personnal HSM - to http://localhost:8080/rt + * port 80 is needed for the CRL endpoint to look like http:///se/crl/1 + * port 8080 is needed for OCF to successfully connect personal HSM to http://localhost:8080/rt :: - vim docker-compose.yml + editor docker-compose.yml :: @@ -100,18 +95,18 @@ We’re good to go Usage ----- -Access to the portal +Access to the Portal ~~~~~~~~~~~~~~~~~~~~ Open your web browser to http:// -Listing devices +Listing Devices ~~~~~~~~~~~~~~~ -As before we will be dealing with to kind of HSM: +As before we will be dealing with two kind of HSM: -- CA HSM to protect the root CA -- personnal HSM to perform authentication +* CA HSM to protect the root CA +* Personal HSM to perform authentication Use ``-l`` option of ocf-cc.jar to list the HSM plugged in your computer: @@ -126,33 +121,33 @@ computer: Available card terminals: Nitrokey Nitrokey HSM 0 -TrustCenter preparation +TrustCenter Preparation ----------------------- -Account activation +Account Activation ~~~~~~~~~~~~~~~~~~ This step is required only the first time we connect to PKIAAS. -For now, we will only plug in the PKIAAS admin’s personnal HSM. +For now, we will only plug in the PKIAAS admin’s personal HSM. :: java -jar ocf-cc.jar -r "Nitrokey Nitrokey HSM 0" -v -In the web browser, reload the page. A java window appears asking for +In the web browser, reload the page. A Java window appears asking for the PIN of the HSM. Type it in and confirm. -An e-mail adress is asked. Give yours, and you should receive and -activation code. You might as well check out your docker logs to find +An e-mail address is asked. Give yours, and you should receive an +activation code. You might as well check out your Docker logs to find the same code. -Enter the activation code when asked, tick the checkboxes you woul’d +Enter the activation code when asked, tick the checkboxes you would like for your notification preferences, and click “Submit”. Now we see the home page. -TrustCenter creation +TrustCenter Creation ~~~~~~~~~~~~~~~~~~~~ Before we are able to actually manage our CA, we have to create a @@ -165,11 +160,10 @@ excerpt: When creating a TrustCenter three roles are created and initially assigned to the person creating the TrustCenter: - -TrustCenter Manager - responsible for managing roles. -TrustCenter - Operator - responsible for operating the TrustCenter -Registration - Officer - responsible for processing certification requests. - -Certification Officer - responsible for managing keys and issuing - certificates. + -TrustCenter Manager - responsible for managing roles. + -TrustCenter Operator - responsible for operating the TrustCenter + -Registration Officer - responsible for processing certification requests. + -Certification Officer - responsible for managing keys and issuing certificates. As part of this service request you can assign a SmartCard-HSM token to the TrustCenter. Assigning a SmartCard-HSM is important to @@ -189,22 +183,22 @@ Click on “Start Request”, then fill in the form: Click on “Save”, then on “Submit”. -CA device registration +CA Device Registration ~~~~~~~~~~~~~~~~~~~~~~ We have to tell to PKIAAS which device to use for our CA. -- stop the ocf client -- unplug the personnal HSM -- plug the CA HSM -- connect the CA HSM with the following command: +#. Stop the OCF client +#. Unplug the personal HSM +#. Plug the CA HSM +#. Connect the CA HSM with the following command: ``java -jar ocf-cc.jar -r "Nitrokey Nitrokey HSM 0" -v`` On the home page: -- click on “Create TrustCenter Subjet ()” -- keep “operation mode” set to “private” -- click on “Add Token” +#. Click on “Create TrustCenter Subject ()” +#. Keep “operation mode” set to “private” +#. Click on “Add Token” Do the same with the second HSM you have to backup your CA! @@ -221,47 +215,47 @@ Connecting HSM ~~~~~~~~~~~~~~ From now on, We’ll keep the CA HSM plugged most of the time, while we -will have to frequently plug and unplugg personnal HSM. In order to +will have to frequently plug and unplug personal HSM. In order to avoid confusion and connectivity issues, we recommend the run two sessions of OCF in parallel. Always connect your CA device first: -- make sure no HSM is currently plugged in -- plug your CA HSM, so it will be detected as “Nitrokey Nitrokey HSM 0” -- connect your CA HSM with +#. Make sure no HSM is currently plugged in +#. Plug your CA HSM, so it will be detected as “Nitrokey Nitrokey HSM 0” +#. Connect your CA HSM with ``java -jar ocf-cc.jar -r "Nitrokey Nitrokey HSM 0" http:///rt/hsm`` When you’ll have to perform authentication, do like so: -- plug the personnal HSM that will be used for authentication, so it +#. Plug the personal HSM that will be used for authentication, so it will be detected as “Nitrokey Nitrokey HSM 1” -- connect the deivce with +#. Connect the device with ``java -jar ocf-cc.jar -r "Nitrokey Nitrokey HSM 1" -v`` -M-of-n authentication +M-of-n Authentication ~~~~~~~~~~~~~~~~~~~~~ -In the navigation bar, go to Views / Subjects. In the table, dind your -TrustCenter and click on its ID at the beggining of the line. +In the navigation bar, go to Views / Subjects. In the table, find your +TrustCenter and click on its ID at the beginning of the line. If necessary, reload the page. There is a line showing your CA device, with the numbers of public keys currently authenticated. -Click on “Authenticate”, then - plug one of the personnal HSM - reload -the page - if the CA HSM is shown instead of the personnal HSM, click on +Click on “Authenticate”, then - plug one of the personal HSM - reload +the page - if the CA HSM is shown instead of the personal HSM, click on “Enumerate key” - pick the key used for authentication (it is recognizable by its label) - click on “Authenticate” - ask the key -custodian to enter their PIN in the java windows - unplug the personnal +custodian to enter their PIN in the Java window - unplug the personal HSM. Reiterate until the quorum is reached. There, the “Authenticate” button will be replaced by a “Logout” button. Do not click on it! -Root CA creation +Root CA Creation ---------------- -Root CA request and signature +Root CA Request and Signature ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In the navigation bar, go to Views / Subjects, then click on your @@ -299,14 +293,14 @@ Signer, then on “Start Request”. Fill in the form: If the CA HSM is plugged in and pubkeys authentication went well, then we can: -- click on “Save” -- click on “Submit” -- click on “Create Signer” +#. click on “Save” +#. click on “Submit” +#. click on “Create Signer” The HSM lights up and a first entry appears in the list of certificates on screen. Congratulations, your root CA has just been created! -Root CA certificate export +Root CA Certificate Export ~~~~~~~~~~~~~~~~~~~~~~~~~~ In the navigation bar, go to Subjects / TrustCenter. @@ -317,13 +311,13 @@ shown. At the bottom of the page, click on “Download Certificate”. This is the file your machines will have to trust to verify the certificates delivered by your external intermediate CA. -Sharing access to PKIAAS +Sharing Access to PKIAAS ------------------------ -Allow additionnal personnal HSM to access the CA -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Allow Additionnal Personal HSM to Access the CA +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The first personnal HSM you used to connect to PKIAAS has been +The first personal HSM you used to connect to PKIAAS has been registered with the TrustCenter. To avoid the risk of being locked out, it’s best to give access to a second key custodian. @@ -337,21 +331,19 @@ On the new page, click on “Start Request”, then fill in the form: :: - Name: - email: + Name: + email: CA: -- click on “Create” -- replace the device currently plugged in with the device to register -- click on “Identify token” -- a HSM ID should appear, looking similar to - /DESRCACC1/DEDINK01/DENK0105102 -- if this device is not authenticated, restart the OCF client and - reload the web page -- click on “Save” +#. Click on “Create” +#. Replace the device currently plugged in with the device to register +#. Click on “Identify token” +#. A HSM ID should appear, looking similar to /DESRCACC1/DEDINK01/DENK0105102 +#. if this device is not authenticated, restart the OCF client and reload the web page +#. click on “Save” -Associate the personnal HSM with the relevant roles -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Associate the Personal HSM With the Relevant Roles +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Now, the device must be given the right permissions to actually being able to sign the certificates. @@ -362,10 +354,10 @@ right before the newly registered custodian. In the navigation bar, a “Subject” menu appears. Click on it, then “Manage role”. On the new page: -- click on “Start Request” -- select all roles -- click on “Save” -- click on “Apply”. +#. Click on “Start Request” +#. Select all roles +#. Click on “Save” +#. Click on “Apply”. Note: authentication relies upon a certificate flashed right on the device. It is independant of the key pairs we generated earlier with @@ -373,19 +365,19 @@ device. It is independant of the key pairs we generated earlier with device even in case of a renitialization, but flashing the device will erase them. -Signing with the root CA +Signing With the Root CA ------------------------ There are basically three things you might want to do with this root CA: -- signing intermediate CA -- revoking intermediate CA -- updating the revocation list +* Signing intermediate CA +* Revoking intermediate CA +* Updating the revocation list -Before anything, make sure your HSM arer connected and authenticated as +Before anything, make sure your HSM are connected and authenticated as described earlier at section “Using the CA HSM”. -Sign an intermediate CA +Sign an Intermediate CA ~~~~~~~~~~~~~~~~~~~~~~~ This requires you already have a ``.csr`` for the intermediate CA you @@ -394,22 +386,21 @@ intend to sign. In the navigation bar, go to Home / Request Certificate (PKCS #10). Then: -- pick the root CA and click on “Start Request” -- click on “Browse”, pick the ``.csr`` file -- click on “Upload” -- review the settings. Name can be changed but that’s no obligation. -- click on “Save”, then on “Submit” -- as a “registration officer”, approve your own request +#. Pick the root CA and click on “Start Request” +#. Click on “Browse”, pick the ``.csr`` file +#. Click on “Upload” +#. Review the settings. Name can be changed but that’s no obligation. +#. Click on “Save”, then on “Submit” +#. As a “registration officer”, approve your own request In the navigation bar, go to Views / Service Requests. Then: -- as a “certification officer”, click the ID matching the line with - “PKCS10ServiceRequest” et “Produce” -- review the request -- click on “Issue Certificate” -- click on “Accept Certificate” +#. As a “certification officer”, click the ID matching the line with “PKCS10ServiceRequest” et “Produce” +#. Review the request +#. Click on “Issue Certificate” +#. Click on “Accept Certificate” -Intermediate CA certificate export +Intermediate CA Certificate Export ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In the certificate list, click on the intermediate authority name. At @@ -418,7 +409,7 @@ the bottom of the page, use the “Download Certificate” button. And voilà! You can return this certificate to the person in charge of this intermediate CA. -Revoke an intermediate CA +Revoke an Intermediate CA ~~~~~~~~~~~~~~~~~~~~~~~~~ From the home page, find the line “Request Certificate” matching the @@ -427,7 +418,7 @@ intermediate CA to revoke. Click on it. Verify the certificate description, and if you are sure confirm by clicking “Revoke Certificate”. -Update certificate revocation list +Update Certificate Revocation List ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Each time a certificate is revoked, or when the CRL reaches its end of @@ -438,19 +429,19 @@ TrustCenter ID. In the navigation bar, click on CA / Issue CRL, then: -- click on “Start Request” -- select your root CA -- click on “Select” -- click on “Issue” +#. Click on “Start Request” +#. Select your root CA +#. Slick on “Select” +#. Click on “Issue” -The new crl can be fetched by clicking “Download CRL”, or through the +The new CRL can be fetched by clicking “Download CRL”, or through the command line: :: wget http:///sr/crl/1 -O root-ca.crl -CRL content can be displayed with openssl: +CRL content can be displayed with OpenSSL: ::