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

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jjwt-api Show documentation
There is a newer version: 0.12.6
/*
 * 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;

/**
 * Accessor methods of X.509-specific properties of a
 * {@link io.jsonwebtoken.ProtectedHeader ProtectedHeader} or {@link AsymmetricJwk}, guaranteeing consistent behavior
 * across similar but distinct JWT concepts with identical parameter names.
 *
 * @see io.jsonwebtoken.ProtectedHeader
 * @see AsymmetricJwk
 * @since 0.12.0
 */
public interface X509Accessor {

    /**
     * Returns the {@code x5u} (X.509 URL) that refers to a resource for the associated X.509 public key certificate
     * or certificate chain, or {@code null} if not present.
     *
     * When present, 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 ProtectedHeader 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 present in a {@link JwsHeader}, the certificate or first certificate in the chain corresponds
     *         the public key complement of the private key used to digitally sign the JWS.
     *     When present in a {@link JweHeader}, the certificate or certificate chain corresponds to the
     *         public key to which the JWE was encrypted, and may be used to determine the private key needed to
     *         decrypt the JWE.
     *     When present in an {@link AsymmetricJwk}, the certificate or first certificate in the chain
     *         MUST contain the public key represented by the JWK.
     * 
     *
     * @return the {@code x5u} (X.509 URL) that refers to a resource for the associated X.509 public key certificate or
     * certificate chain.
     * @see JWK {@code x5u} (X.509 URL) Parameter
     * @see JWS {@code x5u} (X.509 URL) Header Parameter
     * @see JWE {@code x5u} (X.509 URL) Header Parameter
     */
    URI getX509Url();

    /**
     * Returns the associated {@code x5c} (X.509 Certificate Chain), or {@code null} if not present. The initial
     * certificate MAY be followed by additional certificates, with each subsequent certificate being the
     * one used to certify the previous one.
     *
     * 
     *     When present in 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 present in a {@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 present in an {@link AsymmetricJwk}, the first certificate (at list index 0)
     *         MUST contain the public key represented by the JWK.
     * 
     *
     * @return the associated {@code x5c} (X.509 Certificate Chain), or {@code null} if not present.
     * @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
     */
    List getX509Chain();

    /**
     * Returns the {@code x5t} (X.509 Certificate SHA-1 Thumbprint) (a.k.a. digest) of the DER-encoding of the
     * associated X.509 Certificate, or {@code null} if not present.
     *
     * Note that certificate thumbprints are also sometimes known as certificate fingerprints.
     *
     * 
     *     When present in 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 present in a {@link JweHeader}, it is the SHA-1 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 present in an {@link AsymmetricJwk}, it is the SHA-1 thumbprint of the X.509 certificate
     *         containing the public key represented by the JWK.
     * 
     *
     * @return the {@code x5t} (X.509 Certificate SHA-1 Thumbprint) (a.k.a. digest) of the DER-encoding of the
     * associated X.509 Certificate, or {@code null} if not present
     * @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
     */
    byte[] getX509Sha1Thumbprint();

    /**
     * Returns the {@code x5t#S256} (X.509 Certificate SHA-256 Thumbprint) (a.k.a. digest) of the DER-encoding of the
     * associated X.509 Certificate, or {@code null} if not present.
     *
     * Note that certificate thumbprints are also sometimes known as certificate fingerprints.
     *
     * 
     *     When present in 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 present in a {@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 present in an {@link AsymmetricJwk}, it is the SHA-256 thumbprint of the X.509 certificate
     *         containing the public key represented by the JWK.
     * 
     *
     * @return the {@code x5t#S256} (X.509 Certificate SHA-256 Thumbprint) (a.k.a. digest) of the DER-encoding of the
     * associated X.509 Certificate, or {@code null} if not present
     * @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
     */
    byte[] getX509Sha256Thumbprint();
}