Differences between revisions 1 and 3 (spanning 2 versions)
Revision 1 as of 2016-07-11 09:44:23
Size: 401
Editor: DanielPocock
Comment:
Revision 3 as of 2016-07-11 10:53:30
Size: 4746
Editor: DanielPocock
Comment:
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
Line 7: Line 6:

The intention is to minimize the number of things the user has to manually configure into their account settings.

=== Example use cases ===

 * a large organization such as a university or hospital wants to eliminate their traditional phone system and let every staff member connect to a new system using SIP
 * an Internet Telephony Service Provider (ITSP) wants to make it easier for customers to get connected using any app they choose
 * a community organization such as Debian wants to make it as easy as possible for members to access their SIP or XMPP accounts from any device

== Feature summary ==

 * various authentication mechanisms:
  * passwords
  * X.509 client certificates
  * PGP keys
 * standard Java API
 * Android API built on top of the standard Java API

== Workflow ==

 * an account is requested for the user, maybe they request it themselves, maybe it is requested by their manager or some other third party.
  * the only parameter specified at this stage is a username or phonenumber or some other specific identifier for the user
 * instructions to activate the account are given to the user. The instructions may be delivered through a web page, an email or a printed page of instructions that is sent by post.
  * Instructions included in this document include:
   * install the [[https://f-droid.org/repository/browse/?fdfilter=barcode+scanner&fdid=com.google.zxing.client.android|Barcode Scanner app]] or something equivalent
   * install a communications app of your choosing, for example, [[https://lumicall.org|Lumicall]] or CSipSimple for SIP or [[https://f-droid.org/repository/browse/?fdfilter=conversations&fdid=eu.siacs.conversations|Conversations for XMPP]]
   * scan the QR code / 2D barcode on the page or manually type the URL into the app
   * confirm the parameters that appear on screen match the parameters on the page
 * The QR code includes various details, they are also printed in a human-readable form on the page:
  * a URL for a provisioning server
   * and optionally the key fingerprint for the certificate on the provisioning server
  * URL and key fingerprint for a CA root used to sign ''client'' certificates in the network
  * the username being provisioned
  * any PGP keys (with full fingerprints) used to sign the keys of participants in the network
 * the user may also be sent other details, such as a PIN number, by separate means
 * the user follows the instructions to scan the QR code / type the URL
 * if they used the QR code, the details are displayed on screen and the user is asked to compare them with the full printed information they received
 * the provisioning client code connects to the server URL
 * the server may ask for additional details, such as the PIN. In this case, the provisioning client displays a form to ask the user for details. After the user enters the details, the client sends the request to the server again with the extra details as attributes.
 * eventually, when the server has all the details it requires, it sends a response to the client telling the client to generate a password or keypair or both.
  * if the client has to create a password, the server tells it whether it should be hashed and if so, which realm name to use and whether to use HA1 or HA1b hashing
 * the client generates a device UUID (if this is the first time it is setting up an account) and a line UUID each time it creates an account
 * the client generates a password or keypair or both
  * if a password is generated, it is stored in HA1 or HA1b format in the client
  * if a keypair is generated, a Certificate Signing Request (CSR) is also generated
 * the client sends the two UUIDs, the (hashed) password and/or CSR to the server
 * the server stores the UUIDs and associates them with the username
 * if a CSR was submitted, the server generates a client certificate and sends it back to the client along with any intermediate certificates and the root
 * the client periodically polls the server for account and device parameters
 * the server responds to the polls by sending parameters for the account/device
 * if the client detects new parameters, it informs the app through some callback function
 * the app decides whether it wants to use the parameters, it may prompt the user to accept them

Introduction

This page discusses a universal provisioning workflow for softphones and mobile RTC / VoIP apps.

The initial implementation is intended to include a Tomcat-based REST service and a library JAR for inclusion in desktop and mobile softphones built in the Java programming language, including Jitsi on the desktop, Lumicall and CSipSimple on Android.

The intention is to minimize the number of things the user has to manually configure into their account settings.

Example use cases

  • a large organization such as a university or hospital wants to eliminate their traditional phone system and let every staff member connect to a new system using SIP
  • an Internet Telephony Service Provider (ITSP) wants to make it easier for customers to get connected using any app they choose
  • a community organization such as Debian wants to make it as easy as possible for members to access their SIP or XMPP accounts from any device

Feature summary

  • various authentication mechanisms:
    • passwords
    • X.509 client certificates
    • PGP keys
  • standard Java API
  • Android API built on top of the standard Java API

Workflow

  • an account is requested for the user, maybe they request it themselves, maybe it is requested by their manager or some other third party.
    • the only parameter specified at this stage is a username or phonenumber or some other specific identifier for the user
  • instructions to activate the account are given to the user. The instructions may be delivered through a web page, an email or a printed page of instructions that is sent by post.
    • Instructions included in this document include:
      • install the Barcode Scanner app or something equivalent

      • install a communications app of your choosing, for example, Lumicall or CSipSimple for SIP or Conversations for XMPP

      • scan the QR code / 2D barcode on the page or manually type the URL into the app
      • confirm the parameters that appear on screen match the parameters on the page
  • The QR code includes various details, they are also printed in a human-readable form on the page:
    • a URL for a provisioning server
      • and optionally the key fingerprint for the certificate on the provisioning server
    • URL and key fingerprint for a CA root used to sign client certificates in the network

    • the username being provisioned
    • any PGP keys (with full fingerprints) used to sign the keys of participants in the network
  • the user may also be sent other details, such as a PIN number, by separate means
  • the user follows the instructions to scan the QR code / type the URL
  • if they used the QR code, the details are displayed on screen and the user is asked to compare them with the full printed information they received
  • the provisioning client code connects to the server URL
  • the server may ask for additional details, such as the PIN. In this case, the provisioning client displays a form to ask the user for details. After the user enters the details, the client sends the request to the server again with the extra details as attributes.
  • eventually, when the server has all the details it requires, it sends a response to the client telling the client to generate a password or keypair or both.
    • if the client has to create a password, the server tells it whether it should be hashed and if so, which realm name to use and whether to use HA1 or HA1b hashing
  • the client generates a device UUID (if this is the first time it is setting up an account) and a line UUID each time it creates an account
  • the client generates a password or keypair or both
    • if a password is generated, it is stored in HA1 or HA1b format in the client
    • if a keypair is generated, a Certificate Signing Request (CSR) is also generated
  • the client sends the two UUIDs, the (hashed) password and/or CSR to the server
  • the server stores the UUIDs and associates them with the username
  • if a CSR was submitted, the server generates a client certificate and sends it back to the client along with any intermediate certificates and the root
  • the client periodically polls the server for account and device parameters
  • the server responds to the polls by sending parameters for the account/device
  • if the client detects new parameters, it informs the app through some callback function
  • the app decides whether it wants to use the parameters, it may prompt the user to accept them