001/*
002 * Licensed Materials - Property of IBM
003 * Restricted Materials of IBM
004 *
005 * com.ibm.rational.wvcm.stp.cc.CcTrustManagerCallback
006 *
007 * (C) Copyright IBM Corporation 2011, 2016.  All Rights Reserved.
008 * Note to U.S. Government Users Restricted Rights:  Use, duplication or 
009 * disclosure restricted by GSA ADP  Schedule Contract with IBM Corp.
010 */
011package com.ibm.rational.wvcm.stp.cc;
012
013import java.security.KeyStore;
014import java.security.Principal;
015import java.security.cert.CertificateException;
016import java.security.cert.X509Certificate;
017import java.util.List;
018
019/**
020 * This callback is used to handle SSL Certificate problems when initiating a
021 * connection to a remote CCRC WAN server over HTTPS. The callback is not
022 * invoked if the certificate is stored and trusted on the client already.
023 */
024public interface CcTrustManagerCallback {
025    
026    /**
027     * Provides the caller details about what is wrong with a certificate
028     */
029    public enum CertificateStatus {
030        /**
031         * The certificate is not trusted
032         */
033        CERTIFICATE_NOT_TRUSTED,
034        
035        /**
036         * The certificate's date is out of range
037         */
038        CERTIFICATE_DATE_OUT_OF_RANGE,
039        
040        /**
041         * The certificate's name does not match what is trusted in the store
042         */
043        CERTIFICATE_NAME_MISMATCH
044    }
045    
046    /**
047     * The caller provides a response in reply to the callback to indicate
048     * how to handle the certificate problem.
049     */
050    public enum CertificateResponse {
051        
052        /**
053         * Temporarily accept the certificate for this session.
054         */
055        ACCEPT_CERTIFICATE_TEMPORARILY,
056        
057        /**
058         * Accept this certificate and install it into the key store
059         */
060        ACCEPT_AND_INSTALL_CERTIFICATE,
061        
062        /**
063         * Reject this certificate for this session.
064         */
065        REJECT_CERTIFICATE
066    }
067    
068    /**
069     * Callback is invoked when there is a problem with the certificate provided
070     * by the server. Check the <code>CertificateException</code> and the 
071     * <code>CertificateStatus</code> for more details. Respond to the
072     * certificate problem using a <code>CertificateResponse</code>
073     * 
074     * @param cert Java x.509 certificate
075     * @param status List of certificate problems
076     * @param certEx Java certificate exception
077     * @return CertificateResponse accept/install/reject
078     */
079    CertificateResponse getCertificateResponse(
080            X509Certificate cert,
081            List<CertificateStatus> status,
082            CertificateException certEx);
083    
084    /**
085     * Choose a valid client certificate
086     * 
087     * @param keyStore The keyStore or null
088     * @param keyType the key algorithm type name(s), ordered with the most-preferred key type first.
089     * @param issuers the list of acceptable CA issuer subject names or null if it does not matter which issuers are used.
090     * @return The alias of the selected client certificate
091     */
092    String chooseClientCertificate(
093            KeyStore keyStore, 
094            String[] keyType,
095            Principal[] issuers);
096
097}