PFS Service

Perfect Forward Secrecy (PFS) is a technique, that protects previously intercepted traffic from being decrypted even if the main private key is compromised.

Virgil PFS Service is a standalone web-service that is dedicated to solve the PFS use-case scenario. It works over Virgil Cards PKI infrastructure and heavily uses Virgil Cards as building blocks. Virgil PFS service can be accessed by using the Virgil PFS Service SDK or Virgil PFS API.

Virgil PFS Service address:

https://api.virgilsecurity.com/pfs/v2

All API calls require authentication with Virgil JWT. So all requests go through Virgil API Gateway which bypasses the request with preset HTTP headers: X-Application-Id, X-Virgil-Identity.

Each recipient is identified by:

The Virgil PFS REST API supports the following operations:

Creates a set of keys for provided ID of the Identity Card .

Request info

HTTP Request method    PUT
Request URL            https://api.virgilsecurity.com/pfs/v2/keys HTTP/1.1
Headers                Authorization: Virgil {JWT Token}

Request

{
    "identity_card_id": "3084dab511135ec...b5db52bca8f7bf6b0b83a7fa4c740a59",
    "long_term_key": {
      "public_key": "BASE64_STRING",
      "signature":  "BASE64_STRING"
    },
    "one_time_keys": [
      "BASE64_STRING",
      "BASE64_STRING",
      "BASE64_STRING",
      "BASE64_STRING"
    ]
}

Response info

HTTP/1.1 200 OK
Content-Type: application/json

Returns the subset of keys for provided identity (user).

Request info

HTTP Request method    POST
Request URL            https://api.virgilsecurity.com/pfs/v2/keys/actions/pick-one HTTP/1.1
Headers                Authorization: Virgil {JWT Token}

Request

{
    "identity": "[email protected]"
}

Response info

HTTP/1.1 200 OK
Content-Type: application/json

Response

{
	"identity_key": "BASE64_STRING",
	"long_term_key": {
	   "public_key": "BASE64_STRING",
	   "signature":  "BASE64_STRING"
	},
	"one_time_key": "BASE64_STRING"
}

Returns the list of subset of keys for provided identities.

Request info

HTTP Request method    POST
Request URL            https://api.virgilsecurity.com/pfs/v2/keys/actions/pick-batch HTTP/1.1
Headers                Authorization: Virgil {JWT Token}

Request

{
    "identities": ["[email protected]", "[email protected]"]
}

identities - number of identities for search should be between 1 and 50.

Response info

HTTP/1.1 200 OK
Content-Type: application/json

Response

[
  {
    "identity": "[email protected]",
    "identity_key": "BASE64_STRING",
    "long_term_key": {
        "public_key": "BASE64_STRING",
        "signature": "BASE64_STRING"
    },
    "one_time_key": "BASE64_STRING"
  },
  {
    "identity": "[email protected]",
    "identity_key": "BASE64_STRING",
    "long_term_key": {
        "public_key": "BASE64_STRING",
        "signature": "BASE64_STRING"
    },
    "one_time_key": "BASE64_STRING"
  }
]

Validates a list of one-time keys IDs and returns subset of that list with already used one-time keys IDs.

Request info

HTTP Request method    POST
Request URL            https://api.virgilsecurity.com/pfs/v2/keys/actions/validate HTTP/1.1
Headers                Authorization: Virgil {JWT Token}

Request

{
  "long_term_key_id": "BASE64_STRING",
  "one_time_keys_ids": [
      "BASE64_STRING",
      "BASE64_STRING",
      "BASE64_STRING",
      "BASE64_STRING"
  ]
}

Response info

HTTP/1.1 200 OK
Content-Type: application/json

Response

{
  "used_long_term_key_id": "BASE64_STRING",
  "used_one_time_keys_ids": [
      "BASE64_STRING",
      "BASE64_STRING",
      "BASE64_STRING",
      "BASE64_STRING"
  ]
}

Deletes keys entity from the PFS service.

Request info

HTTP Request method    DELETE
Request URL            https://api.virgilsecurity.com/pfs/v2/keys HTTP/1.1
Headers                Authorization: Virgil {JWT Token}

Response info

HTTP/1.1 200 OK
Content-Type: application/json

The Application uses standard HTTP response codes:

This status is returned in extremely rare cases of internal application errors

Virgil Security provides SDKs which allow you to communicate with the Virgil PFS Service to upload, download, and synchronize encrypted sensitive data (private keys) between user's devices:

• Swift
• Kotlin/Java