Zum Inhalt

Introduction

Introduction to BlueID App Integration

Environments

Before we start to explain how BlueID works and how you can use the different SDKs for your purposes, it is fundamental to know that we offer separate environments for different purposes.

Overview

We offer two separate environments for different purposes:

  • Releases are rolled out on the Integration environment first, so that you are able to test the changes against your code. This environment is only for development and test purposes.

  • The Production environment is - as the name suggests - for productive use in your end user application.

Note: Every component which uses one environment cannot be used from any other environment and vice versa. This means that each component is initialized for exactly one environment. An API key is only valid for one specific environment. To sum up, devices that belong to one environment cannot be used in any other environment! If you want to upgrade your application to use the production BlueID Trust Center, you either have to remove and reinstall the application or call destroy() before reinitializing it!

Each environment has two services: The BlueID Device API, which smartphone apps and Lock Servers communicate with, and the BlueID Operator API, which is for BlueID Token and device management.

Integration environment (INT)

This environment offers a basis for testing and development.

Device API: https://deviceapi-int.blueid.net/deviceapi

Operator API: https://operatorapi-int.blueid.net/operatorapi

API Documentation: https://operatorapi-int.blueid.net/operatorapi/apidocs/index.html

Production environment (PROD)

Use this environment for productive use.

Device API: https://deviceapi-prod.blueid.net/deviceapi

Operator API: https://operatorapi-prod.blueid.net/operatorapi

API Documentation: https://operatorapi-prod.blueid.net/operatorapi/apidocs/index.html

Certificate Pinning

It is a good idea to use a technology called certificate pinning. Compare OWASP on this subject.

Since we moved to AWS, it's not recommended to pin to our own certificate but to the Amazon Root Certificate. By doing this, you avoid running into problems when our certificates get renewed and you still gain the security advantage of not being exposed to a broken CA taking over your connections.

Components overview

  1. BlueID Trust Center, which consists of:

    1. BlueID Operator API (used to administrate BlueID Tokens and manage devices)

    2. BlueID Device API (used to communicate with smartphone apps and Lock Servers)

  2. Object secured with a Lock Server (e.g. a car control unit)

  3. A smartphone app with BlueID (e.g. a car sharing app)

All three components must be integrated into your business logic. In this document we will refer to your business logic as operator backend.

The operator backend provides for example bookings, images, user information and the login for your smartphone app. It may also exchange data with your Lock Server (independently of the BlueID protocol).

The operator backend connects via the BlueID Operator API to the BlueID Trust Center to create BlueID Tokens. The tokens are then fetched by the smartphone app that uses the platform-specific BlueID SDK - e.g. BlueID SDK for Android or BlueID SDK for iOS. The smartphone app can then use these BlueID Tokens to control a BlueID Secured Object, e.g. to unlock a car via a smartphone app.

Once you have set up the infrastructure as instructed, you can start to use BlueID.

Granting permissions

In order to gain access to an object secured with BlueID (e.g. a car), you need to issue a BlueID Token (= a permission) to a mobile device so that the owner of the Mobile Device is authorized to connect to the Lock Server of the object.

A BlueID Token contains information about the features that may be accessed, as well as the exact time frame of the access authorization. It is solely created for a specific Lock Server, which verifies the authenticity and validity of the token when a command is executed. Tokens cannot be transferred to other Mobile Devices or used for other Lock Servers except the exact ones for which they were created. Only you - the Operator - can create BlueID Tokens for Mobile Devices and Lock Servers that belong to you.

Device initialization

Before tokens can be issued to customers, both Mobile Devices and Lock Servers must be initialized using your Operator API key. During this process, each device generates a pair of keys - a public and a private one - and sends the public key to the BlueID Trust Center. The BlueID Trust Center then assigns a unique identifier to each device. It is called "mobileDeviceId" for smartphone apps and "securedObjectId" for Lock Servers. These identifiers, as well as the key pairs generated, are valid throughout the lifespan of a smartphone app installation or Lock Server respectively and don't have to be renewed.

BlueID Token creation and usage

Creating a BlueID Token means making a call to our BlueID Operator API (a RESTful interface), which is part of the BlueID Trust Center. More details on how to initiate such a call can be found in the section Managing BlueID Tokens.

To create a BlueID Token you need this information:

  • Identifier of the smartphone app (mobileDeviceId)

  • Identifier of the Lock Server (securedObjectId)

  • Intended validity time frame of the token

  • Permitted communication channels (e.g. Bluetooth, Bluetooth Smart, NFC, ...)

  • Permitted command codes, which are the link to the logic on your Lock Server (e.g. tokn, time, ...)

After creating the BlueID Token, it will be downloaded on the next synchronization of the Mobile Device and is usable from then on by executing a command. Presupposed that the validity time of the BlueID Token is valid.

In a real-world scenario, you would typically want to assign the mobileDeviceId to a person and the securedObjectId to a car, a door or a similar object. This mapping is not provided by BlueID and must be implemented on your own as part of a backend service.

BlueID Token revocation

A BlueID Token can be revoked before the end of its intended lifespan, e.g. if a customer returns a car earlier than expected. In this case, it is possible to revoke that token. This means that the BlueID Token will be removed on the next synchronization of the Mobile Device. The revoke information will also be stored on the Secured Object for the case that the customer does not synchronize its mobile.

Integration into your app
Requirements

Before you can integrate BlueID in your Apple iOS or Google Android app, you need to get a valid Operator API key from us.

BlueID SDK for Android
Requirements

This SDK requires at least Android 5.0 (Lollipop) or higher.

To include the BlueID SDK in your application, you simply have to add the JAR library provided. This process depends very much on your build system, therefore we will not go into detail here.

Initialization

When the smartphone application is started for the first time, you have to check first if the BlueID SDK for Android was already initialized. This can be done with the following code:

BlueIDMobileDevice sdk = SdkForAndroid.getInstance(this);
if (!sdk.isInitialized()) {
  String deviceId = sdk.initialize()
    .withApiKey(API\_KEY)
    .onDefaultIntegrationTrustCenter()
    .now();

  // store deviceId and send it to your server to map it to an entity
}

In line 1, we instantiate a new object which implements the interface BlueIDMobileDevice. This object provides all the basic methods to control the BlueID SDK. If the SDK was not already initialized (line 2), we start the initialization process (line 3). Note line 4 (withApiKey) at initialize(): Here you have to provide your unique Operator API key. At line 5, we tell the SDK to initialize that client on the integration environment. Please note that initialize() is a synchronous method and will block your application if called in the main thread. It is advisable to do this in an AsyncTask. The initialization may fail for several reasons and errors are handled by throwing exceptions: RemoteException (I/O errors), ClientAlreadyInitializedException (initialize() was already called successfully) or -- of course -- a RuntimeException if there was a severe error.

Once the initialization has been completed, you will get the mobileDeviceId of this BlueID SDK for Android instance. You can send it to your backend to map it to a phone number, person or to any other unique identifier that you use in your system.

Synchronizing data and executing a command

Once the Mobile Device has been initialized, you can create a token for it, synchronize the device and execute a command. In the next example, we select the first Secured Object in our list and use an arbitrary command and channel. This is sample code, so you have to adapt it to your needs and also make sure that the Lock Server is running:

sdk.synchronize();
SecuredObject securedObject = sdk.getSecuredObjects().get(0);
Command command = securedObject.getCommands().iterator().next();
Channel channel = securedObject.getChannelsForCommand(command).iterator().next();

CommandExecutionResponse response = sdk.executeCommand(securedObject,
channel, command);

Log.d("BlueIDSDK", "response code = " + response.getResponseCode());

Side note: Earlier, we always talked about "tokens", but it may seem puzzling that we don't select one here! This is because the SDK does this work and selects an appropriate token depending on the current time as well as the selected channel and command. The other way round, this means that the developer cannot select a Secured Object which does have tokens, but they are not valid yet. Only the Secured Objects that are currently valid are listed at getSecuredObjects().

When synchronize() is called, there are also some exceptions that can be thrown: MarshalException (data cannot be parsed) and RemoteException (I/O errors).

On command execution, these exceptions can occur: ConnectException (failed to connect to Lock Server), ConnectionTimeoutException (Lock Server did not provide data in time), ConnectionIOException (I/O error), AuthorizationException (Mobile Device not allowed to execute the command). While the first three exceptions indicate that there is some sort of low-level problem, the AuthorizationException is more likely to be thrown. The main reasons why this exception is thrown are that the token is not valid yet, no longer valid (clock on Lock Server may be wrong) or that the token was revoked. The message of the exception provides details about the exception.

BlueID SDK for iOS
Requirements

This SDK requires at least iOS 10. To include the BlueID SDK in your application, you simply have to add a .framework file provided. We offer .framework files for different use cases:

  • BlueIDSDKiOS-Development.framework is a universal framework for simulator and device. Use this framework during development.

  • BlueIDSDKiOS.framework is a device only framework. Use this framework to upload your app to App Store.

You also have to link your application against the following standard frameworks:

  • Foundation.framework

  • UIKit.framework

  • Security.framework

  • CoreBluetooth.framework

  • SystemConfiguration.framework

Initialization

When the smartphone application is started for the first time, you have to check first if the BlueID SDK for iOS was already initialized. This can be done with the following code:

if (![[BlueIDMobileDevice sharedInstance] isInitialized])
{
  [[BlueIDMobileDevice sharedInstance] 
    initializeWithInitParametersBlock: ^(BlueIDMobileDeviceInitParameters *params) {
    params.apiKey = API_KEY;
    params.trustCenterHostName = [params defaultIntegrationTrustCenterHostName];
  }
  completionHandler:^(NSString *deviceId, NSError *error) {
    // store deviceId and send it to your server to map it to an entity
  }];
}

In line 1, we create a new shared object which implements the interface BlueIDMobileDevice. This object provides all basic methods to control the BlueID SDK. If the SDK was not already initialized (line 1), we start the initialization process (line 3). Note the first argument of initializeWithInitParametersBlock:completionHandler: Here you have to provide your unique Operator API key. Also note that initializeWithInitParametersBlock:completionHandler: is an asynchronous method and will not block your application if called in the main thread. If the initialization fails, the deviceId parameter is nil and the error parameter contains information about the failure. Errors are also handled by throwing exceptions: BlueIDAlreadyInitializedException (BlueIDMobileDevice is already initialized), BlueIDKeychainNotAvailableException (iOS keychain is not available) and NSInvalidArgumentException (a parameter was wrong).

Once the initialization has been completed, you will get the mobileDeviceId of this BlueID SDK for iOS instance. You can send it to your backend to map it to a phone number, person or to any other unique identifier that you use in your system.

Synchronizing data and executing a command

Once the Mobile Device has been initialized, you can create a token for it, synchronize the device and execute a command. In the next example, we select the first Secured Object in our list and use an arbitrary command and channel. This is sample code, so you have to adapt it to your needs and also make sure that the Lock Server is running:

[[BlueIDMobileDevice sharedInstance] 
  synchronizeWithCompletionHandler:^(NSError *error) {

  BlueIDSecuredObject \*securedObject = 
    [[BlueIDMobileDevice sharedInstance] getSecuredObjects][0];
  BlueIDCommand *command = [securedObject getCommands][0];

  BlueIDChannel *channel = [securedObject getChannelsForCommand:command][0];

  [[BlueIDMobileDevice sharedInstance] executeCommand:command
    onChannel:channel
    onSecuredObject:securedObject
    completionHandler:^
    (BlueIDCommandExecutionResponse *commandExecutionResponse, NSError *error)
      {
        if (error != nil) {
            NSLog(@"Command execution failed with error: %@", error);
        }
        else {
            NSLog(@"response code = %ld", commandExecutionResponse.responseCode);
        }
      }];
}];

Side note: Earlier, we always talked about "tokens", but it may seem puzzling that we don't select one here! This is because the SDK does this work and selects an appropriate token depending on the current time as well as the selected channel and command. The other way round, this means that the developer cannot select a Secured Object which does have tokens, but they are not valid yet. Only the Secured Objects that are currently valid are listed at getSecuredObjects.

When synchronizeWithCompletionHandler: is called, there are also some exceptions that can be thrown: BlueIDClientNotInitializedException (BlueIDMobileDevice is not initialized) and BlueIDKeychainNotAvailableException (iOS keychain is not available).

On command execution, these exceptions can occur: BlueIDClientNotInitializedException (BlueIDMobileDevice is not initialized) and BlueIDKeychainNotAvailableException (iOS keychain is not available). If the command execution fails, the error parameter of the handler block contains information about the failure. The most likely error that occurs is the BlueIDErrorAuthorization. The main reasons why this error occurs are that the token is not valid yet, is no longer valid (clock on Lock Server may be wrong) or that the token was revoked. The userInfo dictionary of the error provides details about the failure.

Managing BlueID Tokens

Now after the successful initialization of a Lock Server and a Mobile Device, you can use the BlueID Operator API to create and manage BlueID Tokens, which is described in the BlueID Operator API

Final note

If you have any questions please get in touch with your contact person at BlueID GmbH.