crypto providers structure

heading levels fixed
some sections moved
minor edits

Author: stefan-wenig

docs/crypto-providers/cryptoki.md

@@ -110,7 +110,9 @@ For Cryptoki-based signing, tool setup can be complex. Unlike the KSP/CSP provid
 
 If your signing tool does not provide guidance for using Cryptoki libraries, you probably need a solid understanding of the specific tool chain to configure it. For better results, please also refer to [signing flow](/crypto-providers#flow).
 
-## OpenSSL {#openssl}
+## Common code signing tools
+
+### OpenSSL {#openssl}
 
 _[OpenSSL]_ is a toolkit that provides a range of cryptographic operations, including signing.
 
@@ -119,9 +121,9 @@ _[OpenSSL]_ is a toolkit that provides a range of cryptographic operations, incl
 >
 > Only latest OpenSSL 1.1 and 3.x versions are supported. For Linux, see also the notes in [supported Linux distributions](#supported-linux-distributions).
 
-### Setup {#openssl-setup}
+#### Setup {#openssl-setup}
 
-#### Install the `libp11` OpenSSL engine
+##### Install the `libp11` OpenSSL engine
 
 _OpenSSL_ cannot directly communicate with a Cryptoki library. Instead, the [OpenSC pkcs11 OpenSSL engine (`libp11`)](https://github.com/OpenSC/libp11) can be used as adapter between OpenSSL and the SignPath Cryptoki library.
 
@@ -132,7 +134,7 @@ _OpenSSL_ cannot directly communicate with a Cryptoki library. Instead, the [Ope
 
 **Linux:** Install the OpenSC pkcs11 engine via your package manager (e.g. `apt-get install libengine-pkcs11-openssl` on Debian-based or `dnf install openssl-pkcs11` on RedHat-based distros).
 
-#### Configure OpenSSL
+##### Configure OpenSSL
 
 Set the following variables:
 
@@ -160,7 +162,7 @@ export PKCS11_MODULE_PATH="/path/to/libSignPath.Cryptoki.so"
 openssl dgst -engine pkcs11 -keyform engine -sign "pkcs11:id=$ProjectSlug/$SigningPolicySlug;type=private;pin-value=CONFIG" -sha256 -out "artifact.sig" "artifact.bin"
 ~~~
 
-#### Alternative OpenSSL configuration via `OPENSSL_CONF`
+##### Alternative OpenSSL configuration via `OPENSSL_CONF`
 
 An _alternative_ to using the `OPENSSL_ENGINES`/`PKCS11_MODULE_PATH` env variables is to use create a `openssl-signpath.cnf` file as follows and set the `OPENSSL_CONF` env to point to the configuration file.
 
@@ -182,7 +184,7 @@ init = 0
 PIN = CONFIG
 ~~~
 
-### Invocation {#openssl-invocation}
+#### Invocation {#openssl-invocation}
 
 _OpenSSL_ provides a variety of commands that can be used for signing. In this section, a few of them are outlined.
 
@@ -205,7 +207,7 @@ Generally, all commands require the following parameters to work with the SignPa
 | `-inkey`     | `pkcs11:id=$ProjectSlug/$SigningPolicySlug;type=private;pin-value=CONFIG`  | A PKCS #11 URI including _Project_ and _Signing Policy_ slug, see also [Cryptoki parameters](#cryptoki-parameters).
 {: .break-column-2 }
 
-#### openssl dgst
+##### openssl dgst
 
 The _[dgst][openssl-dsgt]_ command calculates digests of files, but can also be used to create and verify signatures.
 
@@ -220,7 +222,7 @@ openssl dgst -engine pkcs11 -keyform engine -sign "pkcs11:id=$ProjectSlug/$Signi
 >
 > The following digests are supported: `sha256`, `sha384`, `sha512`
 
-#### openssl pkeyutl
+##### openssl pkeyutl
 
 The _[pkeyutl][openssl-pkeyutl]_ command performs low-level cryptographic operations, such as signing.
 
@@ -245,7 +247,7 @@ Sample: sign the hash code in `artifact.hash.bin` using PSS padding, write the s
 openssl pkeyutl -engine pkcs11 -keyform engine -inkey "pkcs11:id=$ProjectSlug/$SigningPolicySlug;type=private;pin-value=CONFIG" -sign -in "artifact.hash.bin" -out "artifact.sig" -pkeyopt digest:sha256 -pkeyopt rsa_padding_mode:pss -pkeyopt rsa_pss_saltlen:-1 -pkeyopt rsa_mgf1_md:sha256
 ~~~
 
-#### openssl cms
+##### openssl cms
 
 The _[cms][openssl-cms]_ command can be used to create embedded S/MIME or detached PEM/DER signatures. It uses the Cryptographic Message Syntax format (CMS, formerly known as PKCS#7).
 
@@ -261,7 +263,7 @@ Sample: sign the file `artifact.bin` using `certificate.pem`, write the detached
 openssl cms -engine pkcs11 -signer "certificate.pem" -inkey "pkcs11:id=$ProjectSlug/$SigningPolicySlug;type=private;pin-value=CONFIG" -keyform engine -sign -binary -in "artifact.bin" -noattr -out "artifact.sig" -outform PEM
 ~~~
 
-## osslsigncode {#osslsigncode}
+### osslsigncode {#osslsigncode}
 
 _[osslsigncode]_ is a tool that allows applying Windows Authenticode signatures on Linux systems using OpenSSL. Accordingly, it also requires an OpenSC pkcs11 OpenSSL engine installation. See the [OpenSSL](#openssl) section for details.
 
@@ -270,15 +272,15 @@ _[osslsigncode]_ is a tool that allows applying Windows Authenticode signatures
 >
 > Only osslsigncode 2.x or higher is supported. Also see the notes in [supported Linux distributions](#supported-linux-distributions) regarding the supported OpenSSL versions.
 
-### Setup {#osslsigncode-setup}
+#### Setup {#osslsigncode-setup}
 
 `osslsigncode` requires the X.509 certificate corresponding to the SignPath Project and Signing Policy to be downloaded from SignPath and converted to _PEM format_. You can convert the certificate using OpenSSL via the following example.
 
 ~~~ powershell
 openssl x509 -inform DER -in "certificate.cer" -outform PEM -out "certificate.pem"
 ~~~
 
-### Invocation {#osslsigncode-invocation}
+#### Invocation {#osslsigncode-invocation}
 
 ~~~ powershell
 osslsigncode sign `
@@ -303,11 +305,11 @@ osslsigncode sign `
 > ./RunScenario.sh -Scenario osslsigncode -OrganizationId "$OrganizationId" -ApiToken "$ApiToken" -ProjectSlug "hash-signing" -SigningPolicySlug "test-signing"
 > ```
 
-## OpenSC pkcs11-tool (Linux) {#opensc-pkcs11-tool}
+### OpenSC pkcs11-tool (Linux) {#opensc-pkcs11-tool}
 
 The [OpenSC](https://github.com/OpenSC/OpenSC) [`pkcs11-tool`](https://linux.die.net/man/1/pkcs11-tool) utility can be used to troubleshoot PKCS #11 modules (e.g. listing all available objects or supported algorithms) but also can be used to read certificates/public keys and to perform signing operations.
 
-### Setup {#opensc-pkcs11-tool-setup}
+#### Setup {#opensc-pkcs11-tool-setup}
 
 {:.panel.info}
 > **`pkcs11-tool` before version 0.23**
@@ -316,7 +318,7 @@ The [OpenSC](https://github.com/OpenSC/OpenSC) [`pkcs11-tool`](https://linux.die
 >
 > _Background: `pkcs11-tool` used to open the Cryptoki session in a read/write mode (see [GitHub issue #2182](https://github.com/OpenSC/OpenSC/issues/2182)) and therefore fails with `PKCS11 function C_OpenSession failed: rv = CKR_TOKEN_WRITE_PROTECTED`. This flag enables compatibility with these earlier versions._
 
-### Invocation {#opensc-pkcs11-tool-invocation}
+#### Invocation {#opensc-pkcs11-tool-invocation}
 
 {:.panel.tip}
 > **Tip**
@@ -328,7 +330,7 @@ The [OpenSC](https://github.com/OpenSC/OpenSC) [`pkcs11-tool`](https://linux.die
 > ```
 > 
 
-#### Common parameters
+##### Common parameters
 
 ~~~ powershell
 pkcs11-tool --module $LibSignPathCryptokiPath --pin CONFIG ...
@@ -339,15 +341,15 @@ pkcs11-tool --module $LibSignPathCryptokiPath --pin CONFIG ...
 | `--module`         | `/path/to/libSignPath.Cryptoki.so`      | Path to the SignPath Cryptoki library
 | `--pin`            | `CONFIG` or `$OrganizationId:$ApiToken` | See [PIN parameter](#cryptoki-parameters)
 
-#### Listing available PKCS #11 objects
+##### Listing available PKCS #11 objects
 
 The following command lists available objects, which corresponds to the list of signing policies for which the authenticated user has _Submitter_ permissions.
 
 ~~~ powershell
 pkcs11-tool --module $LibSignPathCryptokiPath --pin CONFIG --list-objects
 ~~~
 
-#### Signing operation
+##### Signing operation
 
 The following sample call shows an RSA signing operation using PSS padding and SHA-256.
 
@@ -364,11 +366,11 @@ pkcs11-tool --module $LibSignPathCryptokiPath --pin CONFIG `
 | `--label`          | `$ProjectSlug/$SigningPolicySlug` | _Project_ and _Signing Policy_ slugs, separated by a forward slash
 | `--input-file`     | `/path/to/hash.bin`               | File containing a hash in _binary_ form
 
-## Java jarsigner {#jarsigner}
+### Java jarsigner {#jarsigner}
 
 The [`jarsigner`](https://docs.oracle.com/en/java/javase/17/docs/specs/man/jarsigner.html) command signs and verifies Java archives (e.g. JAR, WAR, EAR). It is included with the Java Development Kit (JDK).
 
-### Setup {#jarsigner-setup}
+#### Setup {#jarsigner-setup}
 
 1. Configure the SunPKCS11 Provider
    * OpenJDK: the provider is configured automatically

docs/crypto-providers/gpg.md

@@ -10,7 +10,7 @@ description: Creating GPG signatures with SignPath
 
 [GNU Privacy Guard](https://gnupg.org/), also known as GPG or GnuPG, is an Open Source implementation of the OpenPGP standard. This section provides information about using GPG with SignPath, as well as some code signing tools that build on GPG.
 
-## Terminology
+### Terminology
 
 GPG uses various terms for certificates. We use the term **_GPG key_** in our GPG documentation, but keep in mind that other parts of the SignPath documentation will use the general term _certificate_. See [Managing Certificates](/managing-certificates#certificate-types) for more information.
 
@@ -49,6 +49,8 @@ See [SignPath Crypto Providers](/crypto-providers/#crypto-provider-configuration
 
 ## Signing code with GPG
 
+### Common signing tools
+
 The [Linux samples] contain complete example scripts (including all preparation steps) to sign and verify files using the following formats and tools:
 
 | Format                  | Signing invocation     | Sample script                        | Note

docs/crypto-providers/macos.md

@@ -6,7 +6,7 @@ show_toc: 3
 description: SignPath macOS CryptoTokenKit Crypto Provider
 ---
 
-## General instructions
+## Setup
 
 This section provides information to use SignPath with any tool that supports macOS CryptoTokenKit.
 
@@ -22,13 +22,13 @@ Simply copy-deploy the `SignPathCryptoTokenKit.app` application to the target sy
 
 See [SignPath Crypto Providers](/crypto-providers/#crypto-provider-configuration) for general configuration options.
 
-### Background
+## Usage
 
-macOS allows CryptoTokenKit extensions to be registered in the system. Through these extensions, key material and certificates can be provided. An extension is only available while the application that provides the extension is running. Therefore, before calling signing tools like `codesign`, the `SignPathCryptoTokenKit.app` needs to be started.
+### General usage
 
-### Usage
+#### Enable the CryptoTokenKit extension
 
-The `SignPathCryptoTokenKit.app` application loads all available certificates for the given parameters and makes them avaialble in the macOS keychain through a CryptoTokenKit extension. The application supports the following parameters (all of them are optional):
+Start the `SignPathCryptoTokenKit.app` application to load certificates into the macOS keychain through a CryptoTokenKit extension. The application supports the following parameters (all optional):
 
 | Parameter               | Value                        | Default                       | Description
 |-------------------------|------------------------------|-------------------------------|---------------------------------------
@@ -49,6 +49,11 @@ open SignPathCryptoTokenKit.app --args \
   --organization-id 0241f767-69c8-448d-ad5e-8bd453916068
 ~~~
 
+{:.panel.info}
+> Background
+> 
+> SignPath uses the CryptoTokenKit extension mechanism to provide keys and certificates can be provided. The application that registers the extension must be running. Therefore, before calling signing tools like `codesign`, the `SignPathCryptoTokenKit.app` needs to be started.
+
 #### Project and signing policy {#usage-project-signing-policy}
 
 Identify a specific _Signing Policy_ by specifying _Project_ and _Signing Policy_ slugs. The SignPath CryptoTokenKit provider will select that policy's certificate.
@@ -62,48 +67,7 @@ Default values can be provided as [configuration values](index#crypto-provider-c
 >
 > This works fine if a certificate clearly identifies a single Signing Policy. However, if a certificate is referenced by more than one available _Signing Policy_, using it will result in an ambiguous reference error.
 
-### Troubleshooting
-
-Loading the certificates and making them available in the macOS keychain can take up to 20 seconds.
-
-#### Logs
-
-Unless specified otherwise, the log files are stored in `~/Library/Logs/SignPathCryptoTokenKit/` and `~/Library/Containers/io.signpath.apps.CryptoTokenKit/Data/Library/Logs/ctk/` respectively.
-
-#### Useful commands:
-
-The following commands are helpful to make sure the setup is correct:
-
-Using the `security` command, the registered smart cards can be listed. This list should contain an entry `io.signpath.apps.SignPathCryptoTokenKit.ctk:<identifier>`
-~~~bash
-security list-smartcard
-~~~
-
-Using the `pluginkit` tool, the registration of the token driver can be verified. The command lists all registered tokens and should also list `io.signpath.apps.CryptoTokenKit($Version)`.
-
-~~~bash
-pluginkit -m -v -p com.apple.ctk-tokens
-~~~
-
-The smartcard service on macOS sometimes has issues. If the certificates cannot be loaded, the service can be restarted by running the following command:
-
-~~~bash
-killall ctkd
-~~~
-
-{:.panel.info}
-> **Info: Updated intermediate certificate**
-> 
-> When creating a certificate in the Apple Developer portal, the intermediate certificate can be selected. On some machines, the new intermediate certificate is still missing. You can download it [here](https://www.apple.com/certificateauthority/DeveloperIDG2CA.cer).
-
-{:.panel.warning}
-> **Warning: Produce correct timestamps**
-> 
-> When using codesign (or any other signing tool) directly, you are responsible for correct time stamping. See [Timestamps](/crypto-providers#timestamps)
-
-[codesign]: https://developer.apple.com/library/archive/Security/Conceptual/CodeSigningGuide/Procedures/Procedures.html
-
-## codesign {#codesign}
+### codesign {#codesign}
 
 _[codesign]_ is a command line tool by Apple.
 
@@ -124,7 +88,7 @@ codesign -s MyCertificateSubjectName MyApp.app
 > 
 > `codesign` requires an "Apple Developer Application" certificate.
 
-## productsign {#productsign}
+### productsign {#productsign}
 
 _productsign_ is a command line tool by Apple.
 
@@ -144,3 +108,44 @@ productsign --timestamp --sign "XX6NBJ3UUF" MyInstaller.pkg MyInstaller-signed.p
 > **Info: Using the right certificate**
 > 
 > `productsign` requires an "Apple Developer Installer" certificate.
+
+## Troubleshooting
+
+Loading the certificates and making them available in the macOS keychain can take up to 20 seconds.
+
+### Logs
+
+Unless specified otherwise, the log files are stored in `~/Library/Logs/SignPathCryptoTokenKit/` and `~/Library/Containers/io.signpath.apps.CryptoTokenKit/Data/Library/Logs/ctk/` respectively.
+
+### Useful commands
+
+The following commands are helpful to make sure the setup is correct:
+
+Using the `security` command, the registered smart cards can be listed. This list should contain an entry `io.signpath.apps.SignPathCryptoTokenKit.ctk:<identifier>`
+~~~bash
+security list-smartcard
+~~~
+
+Using the `pluginkit` tool, the registration of the token driver can be verified. The command lists all registered tokens and should also list `io.signpath.apps.CryptoTokenKit($Version)`.
+
+~~~bash
+pluginkit -m -v -p com.apple.ctk-tokens
+~~~
+
+The smartcard service on macOS sometimes has issues. If the certificates cannot be loaded, the service can be restarted by running the following command:
+
+~~~bash
+killall ctkd
+~~~
+
+{:.panel.info}
+> **Info: Updated intermediate certificate**
+> 
+> When creating a certificate in the Apple Developer portal, the intermediate certificate can be selected. On some machines, the new intermediate certificate is still missing. You can download it [here](https://www.apple.com/certificateauthority/DeveloperIDG2CA.cer).
+
+{:.panel.warning}
+> **Warning: Produce correct timestamps**
+> 
+> When using codesign (or any other signing tool) directly, you are responsible for correct time stamping. See [Timestamps](/crypto-providers#timestamps)
+
+[codesign]: https://developer.apple.com/library/archive/Security/Conceptual/CodeSigningGuide/Procedures/Procedures.html

docs/crypto-providers/rest-api.md

@@ -84,7 +84,7 @@ curl -H "Authorization: Bearer $API_TOKEN" \
 
 ## Retrieve Signing Policy details {#retrieve-signing-policy-details}
 
-Use `GET {{site.sp_api_url}}/v1/$OrganizationId/Cryptoki/MySigningPolicies?``projectSlug=$Project&signingPolicySlug=$SigningPolicy` to get information about the signing plicy, including the X.509 certificate and RSA key parameters.
+Use `GET {{site.sp_api_url}}/v1/$OrganizationId/Cryptoki/MySigningPolicies?``projectSlug=$Project&signingPolicySlug=$SigningPolicy` to get information about the signing policy, including the X.509 certificate and RSA key parameters.
 
 (If project and signing policy are not specified, this API returns all signing policies where user identified by the API token is assigned as _Submitter_.)