/**
* 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.
* <p>
* Typically the handler throws an exception when a validation failure occurs.
*
* There is a certain order how the methods are called.
* <ul>
* <li>First, the method {@link #start()} is called when a core validation
* fails.
* <li>Then {@link #signatureValueValidationFailed(SignatureValue)} is called if
* the signature validation fails.
* <li>Then, for each reference in the signed info whose validation fails
* {@link #referenceValidationFailed(Reference)} is called.
* <li>Then, for each reference in the manifests whose validation fails, the
* method {@link #manifestReferenceValidationFailed(Reference)} is called.
* <li>Then, the method {@link #ignoreCoreValidationFailure()} is called where
* you can finally decide whether the processing should go on or be interrupted.
* <li>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.
* </ul>
* 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)}.
* <p>
* 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 <tt>true</tt> is returned then the verifier will go-on as if there was
* no validation failure. If <tt>false</tt> is returned than the verifier
* will throw an {@link XmlSignatureInvalidException}.
* <p>
* Best practice is to return <code>false</code> 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
}