Some additions to SCEP documentation #105
Conversation
|
|
||
| #### Requirements | ||
|
|
||
| Your CA must use an RSA intermediate CA, even if your client supports ECDSA. | ||
| We use the RSA intermediate to encrypt/decrypt data, and you cannot do that with an ECDSA key. | ||
| The RSA intermediate is used to encrypt/decrypt data, and you cannot do that with an ECDSA key. |
There was a problem hiding this comment.
could we elaborate with a couple words what "data" is being encrypted and decrypted with the RSA key?
There was a problem hiding this comment.
Added the pkcsPKIEnvelope SCEP construct and the response data in b5ad71b.
| #### Configure the Provisioner | ||
|
|
||
| Add a SCEP provisoiner: | ||
| Add a SCEP provisioner using challenge secret `secret1234` and `AES-256-CBC` as the <Link href="https://github.com/smallstep/pkcs7/blob/33d05740a3526e382af6395d3513e73d4e66d1cb/encrypt.go#L63">encryption algorithm</Link>: |
There was a problem hiding this comment.
| Add a SCEP provisioner using challenge secret `secret1234` and `AES-256-CBC` as the <Link href="https://github.com/smallstep/pkcs7/blob/33d05740a3526e382af6395d3513e73d4e66d1cb/encrypt.go#L63">encryption algorithm</Link>: | |
| In this example, we will add a SCEP provisioner using challenge secret `secret1234` and `AES-256-CBC` as the [encryption algorithm](https://github.com/smallstep/pkcs7/blob/33d05740a3526e382af6395d3513e73d4e66d1cb/encrypt.go#L63): |
| It behaves the same as `forceCN` in the ACME provisioner, and it defaults to false. | ||
| - `challenge` is the secret shared between the provisioner and SCEP clients. By default no secret is used. | ||
| - The `minimumPublicKeyLength` parameter can be used to set the minimum length of public keys submitted by a client. Defaults to 2048. | ||
| - When `includeRoot` is set to true, the root CA certificate will be returned in `GetCACert` requests in addition to the intermediate CA certificate. Defaults to false. |
There was a problem hiding this comment.
Was there a particular client that motivated this option?
There was a problem hiding this comment.
The macOS client. There's some notes about this in smallstep/certificates#746.
It's been quite a while since then, but I remember there were two cases. One of them required the root to be included in addition to the intermediate, otherwise the request would fail. The other case would happily continue without. They were related to whether the macOS configuration profile had the chain included or not, to function as a trust anchor. So far I don't know about other clients that required this. The macOS client may or may not be doing the right thing, because SCEP's known to have some interoperability issues related to trust anchors. At least this configuration option allows both cases to work.
If we start the implementation of the changes discussed internally, that might affect the macOS client and/or this setting too. I'll have to remain aware of this to ensure compatibility.
There was a problem hiding this comment.
Since it's such a specific setting, seems like it'd be worth mentioning that it's a useful for macOS SCEP clients. Could even link to the issue (I've done that in a couple other places in the docs).
| - `challenge` is the secret shared between the provisioner and SCEP clients. By default no secret is used. | ||
| - The `minimumPublicKeyLength` parameter can be used to set the minimum length of public keys submitted by a client. Defaults to 2048. | ||
| - When `includeRoot` is set to true, the root CA certificate will be returned in `GetCACert` requests in addition to the intermediate CA certificate. Defaults to false. | ||
| - The `encryptionAlgorithmIdentifier` parameter can be used to change the <Link href="https://github.com/smallstep/pkcs7/blob/33d05740a3526e382af6395d3513e73d4e66d1cb/encrypt.go#L63">encryption algorithm</Link> used for encrypting the request content. Defaults to 0: `DES-CBC` for legacy compatibility. |
There was a problem hiding this comment.
| - The `encryptionAlgorithmIdentifier` parameter can be used to change the <Link href="https://github.com/smallstep/pkcs7/blob/33d05740a3526e382af6395d3513e73d4e66d1cb/encrypt.go#L63">encryption algorithm</Link> used for encrypting the request content. Defaults to 0: `DES-CBC` for legacy compatibility. | |
| - The `encryptionAlgorithmIdentifier` parameter can be used to change the [encryption algorithm](https://github.com/smallstep/pkcs7/blob/33d05740a3526e382af6395d3513e73d4e66d1cb/encrypt.go#L63) used for encrypting the request content. Defaults to 0: `DES-CBC` for legacy compatibility. |
This PR adds a bit of additional documentation for the SCEP provisioner configuration.
This addresses the concern in smallstep/certificates#746 regarding the key usage expected by the macOS SCEP client. Added a couple of other notes too for completeness, since some more configuration was introduced after the initial release of the SCEP provisioner. Planning on closing that issue after these docs are merged/live.
There'll probably be changes in the SCEP configuration soon if we decide to go forward with the changes discussed internally, but I think we can keep it (largely) backwards compatible with the current implementation and docs.