001/*
002 *  Licensed to the Apache Software Foundation (ASF) under one
003 *  or more contributor license agreements.  See the NOTICE file
004 *  distributed with this work for additional information
005 *  regarding copyright ownership.  The ASF licenses this file
006 *  to you under the Apache License, Version 2.0 (the
007 *  "License"); you may not use this file except in compliance
008 *  with the License.  You may obtain a copy of the License at
009 *  
010 *    http://www.apache.org/licenses/LICENSE-2.0
011 *  
012 *  Unless required by applicable law or agreed to in writing,
013 *  software distributed under the License is distributed on an
014 *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 *  KIND, either express or implied.  See the License for the
016 *  specific language governing permissions and limitations
017 *  under the License. 
018 *  
019 */
020package org.apache.directory.server.kerberos.sam;
021
022
023import javax.naming.directory.DirContext;
024import javax.security.auth.kerberos.KerberosKey;
025import javax.security.auth.kerberos.KerberosPrincipal;
026
027import org.apache.directory.shared.kerberos.codec.types.SamType;
028
029
030/**
031 * Single-use Authentication Mechanism verifier (subsystem) interface.
032 * SamVerifiers are modules that can be configured and are dynamically
033 * loaded as needed.  Implementations have a few requirements and things
034 * implementors should know:
035 *
036 * <ul>
037 *   <li>A public default constructor is required,</li>
038 *   <li>after instantitation environment properties are supplied,</li>
039 *   <li>next the KeyIntegrityChecker is set for the verifier,</li>
040 *   <li>finally the verifier is started up by calling startup(),
041 *       incidentally this is where all initialization work should be
042 *       done using the environment properties supplied.
043 *   </li>
044 * </ul>
045 *
046 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
047 */
048public interface SamVerifier
049{
050    /**
051     * Starts one of many pluggable SAM type subsystem.
052     * 
053     * @throws SamException If the SamVerifier instance cannot be started
054     */
055    void startup() throws SamException;
056
057
058    /**
059     * Shuts down one of many pluggable SAM type subsystem.
060     */
061    void shutdown();
062
063
064    /**
065     * SamVerifiers require a KeyIntegrityChecker to calculate the integrity of
066     * a generated KerberosKey.  The Kerberos service exposes this interface
067     * and supplies it to the verifier to check generated keys to conduct the
068     * verification workflow.
069     *
070     * @param keyChecker The integrity checker that validates whether or not a
071     * key can decrypt-decode preauth data (an encryped-encoded generalized
072     * timestamp).
073     */
074    void setIntegrityChecker( KeyIntegrityChecker keyChecker );
075
076
077    /**
078     * Verifies the single use password supplied.
079     *
080     * @param principal The kerberos principal to use.
081     * @param sad Single-use authentication data (encrypted generalized timestamp).
082     * @return The {@link KerberosKey}.
083     * @throws SamException If the verification failed
084     */
085    KerberosKey verify( KerberosPrincipal principal, byte[] sad ) throws SamException;
086
087
088    /**
089     * Gets the registered SAM algorithm type implemented by this SamVerifier.
090     *
091     * @return The type value for the SAM algorithm used to verify the SUP.
092     */
093    SamType getSamType();
094
095
096    /**
097     * Sets the user context where users are stored for the primary realm.
098     *  
099     * @param userContext The User context
100     */
101    void setUserContext( DirContext userContext );
102}