## page was renamed from IntegrationInterface
'''CAcert Integration Interface'''

[[Software|Software]]

This is the Integration Interface to CAcert, so that any software can guide the user to CAcert, and automate the retrieval of the certificates.

/!\ STATUS: FIRST DRAFT

<<TableOfContents>>

== Why? ==
Several vendors offered to do a tight integration of CAcert into their 
products/services.
The problem is that CAcert had not designed or developed such interfaces yet, and it turned out to be a bigger task that needs a proper design.

We think it is strongly in the interest of CAcert to make a tight integration 
possible, to make it as easy as possible for anyone to use CAcert.
On the other hand, we have to be very careful with the security.
Password management and automation are dangerous and have to be 
designed carefully, to avoid cross-site scripting and similar attacks.

== Common Scenarios or Patterns ==

=== The client software scenario ===

A customer buys a mailserver from the vendor, downloads it over the Internet, 
and pays via creditcard.

When the customer does the installation of the server software:

The installation wizard should make the account generation at CAcert as easy 
as possible, by using the data the user already had to enter at the vendor, 
or from the configuration (email adress, domains, ...)
Perhaps even generating and managing a password for the user, so that the user 
just has to remember the password for the server.

The software should automatically generate the necessary keys and certificate 
requests, should automatically send the CSR to CAcert, and automatically 
receive and install the certificate. 
The mailserver software might even help to acknowledge the EMail Ping.

Automatic notifications or even automatic renewal of the certificates, or 
revocation, when the domain configuration of the server changes would be 
interesting options as well.

This scenario is not limited to Mailservers. The same (or parts of it) applies to Webservers, Firewalls, Web-Applications, CMS, Mail-Clients, PDF Creators, Client Applications, ...
Non-Mailservers will simply ignore the automatic mail confirmation, and tell the user to confirm it manually. Other applications might also choose only a subset of the integration interface.

==== Do we want Complete automation? ====

Do we want the client software to completely automate the Web-Frontend of CAcert, so that the user only sees the client software, and never needs to visit the CAcert website himself?

Discussion.  When the client software (first scenario above) is given the account passwords by the user, and automates everything, the Client Software would take on the status of a RA.  So the rules and responsibilities of a RA would apply.  The question then would be whether the Client Software is acting on behalf of the user or on behalf of the vendor?

I'm guessing this would be more of an RA situation however, where the integrator stores that kind of information and simply sends us a valid signing request. Obviously we'd need to come up with some kind of watertight agreement that they wouldn't abuse the process, and perhaps we'd require the RA to use specific domain(s)...

 * To some extent this may be a decision of the vendor.  CACert's API could provide the building blocks if the vendor is confident enough and prepared enough to do all the work required.
 * One aspect is that we don't want to hide the CACert part from the user for various reasons (we want the user to be a CACert user, it will be more reliable if the user learns to use the website, and more flexible....)
 * This puts the user's account information (passwords, etc) at the mercy of the 3rd party software vendor's storage system.  This could become a security hole (correction: will become a security disaster ...)

Note that the Organisational scenario (below) is much more likely to be a completely automated interface.


=== The Organisation scenario ===

In the organisation scenario, a larger organisation (>50 people) has a managed infrastructure (server based or managed clients), a good human resources database (LDAP, SAP, ...) and wants to 
 *automatically issue certificates for all employees
 *automatically deploy the certificates into several application
 *add the certificate enrollment into the procedure for new employees
 *automatically revoke the certificates of leaving employees

This scenario is easier than the Client Software scenatio, because the Organisation already has all these capabilities through the web-interface, it just needs automated interfaces.

One very important thing is that we define long-lasting URLs, which can be integrated in Software packages, and which shouldn´t be changed (only enhanced if necessary) after this specification is FINAL.


== Naming ==

||API||Application Programming Interface. In this context the Integration Interface that CAcert will be offering is meant||
||Vendor||The vendor of a software package, that the user wants to install||
||Client||A software package, that is being installed (installation wizard), or is already installed, which uses certificates.  This is a client from CAcert's API's pov, but may actually be a server in the user installation.||
||User||The user installing or working with the software||

== The concept ==

We separate the whole thing into many separate projects, and work them through individually:


 1. Account generation with data from the vendor
 1. Account generation finished -> Installation wizard
 1. Management of the account from the server
 1. Normal CSR transmission to CAcert
 1. CSR Transmission together with the Account generation
 1. CSR Management in the Account
 1. automatic Certificate retrieval
 1. Automating of the Email ping
 1. Notifications, status of the certificates
 1. Renewal, revocation of the certificates

Comments on all the above are below.

== 1. Account generation with data from the vendor ==

That´s the page that currently does it:
[[https://www.cacert.org/index.php?id=1]]

Which fields are likely available from the vendor's process?

||FirstName||likely||
||MiddleName||perhaps||
||LastName||likely||
||Email Address||likely||
||Birthday||unlikely||
||Password||we don´t want that for security reasons||
||Lost Passphrase questions||we don´t want that||

What happens when the first vendor comes along and does want to provide password data?  Should we be able to automate those two fields?

My suggestion would be to add the fields as parameters:

||URL||https://www.cacert.org/index.php?id=1||
||Action||GET/POST||
||FirstName||John||
||MiddleName||M.||
||LastName||Doe||
||EmailAddress||john@doe.at||

/!\ Important: Please only send parameters when you are sure that the content can be correct. Having wrong data in the fields can confuse the users, and might not be corrected by the users afterwards.

Example: https://www.cacert.org/index.php?id=1&FirstName=John&MiddleName=M.&LastName=Doe&EmailAddress=john@doe.at

This opens the page in the browser.  That way the user can easily fill out the rest of the fields, correct the fields if necessary, and still has the normal procedure as set up by the normal form on CAcert's website.

Or should we offer a direct interface for the client to completely automatically register a user?  No.

== 2. Account generation finished -> Installation wizard ==

When the account registration dialog is completed successfully, the Installation wizard should be informed about the successful completion, so that it can continue with the wizard.

There are 3 possibilities:

 *We could forward the user to the next stage of the Installation wizard

For this, the Installation wizard would add the URL to the registration system:

[[https://www.cacert.org/index.php?id=1&continue=http://localhost/wizard/continue]]

When the Registration dialog is finished, we are presenting the normal text "Your request was processed." and in the next line add:

"Please click <here> to continue with the Installation Wizard"

We have to be very careful not to introduce XSS vulnerabilities with this way

 *Inform the Installation wizard through a callback 

This would only work if the Installation wizard would be running on a machine that is reachable through the Internet. (Which does not work, if you setup the Mailserver in the local network first)

In the case of an error (which errors are possible), that makes it impossible for the account to be generated, we should offer a callback to an error page:

[[https://www.cacert.org/index.php?id=1&continue=http://localhost/wizard/continue&error=http://localhost/wizard/error]]

Both Error and Continue callbacks should be given the resulting Email Address (so that they can continue issueing a CSR for the correct email address, in case the user corrected it in between:
||URL||https://localhost/wizard/continue||
||EmailAddress||john@doe.at||

/!\ Note: The parameter EmailAddress is appended to the URL. If the URL does not have parameters yet, it will be the first and only parameter, if the URL already has parameters, it will be appended.


 *Polling with a Ticket

The Installation wizard could first ask CAcert for a ticket.
[[https://www.cacert.org/index.php?id=givemeaticket]] -> 124215

Then it would add the given ticket to the Registration page:
[[https://www.cacert.org/index.php?id=1&ticket=124215]]

Afterwards it can poll CAcert, whether the registration is done or not:
[https://www.cacert.org/index.php?id=isitdone&ticket=124215}


The big question here is what if the user closes the browser?

Should we define a Timeout? 5 minutes? 10 minutes? 30 minutes?


So the resulting interface is the following:

||URL||https://www.cacert.org/index.php?id=1||
||Action||GET/POST||
||FirstName||John||
||MiddleName||M.||
||LastName||Doe||
||EmailAddress||john@doe.at||
||continue||http://localhost/wizard/continue||
||error||http://localhost/wizard/error||



== 4. Normal CSR transmission to CAcert ==

Ok, this is where SCEP could come into play. (Or a more simple protocol *g*) The good thing on SCEP standards is that there are so many to choose from. PGP for Windows has about 4 different SCEP implementations, and I haven't found out yet which one the PGP developers prefer ... OpenCA has a SCEP implementation, but I haven´t succeeded in getting it working yet (not enough time spent).

Let´s take a look from the designer´s perspective:

What does SCEP gives us?
SCEP is a HTTP based protocol to automatically submit CSR´s and receive the resulting certificates through a ticket system.

First the request is sent:
 *Client -> SCEP Request with CSR -> CA
 *Client <- SCEP Answer with Ticket <- CA

Then the client polls:
 *Client -> SCEP Request with Ticket -> CA
 *Client <- SCEP Answer: No certificate there yet <- CA

Until it gets a certificate:
 *Client -> SCEP Request with Ticket -> CA
 *Client <- SCEP Answer: Certificate <- CA

Why can´t we simply use SCEP?
There are two problems with SCEP:
SCEP just transfers the plain CSR, without any information as to which account the CSR belongs to.

Ok, we could guess from the CommonName (or the other SubjectAltNames) who it could belong to. 

A better solution would be to individualize the URL:
Normally the SCEP URL is a fixed URL to the CGI application handling the requests:
http://ca.server.com/cgi-bin/scep.exe
We could personalize this URL:
http://www.cacert.org/scep.php?user=pg@futureware.at

(On the server side, it should be easy to implement that for us.  On the client side, it theoretically would not work for clients which can only work with fixed URLs, but since the vendors want to develop a interface for us, this is not a problem)

The next problem is the missing approval from the user. One possibility would be to send the Password of the user included in the request. (Since most SCEP systems seem to use HTTP (!?!) I would say that´s a bad idea)

=== What about a SCEP to CAcert proxy? ===

While SCEP to CAcert directly may be a bad thing, perhaps for all those network admins out there that have a lot of kit that uses SCEP the use of a local proxy that does have both the ability to securely connect to CAcert and pass requests as well as receiving and queuing SCEP requests might be a possible solution, any one able to code up a proof of concept?

== api/ccsr.php interface ==

This is the documentation of an already existing interface:

Parameters:
||URL||https://www.cacert.org/api/ccsr.php||
||Action||can be POST or GET ($_REQUEST)||
||username||username of the account that is used to issue the certificate||
||password||password of the account that is used to issue the certificate||
||email||email address for the certificate||
||name||the name which should go into the certificate (Firstname Lastname or Firstname Middlename Lastname)||
||codesign||1 or 0, whether it should be a codesigning certificate or not||
||optionalCSR||optionally a CSR||


== api/cemails.php interface ==

Parameters:
||URL||https://www.cacert.org/api/cemails.php||
||Action||can be POST or GET ($_REQUEST)||
||username||username of the account that is used to issue the certificate||
||password||password of the account that is used to issue the certificate||

Returns:
{{{
200,Authentication Ok
CS=0
NAME=CAcert WoT User
NAME=John Doe
NAME=JOhn M. Doe
EMAIL=john@doe.com
EMAIL=john@super.com
EMAIL=j@doe.au
}}}

== 5. CSR Transmission together with the Account generation ==

The idea here is to unify the account creating, CSR sending and CSR approval process.

The idea is that the client can send the CSR together with the account generation URL (or better with a HTTP POST instead, I think it is too long for the URL):

https://www.cacert.org/index.php?id=1&EmailAddress=john@doe.com&CSR=---BEGIN---....


||URL||https://www.cacert.org/index.php?id=1||
||Action||GET/POST||
||FirstName||John||
||MiddleName||M.||
||LastName||Doe||
||EmailAddress||john@doe.at||
||continue||http://localhost/wizard/continue||
||error||http://localhost/wizard/error||
||CSR||---BEGIN--- ...||

Then CAcert could store the CSR for later automatic processing, when the account is created, to make the interaction with the Installation wizard easier.

The Installation wizard does not have to wait for the account generation to 
have finished, before being able to send the CSR. CAcert stores the CSR in 
the mean time.

The question is: What do we do, if the user changes the Email Address in the Registration Screen? Then the CSR can´t be linked together with the email address ...

Questions:

 * what happens if the user closes the browser?
 * what happens if the Account Generation fails? (the CSR may depend on that)


== 6. CSR Management in the Account ==

Another more promising idea is to manage a list of unapproved CSR´s in the user´s account on the website, where the user is informed of a new unapproved CSR that was submitted through the interface per Email, can login normally through the browser and approve or discard the request(s).


Alternatively, we could ignore SCEP and make our own, better suited interface.

== 8. Automating of the Email ping ==

The mailserver might help to acknowledge the EMail Ping. It does not have to, the user can do it on his own, if he wants to (or the Mailserver can´t do it). If the Mailserver can automate it, it can make the setup easier for the user.

To make sure that the mailserver can´t be abused to approve other requests, the mailserver should generate a nonce, and send that nonce together with the domain- or email-verification. CAcert should include the nonce in the EMail Ping, and the Mailserver should only automatically answer Email Pings with valid nonces.

== 10. Revocation ==

If the domain has been dropped or otherwise rendered useless (e.g, email address dropped), it should consider the need for certificate revocation.  The user should be asked whether the client should revoke the certificates for the user automatically.

Need a user interface description.

== TODO ==

 * "Screenshots" for all the scenarios (try MediaWiki)

== Related Documents ==

[[Software/VendorAPI|VendorAPI]]

----
 .CategorySoftware