index.coffee

Classes

Functions

node-posh

See draft-miller-posh for more details on PKIX over Secure HTTP (POSH).

Classes

POSH

extends events.EventEmitter

Make a POSH-verified connection to a given domain on a given service.

Events:

  • 'posh request', url about to request a POSH document at the given URL
  • 'no posh', er No POSH document could be retrieved. Not really an error.
  • 'connecting', host, port, tls Connecting on the given host and port. If tls is true, a TLS handshake will start as soon as the connection finishes.
  • 'error', er an error was detected.
  • 'connect', socket the given socket was connected
  • 'secure', service_cert, posh_document the connection is secure either by RFC 6125 or POSH. The posh_document is null if the service_cert was valid via RFC 6125.
  • 'insecure', service_cert, posh_document the connection could not be determined to be secure. The posh_document is null if it could not be retrieved.

Instance Methods

constructor(@dns_domain, @dns_srv, options)

Create a POSH connection object

  • dns_domain connect to the given domain
  • dns_srv the DNS SRV protocol name to connect with. For example, "_xmpp-server._tcp"
  • options a configuration object
    • fallback_port The port to fall back on if SRV fails. If -1, use the port for the given SRV protocol name from /etc/services. Defaults to -1.
    • start_tls Don't do TLS immediately after connecting. Instead, wait for a listener for the connect event to call start_tls().
    • ca An array of zero or more certificate authority (CA) certs to trust when making HTTPS calls for POSH certs.

get_posh()

Attempt to get the POSH assertion for the domain and SRV protocol given in the constructor

  • returns a Q promise that will be fulfilled with the POSH object when/if it is retrieved. Rejections of this promise usually shouldn't be treated as an error.

resolve()

Do the SRV resolution.

  • returns a Q promise that will be fulfilled with host, port when complete. Ignores DNS errors, returning the original domain and fallback port.

connect_plain()

Connect without starting TLS. Wait for the connect event, then call start_tls.

  • returns a Q promise that will be fulfilled with the connected socket.

connect_tls()

Connect to the given serice, and start TLS immediately.

  • returns a Q promise that will be fulfilled with the connected socket.

start_tls()

On the already-connected socket, start a TLS handshake. This MUST occur after the 'connect' event has been called.

connect()

Connect to the domain on the specified service, using either an initially- plaintext approach (options.start_tls=true), or an initially-encrypted approach (options.start_tls=false).

  • returns a Q promise that will be fulfilled with the connected socket.

Functions

exports.create(certs, maxdepth)

Create a POSH document from a list of certificates.

  • certs an array of PEM-encoded certificate chains. The first certificate in each chain will be extracted into the POSH public key information.
  • maxdepth the maxiumum number of certificates to use from each chain.
  • returns a Q promise that will be fulfilled with a JavaScript representation (not a JSON string!) of the POSH document.

exports.write(dir, service, posh)

Write a file with the given POSH object in a file with the correct name for the given service.

  • dir the directory to write into
  • service the SRV record name for the target service. Example: "_xmpp-server._tcp"
  • returns a Q promise that will be fulfilled when the file is finished writing