<img src="/docs/jpaseto-logo.png" align="right" height="100px"/>

JPaseto - Paseto Library for Java

JPaseto aims to be the easiest to use and understand library for creating and verifying Paseto tokens on the JVM.

JPaseto is a Java implementation based exclusively on the Paseto specification. And is a direct port of JJWT, if you are using JWTs check out that library.

We've also added some convenience extensions that are not yet part of the specification, such as validation of the registered date claims.

The goal of this project is to provide a pure Java implementation of the Paseto specification.

Table of Contents

• Features
  • Differences Between Other Java Paseto Implementations
• Community
  • Getting Help
    • Questions
    • Bugs and Feature Requests
  • Contributing
    • Pull Requests
    • Help Wanted
• What is a Paseto Token?
• Installation
  • JDK Projects
    • Maven
    • Gradle
    • Sodium native library
    • Paseto Format Support
  • Understanding JPaseto Dependencies
• Quickstart
• Keys and Secrets
  • Creating Safe Keys
    • Secret Keys
    • Asymetric Keys
  • Create a Paseto Token
    • Footer
    • Claims
      • Standard Claims
      • Custom Claims
  • Read a Paseto Token
    • Verification Key
      • Find the Verification Key at Runtime
    • Claims Assertions
    • Accounting for Clock Skew
      • Custom Clock
• JSON Processor
  • Custom JSON Processor
  • Parsing of Custom Claim Types
• Learn More
• License

<a name="features"></a>

Features

• Fully functional on all JDKs 1.8+
• Automatic security best practices and assertions
• Easy to learn and read API
• Convenient and readable fluent interfaces, great for IDE auto-completion to write code quickly
• Fully RFC-draft specification compliant on all implemented functionality, tested against RFC-specified test vectors
• Convenience enhancements beyond the specification such as
  • Claims assertions (requiring specific values)
  • Claim POJO marshaling and unmarshaling when using a compatible JSON parser (e.g. Jackson)
  • and more...

<a name="other-options"></a>

Differences Between Other Java Paseto Implementations

Why choose this library over the other Java Paseto implementations?

• Fluent API
• Full security audited performed by Paragon Initiative Enterprises
• Available on Maven Central
• Low dependency count
• Already using JJWT, this library works the same way

<a name="community"></a>

Community

<a name="help"></a>

Getting Help

If you have trouble using JPaseto, please first read the documentation on this page before asking questions. We try very hard to ensure JPaseto's documentation is robust, categorized with a table of contents, and up to date for each release.

<a name="help-questions"></a>

Questions

If the documentation or the API JavaDoc isn't sufficient, and you either have usability questions or are confused about something, please ask your question here.

If you believe you have found a bug or would like to suggest a feature enhancement, please create a new GitHub issue, however:

Please do not create a GitHub issue to ask a question.

We use GitHub Issues to track actionable work that requires changes to JPaseto's design and/or codebase. If you have a usability question, instead please ask your question here.

<a name="help-issues"></a>

Bugs and Feature Requests

If you do not have a usability question and believe you have a legitimate bug or feature request, please do create a new JPaseto issue.

If you feel like you'd like to help fix a bug or implement the new feature yourself, please read the Contributing section next before starting any work.

<a name="contributing"></a>

Contributing

<a name="contributing-pull-requests"></a>

Pull Requests

Simple Pull Requests that fix anything other than JPaseto core code (documentation, JavaDoc, typos, test cases, etc) are always appreciated and have a high likelihood of being merged quickly. Please send them!

However, if you want or feel the need to change JPaseto's functionality or core code, please do not issue a pull request without creating a new JPaseto issue and discussing your desired changes first, before you start working on it.

It would be a shame to reject your earnest and genuinely appreciated pull request if it might not not align with the project's goals, design expectations or planned functionality.

So, please create a new JPaseto issue first to discuss, and then we can see if (or how) a PR is warranted. Thank you!

<a name="contributing-help-wanted"></a>

Help Wanted

If you would like to help, but don't know where to start, please visit the Help Wanted Issues page and pick any of the ones there, and we'll be happy to discuss and answer questions in the issue comments.

If any of those don't appeal to you, no worries! Any help you would like to offer would be appreciated based on the above caveats concerning contributing pull reqeuests. Feel free to discuss or ask questions first if you're not sure. :)

<a name="overview"></a>

What is a Paseto Token?

Don't know what a Paseto Token is? Read on. Otherwise, jump on down to the Installation section.

Paseto is a means of transmitting information between two parties in a compact, verifiable form.

The bits of information encoded in the body of a Paseto token are called claims. The expanded form of the Paseto is in a JSON format, so each claim is a key in the JSON object.

Paseto can be cryptographically signed ("public" tokens) or encrypted with a shared secret ("local" tokens).

This adds a powerful layer of verifiability to the user of Paseto tokens. The receiver has a high degree of confidence that the Paseto token has not been tampered with by verifying the signature, for instance.

The compact representation of a signed Paseto token is a string that has three or four parts, each separated by a .:

version.purpose.payload.footer

the footer is optional

The version is a string that represents the current version of the protocol. Currently, two versions are specified, which each possess their own ciphersuites. Accepted values: v1, v2.

The purpose is a short string describing the purpose of the token. Accepted values: local, public.

• local: shared-key authenticated encryption

• public: public-key digital signatures; not encrypted Any optional data can be appended to the end. This information is NOT encrypted, but it is used in calculating the authentication tag for the payload. It's always base64url-encoded.

• For local tokens, it's included in the associated data alongside the nonce.

• For public tokens, it's appended to the message during the actual authentication/signing step, in accordance to our standard format. Thus, if you want unencrypted, but authenticated, tokens, you can simply set your payload to an empty string and your footer to the message you want to authenticate.

Conversely, if you want to support key rotation, you can use the unencrypted footer to store the kid claim.

There are a number of standard claims, called Registered Claims, see section 6.1 in the specification and sub (for subject) is one of them.

To compute the signature, you need a secret key to sign it. We'll cover keys later.

<a name="install"></a>

Installation

Use your favorite Maven-compatible build tool to pull the dependencies from Maven Central.

The dependencies could differ slightly if you are working with a JDK project.

<a name="install-jdk"></a>

JDK Projects

If you're building a (non-Android) JDK project, you will want to define the following dependencies:

<a name="install-jdk-maven"></a>

Maven

<dependency>
    <groupId>dev.paseto</groupId>
    <artifactId>jpaseto-api</artifactId>
    <version>0.6.0</version>
</dependency>
<dependency>
    <groupId>dev.paseto</groupId>
    <artifactId>jpaseto-impl</artifactId>
    <version>0.6.0</version>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>dev.paseto</groupId>
    <artifactId>jpaseto-jackson</artifactId>
    <version>0.6.0</version>
    <scope>runtime</scope>
</dependency>
<!-- Uncomment the next lines if you want to use Boun