diff --git a/autopush/router/apns2.py b/autopush/router/apns2.py index 6410f4e6..0c6e9dc2 100644 --- a/autopush/router/apns2.py +++ b/autopush/router/apns2.py @@ -34,7 +34,7 @@ def __init__(self, cert_file, key_file, topic, """Create the APNS client connector. The cert_file and key_file can be derived from the exported `.p12` - **Apple Push Services: *bundleID*** key contained in the **Keychain + **Apple Push Services: *bundleID* ** key contained in the **Keychain Access** application. To extract the proper PEM formatted data, you can use the following commands: diff --git a/autopush/router/apnsrouter.py b/autopush/router/apnsrouter.py index 66069e82..3cd6da6e 100644 --- a/autopush/router/apnsrouter.py +++ b/autopush/router/apnsrouter.py @@ -24,6 +24,8 @@ def _connect(self, rel_channel, load_connections=True): :param rel_channel: Release channel name (e.g. Firefox. FirefoxBeta,..) :type rel_channel: str + :param load_connections: (used for testing) + :type load_connections: bool :returns: APNs to be stored under the proper release channel name. :rtype: apns.APNs @@ -43,7 +45,16 @@ def _connect(self, rel_channel, load_connections=True): load_connections=load_connections) def __init__(self, ap_settings, router_conf, load_connections=True): - """Create a new APNS router and connect to APNS""" + """Create a new APNS router and connect to APNS + + :param ap_settings: Configuration settings + :type ap_settings: autopush.settings.AutopushSettings + :param router_conf: Router specific configuration + :type router_conf: dict + :param load_connections: (used for testing) + :type load_connections: bool + + """ self.ap_settings = ap_settings self._base_tags = [] self.apns = dict() @@ -58,7 +69,7 @@ def register(self, uaid, router_data, app_id, *args, **kwargs): """Register an endpoint for APNS, on the `app_id` release channel. This will validate that an APNs instance token is in the - ``router_data``, + `router_data`, :param uaid: User Agent Identifier :type uaid: str diff --git a/autopush/settings.py b/autopush/settings.py index 1c2c34d2..fa5d8daf 100644 --- a/autopush/settings.py +++ b/autopush/settings.py @@ -349,7 +349,7 @@ def parse_endpoint(self, token, version="v1", ckey_header=None, :param token: The obscured subscription data. :param version: This is the API version of the token. :param ckey_header: the Crypto-Key header bearing the public key - (from Crypto-Key: p256ecdsa=) + (from Crypto-Key: p256ecdsa=) :param auth_header: The Authorization header bearing the VAPID info :raises ValueError: In the case of a malformed endpoint. diff --git a/docs/api.rst b/docs/api.rst index f082f335..271481a9 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -10,7 +10,6 @@ documentation is organized alphabetically by module name. :maxdepth: 1 api/db - api/endpoint api/exceptions api/logging api/main diff --git a/docs/api/endpoint.rst b/docs/api/endpoint.rst deleted file mode 100644 index f169cdfe..00000000 --- a/docs/api/endpoint.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. _endpoint_module: - -:mod:`autopush.endpoint` ------------------------- - -.. automodule:: autopush.endpoint - -Base Class -++++++++++ - -.. autoclass:: AutoendpointHandler - :members: - :private-members: - :member-order: bysource - -HTTP Endpoints -++++++++++++++ - -.. autoclass:: EndpointHandler - :members: - :private-members: - :member-order: bysource - -Types -+++++ - -.. autoclass:: Notification - -Utility Functions -+++++++++++++++++ - -.. autofunction:: parse_request_params diff --git a/docs/api/router/apnsrouter.rst b/docs/api/router/apnsrouter.rst index 7c0b6680..00c6124c 100644 --- a/docs/api/router/apnsrouter.rst +++ b/docs/api/router/apnsrouter.rst @@ -10,3 +10,11 @@ :special-members: __init__ :private-members: :member-order: bysource + +.. automodule:: autopush.router.apns2 + +.. autoclass:: APNSClient + :members: + :special-members: __init__ + :private-members: + :member-order: bysource diff --git a/docs/apns.rst b/docs/apns.rst new file mode 100644 index 00000000..d00ce9dc --- /dev/null +++ b/docs/apns.rst @@ -0,0 +1,102 @@ +Configuring for the APNS bridge +=============================== + +APNS requires a current Apple Developer License for the platform +or platforms you wish to bridge to (e.g. iOS, desktop, etc.). Once +that license has been acquired, you will need to create and export +a valid `.p12` type key file. For this document, we will concentrate +on creating an iOS certificate. + +Create the App ID +----------------- + +First, you will need an Application ID. If you do not already have an +application, you will need to `create an application ID `_. +For an App ID to use Push Notifications, it must be created as an **Explicit App ID**. +Please be sure that under "**App Services**" you select **Push Notifications**. +Once these values are set, click on [Continue]. + +Confirm that the app settings are as you desire and click [Register], or click [Back] and correct them. +**Push Notifications** should appear as "Configurable". + +Create the Certificate +---------------------- + +Then `Create a new certificate `_. +Select "Apple Push Notification service SSL" for either Development or Production, depending on +intended usage of the certificate. "Development", in this case, means a certificate that will +not be used by an application released for general public use, but instead only for personal +or team development. This is also known as a "Sandbox" application and will require +setting the "use_sandbox" flag. Once the preferred option is selected, click +[Continue]. + +Select the App ID that matches the Application that will use Push Notifications. Several +Application IDs may be present, be sure to match the correct App ID. This will be the App ID which +will act as the recipient bridge for Push Notifications. Select [Continue]. + +Follow the on-screen instructions to generate a **CSR file**, click [Continue], +and upload the CSR. + +Download the newly created *iOSTeam_Provisioning_Profile_.mobileprovision* keyset, and +import it into your **KeyChain Access** app. + +Exporting the .p12 key set +-------------------------- + +In **KeyChain Access**, for the **login** keychain, in the **Certificates** category, +you should find an **Apple Push Services: *your AppID*** certificate. Right click on +this certificate and select *Export "Apple Push Services:"...*. Provide the file +with a reasonably unique name, such as "Push_Production_APNS_Keys.p12", so that you can find it easily +later. You may wish to secure these keys with a password. + +Converting .p12 to PEM +---------------------- + +You will need to convert the .p12 file to PEM format. *openssl* can perform +these steps for you. A simple script you could use might be: + +.. code-block:: bash + + #!/bin/bash + echo Converting $1 to PEM + openssl pkcs12 -in $1 -out $1_cert.pem -clcerts -nokeys + openssl pkcs12 -in $1 -out $1_key.pem -nocerts -nodes + + +This will divide the p12 key into two components that can be read by the autopush application. + +Sending the APNS message +------------------------ + +The APNS post message contains JSON formatted data similar to the following: + +.. code-block:: json + + { + "aps": { + "alert": "notification title", + "content_available": 1 + } + "key": "value", + ... + } + + +*aps* is reserved as a sub-dictionary. All other *key*: *value* slots are open. + +In addition, you must specify the following headers: +* *apns-id*: A lowercase, dash formatted UUID for this message. +* *apns-priority*: Either **10** for Immediate delivery or **5** for delayable delivery. +* *apns-topic*: The bundle ID for the recipient application. This must match the bundle ID of +the AppID used to create the *"Apple Push Services:..."* certificate. It usually has the format +of `com.example.ApplicationName`. +* *apns-expiration*: The timestamp for when this message should expire in UTC based seconds. +"0" means immediate expiration. + +Handling APNS responses +----------------------- + +APNS returns a status code and an optional JSON block describing the error. A list of `these +responses are provided in the APNS documentation `_ + + diff --git a/docs/architecture.rst b/docs/architecture.rst index 7c781bda..e6ca03df 100644 --- a/docs/architecture.rst +++ b/docs/architecture.rst @@ -194,7 +194,7 @@ After Identification: clients router table entry, proceed to step 2. 2. Read notifications from prior month and send to client. - Once all acks are received for all the notifications for that month proceed + Once all ACKs are received for all the notifications for that month proceed to step 3. 3. Copy the blank message entry of valid channels to the new month message table. @@ -220,7 +220,7 @@ Push Characteristics notifications will be accepted for delivery (except in one edge case). In this state, the Push server will reply to the Endpoint with a 503 to indicate it cannot currently deliver the notification. Once the Push - server has received ack's for all sent notifications, new notifications + server has received ACKs for all sent notifications, new notifications can flow again, and a check of storage will be done if the Push server had to reply with a 503. The Endpoint will put the Notification in storage in this case. @@ -259,7 +259,7 @@ Push Endpoint Length The Endpoint URL may seem excessively long. This may seem needless and confusing since the URL consists of the unique User Agent Identifier (UAID) and the Subscription Channel Identifier (CHID). Both of these are class 4 -Universially Unique Identifiers (UUID) meaning that an endpoint contains +Universally Unique Identifiers (UUID) meaning that an endpoint contains 256 bits of entropy (2 * 128 bits). When used in string format, these UUIDs are always in lower case, dashed format (e.g. "01234567-0123-abcd-0123-0123456789ab"). diff --git a/docs/glossary.rst b/docs/glossary.rst index 4813984b..21fc95f9 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -44,7 +44,7 @@ Glossary also be referred to as a :term:`Channel` UAID - The Push User Agent Regisration ID. Push assigns each remote recipient + The Push User Agent Registration ID. Push assigns each remote recipient (Firefox client) a unique identifier. These may occasionally be reset by the Push Service or the client. diff --git a/docs/http.rst b/docs/http.rst index e3ac8c68..88b76024 100644 --- a/docs/http.rst +++ b/docs/http.rst @@ -40,7 +40,8 @@ Lexicon :{UAID}: The Push User Agent Registration ID Push assigns each remote recipient a unique identifier. {UAID}s are UUIDs in -lower case, dashed format. (e.g. '01234567-abcd-abcd-abcd-012345678abc') This value is assigned during **Registration** +lower case, dashed format. (e.g. '01234567-abcd-abcd-abcd-01234567abcd') This +value is assigned during **Registration** :{CHID}: The :term:`Channel` Subscription ID @@ -225,7 +226,7 @@ Update the message at the given `{message_id}`. .. note:: - In the rare condition that the client is online, and has recieved + In the rare condition that the client is online, and has received the message but has not acknowledged it yet; then it is possible that the client will not get the updated message until reconnect. This should be considered a rare edge-case. @@ -326,7 +327,7 @@ This call requires no Authorization header for first time use. .. note:: If additional information is required for the bridge, it may be - included in the paramters as JSON elements. Currently, no additional + included in the parameters as JSON elements. Currently, no additional information is required. **Reply:** @@ -380,7 +381,7 @@ we are updating existing information. .. note:: If additional information is required for the bridge, it may be - included in the paramters as JSON elements. Currently, no additional + included in the parameters as JSON elements. Currently, no additional information is required. **Reply:** diff --git a/docs/index.rst b/docs/index.rst index fd9830e9..9d2480a1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -22,7 +22,7 @@ the `Mozilla Push Service architecture diagram`_. This push service uses websockets to talk to Firefox, with a Push endpoint that implements the :term:`WebPush` standard for its :ref:`http` API. -Autopush API's +Autopush APIs ============== For developers writing mobile applications in Mozilla, or web developers using @@ -135,7 +135,7 @@ Reference License ======= -``autopush`` is offered under the Apache License 2.0. +``autopush`` is offered under the Mozilla Public License 2.0. .. _\#push: irc://irc.mozilla.org/push .. _Mozilla Push Service architecture diagram: http://mozilla-push-service.readthedocs.io/en/latest/#architecture diff --git a/docs/releasing.rst b/docs/releasing.rst index 7f37d0fb..b70823c2 100644 --- a/docs/releasing.rst +++ b/docs/releasing.rst @@ -14,7 +14,7 @@ Versions Autopush uses a ``{major}.{minor}.{patch}`` version scheme, new ``{major}`` versions are only issued if backwards compatibility is affected. Patch versions are used if a critical bug occurs after production deployment that -requires a bugfix immediately. +requires a bug fix immediately. Dev Releases ============ diff --git a/docs/running.rst b/docs/running.rst index f75ea1b4..8aae94be 100644 --- a/docs/running.rst +++ b/docs/running.rst @@ -69,7 +69,7 @@ run both of the Autopush daemons. To generate one with the docker image: .. code-block:: bash - $ docker run -t -i bbangert/autopush autokey + $ docker run -t -i ~/autopush autokey Key = hkclU1V37Dnp-0DMF9HLe_40Nnr8kDTYVbo2yxuylzk= Store the key for later use (including the trailing ``=``). @@ -91,7 +91,7 @@ By default, the following services will be exposed: ``ws://localhost:8080/`` - websocket server -``http://localhost:8082/`` - HTTP Endoint Server (See :ref:`the HTTP API `) +``http://localhost:8082/`` - HTTP Endpoint Server (See :ref:`the HTTP API `) You could set the ``CRYPTO_KEY`` as an environment variable, or setup a more thorough configuration using config files as documented below. @@ -133,14 +133,14 @@ Configuration files can be located in: The three configuration files are: * *autopush_connection.ini* - contains options for use by the websocket handler. - This file's path can be specifed by the ``--config-connection`` option. + This file's path can be specified by the ``--config-connection`` option. * *autopush_shared.ini* - contains options shared between the connection and endpoint handler. This file's path can be specified by the ``--config-shared`` option. * *autopush_endpoint.ini* - contains options for the HTTP handlers This file's - path can be specifed by the ``--config-endpoint`` option. + path can be specified by the ``--config-endpoint`` option. Sample Configurations --------------------- diff --git a/docs/testing.rst b/docs/testing.rst index 57078a64..3b5133ad 100644 --- a/docs/testing.rst +++ b/docs/testing.rst @@ -65,5 +65,5 @@ On Android, you can set ``dom.push.debug`` to enable debug logging of Push via ``adb logcat``. For desktop use, you can set ``dom.push.loglevel`` to ``"debug"``. This will -log all push messagesto the Browser Console (Tools > Web Developer > Browser +log all push messages to the Browser Console (Tools > Web Developer > Browser Console).