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:
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 intoservice
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. Iftls
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 domainsrv
the DNS SRV protocol name to connect with. For example, "_xmpp-server._tcp"options
a configuration objectfallback_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 theconnect
event to callstart_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.