This is what the SCEP support feature (originally requested in [https://bugzilla.redhat.com/show_bug.cgi?id=1161768 bugzilla]) will look like.  Subject to change.

= High level use cases =

'''Issuing a new certificate over SCEP'''
* Manually approved: client submits request, admin has to push a button to approve it, client polls and eventually obtains its certificate.
* Authenticated by use of a prearranged one-time PIN sent as a ''!ChallengePassword'' attribute value in the signing request.
  * Obtaining one to use is a function of the Dogtag RA: https://access.redhat.com/documentation/en-US/Red_Hat_Certificate_System/8.1/html/Admin_Guide/Enrolling_a_Certificate_in_a_Cisco_Router.html#Generating_the_SCEP_Certificate_on_the_Router
  * Obtaining one to use is an admin function available within ADCS when the Network Device Enrollment role is installed.  The administrator needs to check http://$server/certsrv/mscep_admin for a time-limited PIN.
  * Possible bonus feature for when the SCEP server is part of IPA: set this to the client's bulk enrollment password, and clear it after the client enrolls.

'''Renewing a certificate over SCEP''', authenticated by virtue of having been signed by the private key that matches the requester's previously-issued certificate.
* Support for this feature added in Windows Server 2008 Service Pack 2.
* Status in Dogtag unknown at this time.

'''Replacing a certificate over SCEP''', authenticated by virtue of having been signed by the private key that matches the requester's previously-issued certificate, but request contains a new public key.
* Requires not-yet-implemented general support for rekeying in certmonger as a prerequisite.
* Only supported by an SCEP implementation if its GetCACaps operation produces "Renewal" as a capability, introduced in draft 11 of the spec.

= User Experience =

1. User enables SCEP service at the CA.
  a. Dogtag: https://access.redhat.com/documentation/en-US/Red_Hat_Certificate_System/8.1/html/Admin_Guide/Enrolling_a_Certificate_in_a_Cisco_Router.html
  b. ADCS: http://aka.ms/ndes
2. User configures certmonger with knowledge of the CA.
  As with most CAs that we don't hard-code knowledge of, the daemon is told to call the SCEP helper with a command-line flag which specifies the URL of the SCEP server.  This can be added via a D-Bus API call.  IPA already uses this API to modify flags passed to the IPA helper.  We expose the API via new ''add-ca'', ''modify-ca'', and ''remove-ca'' getcert commands, with ''add-scep-ca'' as a specialized alternative which knows where the SCEP helper is and which options it recognizes.
3. User chooses or obtains a device enrollment password.
  a. Dogtag: browse to the RA services page (https://$server/ra/agent/ra ?), select SCEP Enrollment
  b. ADCS: browse to https://$server/certsrv/mscep_admin
4. User invokes getcert.
  a. The -c option specifies the helper configuration that uses the SCEP helper to talk to an SCEP server.
  b. New options (-l/-L) will allow the user to pass the device enrollment password in as a !ChallengePassword value.
  c. The SCEP spec says we can only use RSA.
  d. Like any CA, one that we access using SCEP may reject a request if it doesn't like either the requested subject name or any of the requested extension values.
  e. In order to better support manual approval cases, as suggested by the spec, ''getcert list'' now notes SCEP fingerprints of requests which are going to CAs via SCEP.  Testing should include checking that we compute and display the values as the server displays them.
  f. In order to better meet security requirements in the spec, ''getcert list-cas'' will start listing key fingerprints for SCEP CA/RA certificates.

= Processing =
* Certmonger prepares SCEP requests.
  * As part of CA data gathering (performed at startup and refreshed as needed), the SCEP helper, configured with URL of the SCEP server, obtains the SCEP server's CA or RA and CA certificates using a GetCACert request.
    * If the result does not include a self-signed (i.e., root) certificate, then the helper will attempt to use a GetCACertChain (draft 3 or later) request to obtain the rest of the chain.
    * If the value returned by the server is a PKCS!#7 signed data blob, the certificate is extracted (preferably not an issuer for any other certificate in the blob, preferably not a CA, preferably marked as able to be used for encryption).  The helper only outputs an X.509 certificate.
    * The daemon caches this information for use later, passing it back to the SCEP helper when it's called as a time-saving measure.
    * This information is not otherwise authenticated, so it is not stored to locations specified using getcert's -F and -a flags.
    * The helper will be able to be told the location of copies of the certificates which have been obtained out-of-band through use of a command-line option, and will prefer those to values retrieved from the server.  This option may be required to be used when contacting a server using HTTPS, to avoid the chicken-egg problem we'd run into in attempting to use a GetCACert request to obtain a CA certificate to trust when making the HTTPS connection to issue the GetCACert request.
  * As part of CA data gathering (performed at startup), the SCEP helper indicates that it will need SCEP messages to pass to the server.
  * Before contacting a server that requires SCEP messages, certmonger generates SCEP request messages relevant to the CSR which it already generated.
    * We do this every time, so that we can generate a new nonce.
    * This requires signing with the request's private key, which we don't expose to helpers, so it's done by the daemon.
    * This step is skipped if we're not talking to an SCEP helper.
    * If we don't have the RA or CA certificate yet, this step is delayed until we get them.

* Certmonger connects to CA or RA using SCEP.
  * The SCEP helper contacts the SCEP server over HTTP and submits its request.
  * The initial request is a PKCSReq PKIOperation.
  * If the request is automatically approved, the SCEP server emits a !CertRep message with status SUCCESS and an encrypted copy of the new certificate.  The helper verifies the server's reply, outputs the encrypted certificate, and then exits with status 0.
  * If the request is rejected, the SCEP server emits a !CertRep message with status FAILURE, and the helper exits with status 2.
  * If manual approval is required for the request, the SCEP server emits a !CertRep message with status PENDING, and the helper exits with status 1 or 5.
  * If manual approval is required for the request, sometime later, certmonger calls the SCEP helper to use the PKIOperation option to make a !GetCertInitial request to poll for its request's status.
  * The helper will sanity-check requests that it's being asked to send to the server for well-formedness, to make troubleshooting easier.
  * As part of parsing a response from an SCEP server, the helper will verify signatures on signed responses before passing their payload, which is enveloped data, back to the certmonger daemon.
  * The certmonger daemon will decrypt portions of the SCEP server's responses which contain enveloped data.
  * This last bit requires the request's private key, which we don't expose to helpers, so it's done by the daemon.

= General Notes =

== Does it check capabilities first? ==
Yes. The GetCACaps operation was introduced in draft 10 of the specification.  Anything implementing an older version of the spec must be assumed to not offer functionality ("Renewal") that would be advertised by this method.

== Can SCEP be used to request certificate revocation? ==
SCEP does not include revocation requests, per http://tools.ietf.org/html/draft-nourse-scep-23#section-2.8

== What are the target draft versions? ==
* Per out-of-band mail, GSA recommends draft 23, but mentions 18 and 13. Reference: http://www.gamingstandards.com/?page=standards/xpt_downloads
* Documentation (http://aka.ms/ndes) suggests that ADCS supports draft 18.
* Dogtag may support draft 2.
* Using an old key to request a certificate (the CA capability named "Renewal") using a new one is a draft 11 feature.
* Querying for CA capabilities is a draft 10 feature.
  * Dogtag does not support GetCACaps requests.
* Supporting communication with servers where the RA's certificate isn't directly issued by the CA is a draft 3 feature.
  * Dogtag does not support GetCACertChain requests.