Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update documentation #618

Merged
merged 8 commits into from
Sep 25, 2024
Merged

Update documentation #618

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
654d78f
Apple: Fix #603: Better activation data sharing documentation
hvge Sep 11, 2024
583b723
docs: Document use of PowerAuth2 library in app extension
hvge Sep 11, 2024
f2fe759
docs: Fix #600: Warning about usage of UIDevice.current.name
hvge Sep 11, 2024
c4683b0
docs: Fix #613: Better documentation for activation states
hvge Sep 12, 2024
aac8a22
docs: Fixed wrong config example in extensions and watchOS SDK
hvge Sep 12, 2024
62a0a8e
Merge from 'develop'
hvge Sep 23, 2024
5ae1749
docs: Fix #580: Added more detailed documentation about additional co…
hvge Sep 23, 2024
05a90c6
docs: Addressed issues found in review
hvge Sep 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 34 additions & 76 deletions docs/PowerAuth-SDK-for-Android.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -813,36 +813,25 @@ fun validateTypedCharacters(input: String): String? {

To obtain detailed activation status information, use the following code:

<!-- begin codetabs Kotlin Java -->
```kotlin
// Check if there is some activation on the device
if (powerAuthSDK.hasValidActivation()) {
// If there is an activation on the device, check the status with server
powerAuthSDK.fetchActivationStatusWithCallback(context, object: IActivationStatusListener {
override fun onActivationStatusSucceed(status: ActivationStatus) {
// Activation state: State_Created, State_Pending_Commit, State_Active, State_Blocked, State_Removed, State_Deadlock
// Activation states are explained in detail in "Activation states" chapter below
when (status.state) {
ActivationStatus.State_Pending_Commit ->
// Activation is awaiting commit on the server.
Log.i(TAG, "Waiting for commit")
ActivationStatus.State_Active ->
// Activation is valid and active.
Log.i(TAG, "Activation is active")
ActivationStatus.State_Blocked ->
// Activation is blocked. You can display unblock
// instructions to the user.
Log.i(TAG, "Activation is blocked")
ActivationStatus.State_Removed -> {
// Activation is no longer valid on the server.
// You can inform user about this situation and remove
// activation locally.
Log.i(TAG, "Activation is no longer valid")
powerAuthSDK.removeActivationLocal(context)
}
ActivationStatus.State_Deadlock -> {
// Local activation is technically blocked and no longer
// can be used for the signature calculations. You can inform
// user about this situation and remove activation locally.
Log.i(TAG, "Activation is technically blocked")
powerAuthSDK.removeActivationLocal(context)
}
Expand All @@ -867,75 +856,44 @@ if (powerAuthSDK.hasValidActivation()) {
// No activation present on device
}
```
```java
// Check if there is some activation on the device
if (powerAuthSDK.hasValidActivation()) {
// If there is an activation on the device, check the status with server
powerAuthSDK.fetchActivationStatusWithCallback(context, new IActivationStatusListener() {
@Override
public void onActivationStatusSucceed(ActivationStatus status) {
// Activation state: State_Created, State_Pending_Commit, State_Active, State_Blocked, State_Removed, State_Deadlock
switch (status.state) {
case ActivationStatus.State_Pending_Commit:
// Activation is awaiting commit on the server.
android.util.Log.i(TAG, "Waiting for commit");
break;
case ActivationStatus.State_Active:
// Activation is valid and active.
android.util.Log.i(TAG, "Activation is active");
break;
case ActivationStatus.State_Blocked:
// Activation is blocked. You can display unblock
// instructions to the user.
android.util.Log.i(TAG, "Activation is blocked");
break;
case ActivationStatus.State_Removed:
// Activation is no longer valid on the server.
// You can inform user about this situation and remove
// activation locally.
android.util.Log.i(TAG, "Activation is no longer valid");
powerAuthSDK.removeActivationLocal(context);
break;
case ActivationStatus.State_Deadlock:
// Local activation is technically blocked and no longer
// can be used for the signature calculations. You can inform
// user about this situation and remove activation locally.
android.util.Log.i(TAG, "Activation is technically blocked");
powerAuthSDK.removeActivationLocal(context);
break;
case ActivationStatus.State_Created:
// Activation is just created. This is the internal
// state on the server and therefore can be ignored
// on the mobile application.
default:
android.util.Log.i(TAG, "Unknown state");
break;
}

// Failed login attempts, remaining = max - current
int currentFailCount = status.failCount;
int maxAllowedFailCount = status.maxFailCount;
int remainingFailCount = status.getRemainingAttempts();
Note that the status fetch may fail at an unrecoverable error `PowerAuthErrorCodes.PROTOCOL_UPGRADE`, meaning that it's not possible to upgrade the PowerAuth protocol to a newer version. In this case, it's recommended to [remove the activation locally](#activation-removal).

if (status.getCustomObject() != null) {
// Custom object contains any proprietary server specific data
}
}
### Activation states

@Override
public void onActivationStatusFailed(Throwable t) {
// Network error occurred, report it to the user
}
});
} else {
// No activation present on device
}
```
<!-- end -->
This chapter explains activation states in detail. To get more information about activation states, check the [Activation States](https://github.com/wultra/powerauth-crypto/blob/develop/docs/Activation.md#activation-states) chapter available in our [powerauth-crypto](https://github.com/wultra/powerauth-crypto) repository.

Note that the status fetch may fail at an unrecoverable error `PowerAuthErrorCodes.PROTOCOL_UPGRADE`, meaning that it's not possible to upgrade the PowerAuth protocol to a newer version. In this case, it's recommended to [remove the activation locally](#activation-removal).
#### `ActivationStatus.State_Created`

The activation record is created using an external channel, such as the Internet banking, but the key exchange between the client and server did not happen yet. This state is never reported to the mobile client.

#### `ActivationStatus.State_Pending_Commit`

The activation record is created and key exchange between the client and server already took place, but the activation record needs additional approval before it can be used.
hvge marked this conversation as resolved.
Show resolved Hide resolved

#### `ActivationStatus.State_Active`

The activation record is created and active. It is ready to be used for typical use-cases, such as generating signatures.

#### `ActivationStatus.State_Blocked`

The activation record is blocked and cannot be used for most of the use-cases, such as generating signatures. It can be unblocked and activated again.
hvge marked this conversation as resolved.
Show resolved Hide resolved

#### `ActivationStatus.State_Removed`

The activation record is removed and permanently blocked. It cannot be used for generating signatures or ever unblocked. You can inform user about this situation and remove the activation locally.

#### `ActivationStatus.State_Deadlock`

The local activation is technically blocked and can no longer be used for signature calculations. You can inform the user about this situation and remove the activation locally.

The reason why the mobile client is no longer capable of calculating valid signatures is that the logical counter is out of sync between the client and the server. This may happen only if the mobile client calculates too many PowerAuth signatures without subsequent validation on the server. For example:

- If your application repeatedly constructs HTTP requests with a PowerAuth signature while the network is unreachable.
- If your application repeatedly creates authentication tokens while the network is unreachable. For example, when trying to register for push notifications in the background, without user interaction.
- If you calculate too many offline signatures without subsequent validation.

To get more information about activation lifecycle, check the [Activation States](https://github.com/wultra/powerauth-crypto/blob/develop/docs/Activation.md#activation-states) chapter available in our [powerauth-crypto](https://github.com/wultra/powerauth-crypto) repository.
In rare situations, this may also happen in development or testing environments, where you’re able to restore the state of the activation on the server from a snapshot.

## Data Signing

Expand Down
48 changes: 36 additions & 12 deletions docs/PowerAuth-SDK-for-iOS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -475,28 +475,18 @@ if powerAuthSDK.hasValidActivation() {

// If no error occurred, process the status
if let status = status {
// Activation state: .created, .pendingCommit, .blocked, .removed, .deadlock
// Activation states are explained in detail in "Activation states" chapter below
switch status.state {
case .pendingCommit:
// Activation is awaiting commit on the server.
print("Waiting for commit")
case .active:
// Activation is valid and active.
print("Activation is active")
case .blocked:
// Activation is blocked. You can display unblock
// instructions to the user.
print("Activation is blocked")
case .removed:
// Activation is no longer valid on the server.
// You can inform the user about this situation and remove
// activation locally.
print("Activation is no longer valid")
powerAuthSDK.removeActivationLocal()
case .deadlock:
// Local activation is technically blocked and no longer
// can be used for the signature calculations. You can inform
// user about this situation and remove activation locally.
print("Activation is technically blocked")
powerAuthSDK.removeActivationLocal()
case .created:
Expand Down Expand Up @@ -529,7 +519,41 @@ if powerAuthSDK.hasValidActivation() {

Note that the status fetch may fail at an unrecoverable error `PowerAuthErrorCode.protocolUpgrade`, meaning that it's not possible to upgrade the PowerAuth protocol to a newer version. In this case, it's recommended to [remove the activation locally](#activation-removal).

To get more information about activation states, check the [Activation States](https://github.com/wultra/powerauth-crypto/blob/develop/docs/Activation.md#activation-states) chapter available in our [powerauth-crypto](https://github.com/wultra/powerauth-crypto) repository.
### Activation states

This chapter explains activation states in detail. To get more information about activation states, check the [Activation States](https://github.com/wultra/powerauth-crypto/blob/develop/docs/Activation.md#activation-states) chapter available in our [powerauth-crypto](https://github.com/wultra/powerauth-crypto) repository.

#### `PowerAuthActivationState.created`

The activation record is created using an external channel, such as the Internet banking, but the key exchange between the client and server did not happen yet. This state is never reported to the mobile client.

#### `PowerAuthActivationState.pendingCommig`

The activation record is created and key exchange between the client and server already took place, but the activation record needs additional approval before it can be used.
hvge marked this conversation as resolved.
Show resolved Hide resolved

#### `PowerAuthActivationState.active`

The activation record is created and active. It is ready to be used for typical use-cases, such as generating signatures.

#### `PowerAuthActivationState.blocked`

The activation record is blocked and cannot be used for most of the use-cases, such as generating signatures. It can be unblocked and activated again.
hvge marked this conversation as resolved.
Show resolved Hide resolved

#### `PowerAuthActivationState.removed`

The activation record is removed and permanently blocked. It cannot be used for generating signatures or ever unblocked. You can inform user about this situation and remove the activation locally.

#### `PowerAuthActivationState.deadlock`

The local activation is technically blocked and can no longer be used for signature calculations. You can inform the user about this situation and remove the activation locally.

The reason why the mobile client is no longer capable of calculating valid signatures is that the logical counter is out of sync between the client and the server. This may happen only if the mobile client calculates too many PowerAuth signatures without subsequent validation on the server. For example:

- If your application repeatedly constructs HTTP requests with a PowerAuth signature while the network is unreachable.
- If your application repeatedly creates authentication tokens while the network is unreachable. For example, when trying to register for push notifications in the background, without user interaction.
- If you calculate too many offline signatures without subsequent validation.

In rare situations, this may also happen in development or testing environments, where you’re able to restore the state of the activation on the server from a snapshot.

## Data Signing

Expand Down