Getting Started

Initial Requirements

Before starting developing using PrivMX Endpoint Kotlin follow our quick start guide.

To connect it to your environment, you need:

• Bridge URL - URL address of the instance of your PrivMX Bridge
• Solution ID - ID of the Solution provided by PrivMX Bridge during its initialization process
• User Private Key - the private key from the user's public-private key pair

You also need to use your own application server to manage users (and their keys) and Contexts.

Adding Dependencies

1. Add mavenCentral() repository to your settings.gradle.kts:

pluginManagement {
  repositories {
      mavenCentral()
  }
}

dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

2. Add dependency to build.gradle.kts:

kotlin {
  sourceSets {
    val commonMain by getting {
      dependencies {
        implementation("com.simplito.kotlin:privmx-endpoint:$privmxLibVersion")
        // optionally you can add privmx-endpoint-extra dependency
//        implementation("com.simplito.kotlin:privmx-endpoint-extra:$privmxLibVersion")
      }
    }
  }
}

3. Add PrivMX plugin to build.gradle:

plugins {
    id("com.simplito.privmx-endpoint-install-native") version "2.0.0"
}

JVM

Native Libraries

The plugin automatically adds the necessary native libraries to the runtime in your Java, Android, or Kotlin project. For Java applications, it includes libraries for all supported desktop platforms. The source code of the plugin is available on GitHub.

When you first use the API, the PrivMX wrapper unpacks and loads these native libraries. They are unpacked to your working directory if your java.library.path includes .. Otherwise, they are unpacked to the last path specified in the java.library.path.

Android

Native Libraries

The plugin automatically adds the necessary native libraries to the runtime in your Java, Android, or Kotlin project. For Android applications, it includes Android-specific binaries. The source code of the plugin is available on GitHub.

On Android, the native libraries are extracted by the installer and then the PrivMX wrapper loads them in the runtime.

Required Permissions

PrivMX Endpoint requires to add the following permissions to your AndroidManifest.xml:

• <uses-permission android:name="android.permission.INTERNET"/>

Initial Assumptions

The initial assumptions for all the code examples below are as follows:

/*
    All the values below like BRIDGE_URL, SOLUTION_ID, CONTEXT_ID
    should be replaced by the ones corresponding to your Bridge Server instance.

    The private keys here are for demonstration purposes only.
    Normally, they should be kept separately by each user and stored in a safe place,
    or generated from a password (see the derivePrivateKey2() method in the Crypto API)
*/

val bridgeUrl = "YOUR_BRIDGE_URL"
val solutionId = "YOUR_SOLUTION_ID"
val contextId = "YOUR_CONTEXT_ID"

val user1Id = "USER_ID_1"
val user1PublicKey = "PUBLIC_KEY_1"
val user1PrivateKey = "PRIVATE_KEY_1"

val user2Id = "USER_ID_2"
val user2PublicKey = "PUBLIC_KEY_2"

Connecting to PrivMX Bridge

To use any of the library's elements, you must first connect to PrivMX Bridge. Use the API keys mentioned earlier:

val pathToCerts = "PATH_TO_CERTS" // Path to .pem ssl certificate to connect with Privmx Bridge
val initModules = setOf(
    Modules.THREAD, // initializes ThreadApi to working with Threads
    Modules.STORE, // initializes StoreApi to working with Stores
    Modules.INBOX, // initializes InboxApi to working with Inboxes
    Modules.CUSTOM_EVENT, // initializes EventApi to working with Custom Events
    Modules.KVDB // initializes KvdbApi to working with KVDBs
) // set of modules to activate in new connection

val endpointContainer = PrivmxEndpointContainer().also {
    it.setCertsPath(pathToCerts)
}

val endpointSession = endpointContainer.connect(
    initModules,
    user1PrivateKey,
    solutionId,
    bridgeUrl
)

The active connection is kept by container and can be accessed using container.getEndpoint(Long) method.

endpointContainer.getEndpoint(endpointSession.connection.getConnectionId()!!)

Disconnecting from PrivMX Bridge

endpointContainer.disconnect(endpointSession.connection.getConnectionId()!!)

Verify Users

To verify whether users belong to the Context and the provided public key is valid, set a callback function that is triggered each time user interacts with a container. The verification process can be performed by an external service, such as your application server or PKI (Public Key Infrastructure) server.

Implement the UserVerifierInterface and provide your own custom verification logic within its verify method and pass it to setUserVerifier method.

val userVerifier = UserVerifierInterface { requests ->
    requests.map { request ->
        // Your verification code for the request
        true
    }
}

endpointSession.connection.setUserVerifier(userVerifier)

If the verify method does not confirm data then:

• listing/getting containers/items will return object with a non-zero statusCode
• modifying containers or items will throw an exception

By default, if no verifier is configured, the system operates as if a verifier is present and always returns successful verification (returns true).

Make sure the verify method always returns a valid, non-null result and doesn't throw exceptions.

Closing PrivmxEndpointContainer

When you finish working with the container, close it to end all connections, close the event loop, and release the resources being used. You can also use a use function in Kotlin.

endpointContainer.close()

Next Steps

With everything ready to go, now it's time to start using all of the platform's capabilities.

Learn how to use:

• Threads - for exchanging encrypted messages;
• Stores - for saving and sharing encrypted files;
• Inboxes - for one way communication with external users.
• KVDBs - for key-value database.