io.jsonwebtoken.security.MacAlgorithm Maven / Gradle / Ivy
/*
* Copyright © 2022 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 javax.crypto.SecretKey;
/**
* A {@link SecureDigestAlgorithm} that uses symmetric {@link SecretKey}s to both compute and verify digests as
* message authentication codes (MACs).
*
* Standard Identifier
*
* {@code MacAlgorithm} extends {@link Identifiable}: when a {@code MacAlgorithm} is used to compute the MAC of a
* JWS, the value returned from {@link Identifiable#getId() macAlgorithm.getId()} will be set as the JWS
* "alg" protected header value.
*
* Key Strength
*
* MAC algorithm strength is in part attributed to how difficult it is to discover the secret key.
* As such, MAC algorithms usually require keys of a minimum length to ensure the keys are difficult to discover
* and the algorithm's security properties are maintained.
*
* The {@code MacAlgorithm} interface extends the {@link KeyLengthSupplier} interface to represent
* the length in bits (not bytes) a key must have to be used with its implementation. If you do not want to
* worry about lengths and parameters of keys required for an algorithm, it is often easier to automatically generate
* a key that adheres to the algorithms requirements, as discussed below.
*
* Key Generation
*
* {@code MacAlgorithm} extends {@link KeyBuilderSupplier} to enable {@link SecretKey} generation.
* Each {@code MacAlgorithm} algorithm instance will return a {@link KeyBuilder} that ensures any created keys will
* have a sufficient length and any algorithm parameters required by that algorithm. For example:
*
*
* SecretKey key = macAlgorithm.key().build();
*
* The resulting {@code key} is guaranteed to have the correct algorithm parameters and strength/length necessary for
* that exact {@code MacAlgorithm} instance.
*
* JWA Standard Implementations
*
* Constant definitions and utility methods for all JWA (RFC 7518) standard MAC algorithms are
* available via {@link io.jsonwebtoken.Jwts.SIG Jwts.SIG}.
*
* @see io.jsonwebtoken.Jwts.SIG Jwts.SIG
* @since 0.12.0
*/
public interface MacAlgorithm extends SecureDigestAlgorithm,
KeyBuilderSupplier, KeyLengthSupplier {
}