https://openjdk.java.net/ 
/*
 * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */
/*
 * $Id: KeySelector.java,v 1.6 2005/05/10 15:47:42 mullan Exp $
 */
package javax.xml.crypto;

import java.security.Key;
import javax.xml.crypto.dsig.keyinfo.KeyInfo;
import javax.xml.crypto.dsig.keyinfo.RetrievalMethod;


A selector that finds and returns a key using the data contained in a KeyInfo object. An example of an implementation of this class is one that searches a KeyStore for trusted keys that match information contained in a KeyInfo.

Whether or not the returned key is trusted and the mechanisms
used to determine that is implementation-specific.

Author:Sean Mullan, JSR 105 Expert Group
Since:1.6
/**
 * A selector that finds and returns a key using the data contained in a
 * {@link KeyInfo} object. An example of an implementation of
 * this class is one that searches a {@link java.security.KeyStore} for
 * trusted keys that match information contained in a <code>KeyInfo</code>.
 *
 * <p>Whether or not the returned key is trusted and the mechanisms
 * used to determine that is implementation-specific.
 *
 * @author Sean Mullan
 * @author JSR 105 Expert Group
 * @since 1.6
 */
public abstract class KeySelector {

    
The purpose of the key that is to be selected.

/**
     * The purpose of the key that is to be selected.
     */
    public static class Purpose {

        private final String name;

        private Purpose(String name)    { this.name = name; }

        
Returns a string representation of this purpose ("sign",
"verify", "encrypt", or "decrypt").

Returns:a string representation of this purpose
/**
         * Returns a string representation of this purpose ("sign",
         * "verify", "encrypt", or "decrypt").
         *
         * @return a string representation of this purpose
         */
        public String toString()        { return name; }

        
A key for signing.

/**
         * A key for signing.
         */
        public static final Purpose SIGN = new Purpose("sign");
        
A key for verifying.

/**
         * A key for verifying.
         */
        public static final Purpose VERIFY = new Purpose("verify");
        
A key for encrypting.

/**
         * A key for encrypting.
         */
        public static final Purpose ENCRYPT = new Purpose("encrypt");
        
A key for decrypting.

/**
         * A key for decrypting.
         */
        public static final Purpose DECRYPT = new Purpose("decrypt");
    }

    
Default no-args constructor; intended for invocation by subclasses only.

/**
     * Default no-args constructor; intended for invocation by subclasses only.
     */
    protected KeySelector() {}

    
Attempts to find a key that satisfies the specified constraints.

Params:
  • keyInfo – a KeyInfo (may be null)
  • purpose – the key's purpose (Purpose.SIGN, Purpose.VERIFY, Purpose.ENCRYPT, or Purpose.DECRYPT)
  • method – the algorithm method that this key is to be used for.
   Only keys that are compatible with the algorithm and meet the
   constraints of the specified algorithm should be returned.
  • context – an XMLCryptoContext that may contain useful information for finding an appropriate key. If this key selector supports resolving RetrievalMethod types, the context's baseURI and dereferencer
   parameters (if specified) should be used by the selector to
   resolve and dereference the URI.
Throws:
  • KeySelectorException – if an exceptional condition occurs while
   attempting to find a key. Note that an inability to find a key is not
   considered an exception (null should be
   returned in that case). However, an error condition (ex: network
   communications failure) that prevented the KeySelector
   from finding a potential key should be considered an exception.
  • ClassCastException – if the data type of method
   is not supported by this key selector
Returns:the result of the key selector
/**
     * Attempts to find a key that satisfies the specified constraints.
     *
     * @param keyInfo a <code>KeyInfo</code> (may be <code>null</code>)
     * @param purpose the key's purpose ({@link Purpose#SIGN},
     *    {@link Purpose#VERIFY}, {@link Purpose#ENCRYPT}, or
     *    {@link Purpose#DECRYPT})
     * @param method the algorithm method that this key is to be used for.
     *    Only keys that are compatible with the algorithm and meet the
     *    constraints of the specified algorithm should be returned.
     * @param context an <code>XMLCryptoContext</code> that may contain
     *    useful information for finding an appropriate key. If this key
     *    selector supports resolving {@link RetrievalMethod} types, the
     *    context's <code>baseURI</code> and <code>dereferencer</code>
     *    parameters (if specified) should be used by the selector to
     *    resolve and dereference the URI.
     * @return the result of the key selector
     * @throws KeySelectorException if an exceptional condition occurs while
     *    attempting to find a key. Note that an inability to find a key is not
     *    considered an exception (<code>null</code> should be
     *    returned in that case). However, an error condition (ex: network
     *    communications failure) that prevented the <code>KeySelector</code>
     *    from finding a potential key should be considered an exception.
     * @throws ClassCastException if the data type of <code>method</code>
     *    is not supported by this key selector
     */
    public abstract KeySelectorResult select(KeyInfo keyInfo, Purpose purpose,
        AlgorithmMethod method, XMLCryptoContext context)
        throws KeySelectorException;

    
Returns a KeySelector that always selects the specified
key, regardless of the KeyInfo passed to it.

Params:
  • key – the sole key to be stored in the key selector
Throws:
Returns:a key selector that always selects the specified key
/**
     * Returns a <code>KeySelector</code> that always selects the specified
     * key, regardless of the <code>KeyInfo</code> passed to it.
     *
     * @param key the sole key to be stored in the key selector
     * @return a key selector that always selects the specified key
     * @throws NullPointerException if <code>key</code> is <code>null</code>
     */
    public static KeySelector singletonKeySelector(Key key) {
        return new SingletonKeySelector(key);
    }

    private static class SingletonKeySelector extends KeySelector {
        private final Key key;

        SingletonKeySelector(Key key) {
            if (key == null) {
                throw new NullPointerException();
            }
            this.key = key;
        }

        public KeySelectorResult select(KeyInfo keyInfo, Purpose purpose,
            AlgorithmMethod method, XMLCryptoContext context)
            throws KeySelectorException {

            return new KeySelectorResult() {
                public Key getKey() {
                    return key;
                }
            };
        }
    }
}