Skip to content

Commit 238c83b

Browse files
mmerklingermmerklinger
authored
Fix rstcheck warnings (#474)
* Fix syntax warnings in NitroPhone docs * Fix syntax warnings in NetHSM docs * Fix syntax warnings in NextBox docs * Fix syntax warnings in NitroPad/NitroPC docs * Fix syntax warnings in Nitrokey docs * Fix syntax warnings in Software docs * Fix syntax warnings in shared-faq docs * Fix includes * Ignore duplicated target name warnings
1 parent b40846f commit 238c83b

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+960
-736
lines changed

‎rstcheck.toml

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,11 @@ ignore_directives = [
55
"faq",
66
"product-table",
77
]
8-
# ignore-messages is needed due to links being used in directives, which
9-
# are not visible by rstcheck as these directives are ignored (mostly faq)
10-
ignore_messages = "faq(.*)Hyperlink target(.*)is not referenced"
8+
ignore_messages = [
9+
# Hyperlinks are not visible by rstcheck as there directives are ignored (mostly faq).
10+
"faq(.*)Hyperlink target(.*)is not referenced",
11+
# Docutils raises this warning even when an explicit target link is set.
12+
# In case it is linked to, it will concert to an error.
13+
"Duplicate implicit target name: .*",
14+
]
1115

‎source/components/nethsm/apache.rst

Lines changed: 34 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -17,48 +17,48 @@ Httpd Configuration
1717

1818
Add the following lines to your ``httpd.conf`` :
1919

20-
.. code-block::
20+
.. code-block:: apache
2121
22-
Listen 443
23-
#...
24-
LoadModule socache_shmcb_module modules/mod_socache_shmcb.so
25-
LoadModule ssl_module modules/mod_ssl.so
26-
#...
27-
28-
<VirtualHost *:443>
29-
DocumentRoot /usr/local/apache2/htdocs
30-
SSLEngine on
31-
SSLCertificateFile /certs/certificate.pem
32-
SSLCertificateKeyFile "pkcs11:object=webserver"
33-
ErrorLog /tmp/a-error.log
34-
CustomLog /tmp/a-access.log combined
35-
</VirtualHost>
22+
Listen 443
23+
#...
24+
LoadModule socache_shmcb_module modules/mod_socache_shmcb.so
25+
LoadModule ssl_module modules/mod_ssl.so
26+
#...
27+
28+
<VirtualHost *:443>
29+
DocumentRoot /usr/local/apache2/htdocs
30+
SSLEngine on
31+
SSLCertificateFile /certs/certificate.pem
32+
SSLCertificateKeyFile "pkcs11:object=webserver"
33+
ErrorLog /tmp/a-error.log
34+
CustomLog /tmp/a-access.log combined
35+
</VirtualHost>
3636
3737
The ``SSLCertificateFile`` must point to a certificate file on the disk.
38-
3938
The ``SSLCertificateKeyFile`` should be a PKCS#11 `URI <https://www.rfc-editor.org/rfc/rfc7512>`__ pointing to the private key in the NetHSM.
4039

41-
.. note::
42-
You must generate the certificate separately and then upload it to the NetHSM. If the certificate on disk and the key in the NetHSM don't match httpd won't start.
40+
.. note::
41+
You must generate the certificate separately and then upload it to the NetHSM.
42+
If the certificate on disk and the key in the NetHSM don't match httpd won't start.
4343

4444
libnethsm_pkcs11 Configuration
4545
------------------------------
4646

4747
.. code-block:: yaml
4848
49-
slots:
50-
- label: LocalHSM
51-
description: Local HSM (docker)
52-
url: "https://192.168.3.161:8443/api/v1"
53-
operator:
54-
username: "operator"
55-
password: "opPassphrase"
49+
slots:
50+
- label: LocalHSM
51+
description: Local HSM (docker)
52+
url: "https://192.168.3.161:8443/api/v1"
53+
operator:
54+
username: "operator"
55+
password: "opPassphrase"
5656
5757
To secure the password you can provide it via an environment variable (see `Passwords <pkcs11-setup.html#passwords>`__) or provide it in the httpd configuration:
5858

59-
.. code-block::
59+
.. code-block:: apache
6060
61-
SSLCertificateKeyFile "pkcs11:object=webserver;type=private;pin=opPassphrase";
61+
SSLCertificateKeyFile "pkcs11:object=webserver;type=private;pin=opPassphrase";
6262
6363
6464
Example
@@ -67,8 +67,7 @@ Example
6767
If you want to experiment with the `given example <https://github.com/Nitrokey/nethsm-pkcs11/tree/main/container/apache>`__ use git to clone the `nethsm-pkcs11 repository <https://github.com/Nitrokey/nethsm-pkcs11>`__ and run the following commands:
6868

6969
.. warning::
70-
71-
Running the generate script deletes the ``webserver`` key and replaces it.
70+
Running the generate script deletes the ``webserver`` key and replaces it.
7271

7372
1. Configure a NetHSM, either a real one or a container. See the `getting-started guide <getting-started.html>`__ for more information. Besides an administrator, you are going to need an operator account.
7473
2. Download and install the latest version of the nethsm-pkcs11 driver `available from here <https://github.com/Nitrokey/nethsm-pkcs11/releases>`__.
@@ -78,20 +77,20 @@ If you want to experiment with the `given example <https://github.com/Nitrokey/n
7877
6. Update the PKCS11 configuration in ``container/apache/p11nethsm.conf`` with your NetHSMs URL and valid operator credentials.
7978
7. Generate the certificate and key.
8079

81-
.. code-block:: bash
80+
.. code-block:: bash
8281
83-
./container/apache/generate.sh
82+
./container/apache/generate.sh
8483
8584
8. Build the container.
8685

87-
.. code-block:: bash
86+
.. code-block:: bash
8887
89-
docker build -f container/apache/Dockerfile . -t pkcs-httpd
88+
docker build -f container/apache/Dockerfile . -t pkcs-httpd
9089
9190
9. Run the container.
9291

93-
.. code-block:: bash
92+
.. code-block:: bash
9493
95-
docker run -p 9443:443 -p 9080:80 pkcs-httpd
94+
docker run -p 9443:443 -p 9080:80 pkcs-httpd
9695
9796
The Apache test page will be available at `https://localhost:9443/ <https://localhost:9443/>`__. Note that your browser, hopefully, will warn you that the websites certificate is self-signed.

‎source/components/nethsm/container/container-hardware-restriction.rst.inc

Lines changed: 0 additions & 6 deletions
This file was deleted.

‎source/components/nethsm/container/image-feature-restrictions.rst

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
Image Feature Restrictions
2+
--------------------------
3+
4+
Compared to the NetHSM hardware the following functions are not implemented at the software container's REST API:
5+
6+
- Network configuration
7+
- Factory reset
8+
- Reboot
9+
- Software update
10+

‎source/components/nethsm/container/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,5 +7,6 @@ Please refer to the following chapters to learn more about the NetHSM container
77
:maxdepth: 1
88
:glob:
99

10+
image-feature-restrictions.rst
1011
production-image.rst
1112
test-image.rst

‎source/components/nethsm/container/production-image.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,13 @@ It requires an external etcd key-value store which is connected through an encry
66
The NetHSM process can be executed with hardware-based separation (KVM) and device-specific encryption.
77
The image is distributed as OCI image and can be run locally with a compatible executor such as Docker and Podman.
88

9-
.. include:: container-hardware-restriction.rst.inc
9+
The image is subject to some feature restrictions in comparison to the NetHSM hardware.
10+
Please refer to chapter `Image Feature Restrictions <image-feature-restrictions.html>`__ to learn more.
1011

1112
The NetHSM production container is a product for paying customers only and can be purchased `here <https://www.nitrokey.com/contact>`__.
1213
The image can be obtained from `Nitrokey NetHSM registry <https://registry.git.nitrokey.com/distribution/nethsm>`_ using the credentials provided after purchase.
1314

1415
.. warning::
15-
1616
The security of the NetHSM software container strongly depends on the platform's security.
1717
A compromised platform could easily compromise a NetHSM software container it executes.
1818
In addition the TRNG is not existent so that the entropy used and provided by the NetHSM depends on the platform's entropy.

‎source/components/nethsm/container/test-image.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,12 @@ It does not offer to run the NetHSM process with hardware-based separation (KVM)
66
The connection between the NetHSM process and the integrated key-value store is unencrypted.
77
The image is distributed as OCI image and can be run locally with a compatible executor such as Docker and Podman.
88

9-
.. include:: container-hardware-restriction.rst.inc
9+
The image is subject to some feature restrictions in comparison to the NetHSM hardware.
10+
Please refer to chapter `Image Feature Restrictions <image-feature-restrictions.html>`__ to learn more.
1011

1112
The image can be obtained from `Docker Hub <https://hub.docker.com/r/nitrokey/nethsm>`_.
1213

1314
.. warning::
14-
1515
Do not use the test image under any circumstances for production data and use cases.
1616
For production environments with high security demands you must use the production image.
1717

‎source/components/nethsm/ejbca.rst

Lines changed: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -7,19 +7,22 @@ To be able to use NetHSM with EJBCA you need to `setup <pkcs11-setup.html>`__ th
77

88
Then configure EJBCA to use the NetHSM PKCS#11 module by adding an entry in the ``/etc/ejbca/conf/web.properties`` file:
99

10-
.. code-block::
10+
.. code-block:: cfg
1111
12-
cryptotoken.p11.lib.418.name=NetHSM
13-
cryptotoken.p11.lib.418.file=/usr/lib/nitrokey/libnethsm_pkcs11.so
12+
cryptotoken.p11.lib.418.name=NetHSM
13+
cryptotoken.p11.lib.418.file=/usr/lib/nitrokey/libnethsm_pkcs11.so
1414
1515
16-
.. note:: The ``418`` in the name is an index that must be unique for each PKCS#11 module in the configuration file.
16+
.. note::
17+
The ``418`` in the name is an index that must be unique for each PKCS#11 module in the configuration file.
1718

1819
To be able to generate keys from the interface you need to set the ``enable_set_attribute_value`` option to true in the ``p11nethsm.conf`` file.
1920

20-
.. warning:: Because of some integration problems with the Sun PKCS11 provider, keys generated from EJBCA will have a random name instead of the name given in the interface.
21+
.. warning::
22+
Because of some integration problems with the Sun PKCS11 provider, keys generated from EJBCA will have a random name instead of the name given in the interface.
2123

22-
After restarting EJBCA you can add a new Crypto Token in the EJBCA Admin GUI ``https://mycahostname/ejbca/adminweb/cryptotoken/cryptotokens.xhtml``. The Crypto Token type is ``PKCS#11 Crypto Token`` and the Crypto Token name is ``NetHSM``.
24+
After restarting EJBCA you can add a new Crypto Token in the EJBCA Admin GUI ``https://mycahostname/ejbca/adminweb/cryptotoken/cryptotokens.xhtml``.
25+
The Crypto Token type is ``PKCS#11 Crypto Token`` and the Crypto Token name is ``NetHSM``.
2326

2427

2528
Executing The Example
@@ -31,14 +34,14 @@ If you want to experiment with the given example you can use git to clone the `n
3134
- Change the libnethsm_pkcs11 configuration to match your NetHSM in ``container/ejbca/p11nethsm.conf``.
3235
- Build the container.
3336

34-
.. code-block:: bash
37+
.. code-block:: shell-session
3538
36-
docker build -f container/ejbca/Dockerfile . -t pkcs-ejbca
39+
docker build -f container/ejbca/Dockerfile . -t pkcs-ejbca
3740
3841
- Run the container.
3942

40-
.. code-block:: bash
43+
.. code-block:: shell-session
4144
42-
docker run --rm -it -p 9443:8443 -p 9080:8080 -h mycahostname -e TLS_SETUP_ENABLED="simple" pkcs-ejbca
45+
docker run --rm -it -p 9443:8443 -p 9080:8080 -h mycahostname -e TLS_SETUP_ENABLED="simple" pkcs-ejbca
4346
4447
The container will be available at `https://localhost:9443/ <https://localhost:9443/>`__.

‎source/components/nethsm/nginx.rst

Lines changed: 50 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -15,85 +15,86 @@ Set up the OpenSSL engine by following the `OpenSSL Engine setup guide <openssl
1515
Providers aren't supported yet by Nginx.
1616

1717
.. note::
18-
Using the libp11 OpenSSL engine version 0.4.12 or older and a NetHSM with a lot of key will make the initial loading of Nginx slow (more than a minute for 1 thousand keys). It is recommended to use version 0.4.13 or newer or to build the engine from `source <https://github.com/OpenSC/libp11>`__.
18+
Using the libp11 OpenSSL engine version 0.4.12 or older and a NetHSM with a lot of key will make the initial loading of Nginx slow (more than a minute for 1 thousand keys). It is recommended to use version 0.4.13 or newer or to build the engine from `source <https://github.com/OpenSC/libp11>`__.
1919

2020
Nginx Configuration
2121
-------------------
2222

23-
.. code-block::
23+
.. code-block:: nginx
2424
25-
ssl_engine pkcs11;
25+
ssl_engine pkcs11;
2626
27-
server {
28-
listen 443 ssl;
29-
server_name localhost;
27+
server {
28+
listen 443 ssl;
29+
server_name localhost;
3030
31-
ssl_certificate /certs/certificate.pem;
31+
ssl_certificate /certs/certificate.pem;
3232
33-
ssl_certificate_key "engine:pkcs11:pkcs11:object=webserver;type=private";
33+
ssl_certificate_key "engine:pkcs11:pkcs11:object=webserver;type=private";
3434
35-
ssl_session_cache shared:SSL:1m;
36-
ssl_session_timeout 10s;
37-
ssl_session_tickets off;
35+
ssl_session_cache shared:SSL:1m;
36+
ssl_session_timeout 10s;
37+
ssl_session_tickets off;
3838
39-
ssl_protocols TLSv1.3;
40-
ssl_prefer_server_ciphers off;
39+
ssl_protocols TLSv1.3;
40+
ssl_prefer_server_ciphers off;
4141
42-
# HSTS (ngx_http_headers_module is required) (63072000 seconds)
43-
add_header Strict-Transport-Security "max-age=63072000" always;
42+
# HSTS (ngx_http_headers_module is required) (63072000 seconds)
43+
add_header Strict-Transport-Security "max-age=63072000" always;
4444
45-
# OCSP stapling
46-
ssl_stapling on;
47-
ssl_stapling_verify on;
45+
# OCSP stapling
46+
ssl_stapling on;
47+
ssl_stapling_verify on;
4848
49-
location / {
50-
root /usr/share/nginx/html;
51-
index index.html index.htm;
52-
}
49+
location / {
50+
root /usr/share/nginx/html;
51+
index index.html index.htm;
52+
}
5353
54-
error_page 500 502 503 504 /50x.html;
55-
location = /50x.html {
56-
root /usr/share/nginx/html;
57-
}
58-
}
54+
error_page 500 502 503 504 /50x.html;
55+
location = /50x.html {
56+
root /usr/share/nginx/html;
57+
}
58+
}
5959
6060
The ``ssl_certificate`` must point to a certificate file on the disk.
6161

6262
The ``ssl_certificate_key`` can be an OpenSSL configuration. Here we use the OpenSSL engine with the PKCS#11 module and select the private key with the label/ID ``webserver`` and the key type ``private``.
6363

64-
``ssl_certificate_key "engine:pkcs11:pkcs11:object=webserver;type=private";``
64+
.. code-block:: nginx
65+
66+
ssl_certificate_key "engine:pkcs11:pkcs11:object=webserver;type=private";
6567
6668
.. note::
67-
You must generate the certificate separately and then upload it to the NetHSM. If the certificate on disk and the key in the NetHSM don't match nginx won't start.
69+
You must generate the certificate separately and then upload it to the NetHSM. If the certificate on disk and the key in the NetHSM don't match nginx won't start.
6870

6971
libnethsm_pkcs11 Configuration
7072
------------------------------
7173

7274
.. code-block:: yaml
7375
74-
slots:
75-
- label: LocalHSM
76-
description: Local HSM (docker)
77-
url: "https://192.168.3.161:8443/api/v1"
78-
operator:
79-
username: "operator"
80-
password: "opPassphrase"
76+
slots:
77+
- label: LocalHSM
78+
description: Local HSM (docker)
79+
url: "https://192.168.3.161:8443/api/v1"
80+
operator:
81+
username: "operator"
82+
password: "opPassphrase"
8183
8284
To secure the password you can provide it via an `environment variable <pkcs11-setup.html#passwords>`__) or provide it in the nginx configuration:
8385

84-
.. code-block::
86+
.. code-block:: nginx
8587
86-
ssl_certificate_key "engine:pkcs11:pkcs11:object=webserver;type=private;pin=opPassphrase";
88+
ssl_certificate_key "engine:pkcs11:pkcs11:object=webserver;type=private;pin=opPassphrase";
8789
8890
8991
Example
9092
-------
9193

9294
If you want to experiment with the `given example <https://github.com/Nitrokey/nethsm-pkcs11/tree/main/container/nginx>`__ use git to clone the `nethsm-pkcs11 repository <https://github.com/Nitrokey/nethsm-pkcs11>`__ and run the following commands:
9395

94-
.. warning::
95-
96-
Running the generate script deletes the ``webserver`` key and replaces it.
96+
.. warning::
97+
Running the generate script deletes the ``webserver`` key and replaces it.
9798

9899
1. Configure a NetHSM, either a real one or a container. See the `getting-started guide <getting-started.html>`__ for more information. Besides an administrator, you are going to need an operator account.
99100
2. Download and install the latest version of the nethsm-pkcs11 driver `available from here <https://github.com/Nitrokey/nethsm-pkcs11/releases>`__.
@@ -103,20 +104,21 @@ If you want to experiment with the `given example <https://github.com/Nitrokey/n
103104
6. Update the PKCS11 configuration in ``container/nginx/p11nethsm.conf`` with your NetHSMs URL and valid operator credentials.
104105
7. Generate the certificate and key.
105106

106-
.. code-block:: bash
107+
.. code-block:: shell-session
107108
108-
./container/nginx/generate.sh
109+
./container/nginx/generate.sh
109110
110111
8. Build the container.
111112

112-
.. code-block:: bash
113+
.. code-block:: shell-session
113114
114-
docker build -f container/nginx/Dockerfile . -t pkcs-nginx
115+
docker build -f container/nginx/Dockerfile . -t pkcs-nginx
115116
116117
9. Run the container.
117118

118-
.. code-block:: bash
119+
.. code-block:: shell-session
119120
120-
docker run -p 9443:443 -p 9080:80 pkcs-nginx
121+
docker run -p 9443:443 -p 9080:80 pkcs-nginx
121122
122-
The NGINX test page will be available at `https://localhost:9443/ <https://localhost:9443/>`__. Note that your browser, hopefully, will warn you that the websites certificate is self-signed.
123+
The NGINX test page will be available at `https://localhost:9443/ <https://localhost:9443/>`__.
124+
Note that your browser, will warn you that the websites certificate is self-signed.

0 commit comments

Comments
 (0)