README.md

Macaroon

Setup

Add the latest Macaroon version to your project:

Using Gradle:

implementation("com.lapanthere:macaroon:0.1")

Using Maven:

<dependency>
    <groupId>com.lapanthere</groupId>
    <artifactId>macaroon</artifactId>
    <version>0.1</version>
</dependency>

Getting started

To start, you'll need to generate a secret key:

val key = generateSecretKey()

var key = Keys.generateSecretKey()

Or using a public/private key setup:

val privateKey = generatePrivateKey()
val publicKey = generatePublicKey()
val key = sharedSecret(publicKey, privateKey)

var privateKey = Keys.generatePrivateKey();
var publicKey = Keys.generatePublicKey();
var key = Keys.sharedSecret(publicKey,privateKey);

Once you have a secret key, you can now build a macaroon:

val macaroon = buildMacaroon(location = "macaroon/kotlin", identifier = "kotlinUsage", key) {
    require("account = 1234")
    require(field("actions") containsAll listOf("read", "write"))
    require(field("time") lt Instant.now().plusSeconds(60))
}

var macaroon = new Macaroon.Builder("macaroon/java", "javaUsage", key)
    .require("account = 1234")
    .require(field("time").lessThan(Instant.now().plusSeconds(60))
    .require(field("actions").containsAll(List.of("read","write")))
    .build();

You can then verify said macaroon:

val verifier = buildVerifier(macaroon) {
    satisfy("account = 1234")
    satisfy { caveat -> caveat.isFirstParty }
    satisfy("actions", "read", "write")
    satisfy("time", Instant.now())
}
verifier.isValid(key)

var verifier = new Verifier.Builder(macaroon)
    .satisfy("account = 1234")
    .satisfy(Caveat::isFirstParty)
    .satisfy("admin", true)
    .satisfy("actions", List.of("read"), String.class)
    .build();
verifier.isValid(key);

To de/serialize a macaroon (using the v2 format):

val serialized = macaroon.serialize()
val macaroon = Macaroon(serialized)

var serialized = macaroon.serialize();
var macaroon = Macaroon.from(serialized);