org.apache.camel.component.xmlsecurity.api.ValidationFailedHandler Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of camel-xmlsecurity Show documentation
Camel Partial XML Encryption/Decryption and XML Signature support
There is a newer version: 4.9.0
/*
 * 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.camel.component.xmlsecurity.api;

import javax.xml.crypto.dsig.Reference;
import javax.xml.crypto.dsig.XMLSignature;
import javax.xml.crypto.dsig.XMLSignature.SignatureValue;
import javax.xml.crypto.dsig.XMLSignatureException;

/**
 * Handler for handling the case when the core signature validation fails or a {@link XMLSignatureException} occurs
 * during calling {@link XMLSignature#validate(javax.xml.crypto.dsig.XMLValidateContext)}.
 *
 * This handler can be used to react in a specific way on validation failures. For example, the handler could write logs
 * or may even ignore certain validation failures.
 * 
 * Typically the handler throws an exception when a validation failure occurs.
 *
 * There is a certain order how the methods are called.
 * 

 * First, the method {@link #start()} is called when a core validation fails.
 * 
Then {@link #signatureValueValidationFailed(SignatureValue)} is called if the signature validation fails.
 * 
Then, for each reference in the signed info whose validation fails {@link #referenceValidationFailed(Reference)}
 * is called.
 * 
Then, for each reference in the manifests whose validation fails, the method
 * {@link #manifestReferenceValidationFailed(Reference)} is called.
 * 
Then, the method {@link #ignoreCoreValidationFailure()} is called where you can finally decide whether the
 * processing should go on or be interrupted.
 * 
It is ensured that the method {@link #end()} is called at the end of the validation, even if the methods called
 * before have thrown an exception. This allows you to hold state between the start and end of the validation handling
 * process.
 * 
 * If you throw an exception then the validation checking is interrupted and after that only the {@link #end()} method
 * is called in a finally block. Best practice is to interrupt the validation at the first occurrence of a validation
 * error.
 */
public interface ValidationFailedHandler {

    /**
     * Method called when an XMLSignatureException is thrown by the method
     * {@link XMLSignature#validate(javax.xml.crypto.dsig.XMLValidateContext)}.
     * 
     * You can return more specific exceptions which are useful for your use-case.
     *
     * @param  e exception
     * @return   exception exception which is then thrown by XmlSignerProcessor.
     */
    Exception onXMLSignatureException(XMLSignatureException e);

    void start();

    void signatureValueValidationFailed(SignatureValue value) throws Exception; // NOPMD

    void referenceValidationFailed(Reference ref) throws Exception; // NOPMD

    void manifestReferenceValidationFailed(Reference ref) throws Exception; // NOPMD

    /**
     * If true is returned then the verifier will go-on as if there was no validation failure. If
     * false is returned than the verifier will throw an {@link XmlSignatureInvalidException}.
     * 
     * Best practice is to return false to ensure that after a core validation failure, the verification
     * fails.
     *
     * @return           true or false
     * @throws Exception
     */
    boolean ignoreCoreValidationFailure() throws Exception; // NOPMD

    void end() throws Exception; // NOPMD

}