{"id":22867867,"url":"https://github.com/osmerion/onetrickpony","last_synced_at":"2025-05-05T19:21:36.386Z","repository":{"id":65802195,"uuid":"593679866","full_name":"Osmerion/OneTrickPony","owner":"Osmerion","description":"OneTrickPony is a modern Java library that implements support for One-Time Passwords. Built-In support is provided for the HOTP (RFC 4226) and TOTP (RFC 6238) algorithms.","archived":false,"fork":false,"pushed_at":"2024-12-02T19:38:00.000Z","size":282,"stargazers_count":59,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-02T20:29:36.706Z","etag":null,"topics":["hotp","java","one-time-password","otp","totp"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Osmerion.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":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-26T15:48:04.000Z","updated_at":"2024-12-02T19:38:03.000Z","dependencies_parsed_at":"2024-09-12T21:04:42.634Z","dependency_job_id":"e4688092-d5be-40d7-82ab-76d3564b827c","html_url":"https://github.com/Osmerion/OneTrickPony","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/Osmerion%2FOneTrickPony","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Osmerion%2FOneTrickPony/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Osmerion%2FOneTrickPony/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Osmerion%2FOneTrickPony/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Osmerion","download_url":"https://codeload.github.com/Osmerion/OneTrickPony/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229541941,"owners_count":18089391,"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":["hotp","java","one-time-password","otp","totp"],"created_at":"2024-12-13T12:29:10.143Z","updated_at":"2024-12-13T12:29:10.743Z","avatar_url":"https://github.com/Osmerion.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OneTrickPony \n\n[![License](https://img.shields.io/badge/license-BSD-blue.svg?style=for-the-badge\u0026label=License)](https://github.com/Osmerion/OneTrickPony/blob/master/LICENSE)\n[![Maven Central](https://img.shields.io/maven-central/v/com.osmerion.onetrickpony/onetrickpony.svg?style=for-the-badge\u0026label=Maven%20Central)](https://maven-badges.herokuapp.com/maven-central/com.osmerion.onetrickpony/onetrickpony)\n[![JavaDoc](https://img.shields.io/maven-central/v/com.osmerion.onetrickpony/onetrickpony.svg?style=for-the-badge\u0026label=JavaDoc\u0026color=blue)](https://javadoc.io/doc/com.osmerion.onetrickpony/onetrickpony)\n![Java](https://img.shields.io/badge/Java-11-green.svg?style=for-the-badge\u0026color=b07219\u0026logo=java)\n\nOneTrickPony is a modern Java library that implements support for One-Time\nPasswords (OTPs). The library requires Java 11 or later and is fully compatible\nwith Java's module system. It has zero runtime dependencies on external\nlibraries. Built-In support is provided for the HOTP ([RFC\u0026nbsp;4226](https://www.rfc-editor.org/rfc/rfc4226))\nand TOTP ([RFC\u0026nbsp;6238](https://www.rfc-editor.org/rfc/rfc6238)) algorithms.\n\n\n## Getting Started\n\nOneTrickPony provides support for OTPs via so-called _engines_.\nThe following engines are provided by the library.\n\n### HMAC-based One-Time Passwords (HOTPs)\n\nThe `HOTPEngine` provides support for HOTPs as specified by RFC\u0026nbsp;4226.\n\n```java\nHOTPEngine engine = HOTPEngine.builder()\n    .withChecksum(false)\n    .withCodeDigits(6)\n    .withMacAlgorithm(\"HmacSHA1\")\n    .withTruncationOffset(HOTPEngine.USE_DYNAMIC_TRUNCATION)\n    .build();\n\nbyte[] secret = \"12345678901234567890\".getBytes(StandardCharsets.UTF_8);\nint counter = 0;\n\nString otp = engine.generate(secret, counter);\nSystem.out.println(otp); // 755224\n```\n\nThe engine's properties can be configured through a builder. All properties are\ninitialized with reasonable defaults that are sufficient for most use-cases.\n\n| Property          |                                                                                            | Default                  |\n|-------------------|--------------------------------------------------------------------------------------------|--------------------------|\n| Checksum          | Whether to add an additional checksum digit to the OTP                                     | `false`                  |\n| Code digits       | The number of code digits of the OTP                                                       | `6`                      |\n| MAC algorithm     | The MAC algorithm to use to generate the hash for the OTP                                  | `HmacSHA1`               |\n| Truncation offset | The offset that will be used to extract the bytes used for the OTP from the generated hash | `USE_DYNAMIC_TRUNCATION` |\n\nThe MAC algorithm is used to retrieve a [javax.crypto.Mac](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/javax/crypto/Mac.html)\ninstance. Check the documentation of your Java distribution for a list of\nsupported algorithms.\n\n\n### Time-based One-Time Passwords (TOTPs)\n\nThe `TOTPEngine` provides support for TOTPs as specified by RFC\u0026nbsp;6238.\n\n```java\nTOTPEngine engine = TOTPEngine.builder()\n    .configureHOTPEngine(hotpBuilder -\u003e {\n        // Use the builder to configure the underlying HOTPEngine\n    })\n    .withTimeStep(Duration.ofSeconds(30))\n    .build();\n\nbyte[] secret = \"12345678901234567890\".getBytes(StandardCharsets.UTF_8);\nInstant time = Instant.parse(\"1970-01-01T00:00:59.00Z\");\n\nString otp = engine.generate(secret, time);\nSystem.out.println(otp); // 287082\n```\n\nThis engine uses an underlying `HOTPEngine` to generate the OTP. Both, the\nengine itself and the underlying engine can be configured through a builder.\n\nThe engine has a single additional property to configure the time step for the\ngenerated OTPs. It defaults to a time step of 30\u0026nbsp;seconds.\n\n\n### Bonus: The Base32 Encoding Scheme\n\nAs secrets for OTPs are commonly shared using the Base32 encoding scheme,\nOneTrickPony also provides a `Base32` class analogous to Java's\n`java.util.Base64` class. This class implements support for Base32 en- and\ndecoding as specified by [RFC\u0026nbsp;6238](https://www.rfc-editor.org/rfc/rfc4648).\n\n```java\n// Retrieve reusable en- and decoder instances\nBase32.Encoder encoder = Base32.getEncoder();\nBase32.Decoder decoder = Base32.getDecoder();\n\n// Encoding\nbyte[] base32Data = encoder.encode(\"foobar\".getBytes(StandardCharset.UTF_8));\nSystem.out.println(new String(base32Data, StandardCharsets.UTF_8)); // MZXW6YTBOI======\n\n// Decoding\nbyte[] decodedData = decoder.decode(base32Data);\nSystem.out.println(new String(decodedData, StandardCharsets.UTF_8)); // foobar\n```\n\n\n## Building from source\n\n### Setup\n\nThis project uses [Gradle's toolchain support](https://docs.gradle.org/current/userguide/toolchains.html)\nto detect and select the JDKs required to run the build. Please refer to the\nbuild scripts to find out which toolchains are requested.\n\nAn installed JDK 1.8 (or later) is required to use Gradle.\n\n### Building\n\nOnce the setup is complete, invoke the respective Gradle tasks using the\nfollowing command on Unix/macOS:\n\n    ./gradlew \u003ctasks\u003e\n\nor the following command on Windows:\n\n    gradlew \u003ctasks\u003e\n\nImportant Gradle tasks to remember are:\n- `clean`                   - clean build results\n- `build`                   - assemble and test the Java library\n- `publishToMavenLocal`     - build and install all public artifacts to the\n                              local maven repository\n\nAdditionally `tasks` may be used to print a list of all available tasks.\n\n\n## License\n\nOneTrickPony is available under the terms of the [3-Clause BSD license](https://spdx.org/licenses/BSD-3-Clause.html).\n\n```\nCopyright (c) 2023-2024 Leon Linhart,\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without\nmodification, are permitted provided that the following conditions are met:\n\n1. Redistributions of source code must retain the above copyright notice,\n   this list of conditions and the following disclaimer.\n\n2. Redistributions in binary form must reproduce the above copyright notice,\n   this list of conditions and the following disclaimer in the documentation\n   and/or other materials provided with the distribution.\n\n3. Neither the name of the copyright holder nor the names of its contributors\n   may be used to endorse or promote products derived from this software\n   without specific prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\"\nAND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\nIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE\nARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE\nLIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR\nCONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF\nSUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS\nINTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN\nCONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)\nARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE\nPOSSIBILITY OF SUCH DAMAGE.\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosmerion%2Fonetrickpony","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fosmerion%2Fonetrickpony","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosmerion%2Fonetrickpony/lists"}