Keys, KeyTokens, and Preferences

From wiki.gpii
Jump to: navigation, search

This page documents the GPII data model that is designed based on this document.

Data Model

The figures below are drawn using entity-relationship diagrams. The arrows used express cardinality, where a single vertical line indicates "at least one", and the crow's foot, "one or more". For example, a Prefs Safe has one or more GPII Keys, or in other words, one or more keys can reference the same safe.

This data model assumes the mapping between GPII keys and server URIs are done through other external mechanisms such as DNS.

GPII data model.png

Document Descriptions

GPII keys

Name Type Required or Optional Description Default
id String Required The value of the key written onto key tokens. None
type String Required The document type for storing GPII keys. The value must be "gpiiKey".
schemaVersion String Required The version of the schema that the current document structure corresponds with.
prefsSafeId String Optional The ID of the preferences safe that the GPII key connects with. Set to null if the GPII key does not have a preferences safe connected. null
prefsSetId String Optional The key of the preferences set in a preferences safe that the GPII key points to. The identifier matches a key within the contexts block of a preference set. For example, the default prefsSetId is a fixed name "gpii-default". null
revoked Boolean Required Whether this GPII key has been revoked. false
revokedReason String Optional The revoked reason. null
timestampCreated Date Required The timestamp when the token is created. now()
timestampUpdated Date Optional The timestamp when the token is updated. null
timestampRevoked Date Optional The timestamp when the token is revoked. null

Prefs Safes

Name Type Required or Optional Description Default
id String Required The ID of the preferences safe. None
type String Required The document type for storing preferences safes. The value must be "prefsSafe".
schemaVersion String Required The version of the schema that the current document structure corresponds with.
prefsSafeType enum of ["snapset", "user"] Required Indicates whether this preferences safe is allowed to be modified: the ones with "snapset" type are unmodifiable while the ones with "user" type are modifiable. "user"
name String Optional The user defined name for this preferences safe. A “preference-safe-name and password” pair can potentially be used as a key. null
password String Optional The user defined password for this preferences safe. A “preference-safe-name and password” pair can potentially be used as a key. null
email String Optional The user email. null
preferences Object Required The user preferences. Refer to the "More Document Field Examples and Explanations" section for an example of this field. null
timestampCreated Date Required The timestamp when the prefs safe is created. now()
timestampUpdated Date Optional The timestamp when the prefs safe is updated. null

Client Credentials

Name Type Required or Optional Description Default
id String Required The ID of the client credential. None
type String Required The document type for storing client credentials. The value must be "clientCredential".
schemaVersion String Required The version of the schema that the current document structure corresponds with.
clientId String Required The client id that this client credential belongs to. None
oauth2ClientId String Required The unique identifier issued to a registered OAuth2 client by the authorization server. None
oauth2ClientSecret String Required Confidential shared secret between the client and the authorization server, used to verify the identity of the client. None
revoked Boolean Required Whether this client credential has been revoked. false
revokedReason String Optional The revoked reason. null
timestampCreated Date Required The timestamp when the prefs safe is created. now()
timestampRevoked Date Optional The timestamp when this client credential is revoked. null

GPII App Installation Clients

Name Type Required or Optional Description Default
id String Required The ID of the GPII app installation client. None
type String Required The document type for storing GPII app installation clients. The value must be "gpiiAppInstallationClient".
schemaVersion String Required The version of the schema that the current document structure corresponds with.
name String Required The user provided client name. null
userId or gpiiKey String Optional The id of the user or the GPII key who creates this client. The intention of this field is to identify the person who manages this client. It's still in question whether this field should record userId or gpiiKey. null
computerType enum of ["public", "private", "shared by trusted parties"] Required Identify the type of the computer where this GPII app is installed. None
timestampCreated Date Required The timestamp when the prefs safe is created. now()
timestampUpdated Date Optional The timestamp when the prefs safe is updated. null

GPII App Installation Authorizations

Name Type Required or Optional Description Default
id String Required The ID of this authorization record. None
type String Required The document type for storing GPII app installation authorizations. The value must be "gpiiAppInstallationAuthorization".
schemaVersion String Required The version of the schema that the current document structure corresponds with.
clientId String Required The client id that this authorization is assigned to. None
gpiiKey String Required The GPII key whose associated user preferences that this authorization is authorized to access. None
clientCredentialId String Required The client credential id that is used to request this authorization. None
accessToken String Required The access token used to retrieved the protected user preferences. None
revoked Boolean Required Whether this authorization has been revoked. false
revokedReason String Optional The revoked reason. null
timestampCreated Date Required The timestamp when the authorization is created. now()
timestampRevoked Date Optional The timestamp when this authorization is revoked. null
timestampExpires Date Required The timestamp when this authorization expires. None

More Document Field Examples and Explanations

prefsSafes.preferences

Object. Required.

  • Each preferences set in a preferences safe is keyed by an internally generated id. The default preferences set is keyed by a fixed string "gpii-default".
  • Each preferences set contains a field called "name" that is to save the user defined name for this preferences set.

Example: 

{
    "flat": {
        "contexts": {
            "gpii-default": {
                "name": "Default preferences",   // user defined name
                "preferences": {
                    "http://registry.gpii.net/common/highContrastEnabled": true,
                    "http://registry.gpii.net/common/highContrastTheme": "white-black",
                    "http://registry.gpii.net/common/cursorSize": 0.5
                },
                "metadata": [
                    {
                        "type": "required",
                        "scope": [
                            "http://registry.gpii.net/common/screenReaderTTSEnabled"
                        ],
                        "value": 1024
                    },
                    {
                        "type": "priority",
                        "scope": [
                            "http://registry.gpii.net/applications/com.freedomScientific.jaws"
                        ],
                        "value": 1024
                    }
                ]
            },
            "internalID-1": {
                "name": "subway",   // user defined name
                "preferences": {
                    "http://registry.gpii.net/common/highContrastEnabled": true,
                    "http://registry.gpii.net/common/highContrastTheme": "white-black",
                    "http://registry.gpii.net/common/cursorSize": 0.5
                },
                "metadata": [
                    {
                        "type": "required",
                        "scope": [
                            "http://registry.gpii.net/common/screenReaderTTSEnabled"
                        ],
                        "value": 1024
                    },
                    {
                        "type": "priority",
                        "scope": [
                            "http://registry.gpii.net/applications/com.freedomScientific.jaws"
                        ],
                        "value": 1024
                    }
                ],
                "conditions": [
                    {
                        "type": "http://registry.gpii.net/conditions/inRange",
                        "min": 400,
                        "inputPath": "http://registry\\.gpii\\.net/common/environment/illuminance"
                    }
                ]
            }
        }
    }
    "ISO24751": {
        "contexts": {
            "gpii-default": {
                "name": "Default preferences",
                "preferences": {
                    "display": {
                        "screenEnhancement": {
                            "fontSize": 24
                        }
                    },
                    "control": {
                        "onscreenKeyboard": true
                    }
                }
            }
        }
    }
}

clientCredentials

This document contains all OAuth2 client credentials assigned to all OAuth clients, including: 1. GPII app installation clients; 2. Privileged prefs creator clients; 3. Web prefs consumer clients.

  • At any time, each client should only have one active un-revoked client credential in this document.
  • TODO: there's an ongoing discussion on whether to stop support privileged prefs creator clients and web prefs consumer clients.

Entities Involved

The information in this section is collected from Keys & KeyToken - Their Role and Use .docx

  • Key
    • "A unique character string used as a pointer to a set of preferences or to a set of preference sets"
    • "Keys can take different forms. But all of them are used to point to a safe where preferences are stored."
    • Used as key to Preference Safe (and/or Preference Set?)
    • A Key may be created without a Preference Safe and may later be linked
    • May contain 3 parts:
      • URI of Preferences Server
      • Identifier to address Preferences Safe (I don't think this can be a Preferences Safe id directly; I think we will need some indirection if we want multiple Keys to point to a single Safe)
      • Identifier to address Preferences Set Context within Safe (default to Context "MAIN")
      • [THE STRUCTURE OF KEYS AND WHICH INFORMATION IS STORED WHERE WAS DISCUSSED 2017-09-11 -- THE ABOVE IS NOT FINAL]
  • KeyToken
    • "Physical device that carries a key"
  • Preferences Server
    • Many-to-one Mapping of [Key -> Preference Safe]
    • More than one Key can map to a single Preference Safe
  • Preferences Cloud Safe
    • One or more mapping of [Context -> Preference Set]
    • Privacy Profile (or in Preference Set?)
    • I think we will need a read-only flag to ensure that shared-use snapset KeyTokens cannot be used to edit preferences ("frozen")
  • Preferences Set
    • "All of the generic and solution-specific preferences"
    • "The default preference set is REGULAR".
    • "The user can rename the REGULAR preference set to any other name. (the default name is currently “My Regular Preferences”"
    • One or more Preferences
  • Preference
    • "A single preferred setting for a Solution"
    • Example:
      • "http://registry.gpii.net/common/magnification": 2.0

Notes

Retrieved from "http://wiki.gpii.net/index.php?title=Keys,_KeyTokens,_and_Preferences&oldid=23721"