io.jsonwebtoken.security.KeyOperationPolicyBuilder Maven / Gradle / Ivy

/*
 * Copyright © 2023 jsonwebtoken.io
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package io.jsonwebtoken.security;

import io.jsonwebtoken.Identifiable;
import io.jsonwebtoken.lang.Builder;
import io.jsonwebtoken.lang.CollectionMutator;

import java.util.Collection;


/**
 * A {@code KeyOperationPolicyBuilder} produces a {@link KeyOperationPolicy} that determines
 * which {@link KeyOperation}s may be assigned to a JWK. Custom {@code KeyOperation}s (such as those created by a
 * {@link Jwks.OP#builder()}) may be added to a policy via the {@link #add(KeyOperation)} or {@link #add(Collection)}
 * methods.
 *
 * @see Jwks.OP#policy()
 * @see JwkBuilder#operationPolicy(KeyOperationPolicy)
 * @see Jwks.OP#builder()
 * @since 0.12.0
 */
public interface KeyOperationPolicyBuilder extends CollectionMutator,
        Builder {

    /**
     * Allows a JWK to have unrelated {@link KeyOperation}s in its {@code key_ops} parameter values. Be careful
     * when calling this method - one should fully understand the security implications of using the same key
     * with multiple algorithms in your application.
     * If this method is not called, unrelated key operations are disabled by default per the recommendations in
     * RFC 7517, Section 4.3:
     *      * Multiple unrelated key operations SHOULD NOT be specified for a key
     * because of the potential vulnerabilities associated with using the
     * same key with multiple algorithms.
     *
     * @return the builder for method chaining
     * @see "key_ops" (Key Operations)
     * Parameter
     */
    KeyOperationPolicyBuilder unrelated();

    /**
     * Adds the specified key operation to the policy's total set of supported key operations
     * used to validate a key's intended usage, replacing any existing one with an identical (CaSe-SeNsItIvE)
     * {@link Identifiable#getId() id}.
     *
     * Standard {@code KeyOperation}s and Overrides
     *
     * The RFC standard {@link Jwks.OP} key operations are supported by default and do not need
     * to be added via this method, but beware: If the {@code op} argument has a JWK standard
     * {@link Identifiable#getId() id}, it will replace the JJWT standard operation implementation.
     * This is to allow application developers to favor their own implementations over JJWT's default implementations
     * if necessary (for example, to support legacy or custom behavior).
     *
     * If a custom {@code KeyOperation} is desired, one may be easily created with a {@link Jwks.OP#builder()}.
     *
     * @param op a key operation to add to the policy's total set of supported operations, replacing any
     *           existing one with the same exact (CaSe-SeNsItIvE) {@link KeyOperation#getId() id}.
     * @return the builder for method chaining.
     * @see Jwks.OP
     * @see Jwks.OP#builder()
     * @see JwkBuilder#operationPolicy(KeyOperationPolicy)
     * @see JwkBuilder#operations()
     */
    @Override
    // for better JavaDoc
    KeyOperationPolicyBuilder add(KeyOperation op);

    /**
     * Adds the specified key operations to the policy's total set of supported key operations
     * used to validate a key's intended usage, replacing any existing ones with identical
     * {@link Identifiable#getId() id}s.
     *
     * There may be only one registered {@code KeyOperation} per CaSe-SeNsItIvE {@code id}, and the
     * {@code ops} collection is added in iteration order; if a duplicate id is found when iterating the {@code ops}
     * collection, the later operation will evict any existing operation with the same {@code id}.
     *
     * Standard {@code KeyOperation}s and Overrides
     *
     * The RFC standard {@link Jwks.OP} key operations are supported by default and do not need
     * to be added via this method, but beware: any operation in the {@code ops} argument with a
     * JWK standard {@link Identifiable#getId() id} will replace the JJWT standard operation implementation.
     * This is to allow application developers to favor their own implementations over JJWT's default implementations
     * if necessary (for example, to support legacy or custom behavior).
     *
     * If custom {@code KeyOperation}s are desired, they may be easily created with a {@link Jwks.OP#builder()}.
     *
     * @param ops collection of key operations to add to the policy's total set of supported operations, replacing any
     *            existing ones with the same exact (CaSe-SeNsItIvE) {@link KeyOperation#getId() id}s.
     * @return the builder for method chaining.
     * @see Jwks.OP
     * @see Jwks.OP#builder()
     * @see JwkBuilder#operationPolicy(KeyOperationPolicy)
     * @see JwkBuilder#operations()
     */
    @Override
    // for better JavaDoc
    KeyOperationPolicyBuilder add(Collection ops);

}