io.jsonwebtoken.security.X509Mutator Maven / Gradle / Ivy

/*
 * 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.security;

import io.jsonwebtoken.JweHeader;
import io.jsonwebtoken.JwsHeader;

import java.net.URI;
import java.security.cert.X509Certificate;
import java.util.List;

/**
 * Mutation (modifications) of X.509-specific properties of an associated JWT Header or JWK, enabling method chaining.
 *
 * @param  the mutator subtype, for method chaining
 * @since 0.12.0
 */
public interface X509Mutator> {

    /**
     * Sets the {@code x5u} (X.509 URL) that refers to a resource containing the X.509 public key certificate or
     * certificate chain of the associated JWT or JWK. A {@code null} value will remove the property from the JSON map.
     *
     * The URI MUST refer to a resource for an X.509 public key certificate or certificate chain that
     * conforms to RFC 5280 in PEM-encoded form, with
     * each certificate delimited as specified in
     * Section 6.1 of RFC 4945.
     * The key in the first certificate MUST match the public key represented by other members of the
     * associated JWT or JWK.  The protocol used to acquire the resource MUST provide integrity protection;
     * an HTTP GET request to retrieve the certificate MUST use
     * HTTP over TLS; the identity of the server
     * MUST be validated, as per
     * Section 6 of RFC 6125.
     *
     * 
     *     When set for a {@link JwsHeader}, the certificate or first certificate in the chain contains
     *         the public key complement of the private key used to digitally sign the JWS.
     *     When set for {@link JweHeader}, the certificate or first certificate in the chain contains the
     *         public key to which the JWE was encrypted, and may be used to determine the private key needed to
     *         decrypt the JWE.
     *     When set for an {@link AsymmetricJwk}, the certificate or first certificate in the chain
     *         MUST contain the public key represented by the JWK.
     * 
     *
     * @param uri the {@code x5u} (X.509 URL) that refers to a resource for the X.509 public key certificate or
     *            certificate chain associated with the JWT or JWK.
     * @return the mutator/builder for method chaining.
     * @see JWK x5u (X.509 URL) Parameter
     * @see JWS x5u (X.509 URL) Header Parameter
     * @see JWE x5u (X.509 URL) Header Parameter
     */
    T x509Url(URI uri);

    /**
     * Sets the {@code x5c} (X.509 Certificate Chain) of the associated JWT or JWK. A {@code null} value will remove the
     * property from the JSON map. The initial certificate MAY be followed by additional certificates, with
     * each subsequent certificate being the one used to certify the previous one.
     *
     * 
     *     When set for a {@link JwsHeader}, the first certificate (at list index 0) MUST contain
     *         the public key complement of the private key used to digitally sign the JWS.
     *     When set for {@link JweHeader}, the first certificate (at list index 0) MUST contain the
     *         public key to which the JWE was encrypted, and may be used to determine the private key needed to
     *         decrypt the JWE.
     *     When set for an {@link AsymmetricJwk}, the first certificate (at list index 0) MUST contain
     *         the public key represented by the JWK.
     * 
     *
     * @param chain the {@code x5c} (X.509 Certificate Chain) of the associated JWT or JWK.
     * @return the header/builder for method chaining.
     * @see JWK x5c (X.509 Certificate Chain) Parameter
     * @see JWS x5c (X.509 Certificate Chain) Header Parameter
     * @see JWE x5c (X.509 Certificate Chain) Header Parameter
     */
    T x509Chain(List chain);

    /**
     * Sets the {@code x5t} (X.509 Certificate SHA-1 Thumbprint) (a.k.a. digest) of the DER-encoding of the
     * X.509 Certificate associated with the JWT or JWK. A {@code null} value will remove the
     * property from the JSON map.
     *
     * Note that certificate thumbprints are also sometimes known as certificate fingerprints.
     *
     * 
     *     When set for a {@link JwsHeader}, it is the SHA-1 thumbprint of the X.509 certificate complement of
     *         the private key used to digitally sign the JWS.
     *     When set for {@link JweHeader}, it is the thumbprint of the X.509 Certificate containing the
     *         public key to which the JWE was encrypted, and may be used to determine the private key needed to
     *         decrypt the JWE.
     *     When set for an {@link AsymmetricJwk}, it is the thumbprint of the X.509 certificate containing the
     *         public key represented by the JWK.
     * 
     *
     * @param thumbprint the {@code x5t} (X.509 Certificate SHA-1 Thumbprint) (a.k.a. digest) of the DER-encoding of the
     *                   X.509 Certificate associated with the JWT or JWK
     * @return the header for method chaining
     * @see JWK x5t (X.509 Certificate SHA-1 Thumbprint) Parameter
     * @see JWS x5t (X.509 Certificate SHA-1 Thumbprint) Header Parameter
     * @see JWE x5t (X.509 Certificate SHA-1 Thumbprint) Header Parameter
     */
    T x509Sha1Thumbprint(byte[] thumbprint);

    /**
     * Sets the {@code x5t#S256} (X.509 Certificate SHA-256 Thumbprint) (a.k.a. digest) of the DER-encoding of the
     * X.509 Certificate associated with the JWT or JWK. A {@code null} value will remove the
     * property from the JSON map.
     *
     * Note that certificate thumbprints are also sometimes known as certificate fingerprints.
     *
     * 
     *     When set for a {@link JwsHeader}, it is the SHA-256 thumbprint of the X.509 certificate complement
     *         of the private key used to digitally sign the JWS.
     *     When set for {@link JweHeader}, it is the SHA-256 thumbprint of the X.509 Certificate containing the
     *         public key to which the JWE was encrypted, and may be used to determine the private key needed to
     *         decrypt the JWE.
     *     When set for a {@link AsymmetricJwk}, it is the SHA-256 thumbprint of the X.509 certificate
     *         containing the public key represented by the JWK.
     * 
     *
     * @param thumbprint the {@code x5t} (X.509 Certificate SHA-1 Thumbprint) (a.k.a. digest) of the DER-encoding of the
     *                   X.509 Certificate associated with the JWT or JWK
     * @return the header for method chaining
     * @see JWK x5t#S256 (X.509 Certificate SHA-256 Thumbprint) Parameter
     * @see JWS x5t#S256 (X.509 Certificate SHA-256 Thumbprint) Header Parameter
     * @see JWE x5t#S256 (X.509 Certificate SHA-256 Thumbprint) Header Parameter
     */
    T x509Sha256Thumbprint(byte[] thumbprint);
}