Notoriously Punctual Manatee

    node-posh

    0.1.1 • Public • Published

    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.

    Keywords

    none

    Install

    npm i node-posh

    DownloadsWeekly Downloads

    10

    Version

    0.1.1

    License

    MIT

    Last publish

    Collaborators

    • hildjj