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

docs: new readme.md for at_java #145

Merged
merged 5 commits into from
Oct 30, 2023
Merged

docs: new readme.md for at_java #145

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
00b0f1b
refactor: rename old readme to changelog
srieteja Jun 29, 2023
0622b71
docs: create a new README
srieteja Jun 29, 2023
7d42401
Merge branch 'trunk' into new_readme
srieteja Oct 27, 2023
2d5eb5c
chore: resolve merge conflicts
srieteja Oct 27, 2023
997777a
docs: removed unnecessary element from CHANGELOG.md
srieteja Oct 27, 2023
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
50 changes: 50 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
## What's here / changelog
### Next ...
* Getting started guide - from nothing to end-to-end-encrypted chat session in < 5 minutes
* fluid client APIs for sharing data - e.g. share(value).with(atSign/s).as(keyName)
* extend client REPL so that you can call AtClient methods (e.g. the share() above) interactively

### May 29 2022
* Retry bug fixed in Register CLI
* Config yaml parameters restructured and backwards compatibility provided so as not to break existing usage.
* New parameter added to validateOtp method in RegisterUtil.java. The usage of this parameter is provided in
java docs of the respective method.


### May 18 2022
* A new CLI tool Register has been introduced which can acquire a free atsign and register it to the provided email.
* Register CLI also handles calling the Onboard client with the cram secret which was received during the registration process.

### May 03 2022
* Better event distribution
* Improved Monitor's event generation
* Added 'userDefined' to the AtEventType enum, to allow the event bus to be used by application code
* Caches shared keys after first retrieval
* AtClientImpl listens for updateNotification events, decrypts the ciphertext on-the-fly, and publishes a decryptedUpdateNotification
which is more useful for application code
* Enhanced REPL to optionally listen to only decryptedUpdateNotification; added command-line flag to listen to both

### Apr 29 2022
* **at_client** : Initial implementation of Java client library for the atPlatform. README will come soon
but here's a very brief summary which will get you going if you already know the basics of the atPlatform
and have used the Dart/Flutter packages
* **Uses Maven**
* The Maven target you want is 'install' which will put things in the 'target' output directory
* The **CLI tools** will give you the best overview of how to use the library as a whole. There are five CLIs
in the initial commit:
* **Onboard** - generate keys for a new @-sign. If you already have a .keys file, you can reuse it.
Currently, the Java library expects keys for @alice to be in ./keys/@alice.keys
* **REPL** - you can use this to type @-protocol commands and see responses; but the best thing about the
REPL currently is that it shows the data notifications as they are received. The REPL code has the
essentials of what a 'receiving' client needs to do - i.e.
* create an AtClient
* add an event listener which
* receives data update/delete notification events (the event data contains the ciphertext)
* calls 'get' to decrypt
* **Share** - a simple 'sender' client - shares some data with another @-sign
* **Get** - gets data which was shared by another @-sign
* **Delete** - deletes data that this Atsign previously shared with another

#### Note:
As of May 3 2022, the Java client library can still be considered a 1.0.0-Beta version - i.e. there may occasionally
be breaking changes, based on feedback from users of the library, until we get to a final version 1.0.0
132 changes: 80 additions & 52 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,6 @@
This repo contains libraries, tools, samples and examples for developers who wish
to work with the atPlatform from Java code.

NB: As of May 3 2022, the Java client library can still be considered a 1.0.0-Beta version - i.e. there may occasionally
be breaking changes, based on feedback from users of the library, until we get to a final version 1.0.0

# Maven Depdendency

The Java SDK can be added to your project through a compiled JAR or by Maven!
Expand All @@ -31,56 +28,87 @@ The Java SDK can be added to your project through a compiled JAR or by Maven!
</dependencies>
```

## Getting Started
#### Note: Java and Maven are Prerequisites to use at_java

Clone the at_java repo from GItHub using

```shell
git clone https://github.com/atsign-foundation/at_java.git
```
Change directory into at_java/at_client

```shell
cd at_client
```

Compile the package using maven with the following command

```shell
mvn install
```

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

```shell
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
```shell
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
```shell
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](CONTRIBUTING.md)

## What's here / changelog
### Next ...
* Getting started guide - from nothing to end-to-end-encrypted chat session in < 5 minutes
* fluid client APIs for sharing data - e.g. share(value).with(atSign/s).as(keyName)
* extend client REPL so that you can call AtClient methods (e.g. the share() above) interactively

### May 29 2022
* Retry bug fixed in Register CLI
* Config yaml parameters restructured and backwards compatibility provided so as not to break existing usage.
* New parameter added to validateOtp method in RegisterUtil.java. The usage of this parameter is provided in
java docs of the respective method.


### May 18 2022
* A new CLI tool Register has been introduced which can acquire a free atsign and register it to the provided email.
* Register CLI also handles calling the Onboard client with the cram secret which was received during the registration process.

### May 03 2022
* Better event distribution
* Improved Monitor's event generation
* Added 'userDefined' to the AtEventType enum, to allow the event bus to be used by application code
* Caches shared keys after first retrieval
* AtClientImpl listens for updateNotification events, decrypts the ciphertext on-the-fly, and publishes a decryptedUpdateNotification
which is more useful for application code
* Enhanced REPL to optionally listen to only decryptedUpdateNotification; added command-line flag to listen to both

### Apr 29 2022
* **at_client** : Initial implementation of Java client library for the atPlatform. README will come soon
but here's a very brief summary which will get you going if you already know the basics of the atPlatform
and have used the Dart/Flutter packages
* **Uses Maven**
* The Maven target you want is 'install' which will put things in the 'target' output directory
* The **CLI tools** will give you the best overview of how to use the library as a whole. There are five CLIs
in the initial commit:
* **Onboard** - generate keys for a new @-sign. If you already have a .keys file, you can reuse it.
Currently, the Java library expects keys for @alice to be in ./keys/@alice.keys
* **REPL** - you can use this to type @-protocol commands and see responses; but the best thing about the
REPL currently is that it shows the data notifications as they are received. The REPL code has the
essentials of what a 'receiving' client needs to do - i.e.
* create an AtClient
* add an event listener which
* receives data update/delete notification events (the event data contains the ciphertext)
* calls 'get' to decrypt
* **Share** - a simple 'sender' client - shares some data with another @-sign
* **Get** - gets data which was shared by another @-sign
* **Delete** - deletes data that this Atsign previously shared with another
* To run them, having done a mvn install
`java -cp "target/at_client-1.0-SNAPSHOT.jar:target/lib/*" org.atsign.client.cli.REPL` (or Onboard/Share/Get/Delete/Register )