{"id":20560669,"url":"https://github.com/nicolasmure/nmureencryptor","last_synced_at":"2025-04-14T14:06:35.967Z","repository":{"id":57027803,"uuid":"63801700","full_name":"nicolasmure/NmureEncryptor","owner":"nicolasmure","description":"PHP data encryptor using open_ssl","archived":false,"fork":false,"pushed_at":"2017-12-02T19:11:09.000Z","size":26,"stargazers_count":7,"open_issues_count":0,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-11-13T17:49:27.667Z","etag":null,"topics":["encryptor","openssl","php"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nicolasmure.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-07-20T17:41:09.000Z","updated_at":"2020-01-28T13:39:19.000Z","dependencies_parsed_at":"2022-08-23T16:20:41.769Z","dependency_job_id":null,"html_url":"https://github.com/nicolasmure/NmureEncryptor","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicolasmure%2FNmureEncryptor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicolasmure%2FNmureEncryptor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicolasmure%2FNmureEncryptor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicolasmure%2FNmureEncryptor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nicolasmure","download_url":"https://codeload.github.com/nicolasmure/NmureEncryptor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224873072,"owners_count":17384078,"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":["encryptor","openssl","php"],"created_at":"2024-11-16T03:55:23.222Z","updated_at":"2024-11-16T03:55:23.715Z","avatar_url":"https://github.com/nicolasmure.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NmureEncryptor\n\n[![Build Status](https://travis-ci.org/nicolasmure/NmureEncryptor.svg?branch=master)](https://travis-ci.org/nicolasmure/NmureEncryptor)\n[![Coverage Status](https://coveralls.io/repos/github/nicolasmure/NmureEncryptor/badge.svg?branch=master)](https://coveralls.io/github/nicolasmure/NmureEncryptor?branch=master)\n\nPHP data encryptor using open_ssl\n\n## Table of contents\n- [Installation](#installation)\n- [Usage](#usage)\n    - [Basic usage](#basic-usage)\n        - [Encrypt](#encrypt)\n        - [Decrypt](#decrypt)\n    - [Advanced usage](#advanced-usage)\n- [Formatters](#formatters)\n    - [Built-in formatters](#built-in-formatters)\n        - [Base64Formatter](#base64formatter)\n        - [HexFormatter](#hexformatter)\n    - [Make your own formatter](#make-your-own-formatter)\n- [API](#api)\n- [Troubleshooting](#troubleshooting)\n    - [Using the HexFormatter with a C# app](#using-the-hexformatter-with-a-c-app)\n- [Integration](#integration)\n- [Development / contributing](#development--contributing)\n    - [Installing ecosystem](#installing-ecosystem)\n    - [Testing](#testing)\n    - [PHP CS Fixer](#php-cs-fixer)\n- [License](#license)\n\n## Installation\nUse composer to install the lib :\n\n```bash\ncomposer require nmure/encryptor \"~1.0.0\"\n```\n\n## Usage\n\n### Basic usage\n\n#### Encrypt\n\nThe simpliest way to use this library is to create an instance of the Encryptor\nby passing it a secret key and a cipher method to use during encryption.\nTo see all the cipher methods supported by your php installation, use the\n[openssl_get_cipher_methods](http://php.net/manual/en/function.openssl-get-cipher-methods.php \"Gets available cipher methods\") function.\n\nThen you can encrypt your plain text data, for instance :\n```php\nuse Nmure\\Encryptor\\Encryptor;\n\n$encryptor = new Encryptor('452F93C1A737722D8B4ED8DD58766D99', 'AES-256-CBC');\n$encrypted = $encryptor-\u003eencrypt('plain text data');\n```\n\nThe encryptor uses an Initialization Vector (IV) in addition to the secret key to encrypt data.\nThis IV is randomly generated to be sure that 2 encryptions of the same data with the\nsame key won't produce the same encrypted output.\n\nThereby, you should store the IV used to encrypt your data along side to the encrypted data\nto be able to decrypt it later.\n\nFor instance, you could store it in a database :\n```\n| id |  iv  | encrypted |\n-----------------------\n| 1  | 945a | oifd4867h |\n| 2  | 894d | 62vbyibd6 |\n```\n\n##### Decrypt\n\nThen, to decrypt your data, initialize the encryptor and call the `decrypt` function :\n\n```php\nuse Nmure\\Encryptor\\Encryptor;\n\n$encryptor = new Encryptor('452F93C1A737722D8B4ED8DD58766D99', 'AES-256-CBC');\n// retrieve the IV ($iv) and the encryped data ($encrypted) from your DB\n// ...\n$encryptor-\u003esetIv($iv);\n$plainText = $encryptor-\u003edecrypt($encrypted);\n```\n\n### Advanced usage\n\nIf you don't want to deal with how to store the encrypted data and the IV,\nyou can use the [formatters](#formatters \"Formatters documentation\").\nThe formatters combine the IV and the encrypted data into one string to make it\neasier to store and to share with an other app.\n\nFor instance, if you want to store an encrypted data to a file, you could use\nthe [Base64Formatter](#base64formatter \"Base64Formatter documentation\") :\n\n```php\nuse Nmure\\Encryptor\\Encryptor;\nuse Nmure\\Encryptor\\Formatter\\Base64Formatter;\n\n$encryptor = new Encryptor('452F93C1A737722D8B4ED8DD58766D99', 'AES-256-CBC');\n$encryptor-\u003esetFormatter(new Base64Formatter());\n\n// will produce a string containg the IV and the encrypted data\n$encrypted = $encryptor-\u003eencrypt('plain text data');\n// store $encrypted to a file\n```\n\nThen, to decrypt your data, use the same encryptor / formatter couple and simply call\nthe `decrypt` function with the combined string :\n\n```php\nuse Nmure\\Encryptor\\Encryptor;\nuse Nmure\\Encryptor\\Formatter\\Base64Formatter;\n\n$encryptor = new Encryptor('452F93C1A737722D8B4ED8DD58766D99', 'AES-256-CBC');\n$encryptor-\u003esetFormatter(new Base64Formatter());\n\n// get the encrypted data from a file, or whatever\n// ... $encrypted\n\n// the encryptor uses the formatter to get the IV used for the encryption from\n// the given $encrypted string\n$plainText = $encryptor-\u003edecrypt($encrypted);\n```\n\nIf you don't want to use the formatter anymore, simply set it to `null` on the encryptor :\n```php\n$encryptor-\u003esetFormatter(null);\n```\n\nUsing formatters is more convenient as all the work to store the IV along side\nthe encrypted data is done by the formatters, and not by you anymore.\n\n## Formatters\n\nThe formatters are used to combine the IV and the encrypted data into one string\n(usually a non binary string), to make it easier to store and to share accross systems.\nThey all implement the [`FormatterInterface`](/src/Formatter/FormatterInterface.php \"Nmure\\Encryptor\\Formatter\\FormatterInterface\").\n\n### Built-in formatters\n\n#### Base64Formatter\n\nThe string returned by the [`Base64Formatter`](/src/Formatter/Base64Formatter.php \"Nmure\\Encryptor\\Formatter\\Base64Formatter\")\nduring the encryption process contains the base64 encoded IV, concatened to a colon (`:`),\nconcatened to the base64 encoded encrypted data.\n\nAs the colon is not a char from the base64 chars, we can easily split this string\nin two parts from the colon, and get back the IV and the encrypted data during the decryption process.\n\n#### HexFormatter\n\nThe string returned by the [`HexFormatter`](/src/Formatter/HexFormatter.php \"Nmure\\Encryptor\\Formatter\\HexFormatter\")\nduring the encryption process contains the hex representation of the concatened\nIV and encrypted data binary string.\n\nDuring the decryption process, this string is splitted to get back the IV\nand the encrypted data. We use the cipher method's IV length to determine\nwhere to split this string.\n\n### Make your own formatter\n\nYou can of course make your own formatter to suit your needs,\nit must just implement the [`FormatterInterface`](/src/Formatter/FormatterInterface.php \"Nmure\\Encryptor\\Formatter\\FormatterInterface\").\n\n## API\n\n- **Nmure\\Encryptor\\Encryptor** :\n    - `public string encrypt($data)` : encrypts the given plain text string and\n    returns it. When a formatter is set to the encyryptor, the returned value of\n    this function is the formatted string composed of the IV and the ecrypted data.\n    - `public string decrypt($data)` : decrypts the given encrypted data and returns it.\n    When a formatter is set to the encryptor, the given data must be the string formatted\n    by this formatter. The IV will be determined from the formatted string.\n    When no formatter is set, the IV must be set to this encryptor to be able\n    to decrypt the given data.\n    - `public string generateIv()` : generate a new ramdom IV according to the cipher method,\n    set it to the encryptor and returns it.\n    - `public void enableAutoIvUpdate()` : enable the automatic IV update before each\n    encryption process to be sure that two encryptions of the same data won't produce\n    the same output. The automatic IV update is enabled by default.\n    - `public void disableAutoIvUpdate()` : disable the automatic IV update before each\n    encryption process. The encryption will use the last set IV or generate one if\n    no IV was set.\n    - `public void turnHexKeyToBin()` : turns the hex secret key into a binary key.\n    - `public string getIv()` : returns the IV of the encryptor.\n    - `public void setIv($iv)` : set the given IV to the encryptor.\n    - `public void setFormatter(FormatterInterface $formatter = null)` : sets the given\n    FormatterInterface to the encryptor. To unset the formatter, pass `null` to this function.\n- **Nmure\\Encryptor\\Formatter\\FormatterInterface** :\n    - `public string format($iv, $encrypted)` : formats the given IV and encrypted data to a string\n    and returns it.\n    - `public array parse($input, $ivLength)` : parse the given `$input` string and return an array\n    containing the IV and the encrypted data. The `$ivLength` parameter can be used to parse\n    the `$input` string.\n\n## Troubleshooting\n\n### Using the HexFormatter with a C# app\n\nIf you use this formatter with the encryptor to share crypted data with a C# app,\nyou'll probably have to turn your secret key into a binary key :\n\n```php\nuse Nmure\\Encryptor\\Encryptor;\nuse Nmure\\Encryptor\\Formatter\\HexFormatter;\n\n$encryptor = new Encryptor('452F93C1A737722D8B4ED8DD58766D99', 'AES-256-CBC');\n$encryptor-\u003eturnHexKeyToBin(); // turning the hex key to a binary key\n$encryptor-\u003esetFormatter(new HexFormatter());\n\n$encrypted = $encryptor-\u003eencrypt('plain text data');\n```\n\n## Integration\n\nYou can use this library as standalone, or if you're using Symfony,\nit is wrapped inside the [`NmureEncryptorBundle`](https://github.com/nicolasmure/NmureEncryptorBundle \"A Symfony Bundle for the nmure/encryptor library\").\n\n## Development / Contributing\n\n### Installing ecosystem\n```bash\ndocker-compose run --rm composer install\n```\n\n### Testing\n``` bash\ndocker-compose run --rm phpunit -c /app\n```\n\nThe formatters test classes should extend the [`AbstractFormatterTest`](/tests/Nmure/Encryptor/Tests/Formatter/AbstractFormatterTest.php \"Nmure\\Encryptor\\Tests\\Formatter\\AbstractFormatterTest\") class\nto be sure that the formatters fulfill the minimum requirements.\n\n### PHP CS Fixer\n```bash\ndocker-compose run --rm phpcs phpcbf --standard=PSR2 /scripts/\n```\n\n## License\n\nThis library is licensed under the MIT License.\nMore informations in the [LICENSE](/LICENSE) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicolasmure%2Fnmureencryptor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnicolasmure%2Fnmureencryptor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicolasmure%2Fnmureencryptor/lists"}