-
Notifications
You must be signed in to change notification settings - Fork 19
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #145 from atsign-foundation/new_readme
docs: new readme.md for at_java
- Loading branch information
Showing
2 changed files
with
130 additions
and
52 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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! | ||
|
|
@@ -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 ) | ||