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();
}