The Secure Messaging specification describes a simple, decentralized security infrastructure for the Web based on public key cryptography. This system enables Web applications to establish identities for agents on the Web, associate security credentials with those identities, and then use those security credentials to send and receive messages that are both encrypted and verifiable via digital signatures.

Introduction

The future of messaging in Web services depends on three key features; message verifiability, secure messaging, and dynamic access control to resources. While a number of popular authorization mechanisms provide a way of performing dynamic access control to resources, most do not address message verifiability and secure messaging. More advanced Web service systems are being built now that require all three features. Historically, public/private key cryptography has provided a mechanism to achieve message verifiability (via digital signatures), and secure messaging (via encryption). Often, access control to resources are built on top of public/private key cryptography systems.

The challenge has always been in building an extensible, distributed, Public Key Infrastructure for the Web. This specification details how a decentralized Public Key Infrastructure can be built on top of the Web using Linked Data principles. This system can then be used to easily achieve message verifiability, secure messaging, and dynamic access control to resources on the Web.

Secure Messaging is not a replacement for Transport Layer Security, but is designed to work in concert with the security protocol. Secure Messaging are also capable of operating in environments where TLS is not available to the application. Similarly, Secure Messaging is compatible with the HTTP Signatures specification, extending it to support discoverable, machine-readable public keys and identity assertions.

Key Technologies

Technologies utilized in this specification include the JavaScript Object Notation for Linking Data [[!JSON-LD]], the HyperText Transfer Protocol [[!HTTP11]], the Public-Key Cryptography Standards (PKCS) #1 [[!PKCS1]], Advanced Encryption Standard [[!AES]], and HTTP Signatures [[!HTTP-SIGNATURES]].

The Key Registration Process

The registration process is necessary in order to publish a public key at a location on the Web.

Do not use .well-known, instead content negotiate for application/ld+json and return a JSON-LD document with the service information. Perhaps generalize this in another spec as "Linked Data Service Discovery".

Key Registration Terms

There are a number of terms that are used during the course of the registration process.

actor
An entity, such as a person or organization, that performs actions on the Internet.
account
An identifier with a set of log in credentials that is associated with a key listing service.
user agent
The piece of software operating on behalf of the actor. This is typically a Web Browser, but could be some other piece of Web-aware automated software acting on behalf of an actor.
key agent
A piece of software acting on behalf of an actor for the purposes of utilizing Secure Messaging. Typically, this is blogging software, content distribution software, online merchant software or a Web-based game.
key listing service
A Web service that is responsible for registering and publishing Secure Messaging for an actor
configuration service
A Web service that is used to publish the public Web service end-points and other public configuration information for a key listing service. A key listing service MUST publish this service at a top-level IRI named /.well-known/keys. The document MUST be available in JSON-LD compacted form and MUST include the https://w3id.org/keys/v1 JSON-LD context. The following key MUST be present in the published document: publicKeyService.
public key registration service
An interactive Web service used to register PEM-encoded X.509 public keys with the key listing service.

Key Owner Registration

In order for an actor to register a key, they must have an account on a key listing service. How this account is created is outside of the scope of this specification.

Web Key Registration

In order for an actor to take part in the public key infrastructure, they MUST register their public key with a key listing service.

The registration process is typically performed by a key agent. The registration is accomplished by executing the following algorithm:
  1. The key agent generates and stores a public/private key-pair that will be used by the key agent to digitally sign and/or encrypt messages.
  2. The key agent retrieves the key listing service configuration from the configuration service IRI.
    1. The configuration service IRI is generated by concatenating a base IRI for the key listing service, such as http://example.com/ with the /.well-known/keys suffix. For example, the previous key listing service IRI concatenated with the configuration suffix would result in the following configuration service IRI: http://example.com/.well-known/keys.
    2. An HTTPS GET is performed on the configuration service IRI with the HTTP Accept header set to application/ld+json; form=compacted. The key listing service MUST respond with a compacted JSON-LD document using the context specified at https://w3id.org/keys/v1.
    3. The result MUST be a JSON-LD document containing a flat set of key-value pairs. The data MUST contain at least the properties defined in the configuration service section.
  3. The key agent initiates an HTTP 302 redirect for the user agent. An HTTPS GET request is performed to the public key registration service IRI with the addition of two IRI query parameters. The first parameter, public-key, is the URL-encoded X.509 PEM-encoded public key. The second parameter, registration-callback, is the URL-encoded registration callback service IRI for the key agent.
  4. The key listing service associates the key agent with the key listing account based on the provided public key. Note that this process MUST authenticate the key listing account via a login process if the key listing account does not have an active login session. Other configuration steps may be performed at this stage, including the specification of defaults and preferences for the particular key agent.
  5. The key listing service specifies a set of key agent configuration values and encrypts the message according to the steps outlined in the Response Encryption Algorithm section. The result is sent back to the registration-callback IRI via a POST initiated by the user agent.
    1. The following configuration value MUST be included in the JSON-LD response to the key agent: publicKey.
    2. The JSON-LD response is compacted and encrypted using the public key associated with the registration request according to the algorithm defined in Response Encryption Algorithm.
    3. The encrypted response is transmitted to the registration-callback via an HTTP POST request that is initiatited by the user agent. This is most commonly accomplished by having the key listing service generate an HTML form that can be submitted to the key agent when a form submission button is clicked via the user agent.
    4. The key agent decrypts the base-64 encoded byte stream, extracts the configuration values and stores the location of the publicKey for use when messages are being digitally signed or encrypted.

The example below shows the full protocol-level exchange between the key agent and the key listing service. For the sake of brevity, not every optional parameter is included, just the bare minimum necessary to perform the key listing service registration.

--------------------------------- Step #1 -----------------------------------

*** Request: user agent -> key agent

POST /register-key HTTP/1.1
Host: my-host.example.org
Content-Length: 47
Content-Type: application/x-www-form-urlencoded

key-listing-service=http%3A%2F%2Fkeys-r-us.example.com%2F

*** key agent generates and stores public/private keypair

-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDptIkqrXhx7YVGsBZ5fY/Lz0il
0LXJrhUY43V/lLWdRf7JXY6tcgA5AmwNGZtJRyH79QXCJn+BAHUtl6gX2gvjs8N2
B5u4m0LtXyaFWtbQV9+hY3JRLOBiydPeXLgsnLwKiJ9v4CNXSNA5wT8vYGXiqq0B
US89y0M909ZTj2zDQwIDAQAB
-----END PUBLIC KEY-----

-----BEGIN RSA PRIVATE KEY-----
MIICXQIBAAKBgQDptIkqrXhx7YVGsBZ5fY/Lz0il0LXJrhUY43V/lLWdRf7JXY6t
cgA5AmwNGZtJRyH79QXCJn+BAHUtl6gX2gvjs8N2B5u4m0LtXyaFWtbQV9+hY3JR
LOBiydPeXLgsnLwKiJ9v4CNXSNA5wT8vYGXiqq0BUS89y0M909ZTj2zDQwIDAQAB
AoGALNmBrVgHEk4T0qH+XihTjThlZ7Tq/h5TXChipy5BwEHriHdU50JGeqpVVBpC
68gj5Hd8OGss8vPEiRBeqN0mhJlRaX5ijyFp2n8+7DhfOIVhCd1MXCGQPTrdXIo5
OOQECSplnALZfKr0VC4TBeW+oUZGMoG4rRSM5DfyPFJtlzECQQD8DkWBkhRsP1An
3qfZR8oUkvbaVg9jsCNvoBazYSS3OhsZ96ZSTyf9hJn28wGJmShuZA2eL5XjuTY4
m0fQDhj5AkEA7VzAqKOx5zlFTWXMIzn29uB59m4yJ7UwCyc7tisQA16I8B2HzJzZ
saipkpU2RUYaBrjtWaiVNtyXvZ7mccJpGwJBAMyE4/8bwfiHcwm2z+ktKBqDmUtW
E0ynKkmz01ef1kPaIQ1z9f/JfMBnrOpFCZVVsgnIo4gcQnox2X4a+S0nkzkCQBre
xCSTG2Gclx7S5lAakL2T3dqq0Nyz4zNwBo9xwodPHVtpTGU6YF5/RGsGnzUqYWnf
Z2cd8X5bbIYXxeic5H8CQQCcBOtOdrq9FXsEnyhG5gQXvGdxEAmM2eUs1g8E8kgx
KBTHOaBRQMgvjsdA/obrs7D0HrEbQqGOy7JBYGWZTsiI
-----END RSA PRIVATE KEY-----

--------------------------------- Step #2 -----------------------------------

*** Request: key agent -> key listing service

GET /.well-known/keys HTTP/1.1
Host: keys-r-us.example.com
Accept: application/ld+json,*/*;q=0.1

*** Response: key agent <- key listing service

HTTP/1.1 200 OK
Connection: close
Content-Length: 6075
Content-Type: application/ld+json
Date: Wed, 21 Sep 2012 22:30:16 GMT
Host: keys-r-us.example.com
Server: Apache/2.2.19 (Debian)

{
  "@context": "https://w3id.org/keys/v1",
  "id": "http://keys-r-us.example.com/i/key-master",
  "publicKeyService": "http://keys-r-us.example.com/keys",
}

--------------------------------- Step #3 -----------------------------------

*** Redirect: user agent <- key agent

HTTP/1.1 303 See Other
Location: http://keys-r-us.example.com/keys?public-key=↩
-----BEGIN+PUBLIC+KEY-----%0A↩
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDptIkqrXhx7YVGsBZ5fY%2FLz0il%0A↩
0LXJrhUY43V%2FlLWdRf7JXY6tcgA5AmwNGZtJRyH79QXCJn%2BBAHUtl6gX2gvjs8N2%0A↩
B5u4m0LtXyaFWtbQV9%2BhY3JRLOBiydPeXLgsnLwKiJ9v4CNXSNA5wT8vYGXiqq0B%0A↩
US89y0M909ZTj2zDQwIDAQAB%0A↩
-----END+PUBLIC+KEY-----↩
&registration-callback=http%3A%2F%2Fmy-host.example.org%2Fregistration-complete?response-nonce=pn9sueh43jefa
Content-Type: text/html
Content-Length: 174

<html>
 <head>
  <title>Identity Registration</title>
 </head>
 <body>
  <h1>Public Key Registration</h1>
   <p>You must now go to your identity provider and
    <a href="http://keys-r-us.example.com/keys?public-key=↩
-----BEGIN+PUBLIC+KEY-----%0A↩
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDptIkqrXhx7YVGsBZ5fY%2FLz0il%0A↩
0LXJrhUY43V%2FlLWdRf7JXY6tcgA5AmwNGZtJRyH79QXCJn%2BBAHUtl6gX2gvjs8N2%0A↩
B5u4m0LtXyaFWtbQV9%2BhY3JRLOBiydPeXLgsnLwKiJ9v4CNXSNA5wT8vYGXiqq0B%0A↩
US89y0M909ZTj2zDQwIDAQAB%0A↩
-----END+PUBLIC+KEY-----↩
&registration-callback=http%3A%2F%2Fmy-host.example.org%2Fregistration-complete?response-nonce=pn9sueh43jefa">
    register your identification information</a>
    there.</p>
 </body>
</html>

--------------------------------- Step #4 -----------------------------------

*** This step consists of a series of key listing service-specific UI
*** interactions that are out of scope for this document.

--------------------------------- Step #5 -----------------------------------

*** The key listing service creates a configuration object to return back
*** to the publishing agent

{
  "publicKey": "http://keys-r-us.example.com/keys/8472",
}

*** The configuration object is then encrypted and sent to the
*** registration-callback specified in the registration request above.

POST registration-complete?response-nonce=pn9sueh43jefa HTTP/1.1
Host: my-host.example.org
Content-Length: 473
Content-Type: application/ld+json

{
  "type": "EncryptedMessage",
  "cipherData": "VTJGc2RHVmtYMThOY3h2dnNVN290Zks1dmxWc3labi9sYkU0TGloRTdxY0dpblE4OHgrUXFNNi9l\n↩
a1JMWjdXOApRSGtrbzh6UG5XOFo3WWI4djJBUG1abnlRNW5CVGViWkRGdklpMEliczNWSzRQTGdB\n↩
UFhxYTR2aWFtemwrWGV3Cmw0eFF4ancvOW85dTlEckNURjMrMDBKMVFubGdtci9abkFRSmc5UjdV\n↩
Rk55ckpYalIxZUJuKytaQ0luUTF2cUwKcm5vcDU1eWk3RFVqVnMrRXZZSkx6RVF1VlBVQ0xxdXR4\n↩
L3lvTWd4bkdhSksxOG5ZakdiekJxSGxOYm9pVStUNwpwOTJ1Q0Y0Q2RiR1NqL0U3OUp4Vmh6OXQr\n↩
Mjc2a1V3RUlNY3o2Z3FadXZMU004KzRtWkZiakh6K2N5a1VVQ2xHCi9RcTk3b2o3N2UrYXlhZjhS\n↩
ZmtEZzlUeWk3Q2szREhSblprcy9WWDJWUGhUOEJ5c3RiYndnMnN4eWc5TXhkbHoKUkVESzFvR0FJ\n↩
UDZVQ09NeWJLTGpBUm0zMTRmcWtXSFdDY29mWFNzSGNPRmM2cnp1Wko0RnVWTFNQMGROUkFRRgpB\n↩
bFQ0QUpPbzRBZHpIb2hpTy8vVGhNOTl1U1ZER1NPQ3graFAvY3V4dGNGUFBSRzNrZS8vUk1MVFZO\n↩
YVBlaUp2Ckg4L1ZWUVU4L3dLZUEyeTQ1TzQ2K2lYTnZsOGErbGg0NjRUS3RabktFb009Cg==",
  "cipherKey": "uATtey0c4nvZIsDIfpFffuCyMYGPKRLIVJCsvedE013SpEJ+1uO7x6SK9hIG9zLWRlPpwmbar2bt\n↩
gTX5NBzYC5+c5ZkXtM1O8REwIJ7wmtLdumRYEbr/TghFl3pAgXhv0mVt8XZ+KLWlxMqXnrT+ByNw\n↩
z7u3IxpqNVcXHExjXQE=",
  "cipherAlgorithm": "aes-128-gcm",
  "authenticationTag": "q25H1CzsE731OmeyEle93w==",
  "initializationVector": "vcDU1eWTy8vVGhNOszREhSblFVqVnGpBUm0zMTRmcWtMrRX==",
  "publicKey": "http://keys-r-us.example.com/keys/8472"
}

Security Concerns for Registration

Discovery

All key listing services MUST generate key URLs that contain machine-readable information when dereferenced. This means that user agents may discover key information, such as the public key parameters and key owner information, by dereferencing the key URLs generated throughout this document. All machine-readable information is required to be available in [[!JSON-LD]] format. Additional machine-readable formats, like HTML5+RDFa [[!HTML-RDFA]], may be content negotiated by the user agent.

Discovery enables applications running on the Web to verify digital signatures without requiring key information to be looked up via a centralized public key repository.

Messaging

There are certain types of messages where it is important to be able to verify the originator of a message. For example, when dealing with a financial transaction, it is important to verify that the payment originator initiated the transaction. It may also be important to encrypt a message such that only the intended recipient is able to decrypt and read it.

Two of the more prevalent features of public/private key cryptography are 1) the ability to verify the originator of a message via a digital signature, and 2) the ability to encrypt messages intended for a particular recipient. This specification details a protocol for encrypting and digitally signing messages such that only the intended recipient is able to decrypt and verify the sender of the message.

Messaging Terms

The following terminology is used to describe concepts used to generate and secure messages that are sent and received using Secure Messaging. Many of these terms are borrowed from public/private key cryptography. A more complete description of RSA-based signatures can be found in Public-Key Cryptography Standards (PKCS) #1 [[!PKCS1]].

message
A JSON-LD byte stream that is used to convey a request or a response in the system.
public key
A cryptographic mechanism that can be used to verify digital signatures or encrypt secrets such that only the software with access to the corresponding private key can decrypt the secret.
private key
A cryptographic mechanism that can be used to generate digital signatures and decrypt encrypted data.
signed message
A type of message that has a digital signature attached to it, generated using a private key, that is verifiable and incredibly difficult to forge.
initialization vector
A cryptographic input to an encryption algorithm. It is typically used to initialize certain block cipher encryption schemes. For a receiving application to be able to decrypt a message, it must know the decryption key and the initialization vector. The value is typically base-64 encoded.
encrypted message
A type of message that has been obfuscated using a public key, which is incredibly difficult to decode by any person except for the one that holds the associated private key.
domain
A string value that specifies the operational domain of the signature. This may be an Internet domain name like example.com, a ad-hoc value such as mycorp-level3-access, or a very specific transaction value like 8zF6T$mqP. The value provides the capability for the signer to specify an intended target such that the signed message cannot be used elsewhere.

Message Signature Algorithm

The following algorithm ensures that the originator of an Web service call can be verified as long as the public key can be retrieved by the receiver. A message is provided as input and, using a private key and a public key IRI, a signed message is produced as output. All strings are UTF-8 encoded.

  1. Remove any signature key-value pair from the top-level of the message. Copy the message to the signed message.
  2. Generate the normalized message by normalizing the message according to the RDF Graph Normalization algorithm.
    Refer to the exact RDF Graph Normalization algorithm.
  3. Generate the signature value:
    1. Create a timestamped message and initialize it to the emtpy string. Generate an ISO8601 combined date and time string containing the current date and time, accurate to at least one second, in Universal Time Code format. For example: 2011-09-23T20:21:34Z. Append the combined date and time string to the timestamped message.
    2. If a nonce is specified, append the value to the timestamped message.
    3. Append the normalized message to the timestamped message.
    4. If a domain is specified, append the character '@' followed by the value to the timestamped message.
    5. Digitally sign the timestamped message using the private key and then base-64 encode the resulting value. The resulting base-64 encoded string is the signature value.
  4. Add a signature key to the signed message with a JSON object containing the following key-value pairs:
    type
    GraphSignature2012
    creator
    A URL pointing to the public key information associated with the private key that created the signature.
    created
    The string value of the combined date and time string generated by this algorithm.
    domain (optional)
    A string value specifying the intended domain of the signature.
    nonce (optional, but strongly recommended)
    A string value that will be encoded in the encrypted response to the requesting agent. It is RECOMMENDED that this value is a session identifier that is associated with the user agent that initiated the request, plus a hyphen, plus a cryptographically secure string for use as a nonce. For example, jf793ksj72jkf-78p82qpj87dnd2f839. See The Response Nonce section to understand more about how this value is used to prevent replay attacks and its accepted limitations.
    signatureValue
    The value of the signature value generated by this algorithm.

The following example shows an input message and the resulting signed message:

*** message
{
  "@context": "https://w3id.org/payswarm/v1",
  "title": "Hello World!"
}

*** signed message
{
  "@context": "https://w3id.org/payswarm/v1",
  "title": "Hello World!",
  "signature": {
    "type": "GraphSignature2012",
    "creator": "http://payswarm.example.com/i/john/keys/5",
    "created": "2011-09-23T20:21:34Z",
    "signatureValue": "OGQzNGVkMzVm4NTIyZTkZDYMmMzQzNmExMgoYzI43Q3ODIyOWM32NjI="
  }
}
        

Message Signature Verification Algorithm

In order to ensure a secure communication environment the following algorithm SHOULD be used to verify all request signatures. A signed message is provided as input and an indication of whether the signature is valid or a forgery is produced as output. All strings are UTF-8 encoded.

  1. Generate the original message by copying the signed message and removing the signature value from the original message.
  2. Generate the original normalized message by normalizing the original message according to the RDF Graph Normalization algorithm.
    Refer to the exact RDF Graph Normalization algorithm.
  3. Verify the original signature value:
    1. Generate the original timestamped message by setting its value to the value of the created key in the signed message. Append the nonce value, if specified. Append the original normalized message to the original timestamped message. If a domain is specified, append the '@' character followed by the value.
    2. Retrieve the PEM-encoded public key from the public key IRI provided in signer value. The public key MAY also be retrieved from a cache. ???Verify the original nonced message using the public key to cryptographically verify the signatureValue???
      We need to be more explicit about what is happening here.

Message Encryption Algorithm

The following algorithm ensures that a message intended for a particular recipient can be obfuscated such that only the intended recipient can read the message. A message is provided as input and, using a public key and a public key IRI, a encrypted message is produced as output.

  1. Generate a cryptographically secure symmetric key that is exactly 16 bytes in length.
  2. Generate a cryptographically secure initialization vector that is exactly 16 bytes in length.
  3. Generate the encrypted initialization vector by using the recipient's public key to encrypt the initialization vector.
  4. Generate the encrypted data and authentication tag by encrypting the message using the RSA with AES 128-bit Galois/Counter Mode (GCM) algorithm, using the symmetric key and the initialization vector generated previously in this algorithm.
  5. Generate the encrypted symmetric key by using the recipient's public key to encrypt the symmetric key.
  6. Generate the encrypted message by creating a JSON object containing the following key-value pairs:
    type
    EncryptedMessage
    cipherData
    The base-64 encoded value of the encrypted data.
    cipherKey
    The base-64 encoded value of the encrypted key.
    cipherAlgorithm
    The value rsa-aes-128-gcm.
    initializationVector
    The base-64 encoded value of the encrypted initialization vector.
    authenticationTag
    The base-64 encoded value of the authentication tag.
    publicKey
    The public key IRI associated with the public key that was used to encrypt the symmetric key in this algorithm.

The following example shows a typical input message and what an encrypted message looks like when generated using the algorithm above.

*** message
{
  "type": "Preferences"
  "currency": "USD",
  "minimumAmount": "0.05",
  "maximumRate": "10.0",
  "destination": "http://example.com/people/manu/accounts/article-sales",
  "publicKey": "http://payswarm.example.com/i/manu/keys/23",
  "license": "https://w3id.org/payswarm/licenses/blogging",
  "licenseHash": "961ec496092bf6ee08d6255d96069b5186332689",
}

*** encrypted message
{
  "type": "EncryptedMessage",
  "cipherData": "VTJGc2RHVmtYMThOY3h2dnNVN290Zks1dmxWc3labi9sYkU0TGloRTdxY0dpblE4OHgrUXFNNi9l\n↩
a1JMWjdXOApRSGtrbzh6UG5XOFo3WWI4djJBUG1abnlRNW5CVGViWkRGdklpMEliczNWSzRQTGdB\n↩
UFhxYTR2aWFtemwrWGV3Cmw0eFF4ancvOW85dTlEckNURjMrMDBKMVFubGdtci9abkFRSmc5UjdV\n↩
Rk55ckpYalIxZUJuKytaQ0luUTF2cUwKcm5vcDU1eWk3RFVqVnMrRXZZSkx6RVF1VlBVQ0xxdXR4\n↩
L3lvTWd4bkdhSksxOG5ZakdiekJxSGxOYm9pVStUNwpwOTJ1Q0Y0Q2RiR1NqL0U3OUp4Vmh6OXQr\n↩
Mjc2a1V3RUlNY3o2Z3FadXZMU004KzRtWkZiakh6K2N5a1VVQ2xHCi9RcTk3b2o3N2UrYXlhZjhS\n↩
ZmtEZzlUeWk3Q2szREhSblprcy9WWDJWUGhUOEJ5c3RiYndnMnN4eWc5TXhkbHoKUkVESzFvR0FJ\n↩
UDZVQ09NeWJLTGpBUm0zMTRmcWtXSFdDY29mWFNzSGNPRmM2cnp1Wko0RnVWTFNQMGROUkFRRgpB\n↩
bFQ0QUpPbzRBZHpIb2hpTy8vVGhNOTl1U1ZER1NPQ3graFAvY3V4dGNGUFBSRzNrZS8vUk1MVFZO\n↩
YVBlaUp2Ckg4L1ZWUVU4L3dLZUEyeTQ1TzQ2K2lYTnZsOGErbGg0NjRUS3RabktFb009Cg==",
  "cipherKey": "uATtey0c4nvZIsDIfpFffuCyMYGPKRLIVJCsvedE013SpEJ+1uO7x6SK9hIG9zLWRlPpwmbar2bt\n↩
gTX5NBzYC5+c5ZkXtM1O8REwIJ7wmtLdumRYEbr/TghFl3pAgXhv0mVt8XZ+KLWlxMqXnrT+ByNw\n↩
z7u3IxpqNVcXHExjXQE=",
  "cipherAlgorithm": "rsa-aes-128-gcm",
  "authenticationTag": "q25H1CzsE731OmeyEle93w==",
  "initializationVector": "vcDU1eWTy8vVGhNOszREhSblFVqVnGpBUm0zMTRmcWtMrRX==",
  "publicKey": "http://payswarm.example.com/i/manu/keys/23"
}
        

Message Decryption Algorithm

The following algorithm is used to decrypt an encrypted response. The input is an encrypted message and the result is the original unencrypted message.

  1. Generate the decryption key by base-64 decoding the cipherKey value and using the private key associated with the public key IRI in publicKey to decrypt the base-64 decoded value.
    Refer to the exact algorithm that is used to do the decryption in the AES spec.
  2. Generate the initialization vector by base-64 decoding the initializationVector value and then using the private key associated with the public key IRI in publicKey to decrypt the base-64 decoded value.
  3. Generate the authentication tag by base-64 decoding the authenticationTag value.
  4. Generate the original unencrypted message by applying the cipherAlgorithm to the cipherData value. Use the decryption key, initialization vector, and base64-decoded authentication tag generated in this algorithm as inputs to the cipher algorithm.

Security Considerations

The following section describes security considerations that developers implementing this specification should be aware of in order to create secure software.

The Response Nonce

The nonce mechanism is used in order to prevent replay attacks, but implementers must be aware that it is not capable of preventing man-in-the-middle attacks. Only a full end-to-end encryption channel is capable of accomplishing that feat and if implementers are concerned about man-in-the-middle attacks, they are strongly advised to run all sensitive messages that could be compromised by man-in-the-middle attacks over HTTPS.

Detail the nonce mechanism that is used in the current PaySwarm implementations.

Permission and Access Rights Delegation

During the Key Registration Process, a key listing service MAY ask the actor that is registering to grant a number of permissions and access rights to any agent that digitally signs a message to a Web service using the registered key. Note that this mechanism is similar to the OAuth permission granting mechanism and can be used in place of OAuth if the system requires both Permission and Access Rights Delegation as well as digital signatures. To take advantage of this mechanism, a agent would digitally sign a message requesting that a certain action be performed on behalf of the actor.

Key Revocation and Expiration

In order for a key pair to be revoked, the revocationDate MUST be associated with the key. In order to specify an expiration date for a key pair, the validUntil date MUST be associated with the key. All software systems utilizing the key pair MUST honor the revocation and validity dates and fail to verify any signatures made on or after the date and time specified. Similarly, the validFrom date establishes the date and time on which the key can be used to digitally sign and encrypt data. All software systems utilizing the key pair MUST honor the creation date and fail to verify any signatures made before the date and time specified.