{"id":13622865,"url":"https://github.com/timoh6/TCrypto","last_synced_at":"2025-04-15T10:31:44.078Z","repository":{"id":57065720,"uuid":"1961517","full_name":"timoh6/TCrypto","owner":"timoh6","description":"TCrypto is a simple and flexible PHP 5.3+ in-memory key-value storage library","archived":false,"fork":false,"pushed_at":"2016-08-10T06:25:11.000Z","size":98,"stargazers_count":61,"open_issues_count":0,"forks_count":13,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-17T12:43:20.218Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/timoh6.png","metadata":{"files":{"readme":"README.markdown","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":"2011-06-27T17:30:44.000Z","updated_at":"2024-09-27T14:32:12.000Z","dependencies_parsed_at":"2022-08-24T14:01:42.481Z","dependency_job_id":null,"html_url":"https://github.com/timoh6/TCrypto","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timoh6%2FTCrypto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timoh6%2FTCrypto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timoh6%2FTCrypto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timoh6%2FTCrypto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/timoh6","download_url":"https://codeload.github.com/timoh6/TCrypto/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249051641,"owners_count":21204860,"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":[],"created_at":"2024-08-01T21:01:25.099Z","updated_at":"2025-04-15T10:31:43.790Z","avatar_url":"https://github.com/timoh6.png","language":"PHP","readme":"About\n=====\n\n[![Build Status](https://secure.travis-ci.org/timoh6/TCrypto.png)](http://travis-ci.org/timoh6/TCrypto)\n\nTCrypto is a simple and flexible PHP 5.3+ in-memory key-value storage library. By default,\na cookie will be used as a storage backend.\n\nTCrypto has been designed from the ground up with security in mind. Safe algorithms\nand modes. Automatic and safe initialization vector creation. Encryption and\nauthentication key creation (Keytool) using strong randomness. Key rotation\n(versioned keys).\n\nTCrypto can be used as a scalable \"session handler\". Especially scalable,\nif cookies are used as a storage backend. This is a bit like Ruby on Rails sessions.\n\nThere's an article outlining basic TCrypto usage at [websec.io](http://websec.io/): [TCrypto: Encrypted data storage for PHP applications](http://websec.io/2012/08/29/TCrypto-Encrypted-Data-Storage-for-PHP.html)\n\nThis is a preview release (although considered stable). Keyfile encryption will be\navailable in version 1.0.0. Otherwise no other changes are planned between current\ndev-master and 1.0.0.\n\n**Important security note about data compression:**\n\nPrior to August 6 2013, TCrypto allowed to use data compression when the data was\nalso being encrypted. This may lead to disclosure of the (confidential) plain text.\nAll TCrypto users are encouraged to update to the current dev-master. Especially\nif CompressPlugin() was used with data encryption.\n\n\nTCrypto is placed in the public domain.\n\n\nRequirements\n------------\n\nTCrypto requires PHP version 5.3 or greater. To use encryption, either Mcrypt or\nOpenSSL extension must be available. If OpenSSL is used for encryption,\nPHP 5.3.3 or greater is required. Optional compression plugin requires zlib.\n\n\nInstallation note\n-----------------\n\nTCrypto supports installation using Composer, but make sure you use at least Composer version 1.0.0-beta1\nto install TCrypto (Composer was vulnerable to MITM attacks before 1.0.0-beta1):\n\n[tcrypto/tcrypto](https://packagist.org/packages/tcrypto/tcrypto)\n\n\nBackward incompatible changes\n-----------------------------\n\n04 Dec 2015 String() StorageHandler was renamed to PlainString().\n\n\nTCrypto Keymanager and Keytool\n------------------------------\n\nKeytool is a small command-line application, which is used to create encryption\nand authentication keys. Keytool can also be used to remove inactive keys.\n\nBefore you start using TCrypto, run Keytool and create your first set of keys:\n\n    $ cd /path/to/TCrypto/bin\n    $ php keytool\n\nMake sure the right keyfile is selected (if necessary, change keyfile) and select\noption 1 \"Add new keys\".\n\nTo remove inactive keys, run Keytool and select option 2 \"Remove inactive keys\".\nYou should always remove inactive keys before you add new keys. This is because\ninactive keys are determined comparing the (current) primary key timestamp and key\nlifetime (keys that can not be active are removed).\n\nThere are a few Keytool settings you can tweak.\nFile `TCrypto/bin/keytool.config.php`:\n\n- **'keyfile_permissions'**: the default filesystem permissions for the keyfile\n- **'bytes_in_key_name'**: key name length\n- **'key_max_lifetime'**: this should be the same as $_macMaxLifetime in TCrypto\n- **'keyfile_location'**: the default keyfile location\n\nIf you remove or comment out 'keyfile_permissions' setting, chmod() won't be run at\nall for the keyfile.\n\n\nKeytool stores keys as a plain PHP array. The key format is as follows:\n\n``` php\n\u003c?php\narray (\n  'tcrypto_key_data' =\u003e \n  array (\n    'keys' =\u003e \n    array (\n      'index_xxx' =\u003e \n      array (\n        'encryption' =\u003e 'key_xxx',\n        'authentication' =\u003e 'key_xxx',\n        'time' =\u003e xxx,\n      ),\n    ),\n    'meta_data' =\u003e \n    array (\n      'primary_index' =\u003e 'index_xxx',\n      'last_key_creation_time' =\u003e xxx,\n    ),\n  ),\n);\n```\n\n'index_xxx' means a unique array index. Keytool will (by default) use 3 bytes of\nentropy in a key name (hexadecimal format). 3 bytes can produce about 4096 \ndistinct keys without collisions. Given that you should probably have no more\nthan a few keys in your keyfile, 3 bytes of entropy in a key name will be\neasily enough.\n\n'meta_data' is used to identify the current primary key index.\n\nThere can be multiple keys in the 'keys' array. However, you should remove\nconstantly inactive keys (to avoid filling your key file with \"junk\"). It is\na good idea to always remove inactive keys before you add new keys.\n\n\nExamples\n--------\n\n``` php\n\u003c?php\nrequire '/path/to/library/TCrypto/Loader.php';\n$loader = new TCrypto\\Loader();\n$loader-\u003eregister();\n```\n``` php\n\u003c?php\n// Keymanager handles encryption/authentication keys. By default, Filesystem()\n// method looks the keyfile from `TCrypto/Keystore/default` file. If you want to use\n// another keyfile, simply give the full path of the keyfile to Filesystem()'s\n// constructor. E.g.\n// $keymanager = new TCrypto\\KeyManager\\Filesystem('/path/to/keyfile');\n$keymanager = new TCrypto\\KeyManager\\Filesystem();\n// You can also inject the key data as a plain PHP array using setKeysAsArray():\n// $keymanager-\u003esetKeysAsArray(array('tcrypto_key_data'...));\n\n// The data will be stored to a cookie.\n$storage = new TCrypto\\StorageHandler\\Cookie();\n// You can pass a boolean false as the first parameter for Cookie,\n// this makes it possible to use cookies even if there is no HTTPS connection,\n// although this is not recommended.\n// The second parameter for Cookie specifies the name of the cookie.\n// $storage = new TCrypto\\StorageHandler\\Cookie(false, 'my_cookie_name');\n\n// or, to get TCrypto payload immediately back as a string:\n// $storage = new TCrypto\\StorageHandler\\PlainString();\n// $tcryptoPayload = $tcrypto-\u003esave();\n// To feed back previously used TCrypto payload, pass it as a first argument to PlainString():\n// $storage = new TCrypto\\StorageHandler\\PlainString($tcryptoPayload);\n\n// In short, you can save TCrypto payload to, say, a database\n// (without the need to use a specific database StorageHandler).\n// Then you can fetch the TCrypto payload from the database, and\n// feed it back into TCrypto.\n// NOTE, using PlainString() StorageHandler will make\n// $tcrypto-\u003esave() to output the actual payload.\n\n// Initialize encryption using either OpenSSL or Mcrypt (optional).\n$crypto = new TCrypto\\CryptoHandler\\OpenSslAes128Cbc();\n// or\n$crypto = new TCrypto\\CryptoHandler\\OpenSslAes256Cbc();\n// or\n$crypto = new TCrypto\\CryptoHandler\\McryptAes128Cbc();\n// or\n$crypto = new TCrypto\\CryptoHandler\\McryptAes256Cbc();\n\n// Initialize the default plugin (serialize/unserialize).\n$plugins = new TCrypto\\PluginContainer();\n\n// Attach an extra plugin (compress/uncompress) (optional).\n$plugins-\u003eattachPlugin(new TCrypto\\Plugin\\CompressPlugin());\n\n// Available options:\n// (array) 'entropy_pool'\n// (int) 'max_lifetime'\n// (bool) 'save_on_set'\n$options = array('max_lifetime' =\u003e 6400);\n\n// Create a new Crypto instance and inject the needed dependencies.\n$tcrypto = new TCrypto\\Crypto($keymanager, $storage, $plugins, $crypto, $options);\n\n// If you create a new TCrypto instance without passing any of the dependencies,\n// e.g. $tc = new TCrypto\\Crypto(), TCrypto will use the following defaults:\n// $keyManager = new KeyManager\\Filesystem(); // Uses the default keyfile.\n// $storage = new StorageHandler\\Cookie(); // Requires HTTPS connection.\n// $plugins = new PluginContainer(); // Default serialize/unserialize plugin.\n// $crypto = null // No encryption.\n// $options = array() // No options are modified.\n\n// Value can be any serializable data type. \n$tcrypto-\u003esetValue('key', 'value');\n$tcrypto-\u003esetValue('object', new stdClass());\n$tcrypto-\u003eremoveValue('object');\n\necho $tcrypto-\u003egetValue('key'); // \"value\"\necho $tcrypto-\u003egetValue('object'); // \"NULL\"\n\n// Saves the data to a storage.\n$tcrypto-\u003esave();\n// If PlainString() StorageHandler is being used, $tcrypto-\u003esave() will output\n// the TCrypto payload (you need to store the payload by some other means).\n\n// Destroys the data both from memory and storage.\n$tcrypto-\u003edestroy();\n```\n\n\nAbout symmetric encryption\n--------------------------\n\nCurrently there are four choices for an encryption provider:\n\n    Crypto\\CryptoHandler\\OpenSslAes128Cbc\n    Crypto\\CryptoHandler\\McryptAes128Cbc\n\nand\n\n    Crypto\\CryptoHandler\\OpenSslAes256Cbc\n    Crypto\\CryptoHandler\\McryptAes256Cbc\n\nOpenSslAes128Cbc/McryptAes128Cbc and OpenSslAes256Cbc/McryptAes256Cbc both\nimplement AES in CBC mode using a random initializing vector. Only the key size\ndiffers between them. 128-bit key size should be unbreakable with foreseeable\ntechnology. But on the other hand, 256-bit keys provides more margin of security\n(against side channels etc.). Encrypting with 128-bit keys should be somewhat\nfaster than encrypting with 256-bit keys. However, in a typical web application\nusage scenario, this speed difference is probably insignificant.\n\nIf you feel paranoid (the bigger, the better fetish), use McryptAes256Cbc.\nOtherwise use McryptAes128Cbc.\n\nTCrypto derives encryption keys from variable data (timestamps, initializing\nvector, key seeds and user supplied extra entropy sources). This guarantees\nthat a fresh and random key will be used for each encryption operation. The key\nsetup combined with (truncated) SHA512 hashing ensures (currently known) related-key\nattacks does not apply against AES-256 (McryptAes256Cbc).\n\nIf your system supports OpenSSL, use OpenSSL based encryption (OpenSslAes128Cbc\nor OpenSslAes256Cbc).\n\n\nPlugins\n-------\n\nTCrypto comes with a simple \"plugin system\". Plugins are run in two separate\nplaces.\n\n* Before saving the data to a storage.\n\n* After extracting the data from a storage (plugins are run in reverse order).\n\nIt is important to note that you can not use data compression plugins if you\nare using data encryption.\n\nIf you configure TCrypto to use data compression at the same time data is\nbeing encrypted, the PluginContainer will automatically skip data compression plugins.\n\nThis is important because compressing confidential (encrypted) data may leak information\nabout the plain text.\n\nThis creates the required serialize/unserialize plugin:\n\n``` php\n\u003c?php\n// PluginContainer() automatically attaches DefaultPlugin(), which handles\n// serializing and unserializing.\n$plugins = new TCrypto\\PluginContainer();\n```\n\nYou can also attach more plugins:\n\n``` php\n\u003c?php\n// NOTE: CompressPlugin will not be run if data encryption is being used.\n// This is because data compression leaks information about the plain text.\n$plugins-\u003eattachPlugin(new TCrypto\\Plugin\\CompressPlugin());\n```\n\nNow the data will be first serialized and then compressed (when saving).\nWhen extracting the data from a storage, the data will be first uncompressed\nand then unserialized.\n\nNOTE: $plugins-\u003eattach() is not supported anymore. Use $plugins-\u003eattachPlugin()\ninstead of $plugins-\u003eattach().\n\n\nSecurity notes\n--------------\n\n### Keystore\n\nTCrypto Keytool will write all encryption/authentication keys to a\nfilesystem. Make sure this keyfile can not be read by anyone else. It is\nprobably a good idea to use chmod 0600 setting for the keyfile\n(depending on your server settings).\n\n### Cookies as a storage backend\n\nBy default, TCrypto uses browser cookies as a \"permanent\" storage backend. If you\ndo not use encryption, anyone who you send the data can read (but not modify)\nit. It is up to you to decide does the data need to be encrypted.\n\nIt should be pointed out that TCrypto does not address replay of old cookies.\nLegitimate client can send previous (old) cookies within the \"max_lifetime\"\nperiod. \n\nHTTPS connection is another important concern about browser cookies. If there is\nno \"secure connection\", the data may be captured (and replayed) by whoever is\neavesdropping on the line.\n\n### Plugins\n\nWhen extracting the data from a storage, an HMAC value will be checked BEFORE\nthe plugins are run. This could potentially lead to bugs or security issues.\nIf you use any extra plugins, make sure they operate correctly.\n\n\nIssues or questions?\n--------------------\n\nMail me at timoh6@gmail.com or use GitHub.\n","funding_links":[],"categories":["安全","目录","Table of Contents","安全 Security","PHP","Security","Frameworks and Libs","安全( Security )"],"sub_categories":["安全 Security","Security","PHP"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimoh6%2FTCrypto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimoh6%2FTCrypto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimoh6%2FTCrypto/lists"}