io.jsonwebtoken.JweHeaderMutator Maven / Gradle / Ivy

/*
 * Copyright (C) 2021 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;

import io.jsonwebtoken.security.KeyAlgorithm;

/**
 * Mutation (modifications) to a {@link JweHeader} instance.
 *
 * @param  the mutator subtype, for method chaining
 * @since 0.12.0
 */
public interface JweHeaderMutator> extends ProtectedHeaderMutator {

    /**
     * Sets any information about the JWE producer for use with key agreement algorithms. A {@code null} or empty value
     * removes the property from the JSON map.
     *
     * @param info information about the JWE producer to use with key agreement algorithms.
     * @return the header for method chaining.
     * @see JWE apu (Agreement PartyUInfo) Header Parameter
     * @see Jwts.KEY#ECDH_ES
     * @see Jwts.KEY#ECDH_ES_A128KW
     * @see Jwts.KEY#ECDH_ES_A192KW
     * @see Jwts.KEY#ECDH_ES_A256KW
     */
    T agreementPartyUInfo(byte[] info);

    /**
     * Sets any information about the JWE producer for use with key agreement algorithms. A {@code null} value removes
     * the property from the JSON map.
     *
     * If not {@code null}, this is a convenience method that calls the equivalent of the following:
     *      * {@link #agreementPartyUInfo(byte[]) agreementPartyUInfo}(info.getBytes(StandardCharsets.UTF_8))
     *
     * @param info information about the JWE producer to use with key agreement algorithms.
     * @return the header for method chaining.
     * @see JWE apu (Agreement PartyUInfo) Header Parameter
     * @see Jwts.KEY#ECDH_ES
     * @see Jwts.KEY#ECDH_ES_A128KW
     * @see Jwts.KEY#ECDH_ES_A192KW
     * @see Jwts.KEY#ECDH_ES_A256KW
     */
    T agreementPartyUInfo(String info);

    /**
     * Sets any information about the JWE recipient for use with key agreement algorithms. A {@code null} value removes
     * the property from the JSON map.
     *
     * @param info information about the JWE recipient to use with key agreement algorithms.
     * @return the header for method chaining.
     * @see JWE apv (Agreement PartyVInfo) Header Parameter
     * @see Jwts.KEY#ECDH_ES
     * @see Jwts.KEY#ECDH_ES_A128KW
     * @see Jwts.KEY#ECDH_ES_A192KW
     * @see Jwts.KEY#ECDH_ES_A256KW
     */
    T agreementPartyVInfo(byte[] info);

    /**
     * Sets any information about the JWE recipient for use with key agreement algorithms. A {@code null} value removes
     * the property from the JSON map.
     *
     * If not {@code null}, this is a convenience method that calls the equivalent of the following:
     *      * {@link #agreementPartyVInfo(byte[]) setAgreementPartVUInfo}(info.getBytes(StandardCharsets.UTF_8))
     *
     * @param info information about the JWE recipient to use with key agreement algorithms.
     * @return the header for method chaining.
     * @see JWE apv (Agreement PartyVInfo) Header Parameter
     * @see Jwts.KEY#ECDH_ES
     * @see Jwts.KEY#ECDH_ES_A128KW
     * @see Jwts.KEY#ECDH_ES_A192KW
     * @see Jwts.KEY#ECDH_ES_A256KW
     */
    T agreementPartyVInfo(String info);

    /**
     * Sets the number of PBKDF2 iterations necessary to derive the key used during JWE encryption. If this value
     * is not set when a password-based {@link KeyAlgorithm} is used, JJWT will automatically choose a suitable
     * number of iterations based on
     * OWASP PBKDF2 Iteration Recommendations.
     *
     * Minimum Count
     *
     * {@code IllegalArgumentException} will be thrown during encryption if a specified {@code count} is
     * less than 1000 (one thousand), which is the
     * minimum number recommended by the
     * JWA specification. Anything less is susceptible to security attacks so the default PBKDF2
     * {@code KeyAlgorithm} implementations reject such values.
     *
     * @param count the number of PBKDF2 iterations necessary to derive the key used during JWE encryption, must be
     *              greater than or equal to 1000 (one thousand).
     * @return the header for method chaining
     * @see JWE p2c (PBES2 Count) Header Parameter
     * @see Jwts.KEY#PBES2_HS256_A128KW
     * @see Jwts.KEY#PBES2_HS384_A192KW
     * @see Jwts.KEY#PBES2_HS512_A256KW
     * @see OWASP PBKDF2 Iteration Recommendations
     */
    T pbes2Count(int count);
}