Skip to content

Commit 0d191b1

Browse files
stefan-wenigstefan-wenig
committed
crypto providers structure
heading levels fixed some sections moved minor edits
1 parent d5e2c78 commit 0d191b1

File tree

1 file changed

+36
-31
lines changed

1 file changed

+36
-31
lines changed

‎docs/crypto-providers/windows.md‎

Lines changed: 36 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,11 @@ description: SignPath Windows CSP and KSP Crypto Providers
88

99
## Overview
1010

11-
Signing tools secifically designed for Windows typicall use CNG KSP or CAPI CSP providers. Install and use the SignPath KSP and CSP providers to use this tools with SignPath.
11+
Signing tools secifically designed for Windows typically use CNG KSP or CAPI CSP providers. Install and use the SignPath KSP and CSP providers to use this tools with SignPath.
1212

13-
## Installation
13+
## Setup
14+
15+
### Installation
1416

1517
To install the Windows CNG KSP and CAPI CSP providers,
1618

@@ -87,35 +89,9 @@ msiexec /x SignPathCryptoProviders-$Version.msi /qn /L* uninstall.log | Out-Host
8789

8890
See [SignPath Crypto Providers](/crypto-providers/#crypto-provider-configuration) for general configuration options.
8991

90-
## Using KSP/CSP parameters of signing tools
91-
92-
Additionally to the general [Crypto Provider configuration](/crypto-providers#crypto-provider-configuration), specify the following values using the parameters provided by your signing tool:
93-
94-
| Parameter | Value | Description
95-
|-----------------------|--------------------------------------|---------------------------------------
96-
| Crypto Provider | `SignPathKSP` or `SignPathCSP` | SignPath KSP (preferred) or CSP
97-
| Key container name | `$ProjectSlug/$SigningPolicySlug` | SignPath _Project_ and _Signing Policy_ slugs, separated by a forward slash
98-
| Certificate file | Path to the x.509 certificate file | Download the respective certificate file from SignPath
99-
100-
{:.panel.info}
101-
> **Use _Project_ and _Signing Policy_ slugs to speficy a key**
102-
>
103-
> Identify a specific _Signing Policy_ by specifying _Project_ and _Signing Policy_ slugs. The SignPath KSP/CSP will select that policy's certificate.
104-
105-
## Error handling
92+
## Signing code
10693

107-
The following table shows the KSP `HRESULT` result codes for different error situations when calling the SignPath REST API.
108-
109-
| Situation | error code (KSP result code or CSP `GetLastError()` code)
110-
|----------------------------------------------------------------------------------------------------------|----------------------------------------------------------
111-
| Transient errors like HTTP timeouts or 503 (Service Unavailable) which still occur after the last retry | `NTE_DEVICE_NOT_READY` ("The device that is required by this cryptographic provider is not ready for use.") for errors without an HTTP status code. Otherwise, HTTP status code as an HRESULT in the `FACILITY_ITF`, e.g. `0x800401F7` for HTTP 503
112-
| Non-transient service errors (e.g. 500 Internal Server Error) | HTTP status code as an HRESULT in the `FACILITY_ITF`, e.g. `0x800401F4` for HTTP 500
113-
| User errors detected by service (4xx returned) | HTTP status code as an HRESULT in the `FACILITY_ITF`, e.g. `0x80040190` for HTTP 400
114-
| Other unspecified errors (fall back) | `NTE_FAIL` ("An internal error occurred.")
115-
116-
The CSP error code has to be retrieved via [`GetLastError()`](https://learn.microsoft.com/en-us/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror).
117-
118-
## SignTool.exe {#signtool}
94+
### SignTool.exe {#signtool}
11995

12096
_[SignTool.exe]_ is a command line tool by Microsoft. _SignTool.exe_ can use both the SignPath CSP and the SignPath KSP. We recommend using the SignPath KSP whenever possible.
12197

@@ -149,4 +125,33 @@ signtool.exe sign /csp SignPathKSP /kc "$ProjectSlug/$SigningPolicySlug" /fd SHA
149125
>
150126
> When using SignTool.exe (or any other signing tool) directly, you are responsible for correct time stamping. See [Timestamps](/crypto-providers#timestamps)
151127
152-
[SignTool.exe]: https://docs.microsoft.com/en-us/dotnet/framework/tools/signtool-exe
128+
[SignTool.exe]: https://docs.microsoft.com/en-us/dotnet/framework/tools/signtool-exe
129+
130+
### Using other signing tools {#ksp-parameters}
131+
132+
In addition to the general [Crypto Provider configuration](/crypto-providers#crypto-provider-configuration), specify the following values using the parameters provided by your signing tool:
133+
134+
| Parameter | Value | Description
135+
|-----------------------|--------------------------------------|---------------------------------------
136+
| Crypto Provider | `SignPathKSP` or `SignPathCSP` | SignPath KSP (preferred) or CSP
137+
| Key container name | `$ProjectSlug/$SigningPolicySlug` | SignPath _Project_ and _Signing Policy_ slugs, separated by a forward slash
138+
| Certificate file | Path to the x.509 certificate file | Download the respective certificate file from SignPath
139+
140+
{:.panel.info}
141+
> **Use _Project_ and _Signing Policy_ slugs to speficy a key**
142+
>
143+
> Identify a specific _Signing Policy_ by specifying _Project_ and _Signing Policy_ slugs. The SignPath KSP/CSP will select that policy's certificate.
144+
145+
### Error handling
146+
147+
The following table shows the KSP `HRESULT` result codes for different error situations when calling the SignPath REST API.
148+
149+
| Situation | error code (KSP result code or CSP `GetLastError()` code)
150+
|----------------------------------------------------------------------------------------------------------|----------------------------------------------------------
151+
| Transient errors like HTTP timeouts or 503 (Service Unavailable) which still occur after the last retry | `NTE_DEVICE_NOT_READY` ("The device that is required by this cryptographic provider is not ready for use.") for errors without an HTTP status code. Otherwise, HTTP status code as an HRESULT in the `FACILITY_ITF`, e.g. `0x800401F7` for HTTP 503
152+
| Non-transient service errors (e.g. 500 Internal Server Error) | HTTP status code as an HRESULT in the `FACILITY_ITF`, e.g. `0x800401F4` for HTTP 500
153+
| User errors detected by service (4xx returned) | HTTP status code as an HRESULT in the `FACILITY_ITF`, e.g. `0x80040190` for HTTP 400
154+
| Other unspecified errors (fall back) | `NTE_FAIL` ("An internal error occurred.")
155+
156+
The CSP error code has to be retrieved via [`GetLastError()`](https://learn.microsoft.com/en-us/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror).
157+

0 commit comments

Comments
 (0)