io.jsonwebtoken.Header Maven / Gradle / Ivy
/*
* Copyright (C) 2014 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 java.util.Map;
/**
* A JWT JOSE header.
*
* This is an immutable JSON map with convenient type-safe getters for JWT standard header parameter names.
*
* Because this interface extends Map<String, Object>, you can use standard {@code Map}
* accessor/iterator methods as desired, for example:
*
*
* header.get("someKey");
*
* However, because {@code Header} instances are immutable, calling any of the map mutation methods
* (such as {@code Map.}{@link Map#put(Object, Object) put}, etc) will result in a runtime exception.
*
* Security
*
* The {@code Header} interface itself makes no implications of integrity protection via either digital signatures or
* encryption. Instead, {@link JwsHeader} and {@link JweHeader} represent this information for respective
* {@link Jws} and {@link Jwe} instances.
*
* @see ProtectedHeader
* @see JwsHeader
* @see JweHeader
* @since 0.1
*/
public interface Header extends Map {
/**
* JWT {@code Type} (typ) value: "JWT"
*
* @deprecated since 0.12.0 - this constant is never used within the JJWT codebase.
*/
@Deprecated
String JWT_TYPE = "JWT";
/**
* JWT {@code Type} header parameter name: "typ"
* @deprecated since 0.12.0 in favor of {@link #getType()}.
*/
@Deprecated
String TYPE = "typ";
/**
* JWT {@code Content Type} header parameter name: "cty"
* @deprecated since 0.12.0 in favor of {@link #getContentType()}.
*/
@Deprecated
String CONTENT_TYPE = "cty";
/**
* JWT {@code Algorithm} header parameter name: "alg".
*
* @see JWS Algorithm Header
* @see JWE Algorithm Header
* @deprecated since 0.12.0 in favor of {@link #getAlgorithm()}.
*/
@Deprecated
String ALGORITHM = "alg";
/**
* JWT {@code Compression Algorithm} header parameter name: "zip"
* @deprecated since 0.12.0 in favor of {@link #getCompressionAlgorithm()}
*/
@Deprecated
String COMPRESSION_ALGORITHM = "zip";
/**
* JJWT legacy/deprecated compression algorithm header parameter name: "calg"
*
* @deprecated use {@link #COMPRESSION_ALGORITHM} instead.
*/
@Deprecated
String DEPRECATED_COMPRESSION_ALGORITHM = "calg";
/**
* Returns the
* typ (Type) header value or {@code null} if not present.
*
* @return the {@code typ} header value or {@code null} if not present.
*/
String getType();
/**
* Returns the
* cty (Content Type) header value or {@code null} if not present.
*
* The cty (Content Type) Header Parameter is used by applications to declare the
* IANA MediaType of the content
* (the payload). This is intended for use by the application when more than
* one kind of object could be present in the Payload; the application can use this value to disambiguate among
* the different kinds of objects that might be present. It will typically not be used by applications when
* the kind of object is already known. This parameter is ignored by JWT implementations (like JJWT); any
* processing of this parameter is performed by the JWS application. Use of this Header Parameter is OPTIONAL.
*
* To keep messages compact in common situations, it is RECOMMENDED that producers omit an
* application/ prefix of a media type value in a {@code cty} Header Parameter when
* no other '/' appears in the media type value. A recipient using the media type value MUST
* treat it as if application/ were prepended to any {@code cty} value not containing a
* '/'. For instance, a {@code cty} value of example SHOULD be used to
* represent the application/example media type, whereas the media type
* application/example;part="1/2" cannot be shortened to
* example;part="1/2".
*
* @return the {@code typ} header parameter value or {@code null} if not present.
*/
String getContentType();
/**
* Returns the JWT {@code alg} (Algorithm) header value or {@code null} if not present.
*
*
* - If the JWT is a Signed JWT (a JWS), the
*
alg (Algorithm) header parameter identifies the cryptographic algorithm used to secure the
* JWS. Consider using {@link Jwts.SIG}.{@link io.jsonwebtoken.lang.Registry#get(Object) get(id)}
* to convert this string value to a type-safe {@code SecureDigestAlgorithm} instance.
* - If the JWT is an Encrypted JWT (a JWE), the
*
alg (Algorithm) header parameter
* identifies the cryptographic key management algorithm used to encrypt or determine the value of the Content
* Encryption Key (CEK). The encrypted content is not usable if the alg value does not represent a
* supported algorithm, or if the recipient does not have a key that can be used with that algorithm. Consider
* using {@link Jwts.KEY}.{@link io.jsonwebtoken.lang.Registry#get(Object) get(id)} to convert this string value
* to a type-safe {@link io.jsonwebtoken.security.KeyAlgorithm KeyAlgorithm} instance.
*
*
* @return the {@code alg} header value or {@code null} if not present. This will always be
* {@code non-null} on validly constructed JWT instances, but could be {@code null} during construction.
* @since 0.12.0
*/
String getAlgorithm();
/**
* Returns the JWT zip
* (Compression Algorithm) header parameter value or {@code null} if not present.
*
* Compatibility Note
*
* While the JWT family of specifications only defines the zip header in the JWE
* (JSON Web Encryption) specification, JJWT will also support compression for JWS as well if you choose to use it.
* However, be aware that if you use compression when creating a JWS token, other libraries may not be able to
* parse the JWS. However, compression when creating JWE tokens should be universally accepted for any library
* that supports JWE.
*
* @return the {@code zip} header parameter value or {@code null} if not present.
* @since 0.6.0
*/
String getCompressionAlgorithm();
}