{"id":15679456,"url":"https://github.com/rugk/threema-msgapi-sdk-php","last_synced_at":"2025-05-07T10:20:41.433Z","repository":{"id":36176820,"uuid":"40480942","full_name":"rugk/threema-msgapi-sdk-php","owner":"rugk","description":"Gateway MsgApi SDK - PHP","archived":false,"fork":false,"pushed_at":"2019-02-25T18:15:47.000Z","size":4092,"stargazers_count":12,"open_issues_count":10,"forks_count":5,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-19T21:23:17.307Z","etag":null,"topics":["cryptography","curve25519","encrypt","encrypted","encryption","gateway","libsodium","message","messenger","mobile","nacl","notification","notifications","php-sdk","sdk","security","sms","switzerland","threema","threema-gateway"],"latest_commit_sha":null,"homepage":"https://rugk.github.io/threema-msgapi-sdk-php/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rugk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-08-10T12:19:20.000Z","updated_at":"2022-12-21T08:34:29.000Z","dependencies_parsed_at":"2022-09-02T23:20:21.144Z","dependency_job_id":null,"html_url":"https://github.com/rugk/threema-msgapi-sdk-php","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rugk%2Fthreema-msgapi-sdk-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rugk%2Fthreema-msgapi-sdk-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rugk%2Fthreema-msgapi-sdk-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rugk%2Fthreema-msgapi-sdk-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rugk","download_url":"https://codeload.github.com/rugk/threema-msgapi-sdk-php/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252856790,"owners_count":21814902,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cryptography","curve25519","encrypt","encrypted","encryption","gateway","libsodium","message","messenger","mobile","nacl","notification","notifications","php-sdk","sdk","security","sms","switzerland","threema","threema-gateway"],"created_at":"2024-10-03T16:31:17.809Z","updated_at":"2025-05-07T10:20:41.386Z","avatar_url":"https://github.com/rugk.png","language":"PHP","readme":"# [Threema Gateway](https://gateway.threema.ch/) PHP SDK\n\nVersion: [1.2.0](https://github.com/rugk/threema-msgapi-sdk-php/releases/tag/v1.2.0)\n\n[![Build Status](https://travis-ci.org/rugk/threema-msgapi-sdk-php.svg?branch=master)](https://travis-ci.org/rugk/threema-msgapi-sdk-php)\n[![Code Climate](https://codeclimate.com/github/rugk/threema-msgapi-sdk-php/badges/gpa.svg)](https://codeclimate.com/github/rugk/threema-msgapi-sdk-php)\n[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/rugk/threema-msgapi-sdk-php/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/rugk/threema-msgapi-sdk-php/?branch=master)\n[![SensioLabsInsight](https://insight.sensiolabs.com/projects/b2d332ae-4100-42e0-abda-9cc96a79b18a/mini.png)](https://insight.sensiolabs.com/projects/b2d332ae-4100-42e0-abda-9cc96a79b18a)\n[![Codacy Badge](https://api.codacy.com/project/badge/grade/28a86de2f74a421b98ecb2dddd4355f6)](https://www.codacy.com/app/rugk/threema-msgapi-sdk-php)  \n\n## Notes about this version\nThis is a fork of the [original repo](https://github.com/threema-ch/threema-msgapi-sdk-php) after it was announced that the GitHub-version is no longer maintained by Threema.\nAs this is the community version of the Threema Gateway PHP SDK it may contain additional changes which are not yet included in the official downloadable version on the Threema website. If you are looking for a simple mirror of the downloadable Threema version you can switch to the branch [`official`](https://github.com/rugk/threema-msgapi-sdk-php/tree/official).  \nMore information is avaliable in [the wiki](https://github.com/rugk/threema-msgapi-sdk-php/wiki/Branches-and-releases).\n\nAn automatically created documentation of this SDK can be found [on GitHub Pages](https://rugk.github.io/threema-msgapi-sdk-php/).\n\nThe contributors of this repository are not affiliated with Threema or the Threema GmbH.\n\n## Installation\n- Install PHP 5.4 or later: [https://secure.php.net/manual/en/install.php](https://secure.php.net/manual/en/install.php)\n- For better encryption performance, install the [libsodium PHP extension](https://github.com/jedisct1/libsodium-php).\n\n  This step is optional; if the libsodium PHP extension is not available, the SDK will automatically fall back to (slower) pure PHP code for ECC encryption (file and image sending not supported).\n\n  A 64bit version of PHP is required for pure PHP encryption.\n\n  To install the libsodium PHP extension:\n\n  ```ShellSession\n  pecl install libsodium\n  ```\n\n  Then add the following line to your php.ini file:\n\n  ```ini\n  extension=libsodium.so\n  ```\n\nIf you want to check whether your server meets the requirements and everything is configured properly you can execute `threema-msgapi-tool.php` without any parameters on the console or point your browser to the location where it is saved on your server.\n\nIf you want to use this library in your own product it is recommend to use [Composer](https://getcomposer.org/) and require  [`rugk/threema-msgapi-sdk-php`](https://packagist.org/packages/rugk/threema-msgapi-sdk-php).\n\n## SDK usage\n### Creating a connection\n\n```php\nuse Threema\\MsgApi\\Connection;\nuse Threema\\MsgApi\\ConnectionSettings;\nuse Threema\\MsgApi\\Receiver;\n\nrequire_once('lib/bootstrap.php');\n\n//define your connection settings\n$settings = new ConnectionSettings(\n    '*THREEMA',\n    'THISISMYSECRET'\n);\n\n//simple php file to store the public keys (this file must already exist)\n$publicKeyStore = new Threema\\MsgApi\\PublicKeyStores\\PhpFile('/path/to/my/keystore.php');\n\n//create a connection\n$connector = new Connection($settings, $publicKeyStore);\n```\n\n### Creating a connection with advanced options\n**Attention:** These settings change internal values of the TLS connection. Choosing wrong settings can weaken the TLS connection or prevent a successful connection to the server. Use them with care!\n\nEach of the additional options shown below is optional. You can leave it out or use `null` to use the default value determinated by cURL for this option.\n\n```php\nuse Threema\\MsgApi\\Connection;\nuse Threema\\MsgApi\\ConnectionSettings;\nuse Threema\\MsgApi\\Receiver;\n\nrequire_once('lib/bootstrap.php');\n\n//define your connection settings\n$settings = new ConnectionSettings(\n    '*THREEMA',\n    'THISISMYSECRET',\n    null, //the host to be used, set to null to use the default (recommend)\n    [\n        'forceHttps' =\u003e true, //set to true to force HTTPS, default: false\n        'tlsVersion' =\u003e '1.2', //set the version of TLS to be used, default: null\n        'tlsCipher' =\u003e 'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384' //choose a cipher or a list of ciphers, default: null\n        'pinnedKey' =\u003e 'sha256//8SLubAXo6MrrGziVya6HjCS/Cuc7eqtzw1v6AfIW57c=;sha256//8kTK9HP1KHIP0sn6T2AFH3Bq+qq3wn2i/OJSMjewpFw=' // the hashes to pin, the default is shown here, it is NOT recommend to change this value!\n    ]\n);\n\n//simple php file to store the public keys (this file must already exist)\n$publicKeyStore = new Threema\\MsgApi\\PublicKeyStores\\PhpFile('/path/to/my/keystore.php');\n\n//create a connection\n$connector = new Connection($settings, $publicKeyStore);\n```\n\nIf you want to get a list of all ciphers you can use have a look at the [SSLLabs scan](https://www.ssllabs.com/ssltest/analyze.html?d=msgapi.threema.ch\u0026latest), at the list of all available [OpenSSL ciphers](https://www.openssl.org/docs/manmaster/apps/ciphers.html) and the [comparison table by Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS#Cipher_names_correspondence_table) which also has some suggestions for good ciphers you should use.\n\n**Note:** For `pinnedKey` to work you must install cURL 7.39 or higher. It is also recommend to use PHP 7.0.7 or higher if you want to support this feature, but it is not required.\nYou can test whether it works by specifying an invalid pin.\n\n### Sending a text message to a Threema ID (Simple Mode)\n\n```php\n//create the connection\n//(...)\n//create a receiver\n$receiver = new Receiver('ABCD1234', Receiver::TYPE_ID);\n\n$result = $connector-\u003esendSimple($receiver, \"This is a Test Message\");\nif($result-\u003eisSuccess()) {\n    echo 'new id created '.$result-\u003egetMessageId();\n}\nelse {\n    echo 'error '.$result-\u003egetErrorMessage();\n}\n```\n\n### Sending a text message to a Threema ID (E2E Mode)\n\n```php\n//create the connection\n//(...)\n\n$e2eHelper = new \\Threema\\MsgApi\\Helpers\\E2EHelper($senderPrivateKey,$connector);\n$result = $e2eHelper-\u003esendTextMessage(\"TEST1234\", \"This is an end-to-end encrypted message\");\n\nif(true === $result-\u003eisSuccess()) {\n    echo 'Message ID: '.$result-\u003egetMessageId() . \"\\n\";\n}\nelse {\n    echo 'Error: '.$result-\u003egetErrorMessage() . \"\\n\";\n}\n```\n\n### Sending a file message to a Threema ID (E2E Mode)\n\n```php\n//create the connection\n//(...)\n\n$senderPrivateKey = \"MY_PUBLIC_KEY_IN_BIN\";\n$filePath = \"/path/to/my/file.pdf\";\n\n$e2eHelper = new \\Threema\\MsgApi\\Helpers\\E2EHelper($senderPrivateKey,$connector);\n$result = $e2eHelper-\u003esendFileMessage(\"TEST1234\", $filePath);\n\nif(true === $result-\u003eisSuccess()) {\n    echo 'File Message ID: '.$result-\u003egetMessageId() . \"\\n\";\n}\nelse {\n    echo 'Error: '.$result-\u003egetErrorMessage() . \"\\n\";\n}\n```\n\n## Console client usage\n### Local operations (no network communication)\n#### Encrypt\n\n```ShellSession\nthreema-msgapi-tool.php -e \u003cprivateKey\u003e \u003cpublicKey\u003e\n```\n\nEncrypt standard input using the given sender private key and recipient public key. Two lines to standard output: first the nonce (hex), and then the box (hex).\n\n#### Decrypt\n\n```ShellSession\nthreema-msgapi-tool.php -D \u003cprivateKey\u003e \u003cpublicKey\u003e \u003cnonce\u003e\n```\n\nDecrypt 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.\n\n#### Hash Email Address\n\n```ShellSession\nthreema-msgapi-tool.php -h -e \u003cemail\u003e\n```\n\nHash an email address for identity lookup. Prints the hash in hex.\n\n#### Hash Phone Number\n\n```ShellSession\nthreema-msgapi-tool.php -h -p \u003cphoneNo\u003e\n```\n\nHash a phone number for identity lookup. Prints the hash in hex.\n\n#### Generate Key Pair\n\n```ShellSession\nthreema-msgapi-tool.php -g \u003cprivateKeyFile\u003e \u003cpublicKeyFile\u003e\n```\n\nGenerate a new key pair and write the private and public keys to the respective files (in hex).\n\n#### Derive Public Key\n\n```ShellSession\nthreema-msgapi-tool.php -d \u003cprivateKey\u003e\n```\n\nDerive the public key that corresponds with the given private key.\n\n### Network operations\n#### Send Simple Message\n\n```ShellSession\nthreema-msgapi-tool.php -s \u003cthreemaId\u003e \u003cfrom\u003e \u003csecret\u003e\n```\n\nSend a message from standard input with server-side encryption to the given ID. `\u003cfrom\u003e` is the API identity and `\u003csecret\u003e` is the API secret. the message ID on success.\n\n#### Send End-to-End Encrypted Text Message\n\n```ShellSession\nthreema-msgapi-tool.php -S \u003cthreemaId\u003e \u003cfrom\u003e \u003csecret\u003e \u003cprivateKey\u003e\n```\n\nEncrypt standard input and send the text message to the given ID. `\u003cfrom\u003e` is the API identity and `\u003csecret\u003e` is the API secret. Prints the message ID on success.\n\n#### Send a End-to-End Encrypted Image Message\n\n```ShellSession\nthreema-msgapi-tool.php -S -i \u003cthreemaId\u003e \u003cfrom\u003e \u003csecret\u003e \u003cprivateKey\u003e \u003cimageFile\u003e\n```\n\nEncrypt the image file and send the message to the given ID. `\u003cfrom\u003e` is the API identity and `\u003csecret\u003e` is the API secret. Prints the message ID on success.\n\n#### Send a End-to-End Encrypted File Message\n\n```ShellSession\nthreema-msgapi-tool.php -S -f \u003cthreemaId\u003e \u003cfrom\u003e \u003csecret\u003e \u003cprivateKey\u003e \u003cfile\u003e \u003cthumbnailFile\u003e\n```\n\nEncrypt the file (and thumbnail if given) and send the message to the given ID. `\u003cfrom\u003e` is the API identity and `\u003csecret\u003e` is the API secret. Prints the message ID on success.\n\n#### ID-Lookup By Email Address\n\n```ShellSession\nthreema-msgapi-tool.php -l -e \u003cemail\u003e \u003cfrom\u003e \u003csecret\u003e\n```\n\nLookup the ID linked to the given email address (will be hashed locally).\n\n#### ID-Lookup By Phone Number\n\n```ShellSession\nthreema-msgapi-tool.php -l -p \u003cphoneNo\u003e \u003cfrom\u003e \u003csecret\u003e\n```\n\nLookup the ID linked to the given phone number (will be hashed locally).\n\n#### Fetch Public Key\n\n```ShellSession\nthreema-msgapi-tool.php -l -k \u003cthreemaId\u003e \u003cfrom\u003e \u003csecret\u003e\n```\n\nLookup the public key for the given ID.\n\n#### Fetch Capability\n\n```ShellSession\nthreema-msgapi-tool.php -c \u003cthreemaId\u003e \u003cfrom\u003e \u003csecret\u003e\n```\n\nFetch the capabilities of a Threema ID.\n\n#### Decrypt a Message and download the Files\n\n```ShellSession\nthreema-msgapi-tool.php -r \u003cthreemaId\u003e \u003cfrom\u003e \u003csecret\u003e \u003cprivateKey\u003e \u003cmessageId\u003e \u003cnonce\u003e \u003coutputFolder\u003e\n```\n\nDecrypt a box (must be provided on stdin) message and download (if the message is an image or file message) the file(s) to the given `\u003coutputFolder\u003e` folder.\n\n#### Remaining credits\n\n```ShellSession\nthreema-msgapi-tool.php -C \u003cfrom\u003e \u003csecret\u003e\n```\n\nFetch remaining credits.\n\n## Contributing\nNice 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.  \nYou can find more information [in our wiki](https://github.com/rugk/threema-msgapi-sdk-php/wiki/Contributing).\n\n## Implementations\n\nLooking for some implementations? Have a look at [the wiki](https://github.com/rugk/threema-msgapi-sdk-php/wiki/Implementations).\n\n## Other platforms (Java and Python)\nAll 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.\n\nYou can find the Java repository at [simmac/threema-msgapi-sdk-java](https://github.com/simmac/threema-msgapi-sdk-java)  \nand the Python repository at [lgrahl/threema-msgapi-sdk-python](https://github.com/lgrahl/threema-msgapi-sdk-python).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frugk%2Fthreema-msgapi-sdk-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frugk%2Fthreema-msgapi-sdk-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frugk%2Fthreema-msgapi-sdk-php/lists"}