Overview

In our internet connected world, information is the currency that keeps everything moving. Unfortunately there is no easy way to authenticate most of the information that people furnish over the internet. Basic information such as someone's name, age or address cannot be easily authenticated without having an expensive back office operation in place.

Solution

In this document we describe a protocol and API implementation that provides a secure,scalable and inexpensive way to authenticate information on the internet. The API can be used to verify someone's personal information such as name,age or authenticate information such as academic transcript, or for that matter any digital information for which verification is required.

Information Trust Relay

The approach described is predicated on a simple observation; which is that while we cannot readily trust the information someone furnishes to us, there are usually other entities (business or otherwise) who have verified that information and as such have established trust for it. What if that established trust can be leveraged by everyone else who's ever presented that information? This observation forms the basis for the protocol and API solution described herein.

Information Trust Relay Protocol & API

At the core of this solution is a Trust Relay Protocol. This protocol uses modern cryptography and end-to-end encryption to guarantee that trusted information can be relayed in a manner that is secure, private and untampered with. The Trust Relay Protocol is modelled after the widely used internet Transport Layer Security (TLS) protocol, thus inheriting both the security and privacy features of TLS. Below is a diagram and detail description of the relevant components:

• Furnisher

  The person/party who presents untrusted information. For instance a customer who presents a credit card number or student who comes in to admission with an academic transcript. In the language of federated identity brokerage, the furnisher is the principal.

• Recipient

  The person/party who is presented with untrusted information by Furnisher. For instance an e-commerce site who receives a credit card number or a college who receives an academic transcript from a student. In the language of federated identity brokerage, the Recipient is the relying party or service provider.

• Trust Anchor

  The party who can relay established trust for information presented by furnisher to a recipient. Trust anchors make our solution possible. A trust anchor is a party that the furnisher does business with. The range of entities that can serve as trust anchors is extensive, this can be a bank, an insurance company, an employer, a hospital, a university...etc. In the language of federated identity brokerage, the Trust Anchor is the attribute provider.

• Cipheredtrust

  • Privacy Buffer

    A privacy buffer protects the privacy of the Furnisher while facilitating information exchange between the Recipient and the Trust Anchor. It may at first seem odd to consider privacy as a potential concern given that the Furnisher is volunteering information and willingly engaging these parties.

    Consider a scenario where the furnisher is using a healthcare provider to verify some bit of information. Maybe the information the furnisher wants to present is blood type, that by itself is innocous enough, now suppose the healthcare provider is a cancer treatment center or an HIV treatment center, it is likely that while the Furnisher wishes to share their blood type information, it does not follow that they wish to reveal other information about their health

    Consider a second scenario where the Furnisher uses their employer to verify their age. Maybe the Recipient is a medical (or recreational) marijuana dealer, it is likely the Furnisher does not wish to reveal that information to their employer regardless of the reason they're buying marijuana.

    With these two simple scenarios we can see that there is grounds for a Furnisher to want a buffer between the Recipient and Trust Anchor even while they wish to share information between the two parties.

  • Trust Bridge

    As the diagram illustrates above, there exists a Trust gap between the Furnisher, Receipient and Trust Anchor, our role is to bridge this gap. Our implementation of the relay protocol via our API is the manifestation of this bridge.

    We can see that there is a trust surplus on the side of the trust anchor and there is a trust deficit on the side of the recipient, we brige this divide.

How the protocol works

Below is an outline of the information trust relay protocol and the important steps involved:

What follows is a precise description of the information trust relay protocol. Each step corresponds to a step in the diagram above. An assumption here is that the furnisher has an account with an existing trust anchor.

1. A furnisher presents information to recipient. This can take many forms, maybe during signing up for a service the furnisher puts in their name or enters a credit card where the recipient is the service provider (ex. social app, e-commerce app).
2. The recipient generates a request object via the POST /requests API call.
3. The API generates the request object and returns it to recipient. At this point the recipient would probably want to store elements of this request for further application flow processing.
4. At this point the recipient would hand the token code to the furnisher of the information. This is also the point where recipient may need to educate furnisher about how to use the token, ie what are they expected to do with it.
5. The furnisher logs into an account they have with a trust anchor, this could be their bank, insurance company ,university, healthcare provider...etc. Furnisher would present this token to trust anchor, probably through a self-service application interface, via phone, email or even in person.
6. The trust anchor uses the token to retrieve the request object generated in step 1. via a GET /requests API call.
7. The furnisher selects the information they wish to verify. This can be through a self-service application interface or via phone, email or even in person.
8. Trust anchor would then encrypt and sign the selected information and post it via the POST /responses API call. This encrypted and cryptographically signed information is essentially a trust seal for the information presented by the furnisher.
9. The furnisher may notify the recipient of the verification, this could also be an automated process where the recipient periodically checks the status of the request object. Also a callback webhook can be setup to notify recipient.
10. Recipient would then retrieve the encrypted trust via GET /responses API call.
11. Optionally the receipient would confirm that they've retrieved trust for the information presented in step 1, and hence can proceed with remaining application flow. Application for instance may have been a checkout application waiting for credit card ownership verification, so at this point a charge would be made against the card.

At its core, the trust relay protocol is a transport protocol that is primarily concerned with transporting/relaying trusted information in a manner that doesn't compromise the security or privacy of the user. It is possible for other protocols to be wrapped within this protocol, for instance it should be possible to wrap the OAuth and OpenID protocols with some caveats since those protocols have weaker privacy features.

REST API

The information trust relay protocol is implemented via a RESTful API that allows developers to easily integrate information verification into any application. The API and the protocol it implements is transparent and makes no assumptions about the logic of the applications that use it, this means developers can implement any workflow around it.

Cipher Suites

Cipher suites dictate the type of encryption and signature verification for trust transmission.

Cipher suites should be specified using the standard format as outlined in the TLS Cipher Suite Registry

The following is the set of cipher suites we currently suggest/support:

[TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256]
  

We currently only support SHA256withRSA,SHA256withPLAIN-ECDSA,SHA256withECDSA for signing and verification, including API call authentication.

Retrieve Cipher Suites

These Cipher Suites will be updated occasionally, users should make an API call to retrieve the current values.

Definition

Example Request

Example Response

Diffie-Hellman Parameters (Elliptical Curve)

Below are the list of recommended elliptical curves when using this method. Recipients are free to use any of the the generally accepted curves.

  	[secp256r1, secp384r1, secp521r1];
  

Retrieve DHParams

Definition (Elliptical Curve)

Example Request

Example Response

API Public Key

This is the public key for the API itself, in cases where the API needs to call itself it uses this key. Also if there is a need to send encrypted infomation to the API, this key can be used. If the API needs to sign something, this key can be used to verify it. Specifcally, webhook calls should be verified with this key.

The public key for the API can be retrieved vai the API call below.

Definition

Example Request

Example Response

API Authentication

For API calls that require authentication, basic HTTP authentication is used. Authentication is based on signature verification using the API public and private keys.

Signature base string construction

The purpose of a signature is to help the API verify that the request came from the owner of the API key (public key) and that the API call being processed has not been tampered with in transit. It is important to know that the tampering being discussed here is where someone intercepts your API call and attempts to modify an element, such as a parameter. Unless you use TLS with proper remote server verification, a man-in-the-middle attack can't be prevented with signature verification. Without TLS someone can intercept your API call and return a response of their choice to you.

The signature is a string concatenation of the following components:

• HTTP METHOD: This can be either GET,POST, DELETE,PUT,PATCH. This should be terminated with the newline character \n.
• API HOST: This is the full HTTP host url including the protocal scheme part. This should be one of the following: https://api.cipheredtrust.com, http://api.cipheredtrust.com. The port is assumed to be 80 or 443 (for TLS) and should not be explicitly specified. This should be terminated with the newline character \n.
• CALL PARAMETERS: This is a lexicographically ordered list of name value pairs that represent the parameters for the API call. The exact names and corresponding values would depend on the particular API call. The format for concatenating this list is as follows: name1=value1&name2=value2..This string must be preceeded by ?. If a particular request parameter is absent,the equivalent signature representation is an empty string. If there are no call parameters, this should be omitted completely, including the proceeding ?.
  
  

  This string should be constructed with the unencoded key/value, in other words don't url-encode before forming the string.

  This should be terminated with the newline character \n.
• CALL TIMESTAMP: This is the unix timestamp in UTC for when the API call was made from the client. It must be within 5 minutes of when the API attempts to verify the call.This must be passed as a request header Timestamp for the API call.

Concatenation is performed as follows:

Encrypt/Decrypt

In order for the trust anchor to encrypt information that the recipient can decrypt, both parties need to operate their cipher routines with the same settings. This section describes the ways the API facilitates successful encryption and decryption. In general the API models TLS and uses common default settings where applicable.

CBC Mode Cipher

• block-size- 128-bit.
• padding-mode- It should be PKCS #7 padding. TLS padding mode should be used, ie the last byte of the cipher text designates the padding length in bytes preceeded by the padding bytes, each with a value of the padding length.
• iv-length- The byte length of the initialization vector used to encrypt the information. This should be 128-bits.
• iv- Initialization vector. This should be prepended to the cipher text.
• hmac-mode- The mode should be Encrypt-then-MAC (EtM) as described here and here.
• hmac- HMAC-SHA256 hash of cipher text portion of ciphered_data. See section below on key derivation for the key that should be used for HMAC. The is 256-bit in length;
• ciphered_data format: iv cipher text hmac.

GCM Mode Cipher

• block-size- 128-bit.
• padding-mode- Padding not required but if a library demands a padding value then supply PKCS #7 padding.
• nonce-length- The byte length of the initialization vector used to encrypt the information. This should be 96-bits in length.
• nonce- Initialization vector. This should be prepended to the cipher text.
• associated-authentication-data- This is an empty string.
• auth-tag-length- The byte length of the authentication tag to be used during decryption. This should be 128-bits.
• auth-tag- The authentication tag to be used during decryption.
• ciphered_data format: nonce cipher text auth-tag.

Key Size

The key size is determined by the cipher suite used, however 128-bit should be considered the preferred key length. See section covering supported list of cipher suites.

Key Derivation

HKDF must be used to derive keys. A PRF must be created and used to derive keys. For 128-bit keys the generated HKDF key should be split in half with the first 128 bits used for encryption/decryption and the second 128 bits used for HMAC in CBC mode. For GCM mode the second half of 128 bits should be discarded.

Cipher Engine Specification

All elements of the API together should be sufficient for implementors to construct correct encryption and decryption routines,however, cryptography is complicated. To prevent situations where it is possible for either ends to correctly implement crypto routines that are however incompatible (even in small ways), the API requires precise specifications of the actual software logic that should be used for both encryption and decryption.

A simple example of implementation detail incompatibility stems from the implementation of the HMAC key derivation function. While minor deviations in implementation might not compromise the cryptographic properties of the derived keys, keys derived from such implementations will differ even when derived from the same shared secret.

Precise crypto routine specifications will ensure the software logic used by both ends of the API are compatible. The specifications will be in the form of source code (Java only for now) that can then be implemented in any language. The default spec is named api.

Retrieving engine specs

Example Response

Authenticating cipher engine specs

The API will authenticate cipher engine implementations used for API posts by decrypting a timestamped encrypted token supplied by the trust anchor against the API maintained implementation of the cipher engine spec. This ensures trust anchors are properly implementing cipher engine specs.

The default cipher engine spec named api can be found here.

Attribute Assertion Certification.

Note: This section is merely a set of ideas for future development that isn't yet integrated into the API.

At the moment the way the API certifies trust is to limit trust anchor status to only certain entities deemed to have credible systems in place for protecting the integrity of information they possess. We ask trust anchors to confirm that the information they relay is stored in a way that users cannot unduely tamper with it and also that some due deligence was done before the information was accepted into their system. For instance an employer that allows an employee to change their date of birth without any proofing cannot relay DOB information because the information cannot be considered trust worthy.

At scale however, what constitutes a valid trust anchor requires a more robust notion of a trusted entity with the right to assert a given attribute. In other words trust anchors are attribute providers and in many context there is going to be regulation around who can provide/assert which attribute. For higher levels of attribute assertion certification/assurance, there would need to be an auditing party that certifies that a given trust anchor is authorized to assert a given set of attributes.

Attribute Assertion Certificate.

This is a certificate sent to recipients to assure them that the attributes they're receiving came from an authentic trust anchor who's been certified to assert the attributes. For instances an employer can assert annual income attribute and can issue a certificate for such an assertion.

Attribute Assertion Certificate Authority.

This is an entity that certifies that a given trust anchor has the right to assert a set of attributes. This entity would also provide an authenticated interface that trust anchors can use to dynamically generate and sign assertion certificates.

The general process for facilitating a robust attribute assertion assurance would involve the following steps:

• To preserve furnisher privacy, a new asymmetric key pair should be generated for each request. Ideally asymmetric key pairs should never be reused between requests, however due to computational concerns this requirement could be relaxed in various ways while still ensuring a high degree of furnisher privacy.
• Send the public key along with the set of attributes to be asserted to an Attribute Assertion Certificate Authority via an authenticated and secure interface.
• Attribute Assertion Certificate Authority should confirm that the attributes for which they are being asked to issue a certificate are included in the set of attributes for which they have certified the given trust anchor.
• Attribute Assertion Certificate Authority should then generate and sign an x.509 certificate that includes the set of attributes being asserted. This certificate should identify the issuer so recipients can verify the certificate. The validity period for such a certificate must be very short to prevent abusive reuse.
• The trust anchor should include this certificate as part of the encrypted information they relay. The exact format for how this information should be included is still open to discussion. It may be that it can just be included as a field in a JSON/XML object, for ex attribute_assertion_certificate.
• The recipient should first verify the certificate,ie verify that it was issued by the specified issuer and the issuer is legitimate. The full list of Attribute Assertion Certificate Authorities would be publically published.

The approach outlined above is a much more robust technical approach. It should be possible to accomplish the same goal by simply have an Attribute Assertion Certificate Authority sign a comma seperated list of attributes along with the current UTC timestamp. This signature can then be relayed along with the identifier of the Attribute Assertion Certificate Authority that generated it.

Error Conditions

Below are the error conditions you can expect from the use of various API calls. The core API methods have a status field. The value of status will be success when the operation completes as expected. In the case of error, the status field would contain error and the response would contain an additional field error_message with one of the textual description below as its value.

Errors

Trust Anchor Accounts

Trust anchors are key to the trust relay protocol, they are the holders of trusted information. Only trust anchor accounts can do a POST /responses request. If you already have an API account, becoming a trust anchor is quite simple.

Domain validation

Domain validation is a way to prove that you have sufficient access to an organization's infrastructure in order for an account to be considered a trust anchor. Domain validation requires proving that the API account owner/creator does not only have access but programmatic access to an organization's infrastruture. These are key points to consider for domain validation:

1. Validated domains are tied to API keys. Every API key created by the API account owner can have a domain associated with it and the domain must be validated at the time of addition of the key. The API console provides the UI for doing this when you login to your API account. Note that domain association is optional for most API keys.

2. The host portion of the validation url is the domain that'll be validated. In other words a validation url that looks like https://mortgage.bankofworld.com/validate would validate only mortgage.bankofworld.com not the bankofworld.com top domain.

3. The validation url must be a programmatic end-point, meaning it must sign the validation url along with a validation code that would be added as a query string parameter by the API validation logic. The returned result from doing a GET request to the url should be the signature of the validation url. This url should be signed by the corresponding API private key and would be verified with the public key. Specifically, suppose you want to validate mortgage.bankofworld.com using the validation url https://mortage.bankofworld.com/validate, the string that must be signed would be:

   https://mortgage.bankofworld.com/validate?verificationCode=.... The query string parameter would be added before calling the validation url and can be retrieved to construct the signature string.

Trust anchor validation

1. Send an email to [email protected], it should include the fingerprint of the API key that has been domain validated and an email address at the organization (ex. [email protected]) that a verification code should be sent to.

2. Once we verify domain validation, we'll send an email to the email address in step 1 containing a verification code.

3. Login to your API account (under Account Information), enter the verification code to activate your Trust anchor status.

Note: not everyone can be a trust anchor, only organizations that we deem reputable would be approved as trust anchors.

Trust anchor accounts are required to rotate thier API keys regularly and the accounts would also be audited occasionally to ensure they are associated with specified organization. Basically the steps above would need to be repeated during an audit.

Webhooks

The API supports webhooks for event callback. You can configure webhooks on your account settings for both test and live modes. All webhook calls are signed with the API's private key so the receiving endpoints can verify using the API public key.

The following events are currently supported.

• ciphereddata_created

  This event is invoked when a POST /responses call is made. The recipient receives the callback.

  event object

  ATTRIBUTES
  event_id string	The unique id of the event.
  event_name string	The name of the event
  request_token string	The request token, use this to retrieve the actual response.
  post_time integer	The time the POST /responses call was made.
  retry_count integer	The number of times the event webhook would be invoked due to failure before it is abandoned.

  JSON

  { "event_id" : "159265ca-2135-4035-893e-0e41326b487c", "request_token" : "ycPvPuEU", "retry_count" : 5, "event_name" : "ciphereddata_created", "post_time" : 1445559172000 }

  The event object is the POST body of the http request that calls the webhook.

Authentication

Webhooks should authenticate events before processing them. Webhooks calls are made with an authorization header similar to what is provided with API calls. Authorization: API Public key fingerprint:Signature

Constructing signature base string

The webhook call is signed using the following signature string:

Webhook in line 2 above is the callback url for the event. The Timestamp component in line 4 is the value passed as the Timestamp header.

If any of the values in line 3 is null in the event object JSON, it must be omitted from the signature string.

Note: Order of the parameters matters, they must remain in lexicographical order.

Data Processing Automation

Once trust has been transmitted, it needs to be processed. In other words if a user verifies their age by encrypting and posting a number, how can the recipient be sure that the value in fact represents an age and how can this determination be made without additional human intervention?

To facilitate automated processing of relayed trust, data needs to be encoded in a manner that can support automated processing, to that end JSON and XML are the two formats supported/recommended for encrypted trust. While the recipient is expected to support either data formats, JSON is highly recommended for all requests unless there is a good reason to use XML.

JSON/XML Schema

When information is posted as a JSON object or XML, it should also be accompanied by a schema that describes the object to facilitate automated processing. The schema should be specified in the POST /responses API call.

In general the recipient would traverse the given schema and retrieve corresponding properties. In most cases it would make sense for the trust anchor to simply provide all data elements in a flat object without creating a complicated object structure in an attempt to maintain any sort of data association relationship.

The schema for the encrypted information should be encrypted and submitted when making a POST /responses API call.

Data Dictionary

While JSON or XML allows for automated processing of the data, the recipient still needs to be able to automatically determine what exactly a particular data element represents. In other words the trust anchor needs to be able to communicate to the recipient the actual meaning of a particular JSON object property or XML element/attribute. We provide a data dictionary API to help with determining the meaning of information.

Data Dictionary Domains

Data elements can be thought of as belonging to various domains/categories, domains generally represent industries,subject matter or object categories. Every data element belongs to a domain, people's name for instance belong to the personal domain, where as RX dose may belong to the healthcare domain. Because general information taxonomy is messy, there are no rules for how information attributes should be mapped to categories.

We maintain a personal data dictionary meant to help recipients automate the processing of information for a wide class of data elements such as personal information attributes (ex. name, age, dob...etc). What this means is that if a data element is annotated by a trust anchor as an item in the dictionary, then the recipient's processing software knows exactly what the data element represents and can process accordingly. For instance an annotation of birth_date, means the the data element represents a birth date without a person having to look at it to verify.

Data Dictionary API

There is an API to retrieve the data dictionary. Simply use the fully qualified path for a particulary dictionary domain or sub-domain.

Definition

{DICTIONARY-PATH} is the fully qualified path for a particular dictionary. Dictionaries can be nested in a hierarchical order as sub-domains starting from a particular domain.

Example Request to retrieve whole dictionary

Response

Example Request for a specific domain dictionary

Response

Annotating Data Elements

When constructing a schema for a given request, the trust anchor should annotate each data element that we have an annotation for in the data dictionary. For instance if a json property in the posted data represents a social security number then it should be annotated with https://api.cipheredtrust.com/v1/data-dictionary/personal.social_security_number, or a BMI value can be annotated with https://api.cipheredtrust.com/v1/data-dictionary/healthcare.bmi.

The dictionary annotation URL should be the first part of the description field in the schema. XML does not have a description attribute by default on the element element/tag, it should be added if XML schema is used.

Crowd Sourcing Data Dictionary

Ultimately, defining a comprehensive data dictionary that meets most needs is going to require an open process of making proposals/suggestions for an entry, developing consensus for the entry and its meaning and adding it to the API. We have created an online forum for building the data dictionary.

Authenticated End Points

The trust relay protocol does not (and cannot) provide for end-point authentication as is possible with TLS. In other words the API cannot prove to the recipient of cipheredtrust posts that the encrypted information has not been altered, for instance that bits have not been removed from a ciphertext, the API is a man-in-the-middle (a trusted one). The overall risk of this limitation to the integrity of the API is vanishingly small.

It is however entirely possible to have anonymous end-point authentication if a trust anchor maintains a per user asymmetric cryptographic key pair. A trust anchor can generate cryptographic (RSA, DSA) key pairs for their users and the user can use the public key to facilitate endpoint authentication and other symmetric-key cryptography functions over the trust relay protocol.

For instance a user (ie furnisher) could give a recipient their public key for a certain trust anchor to be used for encrypting a secret key that the trust anchor can then use for encrypting information to be posted to the API. Of course the resulting cipheredtrust post can also be signed to prevent undetected tampering.

The main point to note is that maintaining and transmitting public keys happens out-of-band, ie the API does not facilitate direct support for such use cases.

Anonymized Identities

While the trust relay protocol solves the problem of information authentication on the internet, a central point of tension on the internet is between the need of users to maintain their privacy through anonymity and the need of service providers to effectively prevent abuse of their services.

Sticky Anonymized Identities

Anonymized identities solve this problem by enabling service providers to establish sticky identities for their users without the users losing their anonymity. A sticky identity is one that is sticky for a given service provider, meaning it will be difficult or impossible for a user to simply create a new account by using a new email address.

User Tracking

Anonymized identities don't leak information about the user, this means a service provider would not be able to identify a user by linking them to some other anonymized identity. For instance if you establish an anonymized identity on Twitter and Facebook, neither service is able to deduce your true identity purely from the anonymized identity tokens they hold for you, even if each knows both tokens.

This feature prevents user tracking on the internet via anonymized identity tokens alone. Of course if a user reveals additional information about themselves via the use of a service then their true identity could be established through other means. Also service providers could use a user's IP address to establish tracking between services.

Constructing An Anonymized Id

Anonymized identities are represented as a HMAC-SHA-256 hash of a private user identity anchor, a recipient domain, a trust anchor domain.

This hash is produced via:

HMAC-SHA-256( recipient_domain+ HMAC-SHA-256( trust_anchor_domain+private_id_hash)).

The private_id_hash is the part of the anonymized_identity_token property of the response supplied by the trust anchor and should be constructed as:

HMAC-SHA-256(private_id)

The hash components are described below:

• private_id: This is any immutable unique id token, for instance a social security number or any trust anchor maintained unique user id.
• recipient_domain: This is the validated domain associated with the recipient of the identity, it will be extracted from their API public key.
• trust_anchor_domain: This is the validated domain associated with the Trust anchor posting the identity, it will be extracted from their API public key.

Note that the combination of components that are used to produce an anonymized identity token establishes a one-to-one mapping between a trust anchor and a recipient for a given anonymized identity.

In other words a furnisher can have as many anonymized identities as the number of trust anchors they have access to for any given recipient. This should not be a problem however since most furnishers are going to have access only to a limited number of trust anchors.

API Browser Extensions

To jumpstart the use of the API while we accumulate trust anchor integrations, we have implemented browser extentions for certain trust anchors. A browser (chrome/firefox) extension is a bit of code that runs in a users browser to provide additional functionality. In our case the extensions we have developed are simply client proxies. They allow us to intercept certain URLs and reroute the browser requests through the API to provide trust anchor functionality.

API browser extension for the Internal Revenue Service(IRS)

We currently have browser extensions for the Internal Revenue Service (IRS). With this extension installed, a user (furnisher) can login to the IRS Get Transcript ONLINE service and use it to verify identity, income, marital status, name, address, social security number.

With the IRS browser extension, the API will connect to the IRS and retrieve tax information and then allow the user to select the bits of information they wish to share with a recipient. The information will be encrypted and posted to the API. The API does not save or log any of the information from a users transcript.

With the API extension for IRS installed:

• A user (furnisher) should login to the Get Transcript ONLINE service.
• Select Record of Account Transcript for any year they wish to share information from.

Note that if IRS implements the API then there would be no need for this extension, we are providing that functionality for now.

More extensions are in development.

Public Key Infrastructure Overview

Public Key Infrastructure (PKI) is an alternative to the Trust Relay Protocol/API, it relies on the mechanics of asymmetric key pairs to facilitate trust on the internet at scale and inexpensively.

Our implementation consist of a consumer web app (Certisfy) and the API below.

PKI REST API

This is an API to support the operations that service providers need to perform to request, issue and verify certificates.

{
    "csr":"...",
    "plainFields":{
       [
        <plain-field-name>:<plain-field-value>
       ]*
     }
}

1.
{
    [<field-name>:<field-value>]*
}

2.
{
    [<masked-field-name>:<masked-field-value>]*
}

Certificate Trust Anchors

There are certain certificates that serve as trust anchors and can be used to delegate trust as well as sign other intermediate trust delegation certificates.

A good example of such a certificate is one issued to a police department. Such a certificate would further delegate trust to individual officer certificates, which can then be used to issue certificates to ordinary citizens.

Our PKI platform can sign such trust anchor certificates after sufficient due diligence has been performed. The PKI root certificate that would be used to sign trust anchor certificates can be accessed via the following endpoint.

Request

Response

Below is the payload format of a trust anchor certificate.

• name

  Name of trust anchor.

• website

  Appropriate website of trust anchor. This should be a page that provides useful information.

• address

  One line physical address

• geo-code

  Geo code of physical address

• labor-code

  Associated labor code. The idea here is to be able use the labor code to determine what the nature of the trust anchor entity is and make verification decisions based on that. Governments have a bunch of such codes, we are working on ways to make them easy to use by service providers.

• pki-maximum-delegates

  The pki-maximum-delegates states how many levels of trustworthiness delegation this trust anchor can have along any given chain that decends directly from the trust anchor. This would be based on the organizational structure of the the trust anchor. For instance a police department has a hierarchy that can be used to determine how many levels of delegation is valid.

  When this value is present on a trust anchor certificate, it means the issued certificates along any given chain that descends directly from the trust anchor and up to the pki-maximum-delegates could be delegates that can themselves issue trustworthy certificates. These can only be directly linked certificates with the field pki-trust-anchor-delegate set to true. In other words an unbroken chain of certificates all with the field pki-trust-anchor-delegate set to true, up to pki-maximum-delegates.

  Any gap in the chain between the trust anchor and an issuer without the pki-trust-anchor-delegate set to true should be considered invalid from the point of the first gap onwards.

  Note that the delegation limit applies only to vertical chains, lateral certificate issuance limits can only be imposed via administrative means.

Identity Anchor Certificates

Our PKI solution allows users to create anonymous identity anchor certificates. The anonymous identities have similar characteristics as described here.

The elements that currently can be used to anchor user identities can be found at this url:

As more suitable elements are discovered they'll be added.

Service Provider Anonymous Identity

The way to leverage an identity anchor certificate is to have a user generate a service specific anonymous identity signature from it. When a user signs information from a certificate, they can choose to include a service provider specific anonymous identity token using an identity anchor certificate.

The service provider specific anonymous identity token is issued by an identity anchor certificate, ie a certificate that contains one of the identity anchor elements.

The token is enclosed in the pki-identity field of the signature object. This service provider specific anonymous pki-identity has the following format:

• pki-sp-identifier

  This is the service identifier (a url for instance) given to a user to identify a service provider. During verification, service providers should confirm this value to acertain that the identity is for their service. The value of this field is a sha-256 hash of the actual identifier.

• pki-id-anchor-element

  This is the identity anchor element whose value the pki-sp-id-anchor-token is anchored to. See details here.

• pki-sp-id-anchor-token

  This is the anonymous identity token generated via the following hash computation:

  HMAC-SHA-256( pki-sp-identifier+ HMAC-SHA-256( pki-id-anchor-element-value)).

  The pki-id-anchor-element-value is the value of one of the identity anchor elements. Specifically, this field is a sha-256 hash of the actual element value.

  Note:In addition to an identity anchor certificate having one (or more) of the identity anchor elements, each such element must have a certificate field entry for a SHA-256 hash of an UPPER-CASE form of the element value. The corresponding hash field name will be <element-name>_HASH.

  This token value will remain unchanged for a given service provider URI and a given identity anchor element value combination, regardless of how many individual identity anchor certificates a user provisions for that same identity anchor element value.

• pki-cosignature

  This is the signature that links the enclosed signature object and the pki-sp-id-anchor-token signed via the PKI root key. Use the PKI root public key to verify it.

  This signature is generated by signing the following construction string:

  pki-id-anchor-element + pki-sp-id-anchor-token + pki-sp-identifier + signature.

  Service providers should verify this signature after verifying the enclosing signature object. Failure to perform this verification means a user could simply be misusing a certificate and doesn't actually own it, since there is no enforced id linkage for the claim without this signature being verified.

Identity Anchor Certificate Linking

Our PKI platform doesn't provide any direct linkage to the identity anchor certificate, this protects users privacy and allows users to use the same identity anchor certificate across different services. An indirect link however is established to prevent misuse.

In addition to the identity elements discussed above, when an identity is requested for an identity certificate itself, an anonymous link id is created that can be associated with a subsequent certificate request created and linked to that id. Every time a new certificate needs to be associated with an identity certificate, a new anonymous identity link must be generated by requesting an identity for a claim on the identity element (hash value) of the identity certificate itself.

The field pki-owner-id-info is present in the response for a certificate identity when the request is on a claim for the identity element (hash value) in an identity anchor certificate. The ownerIdCloak field value must be included as a plainField called pki-id-link in the related certificate request document for all subsequent certificates linked to the id certificate. ownerIdCloak field value is unique for each identity element (hash value) claim identity request, thus each new linked certificate will have a unique link id.

pki-id-link MUST be used every time a claim is made using a given certificate and its associated identity certificate, in order to link the two. pki-id-link should be added as a plainField in enclosed_sig.

The PKI platform will validate pki-id-link before issuing an identity for a claim.

Certisfy Client

The Certisfy client is the app that makes the PKI solution possible. You can think of it as a PKI based trust assertion and projection client. It abstracts away the cryptographic complication of using PKI with user-friendly flows and metaphores.

As a service provider implementing automation via the PKI API, you'll need to be familiar with the relevant data structures of the client. You'll ultimately need to support users importing Documents, Certificate Signing Requests and Certificates into the Certisfy app.

Certisfy Data Structure

These are the Certisfy data structures needed to support import of Documents,CSRs and Certificates created via automation.

{
"id":"...",
"name":"...",
"value":"..."
}

{
    "plainField":{
       "name":"...",
       "value":"..."
    },
    "hmacKey":"...",
    "maskedField":{
       "name":"...",
       "value":"..."       
     }
}

{
  "id":"...",
  "purpose":"..."
}