diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..5f136ae --- /dev/null +++ b/CHANGELOG.md @@ -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 diff --git a/README.md b/README.md index 2a5e2fa..d0c753e 100644 --- a/README.md +++ b/README.md @@ -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! ``` +## 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. [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@email.com +``` + +### 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 +``` + +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 )