From 3c970b1286c82694c121031ab6760b9446a40942 Mon Sep 17 00:00:00 2001 From: Paul Cruickshank Date: Tue, 23 Mar 2021 18:02:27 +0000 Subject: [PATCH 1/2] Try and clarify behaviour when device secret is lost --- content/client-lib-development-guide/features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/client-lib-development-guide/features.textile b/content/client-lib-development-guide/features.textile index 6cfb5950b7..739ea74d30 100644 --- a/content/client-lib-development-guide/features.textile +++ b/content/client-lib-development-guide/features.textile @@ -1000,7 +1000,7 @@ h3(#activation-state-machine). Activation State Machine ***** @(RSH3a2a2)@ If a custom @registerCallback@ was provided to @Push#activate@, pass it the local @DeviceDetails@. ***** @(RSH3a2a3)@ Otherwise, makes an asynchronous HTTP PUT request to @/push/deviceRegistrations/:deviceId@ using the local @DeviceDetails@ with the push details as body. When the registration validation request is complete, a @RegistrationSynced@ or @SyncRegistrationFailed@ event should be fired. ***** @(RSH3a2a4)@ Transitions to @WaitingForRegistrationSync@. -**** @(RSH3a2b)@ If the local device does not have @id@ and @deviceSecret@, both are generated locally. The @id@ must be a "ulid":https://github.com/ulid/spec or similar globally-unique identifier. The @deviceSecret@ must be created using secure random data with sufficient entropy to generate a digest of at least 32 bytes (eg using sha256) and encoding that digest with base64. The local @DeviceDetails@ is updated with the resulting @deviceId@ and @deviceSecret@. +**** @(RSH3a2b)@ If the local device does not have @id@ or @deviceSecret@, both are generated locally. The @id@ must be a "ulid":https://github.com/ulid/spec or similar globally-unique identifier. The @deviceSecret@ must be created using secure random data with sufficient entropy to generate a digest of at least 32 bytes (eg using sha256) and encoding that digest with base64. The local @DeviceDetails@ is updated with the resulting @deviceId@ and @deviceSecret@. If either the @id@ or the @deviceSecret@ is lost then a new pair must be created. **** @(RSH3a2c)@ If the local device has the necessary push details (registration token, etc.), sends a @GotPushDeviceDetails@ event. **** @(RSH3a2d)@ If the local device does not have the necessary push details, it initiates a request to the underlying platform (or otherwise generates them) **** @(RSH3a2e)@ Transitions to @WaitingForPushDeviceDetails@. From 395588ca326bb64cdaacd9684a53e913d8c588b5 Mon Sep 17 00:00:00 2001 From: Paul Cruickshank Date: Wed, 7 Apr 2021 14:01:48 +0100 Subject: [PATCH 2/2] Add explicit device secret statement to RSH8 --- content/client-lib-development-guide/features.textile | 1 + 1 file changed, 1 insertion(+) diff --git a/content/client-lib-development-guide/features.textile b/content/client-lib-development-guide/features.textile index 739ea74d30..f751de176a 100644 --- a/content/client-lib-development-guide/features.textile +++ b/content/client-lib-development-guide/features.textile @@ -1110,6 +1110,7 @@ h3(#local-device). LocalDevice ** @(RSH8g)@ Whenever any change arises of the push transport details for local device (eg an FCM registration token update triggered by the platform), a @GotPushDeviceDetails@ event is sent to "the state machine":#RSH3. ** @(RSH8h)@ If an attempt to obtain the push transport details for local device (eg an FCM registration token) fails, a @GettingPushDeviceDetailsFailed@ event containing the indicated error is sent to "the state machine":#RSH3. ** @(RSH8i)@ Each time the library is instanced, if the LocalDevice has push device details (eg an APNS deviceToken), and if the platform supports it, it must verify the validity of those details (eg by requesting a token from the platform and comparing that with the already-known token). If as a result there are updated details, then an update to the Ably server is triggered by sending a @GotPushDeviceDetails@ event to "the state machine":#RSH3. +** @(RSH8j)@ If during library initialisation the @LocalDevice@ @id@ or @deviceSecret@ attributes are not able to be loaded then those LocalDevice details must be discarded and the ActivationStateMachine machine should transition to the @NotActivated@ state. New @LocalDevice@ @id@ and @deviceSecret@ attributes should be generated on the next activation event. h2. Types