atsign-foundation/at_java

Java libraries, tools, samples and examples for the atPlatform

The atPlatform for Java developers

This repo contains libraries, tools, samples and examples for developers who wish to work with the atPlatform from Java code.

Maven Depdendency

The Java SDK can be added to your project through a compiled JAR or by Maven!

<repositories>
    <repository>
        <id>ossrh</id>
        <url>https://s01.oss.sonatype.org/content/repositories/snapshots</url>
    </repository>
</repositories>
<dependencies>
  <dependency>
      <groupId>io.github.atsign-foundation</groupId>
      <artifactId>at_client</artifactId>
      <version>1.0-SNAPSHOT</version>
    </dependency>
</dependencies>

Getting Started

Note: Java and Maven are Prerequisites to use at_java

Clone the at_java repo from GItHub using

git clone https://github.com/atsign-foundation/at_java.git

Change directory into at_java/at_client

cd at_client

Compile the package using maven with the following command

mvn install

Now that the programs have been compiled, execute the following command to use at_java

java -cp "target/at_client-1.0-SNAPSHOT.jar:target/lib/*" org.atsign.client.cli.<class> [required arguments]

The different classes(functionalities) that at_java contains:

1. REPL
2. Share
3. Get
4. Delete
5. Register
6. Onboard

Note: Each of these classes requires a different set of arguments, make sure to read the help text and provide necessary arguments

** Text about the remaining functionalities coming soon **

Register

A class that accepts command line arguments which are used to fetch a free atsign and register it to the email provided. Further, this atsign can be activated using a verification code sent to the registered email.

• To run use the following command

java -cp "target/at_client-1.0-SNAPSHOT.jar:target/lib/*" org.atsign.client.cli.Register -e [email protected]

Register with SUPER_API Key

Register* can also be used with a SUPER_API Key* that has privileges to preset and atsign with an activation code.

• To run use the following command

java -cp "target/at_client-1.0-SNAPSHOT.jar:target/lib/*" org.atsign.client.cli.Register -k <SUPER_API Key>

When using the SUPER_API Key to register an atsign, the following sequence of calls take place:

1. User provides at_java/Register with the SUPER_API Key passed as an argument
2. at_java calls the AtSign Registrar API* Endpoint(get-atsign) with the SUPER_API Key provided
3. The AtSign registrar API responds with an AtSign-ActivationKey pair
4. at_java now call the AtSign Registrar API* Endpoint(activate-atsign) with the AtSign-ActivationKey pair
5. The API responds with a json containing the CRAM_KEY* for the concerned atsign
6. This CRAM_KEY* can be used to activate the atsign further making it usable
7. at_java does the activation automatically for you and stores your atKeys* file at path '~/.atsign/keys'
8. Now the atsign is activated and the atKeys file can be used to authenticate and perform protected operation with/on the atSign.

Things to know about at_platform

1. Register: This is a class in at_java that has the functionality to call the necessary API, handle responses in order to fetch and register atsigns
2. AtSign Registrar API: An AtSign service that is responsible for handling atsign's server creation, registration, authentication, reset and deletion
3. SUPER_API Key:
   • All calls to the AtSign Registrar API require an API_KEY. But the SUPER_API Key has some additional privileges.
   • SUPER_API Keys have the privilege to preset an AtSign with an activation key so that this AtSign can be activated without manually entering a verification code that is sent to the registered email
   • All SUPER_API Keys have a name containing two elements [say pre and post], all the atsigns generated using this API_Key will be of the following format: (pre)atsign(post). Now the atsign will be @preatsignpost. This is done to separate atsigns generated using SUPER_API Keys to the atsigns that are generated through other methods.
4. CRAM_KEY: This is an authentication key that will be used for a one-time authentication to activate an atsign which allows for assigning random, secure non-symmetric keypairs which will be further stored in the users atKeys file.
   • Note: CRAM_KEY will be deleted from the atsign server after an atKeys file has been generated, so only you have the keys to authenticate into your atsign
5. atKeys file: This will be a file generated during activation of an atsign that stores all the keys necessary for authenticating into atSign
   • That would mean users have to keep this file in a secured location
   • Users should keep this file safe, as there's only one copy of this file and losing it would mean the user would be unable to log in to the atsign
   • If lost, users can reset the atsign and get a new atKeys file. This would result in loss of all data stored in the atsign's server

Contributions welcome!

All of our software is open with intent. We welcome contributions - we want pull requests, and we want to hear about issues. See also CONTRIBUTING.md

at_java's Issues

Android Studio emulator does not support AES SIC

Describe the bug
Making an Android App and using at_java as a dependency and trying to use AES SIC does not seem to work. Sample size is 1 for this bug.

To Reproduce
Use any at_java functionality that involves AES decryption/encryption

Expected behavior
Work

Screenshots

Smartphone (please complete the following information):
To be filled

Additional context
To fix, use AES/CTR instead.

From this wikipedia page, SIC work the exact same as CTR. "Note: CTR mode (CM) is also known as integer counter mode (ICM) and segmented integer counter (SIC) mode." So to fix this bug, simply change SIC to CTR. Maybe it's as simple as Android Studio's Java encryption library is missing the aliases?

Maybe have a separate release for developers who are making an android app through android studio?

Implement _get, _put, _delete, PrivateHiddenKey

Is your feature request related to a problem? Please describe.
Implement AtClientImpl.get(PrivateHiddenKey) just like the rest of the AtKey types.

• _get(PrivateHiddenKey)
• _put(PrivateHiddenKey)
• _delete(PrivateHiddenKey)
• Implement new functionalities into the REPL

Create a Getting Started guide

Is your feature request related to a problem? Please describe.
There is no getting-started guide for this library.

Describe the solution you'd like
Need a good getting started guide

Implement CLI for getting (registering) a new atSign

Is your feature request related to a problem? Please describe.
Currently there is an Onboard CLI for onboarding a new atSign, but it requires that you already know the atSign and its shared secret.

Describe the solution you'd like
Need a Register CLI which will grab a new atSign and its shared secret; this information can then be used by the Onboard CLI to generate keys etc

hacktoberfest java | File <-> byte[] utility

Premise

The atPlatform is perfect for sending end-to-end encrypted files. atmospherePro does this too, but is written in Dart. It would be great if we could do the same in Java.

What needs to be done

A utility method that converts a File object into an array of bytes (byte[]).
Another method that converts the byte[] back to a File object would be great as well.

Something like:

public static byte[] convert(File);
public static File convert(byte[]);

Support

In case you need any kind of help (such as getting your environment setup or asking questions about our tech) don’t be afraid to ask in our discord. There is a team full of developers ready to jump in and help on whatever your issue may be.

hacktoberfest java | image <-> byte[] utility

Premise

The atPlatform is perfect for sending data and files peer-to-peer. The atPlatform ensures that the data sent is only readable by the end user.

What needs to be done

• Create 2 utility methods (one for converting an image to an array of bytes (byte[]) and another for converting the byte[] image to an image object)
• You can do this in anyway you like (does not have to be a method, could be an entire class! or multiple classes)
• Even codeblocks are appreciated

Support

In case you need any kind of help (such as getting your environment setup or asking questions about our tech) don’t be afraid to ask in our discord. There is a team full of developers ready to jump in and help on whatever your issue may be.

Make AtClient API more 'fluent'

Is your feature request related to a problem? Please describe.
A more fluent API would be really useful for users in cutting down boilerplate and improving readability - e.g. share(value).with(atSign/s).as(keyName)

Describe the solution you'd like
Add fluent API a fluid share(....)

e2e tests for Java SDK

Describe the bug
no e2e tests at present

Expected behavior
Tests of sharing data between at signs, and associated notification delivery and receipt. Tests should run as GitHub action on PR create / PR branch push / merge to trunk

hacktoberfest java | String <-> byte[]

What needs to be done

• Create a class named ByteUtil
• Create a method String convert(byte[] data) that converts an array of bytes to a String
• Create another method byte[] convert(String data) that converts a String to an array of bytes
• Please comment on the GitHub issue to be assigned this task.

How to contribute

1. Create a fork of at_java
2. Make your contributions via git add . and `git commit -m "feat: new feature!"
3. Make a pull request to the trunk of this repository and make sure you add closes #XYZissue to the description so it will be related to this issue

Support

In case you need any kind of help (such as getting your environment setup or asking questions about our tech) don’t be afraid to ask in our discord. There is a team full of developers ready to jump in and help on whatever your issue may be.

ttr not being set on public key metadata

Describe the bug

OnboardingUtil.storePublicEncryptionKey is not setting ttr for public key, thus ttr is defaulting to null

Expected behavior

should set a ttr of -1 (cache indefinitely) when storing the public encryption key. See this other bug report for the explanation of why

Add clarity to key names

Describe the bug
Not clear from looking at key names in the keys file or when being used, what format those keys are in

Expected behavior
Better code comments explaining why the key names in the keys file are called what they are

Better names for the in-memory key map entries once they have been loaded from file and decrypted / processed as required

Additional context
From @realvarx

Can I treat "aesPkamPrivateKey" as a RSA private key? Or is it encrypted in other way?

Reply from @gkc

Hmmm I think the reason it’s called that in the keys file is because it is an RSA private key but it is AES-encrypted using the selfEncryptionKey

Implement creation of self keys in Java SDK

Implement the ability to create the self keys in the Java SDK

Namespace support for `KeyStringUtil`

What needs to be done

When using KeyStringUtil to extract data from a String fullKeyName, it does not detect for namespaces.

Having trouble finding namespace from keys like:

shared_key.denise@smoothalligator assume no namespace?
atconnections.misstremendous3.smoothalligator.at_contact.mospherepro@smoothalligator assume namespace mospherepro
public:name.wavi@smoothalligator assume namespace wavi

Implement creation of public keys in Java SDK

Implement the ability to create the public keys in the Java SDK

Numerous Dependabot alerts relating to snakeYAML

https://github.com/atsign-foundation/at_java/security/dependabot?q=is%3Aopen+package%3Aorg.yaml%3Asnakeyaml

Looks like some of these can be resolved by upgrading to 1.32, but no fix for the worst one:

at_java: Bring Java client up to date with Dart client

Is your feature request related to a problem? Please describe.

Java client is lagging significantly behind Dart client in multiple ways

• APKAM
• Shared key exchange
• Encryption / decryption
• Notifications
• Logging

Describe the solution you'd like

Java AtClient needs feature parity with dart Client (apart from sync which should remain out of scope for Java client for now)

Describe alternatives you've considered

No response

Additional context

No response

Java PublicKey bypassCache

Background

In our Dart SDK, we provide an optional parameter GetRequestOptions for the developer to bypassCache:true when doing a plookup: (which does a fresh plookup as opposed to llooking up the local cached public key, if it exists).

// AtClient.get method
@override
Future<AtValue> get(AtKey atKey, {bool isDedicated = false, GetRequestOptions? getRequestOptions})

// GetRequestOptions class allows them to bypass cache when getting a PublicKey
/// Request params for at client get method
class GetRequestOptions extends RequestOptions {
  bool bypassCache = false;
}

Problem

Java needs a way of doing a plookup:bypassCache:true as well. Should this be the approach?

Overload the get(PublicKey) method with some kind of arguments option

public CompletableFuture<String> get(PublicKey publicKey, GetRequestOptions getRequestOptions) {
    // check if bypassCache, then do `bypassCache:true`
}

Usage would be similar to:

// assume atClient and publicKey variables are non-null
atClient.get(publicKey, new GetRequestOptions().bypassCache(true).build());

Update register_cli to match API changes in AtRegistrar

Describe the bug

• The registrar has modified some API calls, update the methods to match the current behaviour of the registrar.
• Update the code in RegisterUtil class according to the new Registrar API responses
• Update exception catching and user-messages

Expected behavior

Register should be able to activate atsigns and display accurate user messages

Process Checklist

• Modify RegisterUtil methods with new Registrar API call responses
• Update docs/readme

[Java] AtClientImpl refactoring to be similar to Dart SDK

Description
The _get, _put, and _delete methods in AtClientImpl.java should follow similar Dart SDK methodologies.

Tasks

• Implement key validation like in the Dart SDK (AtClientValidation)
• Write AtClientValidation junit tests
• Implement VerbBuilders (from, cram, pkam, llookup, lookup, plookup)
• Write VerbBuilder junit tests
• Assume SelfKey data is always encrypted (do not do Metadata.isEncrypted check)
• Implement ResponseTransformers
• Use llookup:all to both 1. get the data and 2. update the Metadata in the AtKey object. (Use Transformers)

Additional context
Comment from gkc: #29 (comment)
Comment from VJag: #29 (comment)

at_java: Add Dependabot for Maven dependencies

Is your feature request related to a problem? Please describe.

We presently don't have automated dependency updates for the Java dependencies in this repo (just GitHub Actions)

Describe the solution you'd like

Add Maven to the dependabot.yml and merge the resulting PRs

Maven dependency or JAR dependency?

Maven Dependency

Just like how we can do dart pub add at_client for our flutter apps,
could there be a way we can add a <dependency>...</dependency> in our own Java project's pom.xml?

JAR Dependency

Would it be reasonable to add a .jar file to the at_java repository under Releases?
For developers to download and add it as a dependency in their own Java projects (just like how I did it for Minecraft)

Implement notify in Java SDK

Implement the ability to notify and get status if a notification in Java SDK

Java SDK searches for atKeys in root project dir

Describe the bug
When searching for keys of an atsign, SDK searches within root of the Java project rather than ~/.atsign/keys
All documentation for storing atsign's describes storing keys in ~/.atsign/keys

To Reproduce
Steps to reproduce the behavior:

1. Use any verb/method that requires key of an atsign

Expected behavior
Verbs/methods search for atsign keys within ~/.atsign/keys

Register CLI doesn't complete if OTP is typed incorrectly

Describe the bug
Register CLI doesn't complete if OTP is typed incorrectly

To Reproduce

• Run the Register CLI
• Once you receive the OTP, type it in incorrectly
• Then, when prompted, re-enter the OTP correctly
• You will see Got response: Verified but that's all - i.e. it stops there, doesn't proceed to the next step (output the cram secret)

Expected behavior
It should work the same as when you type the OTP correctly the first time

Additional context
(I've replaced the email address I was using with [email protected] and changed the name of the atsign that was registered, but otherwise this is the output I got)

gkc2019-2:at_client gary$ java -cp "target/client-1.0-SNAPSHOT.jar:target/lib/*" org.atsign.client.cli.Register '[email protected]'
Getting free atsign
Got atsign: @atsign_redacted_for_this_issue
Sending one-time-password to :[email protected]
Got response: Sent Successfully
Enter OTP received on: [email protected]
w9kw
Validating one-time-password
Got response: Hmm, that code is invalid or expired. Try again?
Incorrect OTP entered. Re-enter the OTP: 
W9KW
Got response: Verified

Scan CLI and AtClientImpl _getAtKeys implementation

PR = #19

There is a lot of hidden work behind _getAtKeys in AtClientImpl such as string parsing from scan and AtKey object instantiating via KeyBuilders.

hacktoberfest java | camera stream byte[] utility

Premise

One of the things the atPlatform specializes in is sending end-to-end encrypted binary data. A huge application would be to send a camera stream through atSigns.

What to do

Create a utility class to fetch the camera stream from a USB camera (or a camera from your choice) and convert it into a Map of images.
Perhaps start with taking a screenshot of the camera stream and converting that into a byte[] array.

Support

In case you need any kind of help (such as getting your environment setup or asking questions about our tech) don’t be afraid to ask in our discord. There is a team full of developers ready to jump in and help on whatever your issue may be.

Implement `_getBinary(AtKey)` and `_put(AtKey, byte[])`

_getBinary(AtKey) implementation

• _getBinary(SharedKey, byte[])
• _getBinary(SelfKey, byte[])
• _getBinary(PublicKey, byte[])

_put(AtKey, byte[]) implementation

• _put(SharedKey, byte[]) in AtClientImpl.java
• _put(SelfKey, byte[]) in AtClientImpl.java
• _put(PublicKey, byte[]) in AtClientImpl.java

at_java: atKey.toString() not prefixing `cached:`

The reason why I thought prefixing cached: was incorrect was because of this commen tmade in 2022 : #64 (comment)

The Issue:

Java REPL

The first line shows .getAtKeys() working (where it would ultimately use atKey.toString())
The second line shows a raw atProtocol scan where cached: is shown (because that is how the protocol behaves)

@jeremy_0@ /scan shared_key@smoothalligator
  => [@jeremy_0:shared_key@smoothalligator]
@jeremy_0@ scan shared_key@smoothalligator
  => data:["cached:@jeremy_0:shared_key@smoothalligator"]

Correct behaviour should be atKey.toString() should prefix cached: just like the raw scan.

Tests AtClientImpl _put, _delete, and _get for PublicKey and SelfKey

tasks

• setup GitHub secrets with an atSign and the keys to that atSign
• make tests for _put, _get, and _delete PublicKey
• make tests for _put, _get, and _delete SelfKey

Enhance REPL so that some AtClient methods can be called interactively

Is your feature request related to a problem? Please describe.
REPL is super-useful but currently just handles everything it's sent as an @ protocol command which it sends directly to the Secondary; this greatly limits its usefulness for interactive sharing of data, as the value needs to be encrypted before it is sent

Describe the solution you'd like
Enable share(..), get(..), put(..), delete(..) methods to be called from the REPL. At a minimum, support share(..) and get(..)