[[Software|Software]] /!\ STATUS: FIRST DRAFT = Vendor API = <> == Introduction == === Purpose === The Vendor API provides other applications with a means for retrieving data from CAcert's critical account database. === Examples === * the “Find an Assurer” application could ask whether a certain person is an assurer or not or how many points a certain assurer can grant. === Status === The VendorAPI is a ''work-in-progress'' and is not approved. At this stage, the documentation has been written in order to test the concept in the community. Work to write software would follow once we have got the architecture laid out, and we are agreed this is a good direction for CAcert. === Terms === ||VendorAPI|| CAcert Application Programming Interface that enables a third party application to retrieve data from WebDB|| ||Vendor|| The operator of a software package that is using the VendorAPI. Vendor is a term of art, it does not mean that the operator is commercial. || ||Vendor application || A software package that uses the VendorAPI to retrieve data from the CAcert WebDB e.g. the planned new "Find an Assurer" application.|| ||User|| CAcert Community Member under CCA with an account at www.cacert.org, with data stored in the WebDB || || WebDB || CAcert's existing critical application where the user data is stored. In other words, everything that is found under www.cacert.org || == Preconditions == * The Vendor MUST be approved by CAcert and the application MUST be approved by CAcert as well. * The user MUST be asked to accept that their data can be used by vendor applications. === How to fulfil the preconditions? === ==== Vendor / vendor application ==== There should be a vendor team that checks the vendor and the application. The vendor MUST give the source code to CAcert so CAcert is able to see what their application does prior to giving access to the data. The vendor must ask for each Vendor API function separately to get permission to use it and he must state whether he is storing the data or not. CAcert must define what data can be stored by a vendor and, if any data is stored, define data retention times and other conditions. The vendor MUST be an assurer and SHOULD have an organisation account. The domain that is used for the application MUST be owned by the vendor or the organisation. The vendor team should consist of software assessors and people who are familiar with privacy (Privacy officer). ==== User permissions ==== There should be a privacy page in the account where the user can grant access for each API function separately for each vendor application. By default all settings MUST be unset. There should be one option to block all settings. There should be a link list for each application where the application and the vendor are described. Description of each Vendor API function and the intended usage There should be one setting for each function to grant permission to every application (existing and new ones) to use this function or the choice to select single applications for usage. The choice part should not be inheritable for new applications. === Problems identified === * How does the user get to know that he needs to make settings for the vendor applications? * List in the license agreement of the vendor application * ''Iang: is this a licence agreement or is this a policy?'' * Should the vendor application be allowed to change privacy settings? If yes, only settings for the single application are allowed? * This option should not be given. * Insert a second level of permissions for CAcert applications and third party applications? * INOPIAE: My opinion is that we should not insert a second level to split up the information, as I feel that the user will get lost in the multiple choices. We need to think about our users as not necessarily IT affine. * ''Iang: not sure what this means, but I'd agree there should only be one mechanism.'' * How does the community audit the vendors, the agreements and the vendor-level settings? == Technical Requirements == The data must be transmitted in a secure way, for example to the level of SSL communication with mutual authentication (e.g., client & server certs). For the data exchange REST should be used. For each function call the vendor id, a function id and a user identity criteria must be sent. The user identity criteria could be the certificate number. Q: Should the sending domain be checked against the vendor information? . ''Iang: the requestor using the VendorAPI should be authenticated somehow, preferably using client certs. Probably source ip# can be checked as well, which means we are protected against stolen certs.'' Each function should at least check if the vendor application is allowed to use the function and do an “Is user identity valid” check. The result in the case “not allowed” should be “not allowed”, the result of the identity check can differ between the functions but must be defined. <> == Data structure == <> == Related Documents == [[Software/IntegrationInterface|IntegrationInterface]] ---- * [[Software/Assessment/20110222-S-A-MiniTOP]] ---- .CategorySoftware