Why? Download Documentation Develop News

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

  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)