![/!\](/moin_static199/cacert/img/alert.png "/!\"){kind=small}
STATUS: FIRST DRAFT
Vendor API
Contents
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.
List of functions of the Vendor API
Note: All functions in paranthesis () are suggestions, the ones without MUST be realised.
Especially the functions regarding the age verification need be discussed.
Is Assurer
The function returns whether the requested person has assurer status or not.
Presently assurer status is defined by 100 valid assurance points and passed CATS test.
Return values: yes/no/no valid information if no permission
Assurer points
The function returns the number of points that the requested person can grant as maximum.
If the requested person is not an assurer the return value should be 0.
Return values: 0,10,15,20,25,30,35, no valid information if no permission
Last Activity
The function returns one of the following 4 status information about the last activity of the requested person in their account:
<= 6 months
<= 12 month
<=24 month
>= 24 month / no information
Problems
might be that support activity is tracked as well on the account
Return Values: 6, 12, 24, no valid information if no permission or > 24 months
(Is minor)
The function returns whether the requested person is below a certain age. Returns true or false
This function could also be used within the account application for setting PoJAM restrictions.
Problems
Which country restriction should be used for the age criteria? The one of the vendor, the one where the requested person is born or the one where the requested person is living.
Who approves that the county settings are correct?
(Age range)
The function returns whether the requested person is in one of the following age ranges:
< 17
>= 17 and < 21
>=21 and <30
>=30 and <40
…
(AgeRestriction)
The function returns whether the requested person matches one of the following statements if the requested person allowed the statement to be returned. If not, “no information available” should be returned.
below 17
below 18
below 19
below 20
below 21
ValidCertificate (Is User identity valid)
The function returns whether the requested person's identity information is valid, expired, blocked or unknown.
This function may only be an internal one for a check whether the requested user information is valid.
Thinking of using the certificate serial number as identity check, the result could be:
valid – if the certificate is valid
expired/revoked – if the certificate is expired or revoked
unknown – if the identity could not be verified or if the account is blocked/locked/deleted
Return values: valid, expired, revoked, no valid information if no permission or any other state of the account
AccountID
Returns the AccountID for a certificate
Return Values: AccountID or no valid information if no permission
RealName
Returns the name in the account first name + middle name + last name + suffix.
Return values: real name, no valid information if no permission
AccountDeleted
Returns whether an account is deleted or not.
Q: What are the indicators for a deleted account?
Return values: yes, no, no valid information if no permission
AccountDeletedList(since)
Returns a list of all accounts that have been deleted since a given date
Return value: list of account ids
IsVerifiedUser
Returns if persons have reached the assured status which means that they can place their name in the certificate.
Presently CAcert Member with >=50 assurance points
Return values: yes, no, no valid information if no permission
Data structure
List of tables for the Vendor API
Note: All tables in paranthesis () are suggestions, the ones without MUST be realised.
Table Vendor
Holds information about the vendor
Name |
Type |
Function |
Remarks |
VendorID |
long |
internal reference ID |
Primary Key, autoincrement |
AccountID |
long |
reference to the account id |
|
Account Type |
int |
reference if personal account or organisation account |
|
Remark |
varchar |
Remarks about anything of interest |
|
created |
date |
|
|
created by |
long |
User ID |
|
deleted |
date |
|
|
deleted by |
long |
User id |
|
History to be defined
Table !VendorApplication
Holds information about the vendor application
Name |
Type |
Function |
Remarks |
VendorAppID |
long |
internal reference ID |
Primary Key, autoincrement |
VendorID |
long |
reference to the vendor |
|
Application |
varchar |
Title of the application |
|
Description |
varchar |
Description of the application, what it does, what is its purpose |
Information must be given by the vendor and approved of by the vendor team |
domain |
varchar |
must be given in account |
how to hanlde multiple domains |
created |
date |
|
|
created by |
long |
User ID |
|
deleted |
date |
|
|
deleted by |
long |
User id |
|
History to be defined
One idea is it to make commercial users ay for the use of the VendorAPI. If that comes true the information could be placed here with commercial use and payment received.
Table VendorFunction
Defines the function that can be used through the VendorAPI
Name |
Type |
Function |
Remarks |
VendorFunctionID |
long |
internal reference ID |
Primary Key, autoincrement |
Function name |
varchar |
|
|
Description |
varchar |
|
|
active |
bit |
true allows applications to use this function. |
|
Table VendorApplicationFunction
Defines what application can use which function from the Vendor API
Name |
Type |
Function |
Remarks |
VendorApplicationFunctionID |
long |
internal reference ID |
Primary Key, autoincrement |
VendorApplicationID |
long |
reference to the vendor application |
|
VendorFunctionID |
long |
reference to the function that can be used by the application |
|
Status |
int |
0 – not allowed |
|
created |
date |
|
|
created by |
long |
User ID |
|
deleted |
date |
|
|
deleted by |
long |
User id |
|
History to be defined
Table UserPrivacyFunction
Defines the functions that the user allows to be used. If not existing, no permission to use the function is granted.
Name |
Type |
Function |
Remarks |
UserPrivacyFunctionID |
long |
internal reference ID |
Primary Key, autoincrement |
VendorFunctionID |
long |
reference to VendorFunction |
|
Status |
int |
0 – not allowed |
|
AccountID |
int |
User Account ID |
|
created |
date |
|
|
created by |
long |
User ID |
|
deleted |
date |
|
|
deleted by |
long |
User id |
|
History to be defined
existing table user
Add one field to the table users VendorPermission as Boolean. True allows the User Privacy Settings to be used, false blocks ALL Vendor API calls.
Table UserPrivacyFunctionApplication
Is used if status of UserPrivacyFunction is 2 and defines which application is allowed to the function
Name |
Type |
Function |
Remarks |
UserPrivacyFunctionApplicationID |
long |
internal reference ID |
Primary Key, autoincrement |
UserPrivacyFunctionID |
long |
reference to the user's permission for one function |
|
VendorAppID |
long |
|
|
created |
date |
|
|
created by |
long |
User ID |
|
deleted |
date |
|
|
deleted by |
long |
User id |
|
(Table CountryRestrictions)
This table could hold information about the country restrictions.
Name |
Type |
Function |
Remarks |
CountryRestrictionID |
long |
internal reference ID |
Primary Key, autoincrement |
Country |
varchar |
Name of country |
|
CountryCode |
varchar(2) |
iso code 2 letters |
|
AdultAge |
int |
defines when a person is able to legally sign a contract on his own |
|
DrinkingAge |
int |
defines the age for drinking in that country |
|
…. |
|
|
|
Entity relationship
possibile entity relationship
Related Documents