acscommons.io.jsonwebtoken.JwsHeader Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of acs-aem-commons-bundle Show documentation
Main ACS AEM Commons OSGi Bundle. Includes commons utilities.
There is a newer version: 6.9.4
Show newest version
/*
 * 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 acscommons.io.jsonwebtoken;

/**
 * A JWS header.
 *
 * @param  header type
 * @since 0.1
 */
public interface JwsHeader> extends Header {

    /** JWS {@code Algorithm} header parameter name: "alg" */
    public static final String ALGORITHM = "alg";

    /** JWS {@code JWT Set URL} header parameter name: "jku" */
    public static final String JWK_SET_URL = "jku";

    /** JWS {@code JSON Web Key} header parameter name: "jwk" */
    public static final String JSON_WEB_KEY = "jwk";

    /** JWS {@code Key ID} header parameter name: "kid" */
    public static final String KEY_ID = "kid";

    /** JWS {@code X.509 URL} header parameter name: "x5u" */
    public static final String X509_URL = "x5u";

    /** JWS {@code X.509 Certificate Chain} header parameter name: "x5c" */
    public static final String X509_CERT_CHAIN = "x5c";

    /** JWS {@code X.509 Certificate SHA-1 Thumbprint} header parameter name: "x5t" */
    public static final String X509_CERT_SHA1_THUMBPRINT = "x5t";

    /** JWS {@code X.509 Certificate SHA-256 Thumbprint} header parameter name: "x5t#S256" */
    public static final String X509_CERT_SHA256_THUMBPRINT = "x5t#S256";

    /** JWS {@code Critical} header parameter name: "crit" */
    public static final String CRITICAL = "crit";

    /**
     * Returns the JWS 
     * alg (algorithm) header value or {@code null} if not present.
     *
     * The algorithm header parameter identifies the cryptographic algorithm used to secure the JWS.  Consider
     * using {@link acscommons.io.jsonwebtoken.SignatureAlgorithm#forName(String) SignatureAlgorithm.forName} to convert this
     * string value to a type-safe enum instance.
     *
     * @return the JWS {@code alg} header value or {@code null} if not present.  This will always be
     * {@code non-null} on validly constructed JWS instances, but could be {@code null} during construction.
     */
    String getAlgorithm();

    /**
     * Sets the JWT 
     * alg (Algorithm) header value.  A {@code null} value will remove the property from the JSON map.
     *
     * The algorithm header parameter identifies the cryptographic algorithm used to secure the JWS.  Consider
     * using a type-safe {@link acscommons.io.jsonwebtoken.SignatureAlgorithm SignatureAlgorithm} instance and using its
     * {@link acscommons.io.jsonwebtoken.SignatureAlgorithm#getValue() value} as the argument to this method.
     *
     * @param alg the JWS {@code alg} header value or {@code null} to remove the property from the JSON map.
     * @return the {@code Header} instance for method chaining.
     */
    T setAlgorithm(String alg);

    /**
     * Returns the JWS 
     * kid (Key ID) header value or {@code null} if not present.
     *
     * The keyId header parameter is a hint indicating which key was used to secure the JWS.  This parameter allows
     * originators to explicitly signal a change of key to recipients.  The structure of the keyId value is
     * unspecified.
     *
     * When used with a JWK, the keyId value is used to match a JWK {@code keyId} parameter value.
     *
     * @return the JWS {@code kid} header value or {@code null} if not present.
     */
    String getKeyId();

    /**
     * Sets the JWT 
     * kid (Key ID) header value.  A {@code null} value will remove the property from the JSON map.
     *
     * The keyId header parameter is a hint indicating which key was used to secure the JWS.  This parameter allows
     * originators to explicitly signal a change of key to recipients.  The structure of the keyId value is
     * unspecified.
     *
     * When used with a JWK, the keyId value is used to match a JWK {@code keyId} parameter value.
     *
     * @param kid the JWS {@code kid} header value or {@code null} to remove the property from the JSON map.
     * @return the {@code Header} instance for method chaining.
     */
    T setKeyId(String kid);
}