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

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

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

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?

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
1 – waiting for approval
2 – 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
1 – for all applications
2 – for single application

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

entity_relationship_vendor_api.png


IntegrationInterface



Software/VendorAPI (last edited 2012-03-04 06:18:59 by SunTzuTormenta)