Package org.forgerock.macaroons

Class MacaroonVerifier

  • public final class MacaroonVerifier
extends Object
    A macaroon verifier is used to verify the caveats on a Macaroon. To verify a macaroon, create a fresh MacaroonVerifier object and call the various verifier.satisfyXXX(...) methods to satisfy caveats. Finally, call the Macaroon.verify(Key, MacaroonVerifier) method passing in the macaroon key and the verify object to check the macaroon signature and verify all caveats are satisfied: 
    
     Macaroon macaroon = ...;
     MacaroonVerifier verifier = new MacaroonVerifier(secretsProvider, purpose)
         .satisfyExact("account = 123456")
         .satisfyExpiryTime(Clock.systemUTC());
     VerifierResult result = verifier.verify(macaroon).getOrThrow();
     if (result.isValid()) {
         // Signature is ok and all caveats are satisfied
     } else {
         if (!result.isSignatureValid()) {
             ...
         }
         Set<Caveat> unsatisfied = result.getUnsatisfiedCaveats();
     }
    You can use the general satisfy(CaveatVerifier) method to satisfy arbitrary 1st-party caveats. A caveat is satisfied if any caveat verifier returns true for that caveat.

    Third-party caveats can be satisfied by using the satisfyThirdParty(Macaroon) method and passing in the discharge macaroon received from the third-party service. Discharge macaroons are recursively verified to ensure that all caveats on the discharge are also satisfied.

    A macaroon verifier is not thread-safe and is intended to be created fresh for each macaroon that needs to be verified.

    Naming conventions

    Methods of the form verifyXXX(...) are intended for verifying that macaroons and caveats are satisfied. Methods named in the form satisfyXXX(...) are intended for the caller to provide evidence that will be used to satisfy caveats. This naming convention is inherited from libmacaroons.

    • Constructor Detail

      • MacaroonVerifier

        public MacaroonVerifier​(SecretsProvider secretsProvider,
                        Purpose<VerificationKey> purpose)
        Constructs the macaroon verifier with the given source of verification keys.
        Parameters:
        secretsProvider - the secrets provider to use to look up verification keys.
        purpose - the purpose for verification keys.

    • Method Detail

      • maxCaveats

        public MacaroonVerifier maxCaveats​(int maxCaveats)
        Sets the maximum number of caveats that can be verified before the verifier rejects a macaroon as invalid. This is used to prevent a denial-of-service attack if an attacker submits a macaroon with a very large number of caveats. The maximum value includes caveats from any discharge macaroons. The default maximum is 30.
        Parameters:
        maxCaveats - the maximum number of caveats to allow.
        Returns:
        this

      • satisfyExact

        public MacaroonVerifier satisfyExact​(String exactString)
        Satisfies any 1st-party caveat whose identifier exactly matches the given string. Differences in whitespace are ignored.
        Parameters:
        exactString - the exact string to match.
        Returns:
        this verifier.

      • satisfyPattern

        public MacaroonVerifier satisfyPattern​(String regex)
        Satisfies any 1st-party caveat that matches the given regular expression. Care should be taken to avoid ReDoS attacks when using regular expressions.
        Parameters:
        regex - the regular expression.
        Returns:
        this verifier.

      • satisfyPattern

        public MacaroonVerifier satisfyPattern​(Pattern pattern)
        Satisfies any 1st-party caveat that matches the given regular expression. Care should be taken to avoid ReDoS attacks when using regular expressions.
        Parameters:
        pattern - the regular expression.
        Returns:
        this verifier.

      • satisfyExpiryTime

        public MacaroonVerifier satisfyExpiryTime​(Instant timeOfUse,
                                          Duration allowedClockSkew)
        Satisfies expiry time caveats of the form time < 2020-01-01T09:32:27Z.
        Parameters:
        timeOfUse - the time at which the macaroon is being used.
        allowedClockSkew - the amount of time to allow for clock skew when comparing times.
        Returns:
        this verifier.

      • satisfyExpiryTime

        public MacaroonVerifier satisfyExpiryTime​(Instant timeOfUse)
        Satisfies expiry time caveats of the form time < 2020-01-01T09:32:27Z. No clock skew is allowed.
        Parameters:
        timeOfUse - the time at which the macaroon is being used.
        Returns:
        this verifier.

      • satisfy

        public MacaroonVerifier satisfy​(CaveatVerifier verifier)
        Satisfies a general 1st-party caveat with the given verifier.
        Parameters:
        verifier - the caveat verifier.
        Returns:
        this verifier.

      • withJsonCaveatVerifier

        public JsonCaveatVerifier withJsonCaveatVerifier()
        Enables support for verifying JSON-formatted caveats and returns a JsonCaveatVerifier that can be used to satisfy such caveats.
        Returns:
        a JsonCaveatVerifier that can be configured to check JSON-formatted 1st-party caveats.

      • satisfyThirdParty

        public MacaroonVerifier satisfyThirdParty​(Macaroon dischargeMacaroon)
        Satisfies a 3rd-party caveat using the given discharge macaroon. Any caveats attached to the discharge macaroon will be recursively verified. It is assumed that the discharge macaroon has been bound to the main authorizing macaroon using the Macaroon.prepareForRequest(Macaroon...) method prior to being sent over the network.
        Parameters:
        dischargeMacaroon - the discharge macaroon.
        Returns:
        this verifier.
        Throws:
        ArithmeticException - if the total number of caveats in all added discharge macaroons exceeds Integer.MAX_VALUE.

      • satisfyThirdParty

        public MacaroonVerifier satisfyThirdParty​(Iterable<Macaroon> dischargeMacaroons)
        Satisfies one or more 3rd-party caveats using the given discharge macaroons. Any caveats attached to the discharge macaroons will be recursively verified.
        Parameters:
        dischargeMacaroons - the discharge macaroons.
        Returns:
        this verifier.
        Throws:
        ArithmeticException - if the total number of caveats in all added discharge macaroons exceeds Integer.MAX_VALUE.

      • verify

        public Promise<MacaroonVerifierResult,​RejectedMacaroonException> verify​(Macaroon macaroon)
        Verifies the given macaroon using any valid verification key and testing to see that all caveats are satisfied. Any discharge macaroons for 3rd-party caveats are recursively verified.
        Parameters:
        macaroon - the macaroon to verify.
        Returns:
        a promise for the verification result or a RejectedMacaroonException if the macaroon was rejected due to having too many caveats or some other reason unrelated to its validity.