/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you 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 org.apache.cassandra.auth;

import java.net.InetAddress;
import java.security.cert.Certificate;
import java.util.Collections;
import java.util.Map;
import java.util.Objects;
import java.util.Set;

import javax.annotation.Nonnull;

import org.apache.cassandra.exceptions.AuthenticationException;
import org.apache.cassandra.exceptions.ConfigurationException;
import org.apache.cassandra.service.ClientState;
import org.apache.cassandra.transport.messages.AuthenticateMessage;

public interface IAuthenticator
{
    /**
     * Whether the authenticator requires explicit login.
     * If false will instantiate user with AuthenticatedUser.ANONYMOUS_USER.
     */
    boolean requireAuthentication();

    /**
     * Whether the authenticator supports 'early' authentication, meaning that it can be authenticated without
     * the need to send an AUTHENTICATE request to the client after receiveing a STARTUP message from the client.
     * <p>
     * An example use case of this would be if the client could be authenticated using certificates present
     * on a TLS-encrypted connection, as is done in {@link MutualTlsAuthenticator}.  In this case, an AUTHENTICATE
     * message is not needed because the client can be identified by information present in its provided certificate.
     * <p>
     * If an authenticator supports requires early authentication, this should be <code>true</code>;
     * otherwise if a client cannot authenticate using its connection details (e.g. a certificate), an AUTHENTICATE
     * will be sent to the client. This may confuse a driver implementation into thinking an authenticator is needed,
     * when instead the real issue is that something is missing on the connection, such as a certificate.
     * <p>
     * If <code>false</code> (default behavior), an AUTHENTICATE request will be sent to the client.
     */
    default boolean supportsEarlyAuthentication()
    {
        return false;
    }

    /**
     * Set of resources that should be made inaccessible to users and only accessible internally.
     *
     * @return Keyspaces, column families that will be unmodifiable by users; other resources.
     */
    Set<? extends IResource> protectedResources();

    /**
     * Additional set of IRoleManager.Options used by this authenticator and supported by CREATE ROLE and ALTER ROLE
     * statements. These are in addition to any default options supported by the role manager.
     *
     * @return A set of IRoleManager.Options that this authenticator requires support for.
     */
    default Set<IRoleManager.Option> getSupportedRoleOptions()
    {
        return Set.of();
    }

    /**
     * Additional set of IRoleManager.Options used by this authenticator that users are allowed to alter via
     * ALTER ROLE statements. These are in addition to any default alterable options supported by the role manager.
     * Alterable role options must also be supported role options.
     *
     * @return A set of supported role options that users are allowed to alter.
     */
    default Set<IRoleManager.Option> getAlterableRoleOptions()
    {
        return Set.of();
    }

    /**
     * Validates configuration of IAuthenticator implementation (if configurable).
     *
     * @throws ConfigurationException when there is a configuration error.
     */
    void validateConfiguration() throws ConfigurationException;

    /**
     * Setup is called once upon system startup to initialize the IAuthenticator.
     * <p>
     * For example, use this method to create any required keyspaces/column families.
     */
    void setup();

    /**
     * Allows custom authenticators to return their own {@link AuthenticateMessage} based on
     * {@link ClientState} information. For example, this allows returning the FQCN of a driver's
     * known authenticator (e.g. "com.datastax.bdp.cassandra.auth.DseAuthenticator") to enable
     * SASL scheme negotiation.
     */
    default AuthenticateMessage getAuthenticateMessage(ClientState clientState)
    {
        return new AuthenticateMessage(getClass().getName());
    }

    /**
     * Provide a SASL handler to perform authentication for an single connection. SASL
     * is a stateful protocol, so a new instance must be used for each authentication
     * attempt.
     *
     * @param clientAddress the IP address of the client whom we wish to authenticate, or null
     *                      if an internal client (one not connected over the remote transport).
     * @return org.apache.cassandra.auth.IAuthenticator.SaslNegotiator implementation
     * (see {@link org.apache.cassandra.auth.PasswordAuthenticator.PlainTextSaslAuthenticator})
     */
    SaslNegotiator newSaslNegotiator(InetAddress clientAddress);

    /**
     * Provide a SASL handler to perform authentication for an single connection. SASL
     * is a stateful protocol, so a new instance must be used for each authentication
     * attempt. This method accepts certificates as well. Authentication strategies can
     * override this method to gain access to client's certificate chain, if present.
     *
     * @param clientAddress the IP address of the client whom we wish to authenticate, or null
     *                      if an internal client (one not connected over the remote transport).
     * @param certificates  the peer's Certificate chain, if present.
     *                      It is expected that these will all be instances of {@link java.security.cert.X509Certificate},
     *                      but we pass them as the base {@link Certificate} in case future implementations leverage
     *                      other certificate types.
     * @return org.apache.cassandra.auth.IAuthenticator.SaslNegotiator implementation
     * (see {@link org.apache.cassandra.auth.PasswordAuthenticator.PlainTextSaslAuthenticator})
     */
    default SaslNegotiator newSaslNegotiator(InetAddress clientAddress, Certificate[] certificates)
    {
        return newSaslNegotiator(clientAddress);
    }

    /**
     * @return The supported authentication 'modes' of this authenticator scheme.
     * <p>
     * This is currently only used for registering metrics tied to authentication by mode.
     */
    default Set<AuthenticationMode> getSupportedAuthenticationModes()
    {
        return Collections.emptySet();
    }

    /**
     * A legacy method that is still used by JMX authentication.
     * <p>
     * You should implement this for having JMX authentication through your
     * authenticator.
     * <p>
     * Should never return null - always throw AuthenticationException instead.
     * Returning AuthenticatedUser.ANONYMOUS_USER is an option as well if authentication is not required.
     *
     * @param credentials implementation specific key/value pairs
     * @return non-null representation of the authenticated subject
     * @throws AuthenticationException
     */
    AuthenticatedUser legacyAuthenticate(Map<String, String> credentials) throws AuthenticationException;

    /**
     * Performs the actual SASL negotiation for a single authentication attempt.
     * SASL is stateful, so a new instance should be used for each attempt.
     * Non-trivial implementations may delegate to an instance of {@link javax.security.sasl.SaslServer}
     */
    public interface SaslNegotiator
    {
        /**
         * Evaluates the client response data and generates a byte[] response which may be a further challenge or purely
         * informational in the case that the negotiation is completed on this round.
         * <p>
         * This method is called each time a {@link org.apache.cassandra.transport.messages.AuthResponse} is received
         * from a client. After it is called, {@link #isComplete()} is checked to determine whether the negotiation has
         * finished. If so, an AuthenticatedUser is obtained by calling {@link #getAuthenticatedUser()} and that user
         * associated with the active connection and the byte[] sent back to the client via an
         * {@link org.apache.cassandra.transport.messages.AuthSuccess} message. If the negotiation is not yet complete,
         * the byte[] is returned to the client as a further challenge in an
         * {@link org.apache.cassandra.transport.messages.AuthChallenge} message. This continues until the negotiation
         * does complete or an error is encountered.
         *
         * @param clientResponse The non-null (but possibly empty) response sent by the client
         * @return The possibly null response to send to the client.
         * @throws AuthenticationException see {@link javax.security.sasl.SaslServer#evaluateResponse(byte[])}
         */
        public byte[] evaluateResponse(byte[] clientResponse) throws AuthenticationException;

        /**
         * Called after each invocation of {@link #evaluateResponse(byte[])} to determine whether the  authentication has
         * completed successfully or should be continued.
         *
         * @return true if the authentication exchange has completed; false otherwise.
         * see {@link javax.security.sasl.SaslServer#isComplete()}
         */
        public boolean isComplete();

        /**
         * Following a sucessful negotiation, get the AuthenticatedUser representing the logged in subject.
         * This method should only be called if {@link #isComplete()} returns true.
         * Should never return null - always throw AuthenticationException instead.
         * Returning AuthenticatedUser.ANONYMOUS_USER is an option if authentication is not required.
         *
         * @return non-null representation of the authenticated subject
         * @throws AuthenticationException
         */
        public AuthenticatedUser getAuthenticatedUser() throws AuthenticationException;

        /**
         * Whether it is determined that an AUTHENTICATE message should be sent to properly negotiate.
         * This is used in conjunction with {@link #supportsEarlyAuthentication()} in determining if authentication
         * can be done early, for example if the client can be authenticated using client certificates when handling
         * a STARTUP message.
         * <p>
         * If <code>true</code> (default behavior), an AUTHENTICATE message will be sent in response to a STARTUP,
         * otherwise {@link #evaluateResponse(byte[])} will be called with an empty byte array when handling STARTUP.
         */
        default boolean shouldSendAuthenticateMessage()
        {
            return true;
        }

        /**
         * @return The assumed mode of authentication attempted using this negotiator, this will usually be some value
         * of {@link AuthenticationMode#toString()}} unless an implementor provides their own custom authentication
         * scheme.
         */
        default AuthenticationMode getAuthenticationMode()
        {
            return AuthenticationMode.UNAUTHENTICATED;
        }
    }

    /**
     * Known modes of authentication supported by Cassandra's provided {@link IAuthenticator} implementations.
     */
    abstract class AuthenticationMode
    {
        private final String displayName;

        /**
         * @param displayName How this mode should be displayed in tooling and JMX beans.  Note that it is desirable
         *                    for this name to not have spaces as it may not work well with tooling around JMX.
         */
        public AuthenticationMode(@Nonnull String displayName)
        {
            this.displayName = displayName;
        }

        /**
         * User was not authenticated in any particular way.
         */
        public static final AuthenticationMode UNAUTHENTICATED = new AuthenticationMode("Unauthenticated") {};

        /**
         * User authenticated using a password.
         */
        public static final AuthenticationMode PASSWORD = new AuthenticationMode("Password") {};

        /**
         * User authenticated using a trusted identity in their client certificate.
         */
        public static final AuthenticationMode MTLS = new AuthenticationMode("MutualTls") {};

        @Override
        public String toString()
        {
            return displayName;
        }

        @Override
        public boolean equals(Object o)
        {
            if (this == o) return true;
            if (o == null || getClass() != o.getClass()) return false;
            AuthenticationMode that = (AuthenticationMode) o;
            return displayName.equals(that.displayName);
        }

        @Override
        public int hashCode()
        {
            return Objects.hash(displayName);
        }
    }
}
