node-posh

PKIX Over Secure HTTP (POSH) tools for node.js. See http://tools.ietf.org/html/draft-miller-posh-00 for more information.

Usage

Usage: genposh [options] [cert filename...]

Options:
  --help, -h        Show this message and exit
  --out, -o         Directory in which to output files             [default: "."]
  --days, -d        Days of validity for the generated certificate [default: 365]
  --service, -s     SRV-style service name for the POSH file       [default: "_xmpp._tcp"]
  --maxcerts, -m    The maximum number of certs to output in the
                    x5c field.  0 means all.                       [default: 0]
  --commonname, -c  Create a new certificate, with this common name (multiple ok)

Installation

npm install node-posh

Example

Generate a new certificate that is good for 30 days. Keep the old certificate in the the POSH output to support the roll-over period:

genposh -d 30 -s _imap._tcp -c localhost old-cert.pem

This will generate a file called posh._imap._tcp.json that contains POSH JSON that looks like this:

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "localhost:Jb9DgTJyJQQuMo0lgEU0FijVaF0",
      "n": "tgN-hrmVCeAz4dCRnsNDaIyYOFIHaRK1zqCURvsiY-NopMFq38qBwOecRso0Xy8qHbUMw7xwvfn2cOAkG4G8k-_Fo55hV_kMZQVIZMOpXVmEsNZ34N9Bj91e_UI_-UK-ejeUwkSxyH9fpPf5L4bZZtGi2_vZl2y-Ik39OV5c5Uc",
      "e": "AQAB",
      "x5c": [
        "MIIBnzCCAQgCCQCLHVds8mHyBDANBgkqhkiG9w0BAQUFADAUMRIwEAYDVQQDDAlsb2NhbGhvc3QwHhcNMTMwNzI4MDU0MzI3WhcNMTMwODI3MDU0MzI3WjAUMRIwEAYDVQQDDAlsb2NhbGhvc3QwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBALYDfoa5lQngM+HQkZ7DQ2iMmDhSB2kStc6glEb7ImPjaKTBat/KgcDnnEbKNF8vKh21DMO8cL359nDgJBuBvJPvxaOeYVf5DGUFSGTDqV1ZhLDWd+DfQY/dXv1CP/lCvno3lMJEsch/X6T3+S+G2WbRotv72ZdsviJN/TleXOVHAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAi2QwxfUp2xrdBftEsuAxg2LrEaoO+WwvSCPbyUUGU+98/d8+gYqeIybDWDltzGt/ZSZvZstgNsgGPEPeK4M29m6BIZzOhztqZ5GEsnhvSI2Yhg2ZBxP7hmiDkBqPoq6HoX3FVec0ilnLmRU1WDWXwOVLY6Wn7F6hTys9pKSU9aw="
      ]
    },
    {
      "kty": "RSA",
      "kid": "localhost:xpqT5yQpLvdwCeBB6Fydah1rQkE",
      "n": "1l4_n_wO2zOL3BNcAaw_aeVmryoVVRI429mSQ00AcwArW6U02lxM7fuIR-RJe0xl7KtDZBsgZbgK_Y5lCpRHUAuk9ZAsl-gsZIBWQXnyFKVNSV6yxlv3OgE__K9Wfqih1j8SKfPLffnvsXisb979DR-DgvrwxtBj0oJYwI4yUqc",
      "e": "AQAB",
      "x5c": [
        "MIIBnzCCAQgCCQDdbgfPWRJHHTANBgkqhkiG9w0BAQUFADAUMRIwEAYDVQQDDAlsb2NhbGhvc3QwHhcNMTMwNzI4MDU0MzExWhcNMTMwODI3MDU0MzExWjAUMRIwEAYDVQQDDAlsb2NhbGhvc3QwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBANZeP5/8Dtszi9wTXAGsP2nlZq8qFVUSONvZkkNNAHMAK1ulNNpcTO37iEfkSXtMZeyrQ2QbIGW4Cv2OZQqUR1ALpPWQLJfoLGSAVkF58hSlTUlessZb9zoBP/yvVn6oodY/Einzy33577F4rG/e/Q0fg4L68MbQY9KCWMCOMlKnAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEACbIaGqXdRUkrlmjXTyo4Rikh1sYrxtZQL/XSmNw1uwzNPtlwaEziAtLI9HsCfryZ7vwshEy81xcoBCsIu7WJ1xX/iLaVzFOt2bkN3de6UECqPsEaUEXksg2wTCV4ItpAlMNh4Ix/yF5cHwJ91dSvkcEZm2ERr1TPs/BeAHUIHKs="
      ]
    }
  ]
}

API

Functions

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.

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

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(@domain, @srv, options)

Create a POSH connection object

• domain connect to the given domain
• 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.