{"id":17760828,"url":"https://github.com/cipherstash/goeql","last_synced_at":"2026-01-25T00:01:42.907Z","repository":{"id":259134720,"uuid":"876405067","full_name":"cipherstash/goeql","owner":"cipherstash","description":"Golang helper package for use with EQL","archived":false,"fork":false,"pushed_at":"2024-10-23T23:30:24.000Z","size":14,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-24T12:54:40.038Z","etag":null,"topics":["cipherstash","encryption-in-use","eql","golang","security"],"latest_commit_sha":null,"homepage":"https://github.com/cipherstash/encrypt-query-language","language":"Go","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/cipherstash.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-21T23:08:51.000Z","updated_at":"2024-10-23T23:28:13.000Z","dependencies_parsed_at":"2024-10-26T19:31:13.819Z","dependency_job_id":"e0e72b91-42cf-43e5-9b85-8ce0506ed1a1","html_url":"https://github.com/cipherstash/goeql","commit_stats":null,"previous_names":["cipherstash/goeql"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/cipherstash/goeql","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipherstash%2Fgoeql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipherstash%2Fgoeql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipherstash%2Fgoeql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipherstash%2Fgoeql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cipherstash","download_url":"https://codeload.github.com/cipherstash/goeql/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipherstash%2Fgoeql/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28739320,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-24T22:12:27.248Z","status":"ssl_error","status_checked_at":"2026-01-24T22:12:10.529Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["cipherstash","encryption-in-use","eql","golang","security"],"created_at":"2024-10-26T19:13:32.838Z","updated_at":"2026-01-25T00:01:42.882Z","avatar_url":"https://github.com/cipherstash.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# goeql Package\n\n## Overview\n\nThe `goeql` package provides a set of helper functions to assist with serializing and deserializing various data types into a format that is compatible with CipherStash Proxy. This package enables seamless encryption and decryption of values and facilitates search operations on encrypted data without exposing the plaintext.\n\nThe package is designed to support [CipherStash’s Encrypt Query Language (EQL)](https://github.com/cipherstash/encrypt-query-language), which is a language for querying encrypted data in a PostgreSQL database.\n\n## Installation\n\nTo install `goeql`, use `go get`:\n\n```bash\ngo get github.com/cipherstash/goeql\n```\n\n## Data Format\n\nEQL requires data to be serialized in the following JSON format:\n\n```json\n{\n  \"k\": \"pt\",\n  \"p\": \"a string representation of the plaintext that is being encrypted\",\n  \"i\": {\n    \"t\": \"table\",\n    \"c\": \"column\"\n  },\n  \"v\": 1\n}\n```\n\nFor more information about this format, refer to the [Encrypt Query Language documentation](https://github.com/cipherstash/encrypt-query-language#data-format).\n\n## Supported Types\n\nThe `goeql` package supports the following data types for serialization and deserialization:\n\n- `EncryptedText`: Represents a `string` value.\n- `EncryptedJsonb`: Represents a `jsonb` object (map).\n- `EncryptedInt`: Represents an `int` value.\n- `EncryptedBool`: Represents a `bool` value.\n\n## Usage\n\n### Serialization\n\nEach supported type provides a `Serialize` method that converts the value into an EQL-compatible JSON format for CipherStash Proxy:\n\n```go\ntext := EncryptedText(\"secret value\")\ndata, err := text.Serialize(\"users\", \"password\")\nif err != nil {\n    log.Fatal(err)\n}\nfmt.Println(string(data))  // JSON-encoded EQL object\n```\n\n### Deserialization\n\nThe `Deserialize` method allows converting a JSON payload from CipherStash Proxy back into the corresponding type:\n\n```go\nvar text EncryptedText\nerr := text.Deserialize(data)\nif err != nil {\n    log.Fatal(err)\n}\nfmt.Println(text)  // Decrypted plaintext value\n```\n\n### Query Serialization\n\nThe package provides helper functions to serialize queries that interact with encrypted data in various ways:\n\n- `MatchQuery`: Serializes a plaintext value for an equality query.\n- `OreQuery`: Serializes a value for order-preserving encryption queries (range).\n- `UniqueQuery`: Serializes a value for a unique constraint check.\n- `JsonbQuery`: Serializes a value for JSONB vector-based queries.\n\nExample:\n\n```go\nqueryData, err := MatchQuery(\"search term\", \"users\", \"username\")\nif err != nil {\n    log.Fatal(err)\n}\nfmt.Println(string(queryData))\n```\n\n## Functions\n\n### `Serialize()`\n\n- **Description**: Converts a plaintext value into an encrypted JSON payload that conforms to the EQL format.\n- **Parameters**: \n  - `table`: The name of the table.\n  - `column`: The name of the column.\n- **Returns**: `[]byte` (serialized JSON), `error`\n\n### `Deserialize()`\n\n- **Description**: Converts an encrypted JSON payload back into its plaintext representation.\n- **Parameters**: \n  - `data`: JSON payload from CipherStash Proxy.\n- **Returns**: Decrypted value, `error`\n\n### `MatchQuery()`\n\n- **Description**: Serializes a value for use in an equality query in EQL.\n- **Parameters**: \n  - `value`: The plaintext value to query.\n  - `table`: The name of the table.\n  - `column`: The name of the column.\n- **Returns**: Serialized query, `error`\n\n### `OreQuery()`, `UniqueQuery()`, `JsonbQuery()`\n\nThese functions work similarly to `MatchQuery()`, but are used for different query types, such as range, unique, and JSONB queries.\n\n## Example\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"log\"\n)\n\nfunc main() {\n    // Encrypt a text value\n    text := EncryptedText(\"example plaintext\")\n    data, err := text.Serialize(\"users\", \"email\")\n    if err != nil {\n        log.Fatal(err)\n    }\n    fmt.Println(\"Serialized data:\", string(data))\n    \n    // Decrypt the value\n    var decryptedText EncryptedText\n    decryptedText, err = decryptedText.Deserialize(data)\n    if err != nil {\n        log.Fatal(err)\n    }\n    fmt.Println(\"Decrypted text:\", decryptedText)\n}\n```\n\n## Contributing\n\nWe welcome contributions! Feel free to open an issue or submit a pull request if you find a bug or have suggestions for improvement.\n\n## License\n\nThis project is licensed under the MIT License.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcipherstash%2Fgoeql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcipherstash%2Fgoeql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcipherstash%2Fgoeql/lists"}