.. image:: https://raw.githubusercontent.com/openziti/branding/main/images/banners/Java.jpg
    :alt: Ziggy using the ziti-sdk-jvm
    
.. image:: https://github.com/openziti/ziti-sdk-jvm/workflows/CI%20build/badge.svg
    :target: https://github.com/openziti/ziti-sdk-jvm/actions?query=workflow%3A%22CI+build%22

.. image:: http://maven-badges.herokuapp.com/maven-central/org.openziti/ziti/badge.svg
    :target: http://maven-badges.herokuapp.com/maven-central/org.openziti/ziti

Ziti SDK for JVM
=================
The **Ziti SDK for JVM** enables Java and other developers to easily and securely connect their applications
to backend services over Ziti networks.

.. contents::


Release Notes
-------------


Obtaining SDK
------------
The recommended way to use the OpenZiti SDK for Java in your project is to add the dependency
using your favorite build tool.
Our artifacts are hosted on Maven Central, so add repo(if needed) and dependency to your project.
Make sure to use latest version from the top of this page.

Maven
_____
.. code-block:: xml

  <project>
     ....
     <repositories>
        ....
        <repository>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
            <id>central</id>
            <name>Maven Central</name>
            <url>https://repo.maven.apache.org/maven2/</url>
         </repository>
     </repositories>
     ....
     <dependencies>
        ...
        <dependency>
           <groupId>org.openziti</groupId>
           <artifactId>ziti</artifactId>
           <version>[0,)</version>
        </dependency>
     </dependencies>
     ....
  </project>

Gradle
______
.. code-block:: gradle

   repositories {
       ...
       mavenCentral()
   }
   ...
   dependencies {
      ...
      implementation 'org.openziti:ziti:+' // TODO fix version
   }

Building from Source
--------------------
Once you check out the project from GitHub, you can build it using gradle:

.. code-block::

    ./gradlew build

    # install into your local maven cache
    ./gradlew :ziti:install


Features
--------
- allows to develop applications that connect to services on NetFoundry Ziti Service mesh
- strong identity support
- transparent use -- in seamless mode connections to network resources are intercepted and 
  routed over Ziti network for any Ziti service that identity has access to
- written in `Kotlin <https://kotlinlang.org/>`_ with Java-friendly API
- read more in our docs_

Enrollment
__________
See background `here <https://openziti.github.io/ziti/identities/enrolling.html>`_

Java SDK provides a way to enroll and generate *identity file*.
The default identity format for Java SDK is Java KeyStore stored as ``.p12/.pfx`` files,
however it can use identity JSON files generated by ``ziti-enroller`` as well.

Enrolling creates two(or more) entries in Java KeyStore:

private key entry
   client SSL private key/certificate identifying the application instance. this entry is stored with
   ``ziti://<controller_addr>/<id>`` alias (pkcs#12 - friendly name)

rootCA
   root CA certificates used to validate `Ziti controller <https://openziti.github.io/ziti/manage/controller.html>`_ and
   `routers <https://openziti.github.io/ziti/manage/router-overview.html>`_

Note:

   This allows enrolling and storing multiple identity keys and certificates in a single key store (pkcs#12 file).
   However, typically an application instance would only have a single enrollment or identity


Getting Help
------------
Please use these community resources for getting help. We use GitHub issues_
for tracking bugs and feature requests and have limited bandwidth
to address them.

- Read the docs_
- Join our `Developer Community`_
- Participate in discussion on Discourse_


.. _Developer Community: https://ziti.dev
.. _docs: https://openziti.github.io/ziti/overview.html
.. _Discourse: https://openziti.discourse.group/
.. _issues: https://github.com/openziti/ziti-sdk-jvm/issues