Giter Club home page Giter Club logo

threema-msgapi-sdk-java's Introduction

Threema Gateway Java SDK

Build Status

Version: 1.1.3-CE

An automatically created documentation of this SDK can be found here.

Notes about this version

This is a fork of the original repo after it was announced that it is no longer maintained by Threema. As this is the community version of the Threema Gateway Java SDK it may contain additional changes compared to the official one downloadable from the Threema website. If you are looking for an exact mirror of the downloadable Threema version you can switch to the branch official.

The contributors of this repository are not affiliated with Threema or the Threema GmbH.

Installation

NOTE: This instructions are copied from https://gateway.threema.ch/en/developer/howto/create-keys/java.

Install Java:

If you don't have a Java runtime installed yet, go to java.com to download one for your platform.

Download and unzip the Java API tool:

You can either download the precompiled .jar file or clone the repository and build the tool on your own

Generate a keypair by running the tool

Open a shell (on Windows open the command line) and go to the directory where you have extracted the ZIP. Create a new private and public key by typing the following command: java -jar threema-msgapi-tool.jar -g privateKey.txt publicKey.txt A new key pair will be generated. The private key will be saved in privateKey.txt and the public key in publicKey.txt. Both keys are formatted in hexadecimal with a prefix that indicates the key type. IMPORTANT: Create a backup (or preferrably multiple backups) of your private key! If you lose it, your custom Threema ID will be unusable. We have no way to recover lost private keys for you, and it is also not possible to assign a new key to an existing ID.

Request custom Threema ID and submit key

Log in to your profile on the Threema Gateway website, click on "ID" in the navigation bar and then "Request Threema ID". Choose End-to-End mode, enter the desired ID, and copy & paste the public key from the publicKey.txt file.

Wait for review

Wait until your custom Threema ID has been reviewed and accepted. As this is a manual process, it may take several days.

When your ID has been accepted, you will receive an API secret for authentication with the service.

Console client usage

###Local operations (no network communication) ####Encrypt java -jar threema-msgapi-tool.jar -e Encrypt standard input using the given sender private key and recipient public key. Prints two lines to standard output: first the nonce (hex), and then the box (hex).

####Decrypt java -jar threema-msgapi-tool.jar -d Decrypt standard input using the given recipient private key and sender public key. The nonce must be given on the command line, and the box (hex) on standard input. Prints the decrypted message to standard output.

####Hash Email Address java -jar threema-msgapi-tool.jar -h -e Hash an email address for identity lookup. Prints the hash in hex.

####Hash Phone Number java -jar threema-msgapi-tool.jar -h -p Hash a phone number for identity lookup. Prints the hash in hex.

####Generate Key Pair java -jar threema-msgapi-tool.jar -g Generate a new key pair and write the private and public keys to the respective files (in hex).

####Derive Public Key java -jar threema-msgapi-tool.jar -p Derive the public key that corresponds with the given private key.

###Network operations ####Send Simple Message java -jar threema-msgapi-tool.jar -s Send a message from standard input with server-side encryption to the given ID. 'from' is the API identity and 'secret' is the API secret. Returns the message ID on success.

####Send End-to-End Encrypted Text Message java -jar threema-msgapi-tool.jar -S Encrypt standard input and send the message to the given ID. 'from' is the API identity and 'secret' is the API secret. Prints the message ID on success.

####Send End-to-End Encrypted Image Message java -jar threema-msgapi-tool.jar -S -i Encrypt standard input and send the message to the given ID. 'from' is the API identity and 'secret' is the API secret. Prints the message ID on success.

####Send End-to-End Encrypted File Message java -jar threema-msgapi-tool.jar -S -f [thumbnail] Encrypt the file (and thumbnail) and send a file message to the given ID. 'from' is the API identity and 'secret' is the API secret. Prints the message ID on success.

####ID Lookup By Email Address java -jar threema-msgapi-tool.jar -l -e Lookup the ID linked to the given email address (will be hashed locally).

####ID Lookup By Phone Number java -jar threema-msgapi-tool.jar -l -p Lookup the ID linked to the given phone number (will be hashed locally).

####Fetch Public Key java -jar threema-msgapi-tool.jar -l -k Lookup the public key for the given ID.

####Fetch Capability java -jar threema-msgapi-tool.jar -c Fetch the capability of a Threema ID

####Decrypt and download java -jar threema-msgapi-tool.jar -D [outputFolder] Decrypt a box (box from the stdin) message and download (if the message is a image or file message) the file(s) to the defined directory

Feature Levels

Level Text Capabilities Image File Credits
1 X
2 X X X X
3 X X X X X

You can see the implemented feature level by invoking the following command:

$ java -jar threema-msgapi-tool.jar -v

Contributing

Nice to see you want to contribute. We may periodically send patches to Threema to make it possible for them to implement them in the official SDK version.

Other platforms (PHP and Python)

All repositories on GitHub are no longer maintained by the Threema GmbH. However, the community has forked the repositories of all platforms and they are now maintained unofficially.

You can find the PHP repository at rugk/threema-msgapi-sdk-php
and the Python repository at lgrahl/threema-msgapi-sdk-python.

threema-msgapi-sdk-java's People

Contributors

marschall avatar mrthreema avatar simmac avatar

Stargazers

avatar

Watchers

avatar avatar avatar avatar

Forkers

rugk marschall

threema-msgapi-sdk-java's Issues

E2E-sending files not working

It seems like the file sending doesn't work in E2E mode.
java -jar threema-msgapi-tool.jar -S -f <to> <from> <secret> <privateKey> <file> prints out a message id, but the message never arrives.

Tested on OS X 10.11 with Java 8

Unknown filetypes are not sent

Files with a type unknown to File.probeContentType() (or URLConnection.guessContentTypeFromName, so this issue is not dependent on #11) can't be sent in E2E-mode.
The two named methods return null for unknown filetypes, the Gateway SDK seems to ignore files with mimeType=null.

I would recommend checking for null when calling the filetype-function and using either MIME-type application/unknown or application/octet-stream for unknown filetypes (and maybe notifying the sender that this file will be sent as unknown via console output).

Code quality

From @m007 on March 27, 2015 9:9

Problem

An analysis of the project source with SonarQube (see #1) has also revealed many quality issues with the code.

How to find out

Run a project analysis with SonarQube. A quick view of my analysis:

254 Major Issues
untitled

And even 4 Critical Issues
untitled1

How to fix

Before adding new features I suggest to first fix about 85% of the found quality issues to ensure that we can call it clean code (at least kind of).

Copied from original issue: threema-ch/threema-msgapi-sdk-java#2

Code coverage in tests

From @m007 on March 27, 2015 9:0

Problem

Analyzed the code with my own SonarQube instance and found it having a test coverage of just about 55%.

How to find out

For anyone interested by running this analysis on your own:
I did so by adding following lines within the <build> .... </build> tag of the pom.xml file.

             <plugin>
                <groupId>org.jacoco</groupId>
                <artifactId>jacoco-maven-plugin</artifactId>
                <version>0.7.1.201405082137</version>

                <executions>
                    <execution>
                        <id>pre-unit-test</id>
                        <goals>
                            <goal>prepare-agent</goal>
                        </goals>
                    </execution>
                    <execution>
                        <id>post-unit-test</id>
                        <phase>test</phase>
                        <goals>
                            <goal>report</goal>
                        </goals>
                    </execution>
                    <execution>
                        <id>pre-integration-test</id>
                        <phase>pre-integration-test</phase>
                        <goals>
                            <goal>prepare-agent</goal>
                        </goals>
                        <configuration>
                            <destFile>${project.build.directory}/jacoco-it.exec</destFile>
                            <propertyName>failsafe.argLine</propertyName>
                        </configuration>
                    </execution>
                    <execution>
                        <id>post-integration-test</id>
                        <phase>post-integration-test</phase>
                        <goals>
                            <goal>report</goal>
                        </goals>
                        <configuration>
                            <dataFile>${project.build.directory}/jacoco-it.exec</dataFile>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

Needless to say that you need to have a running/configured SonarQube server.

How to fix

There should be more tests. Many more tests. In 2015 nothing less than 85% is reasonable. Maybe the code should be developed test first. See TDD.

Copied from original issue: threema-ch/threema-msgapi-sdk-java#1

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.