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/getting-started-with-pkiaas.rst b/source/components/nitrokeys/hsm/getting-started-with-pkiaas.rst new file mode 100644 index 0000000000..a8f262b6be --- /dev/null +++ b/source/components/nitrokeys/hsm/getting-started-with-pkiaas.rst @@ -0,0 +1,69 @@ +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. + +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 personal 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 personal authentication +- we also suggest to keep one spare device, just in case + +Our setup will involve: + +- the certificate operator personal 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 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 “personal 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/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>`_ diff --git a/source/components/nitrokeys/hsm/pkiaas.rst b/source/components/nitrokeys/hsm/pkiaas.rst new file mode 100644 index 0000000000..54010a993e --- /dev/null +++ b/source/components/nitrokeys/hsm/pkiaas.rst @@ -0,0 +1,448 @@ +PKI-as-a-Service +================ + +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 +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 docker.io 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 the +“serverURL” - amongs other settings - according to your needs: + +:: + + cp pkiaas/etc/template/configuration.js env/etc/configuration.js + editor 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 personal HSM to http://localhost:8080/rt + +:: + + editor 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 two kind of HSM: + +* 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: + +:: + + > 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 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 +the PIN of the HSM. Type it in and confirm. + +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 would +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 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 Subject ()” +#. 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 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 + ``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 personal HSM that will be used for authentication, so it + will be detected as “Nitrokey Nitrokey HSM 1” +#. Connect the device 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, 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 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 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 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 Personal HSM to Access the CA +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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. + +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 Personal 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 are 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 +#. Slick 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..636099beef --- /dev/null +++ b/source/components/nitrokeys/hsm/smart-card-shell.rst @@ -0,0 +1,199 @@ +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 Personal HSM +-------------------- + +Personal HSM will be used for authentication. + +Initialize the Personal HSM +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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 window. + +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 personal 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 personal +HSM one after the other. + +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 +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 personal 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 `__