io.jsonwebtoken.security.AsymmetricJwkBuilder 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 java.security.Key;
/**
* A {@link JwkBuilder} that builds asymmetric (public or private) JWKs.
*
* @param the type of Java key provided by the JWK.
* @param the type of asymmetric JWK created
* @param the type of the builder, for subtype method chaining
* @since 0.12.0
*/
public interface AsymmetricJwkBuilder, T extends AsymmetricJwkBuilder>
extends JwkBuilder, X509Builder {
/**
* Sets the JWK
* {@code use} (Public Key Use)
* parameter value. {@code use} values are CaSe-SeNsItIvE. A {@code null} value will remove the property
* from the JWK.
*
* The JWK specification defines the
* following {@code use} values:
*
*
* JWK Key Use Values
*
*
* Value
* Key Use
*
*
*
*
* {@code sig}
* signature
*
*
* {@code enc}
* encryption
*
*
*
*
* Other values MAY be used. For best interoperability with other applications however, it is
* recommended to use only the values above.
*
* When a key is used to wrap another key and a public key use designation for the first key is desired, the
* {@code enc} (encryption) key use value is used, since key wrapping is a kind of encryption. The
* {@code enc} value is also to be used for public keys used for key agreement operations.
*
* Public Key Use vs Key Operations
*
* Per
* JWK RFC 7517, Section 4.3, last paragraph,
* the use (Public Key Use) and {@link #operations() key_ops (Key Operations)} members
* SHOULD NOT be used together; however, if both are used, the information they convey MUST be
* consistent. Applications should specify which of these members they use, if either is to be used by the
* application.
*
* @param use the JWK {@code use} value.
* @return the builder for method chaining.
* @throws IllegalArgumentException if the {@code use} value is {@code null} or empty.
*/
T publicKeyUse(String use) throws IllegalArgumentException;
}