001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.rest.server.auth;
018
019import java.security.*;
020import java.util.*;
021
022/**
023 * SPI for resolving a raw API key string to its associated {@link Principal}.
024 *
025 * <p>
026 * {@link ApiKeyGuard} extracts the key from a configurable source (header / query / cookie) and
027 * delegates lookup to an {@code ApiKeyStore} the host supplies. The store is the authoritative
028 * source of "is this key valid and which client owns it?" &mdash; it can hit a database, an in-memory
029 * map, an external KMS, etc.
030 *
031 * <p>
032 * Implementations should:
033 * <ul>
034 *    <li>Treat the key as untrusted input (no logging of full keys, no exception messages echoing the key).
035 *    <li>Compare keys with a constant-time comparison if the store is in-memory &mdash; this matters for
036 *       short keys where a timing side-channel could leak bytes. {@code MessageDigest.isEqual(...)}
037 *       over the UTF-8 byte arrays is the standard idiom.
038 *    <li>Return {@link Optional#empty()} for any unknown / revoked / expired key; do not throw for ordinary
039 *       "not found" misses (that would couple lookup failures to exception-construction overhead under load).
040 * </ul>
041 *
042 * <h5 class='section'>Example &mdash; in-memory store:</h5>
043 *
044 * <p class='bjava'>
045 *    <jk>final</jk> Map&lt;String,Principal&gt; <jv>keys</jv> = Map.<jsm>of</jsm>(
046 *       <js>"key-alice"</js>, () -&gt; <js>"alice"</js>,
047 *       <js>"key-bob"</js>,   () -&gt; <js>"bob"</js>
048 *    );
049 *
050 *    ApiKeyStore <jv>store</jv> = <jv>key</jv> -&gt; Optional.<jsm>ofNullable</jsm>(<jv>keys</jv>.get(<jv>key</jv>));
051 * </p>
052 *
053 * <h5 class='section'>See Also:</h5><ul>
054 *    <li class='jc'>{@link ApiKeyGuard}
055 *    <li class='jc'>{@link AuthenticationException}
056 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerAuthGuards">AuthN Guards — Bearer / API-Key / JWT</a>
057 * </ul>
058 *
059 * @since 10.0.0
060 */
061@FunctionalInterface
062public interface ApiKeyStore {
063
064   /**
065    * Looks up the {@link Principal} associated with the supplied API key.
066    *
067    * @param key The raw API key from the configured source (header / query / cookie). Never <jk>null</jk>.
068    * @return The associated principal, or {@link Optional#empty()} if the key is unknown / revoked / expired.
069    */
070   Optional<Principal> lookup(String key);
071}