{"id":21334911,"url":"https://github.com/vlsergey/seccookie","last_synced_at":"2025-07-03T01:35:44.406Z","repository":{"id":57735143,"uuid":"460966873","full_name":"vlsergey/seccookie","owner":"vlsergey","description":"Java library for security cookies, client-side pieces of data protected from reading and modifications by client with strong cryptography","archived":false,"fork":false,"pushed_at":"2022-02-21T08:22:51.000Z","size":88,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-16T01:42:02.578Z","etag":null,"topics":["cookie","cookies","cryptography","cryptography-library","java","java-library","security"],"latest_commit_sha":null,"homepage":"","language":"Java","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/vlsergey.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":"2022-02-18T18:41:07.000Z","updated_at":"2022-10-09T20:17:22.000Z","dependencies_parsed_at":"2022-08-24T03:30:06.121Z","dependency_job_id":null,"html_url":"https://github.com/vlsergey/seccookie","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/vlsergey/seccookie","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlsergey%2Fseccookie","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlsergey%2Fseccookie/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlsergey%2Fseccookie/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlsergey%2Fseccookie/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vlsergey","download_url":"https://codeload.github.com/vlsergey/seccookie/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlsergey%2Fseccookie/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263244688,"owners_count":23436478,"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":["cookie","cookies","cryptography","cryptography-library","java","java-library","security"],"created_at":"2024-11-21T23:36:15.410Z","updated_at":"2025-07-03T01:35:44.360Z","avatar_url":"https://github.com/vlsergey.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Secure Cookie Library\nJava library for security cookies, client-side pieces of data protected from reading and modifications by client with strong cryptography\n\n* Allows to store small pieces of data at client side protected from reading **and modifications** by client and by third party.\n* Uses strong encryption ([AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) with [GCM](https://en.wikipedia.org/wiki/Galois/Counter_Mode)) to encrypt, decipher and validate data.\n* Has no runtime dependencies, plain JDK is enough.\n\nShort explanation of idea of secure cookie usage was presented at JPoint 2020 conference in \"Cryptography for Java Developer\" presentation that can be viewed (in Russian) here: https://youtu.be/YQEb1mjjpZg?t=1279\n\n[![Build with Gradle](https://github.com/vlsergey/seccookie/actions/workflows/build.yml/badge.svg)](https://github.com/vlsergey/seccookie/actions/workflows/build.yml)\n[![CodeQL](https://github.com/vlsergey/seccookie/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/vlsergey/seccookie/actions/workflows/codeql-analysis.yml)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.github.vlsergey/seccookie/badge.svg)](https://search.maven.org/artifact/io.github.vlsergey/seccookie)\n\n## Installation\n\n### Gradle\n\n```groovy\ndependencies {\n  implementation group: 'io.github.vlsergey', name: 'seccookie', version: '1.0.0'\n}\n```\n\n### Maven\n\n```xml\n  \u003cdependency\u003e\n    \u003cgroupId\u003eio.github.vlsergey\u003c/groupId\u003e\n    \u003cartifactId\u003eseccookie\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.0\u003c/version\u003e\n  \u003c/dependency\u003e\n```\n\n## Simple usage (`SimpleSecCookieMapper`)\n```java\n\n// Define a way to obtain SecretKey. Usually it is part of application configuration.\n// Note. It's better to store SecretKey instance in memory than recreating it from char[] or byte[] on each call.\nSecretKey secretKey = /* ... */;\nSupplier\u003cSecretKey\u003e secretKeySupplier = () -\u003e secretKey;\n\n// Define a way to (de)serialize your data type to/from byte array.\n// It may be Java serialization, Jackson ObjectMapper call for complex objects, or simple getBytes() for Strings:\nFunction\u003cString, byte[]\u003e serializer = String::getBytes;\nFunction\u003cbyte[], String\u003e deserializer = String::new;\n\n// Construct instance of SimpleSecCookieMapper\nSimpleSecCookieMapper.Settings settings = new SimpleSecCookieMapper.Settings(\n   serializer, deserializer, secretKeySupplier);\nSimpleSecCookieMapper mapper = new SimpleSecCookieMapper(settings);\n\n// use mapper to serialize to secure cookie\n\nString dataToStoreInCookie = UUID.randomUUID().toString();\nbyte[] secCookie = mapper.writeValue( dataToStoreInCookie );\n\n// sometimes one need to serialize it to String.\n// We recommend `apache-codec` library for that:\nString encoded = org.apache.commons.codec.binary.Base64.encodeBase64URLSafeString(secCookie)\n\n// Decoding and validation is quite straightforward\nbyte[] secCookie2 = org.apache.commons.codec.binary.Base64.decodeBase64( encoded )\ntry {\n  return mapper.readValue(secCookie2);\n} catch (WrongSecureCookieException exc) {\n  // can be replaced with ControllerAdvice Exception handler\n  throw RuntimeException(\"Supplied data is invalid\", exc);\n}\n```\n\n## Key rolling technique\nFor long living and secure-oriented systems it may be required to provide a \"key rolling\" support where keys can be replaced in runtime without problems with existing user data. `SimpleSecCookieMapper` supports it via providing list of keys that can be used to try and decrypt secure cookie. All keys will be used in provided order and only after all of them tried single success result will be returned. I.e. there is no \"fast first success\" shortcut to prevent timing attacks (but at the cost of exception creation in JVM).\n\nTo provide multiple decryption key just set `decryptionKeysSupplier` property in `SimpleSecCookieMapper.Settings`:\n\n```java\nSimpleSecCookieMapper.Settings settings = new SimpleSecCookieMapper.Settings(\n   serializer, deserializer, secretKeySupplier);\nsettings.setDecryptionKeysSupplier = () -\u003e Arrays.asList( secretKey1, secretKey2, secretKey3, ... );\n```\n\nThere are 2 rules when changing keys configuration:\n* Encrypt with newest key.\n* Have all old keys in decryption keys list until keys/cookie TTL expired.\n\nAssume we have configuration alike following:\n\n```yaml\nencryptWith: secretKey2\ndecryptWith:\n  - secretKey1\n  - secretKey2\n```\n\n`secretKey1` was used long time before. So we removing it from the list and add new `secretKey3` to decryption keys list:\n\n```yaml\nencryptWith: secretKey2\ndecryptWith:\n  - secretKey2\n  - secretKey3\n```\n\nAfter that (or at the same time -- it's safe to do it simultaneously) one need to replace encryption key with new one:\n\n```yaml\nencryptWith: secretKey3\ndecryptWith:\n  - secretKey2\n  - secretKey3\n```\n\nJust make sure that encryption key is always somewhere in the list of decryption keys.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvlsergey%2Fseccookie","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvlsergey%2Fseccookie","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvlsergey%2Fseccookie/lists"}