Validation Agent Protocol

In its current form, the Monkeysphere Validation Agent is conceived of as a minimalistic HTTP server that accepts two different requests:

GET / -- initial contact query, protocol version compatibility. (no query parameters) (returns: PROTOVERSION, SERVER, AVAILABLE)

POST /reviewcert -- request validation of a certificate (required query parameters: PEER, CONTEXT, PKC{DATA,TYPE}) (optional query parameters: KEYSERVERPOLICY) (returns: VALID, MESSAGE, SERVER)

Query parameters are posted as a JSON blob (not as www-form-encoded).

The variables that are returned are application/json as well.

Definitions

query parameters

  • PEER: the identity of the entity being validated. A dictionary of two elements: NAME is the name of the peer (such as an OpenPGP UID) and TYPE is role of peer with the following types accepted:

    • client
    • server
    • peer
  • CONTEXT: the setting in which the certificate is offered. For example, "https" means: "this certificate was offered by an HTTPS server". The currently understood contexts are:

    • https
    • ssh
    • smtp
    • ike
    • postgresql
    • imaps
    • imap
    • submission
  • PKC: the "public key carrier". The PKC is a dictionary of two elements: TYPE is the type of carrier with the following types accepted:

    • x509der
    • x509pem
    • opensshpubkey
    • rfc4716
    • openpgp4fpr

    DATA is the key carrier data itself (e.g. 'x509der' is an array of bytes that can be assembled into the certificate).

  • KEYSERVERPOLICY: optional; states an advisory preference for how/whether the agent should contact the keyserver network for information about the key. The options are always, never, and unlessvalid (see the msva-perl(1) man page section about the KEYSERVER_POLICY environment variable for more details). Be aware that the agent may disregard, override, or simply not implement this preference.

return parameters

  • VALID: a bool that states the validity of the context/peer given the key supplied by the PKC: "true" means valid, "false" means not valid.

  • MESSAGE: a message about the validity of the request.

  • SERVER: a simple string reporting the implementation of the server. For example: "MSVA-Perl 0.6"

  • PROTOVERSION: API version

  • AVAILABLE: server availability (bool)