All Downloads are FREE. Search and download functionalities are using the official Maven repository.

io.jsonwebtoken.JweHeader Maven / Gradle / Ivy

Go to download 

/*
 * 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.AeadAlgorithm;
import io.jsonwebtoken.security.KeyAlgorithm;
import io.jsonwebtoken.security.PublicJwk;

import javax.crypto.SecretKey;
import java.security.Key;

/**
 * A JWE header.
 *
 * @since 0.12.0
 */
public interface JweHeader extends ProtectedHeader {

    /**
     * Returns the JWE {@code enc} (Encryption
     * Algorithm) header value or {@code null} if not present.
     *
     * 
The JWE {@code enc} (encryption algorithm) Header Parameter identifies the content encryption algorithm
     * used to perform authenticated encryption on the plaintext to produce the ciphertext and the JWE
     * {@code Authentication Tag}.

     *
     * 
Note that there is no corresponding 'setter' method for this 'getter' because JJWT users set this value by
     * supplying an {@link AeadAlgorithm} to a {@link JwtBuilder} via one of its
     * {@link JwtBuilder#encryptWith(SecretKey, AeadAlgorithm) encryptWith(SecretKey, AeadAlgorithm)} or
     * {@link JwtBuilder#encryptWith(Key, KeyAlgorithm, AeadAlgorithm) encryptWith(Key, KeyAlgorithm, AeadAlgorithm)}
     * methods. JJWT will then set this {@code enc} header value automatically to the {@code AeadAlgorithm}'s
     * {@link AeadAlgorithm#getId() getId()} value during encryption.

     *
     * @return the JWE {@code enc} (Encryption Algorithm) header value or {@code null} if not present.  This will
     * always be {@code non-null} on validly-constructed JWE instances, but could be {@code null} during construction.
     * @see JwtBuilder#encryptWith(SecretKey, AeadAlgorithm)
     * @see JwtBuilder#encryptWith(Key, KeyAlgorithm, AeadAlgorithm)
     */
    String getEncryptionAlgorithm();

    /**
     * Returns the {@code epk} (Ephemeral
     * Public Key) header value created by the JWE originator for use with key agreement algorithms, or
     * {@code null} if not present.
     *
     * 
Note that there is no corresponding 'setter' method for this 'getter' because JJWT users set this value by
     * supplying an ECDH-ES {@link KeyAlgorithm} to a {@link JwtBuilder} via its
     * {@link JwtBuilder#encryptWith(Key, KeyAlgorithm, AeadAlgorithm) encryptWith(Key, KeyAlgorithm, AeadAlgorithm)}
     * method. The ECDH-ES {@code KeyAlgorithm} implementation will then set this {@code epk} header value
     * automatically when producing the encryption key.

     *
     * @return the {@code epk} (Ephemeral
     * Public Key) header value created by the JWE originator for use with key agreement algorithms, or
     * {@code null} if not present.
     * @see Jwts.KEY
     * @see Jwts.KEY#ECDH_ES
     * @see Jwts.KEY#ECDH_ES_A128KW
     * @see Jwts.KEY#ECDH_ES_A192KW
     * @see Jwts.KEY#ECDH_ES_A256KW
     */
    PublicJwk getEphemeralPublicKey();

    /**
     * Returns any information about the JWE producer for use with key agreement algorithms, or {@code null} if not
     * present.
     *
     * @return any information about the JWE producer for use with key agreement algorithms, or {@code null} if not
     * present.
     * @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
     */
    byte[] getAgreementPartyUInfo();

    /**
     * Returns any information about the JWE recipient for use with key agreement algorithms, or {@code null} if not
     * present.
     *
     * @return any information about the JWE recipient for use with key agreement algorithms, or {@code null} if not
     * present.
     * @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
     */
    byte[] getAgreementPartyVInfo();

    /**
     * Returns the 96-bit "iv"
     * (Initialization Vector) generated during key encryption, or {@code null} if not present.
     * Set by AES GCM {@link io.jsonwebtoken.security.KeyAlgorithm KeyAlgorithm} implementations.
     *
     * 
Note that there is no corresponding 'setter' method for this 'getter' because JJWT users set this value by
     * supplying an AES GCM Wrap {@link KeyAlgorithm} to a {@link JwtBuilder} via its
     * {@link JwtBuilder#encryptWith(Key, KeyAlgorithm, AeadAlgorithm) encryptWith(Key, KeyAlgorithm, AeadAlgorithm)}
     * method. The AES GCM Wrap {@code KeyAlgorithm} implementation will then set this {@code iv} header value
     * automatically when producing the encryption key.

     *
     * @return the 96-bit initialization vector generated during key encryption, or {@code null} if not present.
     * @see Jwts.KEY#A128GCMKW
     * @see Jwts.KEY#A192GCMKW
     * @see Jwts.KEY#A256GCMKW
     */
    byte[] getInitializationVector();

    /**
     * Returns the 128-bit "tag"
     * (Authentication Tag) resulting from key encryption, or {@code null} if not present.
     *
     * 
Note that there is no corresponding 'setter' method for this 'getter' because JJWT users set this value by
     * supplying an AES GCM Wrap {@link KeyAlgorithm} to a {@link JwtBuilder} via its
     * {@link JwtBuilder#encryptWith(Key, KeyAlgorithm, AeadAlgorithm) encryptWith(Key, KeyAlgorithm, AeadAlgorithm)}
     * method. The AES GCM Wrap {@code KeyAlgorithm} implementation will then set this {@code tag} header value
     * automatically when producing the encryption key.

     *
     * @return the 128-bit authentication tag resulting from key encryption, or {@code null} if not present.
     * @see Jwts.KEY#A128GCMKW
     * @see Jwts.KEY#A192GCMKW
     * @see Jwts.KEY#A256GCMKW
     */
    byte[] getAuthenticationTag();

    /**
     * Returns the number of PBKDF2 iterations necessary to derive the key used during JWE encryption, or {@code null}
     * if not present. Used with password-based {@link io.jsonwebtoken.security.KeyAlgorithm KeyAlgorithm}s.
     *
     * @return the number of PBKDF2 iterations necessary to derive the key used during JWE encryption, or {@code null}
     * if not present.
     * @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
     */
    Integer getPbes2Count();

    /**
     * Returns the PBKDF2 {@code Salt Input} value necessary to derive the key used during JWE encryption, or
     * {@code null} if not present.
     *
     * 
Note that there is no corresponding 'setter' method for this 'getter' because JJWT users set this value by
     * supplying a password-based {@link KeyAlgorithm} to a {@link JwtBuilder} via its
     * {@link JwtBuilder#encryptWith(Key, KeyAlgorithm, AeadAlgorithm) encryptWith(Key, KeyAlgorithm, AeadAlgorithm)}
     * method. The password-based {@code KeyAlgorithm} implementation will then set this {@code p2s} header value
     * automatically when producing the encryption key.

     *
     * @return the PBKDF2 {@code Salt Input} value necessary to derive the key used during JWE encryption, or
     * {@code null} if not present.
     * @see JWE p2s (PBES2 Salt Input) Header Parameter
     * @see Jwts.KEY#PBES2_HS256_A128KW
     * @see Jwts.KEY#PBES2_HS384_A192KW
     * @see Jwts.KEY#PBES2_HS512_A256KW
     */
    byte[] getPbes2Salt();
}




© 2015 - 2024 Weber Informatics LLC | Privacy Policy