Difference between revisions of "Software Statement"

Revision as of 10:12, 22 February 2020

Full Title or Meme

A json document that describes the provenance, certification and operational environment of an implementation of a software package on a computing machine.

Context

1. The context is a computing machine, like a Smart Phone, in the possession of the user that allows the user to load Native Apps.
2. The user will perform authentication with Web Sites on this device, some of which will require a high level of assurance of the user's authenticity.
3. In determining an authentication assurance level (NIST 800-63-3B AAL2 or 3) a website needs to see some sort of attestation statement that can be used to determine the level of assurance that a user's credential will not be exposed.
4. All of the existing software statements have been focused on relying Party or clients in the OAuth jargon.

OAuth 2.0 Dynamic Client Registration Protocol

• OAuth 2.0 Dynamic Client Registration Protocol

A software statement is a JSON Web Token (JWT) RFC 7519 that asserts metadata values about the client software as a bundle. A set of claims that can be used in a software statement are defined in Section 2. When presented to the authorization server as part of a client registration request, the software statement MUST be digitally signed or MACed using JSON Web Signature (JWS) RFC 7515 and MUST contain an "iss" (issuer) claim denoting the party attesting to the claims in the software statement. It is RECOMMENDED that software statements be digitally signed using the "RS256" signature algorithm, although particular applications MAY specify the use of different algorithms.

  For example, a software statement could contain the following claims:
    {
     "software_id": "4NRB1-0XZABZI9E6-5SM3R",
     "client_name": "Example Statement-based Client",
     "client_uri": "https://client.example.net/"
    }

• Health Relationship Trust Profile for OAuth 2.0 from the OpenID HEART working group also defines software statement for clients

Authorization servers MAY accept signed software statements as described in [RFC7591] issued to client software developers from a trusted registration entity. The software statement can be used to tie together many instances of the same client software that will be run, dynamically registered, and authorized separately at runtime. The software statement MUST include the following client metadata parameters:

• redirect_uris

 array of redirect URIs used by the client; subject to the requirements listed in Section 2.2.3.1

• grant_types

 grant type used by the client; must be "authorization_code” or "implicit”

• jwks_uri or jwks

c lient's public key in JWK Set format; if jwks_uri is used it MUST be reachable by the Authorization Server and point to the client's public key set

• client_name

 human-readable name of the client

• client_uri

 URL of a web page containing further information about the client

UK Open Banking Registration

• Dynamic Client Registration - v3.1. defines the APIs for a TPP to submit a Software Statement Assertion to an ASPSP for the purpose of creating OAuth clients that are registered with ASPSP. it includes a software statement JWS as a single element. The data model for the software statements issued by the Open Banking directory are documented as part of the Directory Specification.

Example SSA The elements defined in the software statement will consist of the following values.

Note that there are inconsistent applications of booleans or "Active" strings in the current data model.

Note that there are inconsistent applications of status flags case sensitivity.

The attributes required to be displayed by ASPSPs

{
   "typ": "JWT",
   "alg": "ES256",
   "kid": "ABCD1234"
}
{
   "iss": "OpenBanking Ltd",
   "iat": 1492756331,
   "jti": "id12345685439487678",
   "software_environment": "production",
   "software_mode": "live",
   "software_id": "65d1f27c-4aea-4549-9c21-60e495a7a86f",
   "software_client_id": "OpenBanking TPP Client Unique ID",
   "software_client_name": "Amazon Prime Movies",
   "software_client_description": "Amazon Prime Movies is a moving streaming service",
   "software_version": "2.2",
   "software_client_uri": "https://prime.amazon.com",
   "software_redirect_uris":
   [
       "https://prime.amazon.com/cb",
       "https://prime.amazon.co.uk/cb"
   ],
   "software_roles": [
       "PISP",
       "AISP"
   ],
   "organisation_competent_authority_claims": [
     {
       "authority_id": "FMA", // Austrian Financial Market Authority
       "registration_id": "111111",
       "status": "Active",
       "authorisations":  [
               {
                   "member_state": "GBR",
                       "roles": [
                           "PISP",
                           "AISP"
                   ]
               },
               {
                   "member_state": "ROI",
                       "roles": [
                           "PISP"
                   ]
               }
           ]
     }
   ],
   "software_logo_uri": "https://prime.amazon.com/logo.png",
   "org_status": "Active",
   "org_id": "Amazon TPPID",
   "org_name": "OpenBanking TPP Registered Name",
   "org_contacts": [
     {
       "name": "contact name",
       "email": "contact@contact.com",
       "phone": "+447890130558"
       "type": "business"
     },
     {
       "name": "contact name",
       "email": "contact@contact.com",
       "phone": "+447890130558",
       "type": "technical"
     }
   ],
   "org_jwks_endpoint": "https://jwks.openbanking.org.uk/org_id/org_id.jkws",
   "org_jwks_revoked_endpoint": "https://jwks.openbanking.org.uk/org_id/revoked/org_id.jkws",
   "software_jwks_endpoint": "https://jwks.openbanking.org.uk/org_id/software_id.jkws",
   "software_jwks_revoked_endpoint": "https://jwks.openbanking.org.uk/org_id/revoked/software_id.jkws",
   "software_policy_uri": "https://tpp.com/policy.html",
   "software_tos_uri": "https://tpp.com/tos.html",
   "software_on_behalf_of_org": "https://api.openbanking.org.uk/scim2/OBTrustedPaymentParty/1234567789",
   "ob_registry_tos": "https://registry.openbanking.org.uk/tos.html"
}
{
   Signature
}

OpenID Connect Mobile Registration Profile

• OpenID Connect Mobile Registration Profile 1.0

This spec is focused on Smart Phones

 { 
      "iss": "https://registry.exampleregistry.com",
      "aud": ["https://accounts.operator1.com","https://accounts.operator2.com","https://accounts.operator3.com"], 
      "exp": "1311281970",
      "iat": "1311280970",
      "jti": "id12345685439487678",
     "software_id": "4NRB1-0XZABZI9E6-5SM3R",
     "software_version": "2.2",
     "client_name": "Example Statement-based Client",
     "client_uri": "https://client.example.net/",
     "redirect_uris": ["https://client.example.org/callback",
     "https://client.example.org/callback2"],
     "token_endpoint_auth_method": "client_secret_basic",
     "grant_types": ["authorization_code"],
     "response_types": ["code"],
     "logo_uri": "https://client.example.org/logo.png",
     "scope": "openid",
     "contacts": ["ve7jtb@example.org", "mary@example.org"],
     "tos_uri": "https://client.example.org/tos.html",
     "policy_uri": "https://client.example.org/policy.html",
     "application_type": "web",
     "sector_identifier_uri": "https://other.example.net/file_of_redirect_uris.json",
     "subject_type": "pairwise",
     "id_token_signed_response_alg": "RS256", 
     "allowed_claims": ["name", "family_name", "phone_number", "phone_number_verified"],
     "allowed_acrs": ["urn:modrna:acr:credential:loa2", "urn:modrna:acr:credential:loa3"],
     "registry_tos": "https://registry.exampleregistry.com/tos.html"
}

• This json object MUST be signed as a JWS JOSE message which may then be included with other json objects in an encrypted JWE JOSE message.
• The issue of multiple signatures on a single JWS has not yet been addressed.
• [Editor's note:] Proposal to is to limit the signature algorithm to RSA to start with.

Security for Native Apps

• RFC 8258 OAuth 2.0 for Native Apps is a best practice document that requires all requests from native apps should only be made through external user-agents. This document assumes that those are browsers supplied by the o/s vendor or otherwise vetted as secure for the user.
• Proof Key for Code Exchange is a method to secure interchange with native apps that has been implemented in client code running on the patient's Smart Phone by the CMS Blue Button API.
• [SP 800-163 Rev. 1 Vetting the Security of Mobile Applications]

Capability Statement

The HL7 FHIR Release 4 Resource CapabilityStatement describes actual server functionality or a desired server implementation. Capability Statements provide for a degree of automatic configuration and adaptation. However, capturing absolutely every variation that could impact the interoperability of two systems, let alone keeping that detailed information up-to-date as systems evolve through maintenance and upgrades, is rarely practical. Therefore, capability statements should be seen as an interim step. They provide a degree of automation. However, they also provide a great deal of human-readable content that can minimize the need for direct communication between the operators of the systems being configured to interoperate. The capability statement is only one part of the conformance module.

• TR = trust registry name
• M = Must
• R = Recommended

Some interesting context fields. The entire document is much much longer.

Problems or Threats

1. Spoofing the user by acquiring access to the user's authentication credentials.

Solution

There are three audiences for software statements. They are represented in the following table by these codes:

1. M = mandatory
2. H = Human readible required

References