xmltooling/signature/Signature.h

   1 /*
   2  *  Copyright 2001-2006 Internet2
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * @file Signature.h
  19  *
  20  * XMLObject representing XML Digital Signature, version 20020212, Signature element.
  21  */
  22
  23 #if !defined(__xmltooling_sig_h__) && !defined(XMLTOOLING_NO_XMLSEC)
  24 #define __xmltooling_sig_h__
  25
  26 #include <xmltooling/exceptions.h>
  27 #include <xmltooling/XMLObjectBuilder.h>
  28 #include <xmltooling/signature/ContentReference.h>
  29 #include <xmltooling/util/XMLConstants.h>
  30
  31 #include <xsec/dsig/DSIGSignature.hpp>
  32
  33 /**
  34  * @namespace xmlsignature
  35  * Public namespace of XML Signature classes
  36  */
  37 namespace xmlsignature {
  38
  39     class XMLTOOL_API KeyInfo;
  40
  41     /**
  42      * XMLObject representing XML Digital Signature, version 20020212, Signature element.
  43      * The default signature settings include Exclusive c14n w/o comments, SHA-1 digests,
  44      * and RSA-SHA1 signing.
  45      */
  46     class XMLTOOL_API Signature : public virtual xmltooling::XMLObject
  47     {
  48     public:
  49         virtual ~Signature() {}
  50
  51         /** Element local name */
  52         static const XMLCh LOCAL_NAME[];
  53
  54         /**
  55          * Sets the canonicalization method for the ds:SignedInfo element
  56          *
  57          * @param c14n  the canonicalization method
  58          */
  59         virtual void setCanonicalizationMethod(const XMLCh* c14n)=0;
  60
  61         /**
  62          * Sets the signing algorithm for the signature.
  63          *
  64          * @param sm    the signature algorithm
  65          */
  66         virtual void setSignatureAlgorithm(const XMLCh* sm)=0;
  67
  68         /**
  69          * Sets the signing key used to create the signature.
  70          *
  71          * @param signingKey the secret/private key used to create the signature
  72          */
  73         virtual void setSigningKey(XSECCryptoKey* signingKey)=0;
  74
  75         /**
  76          * Sets a KeyInfo object to embed in the Signature.
  77          *
  78          * @param keyInfo   pointer to a KeyInfo object, or NULL
  79          */
  80         virtual void setKeyInfo(KeyInfo* keyInfo)=0;
  81
  82         /**
  83          * Gets the KeyInfo object associated with the Signature.
  84          * This is <strong>NOT</strong> provided for access to the
  85          * data associated with an unmarshalled signature. It is
  86          * used only in the creation of signatures. Access to data
  87          * for validation purposes is provided through the native
  88          * DSIGSignature object.
  89          *
  90          * @return  pointer to a KeyInfo object, or NULL
  91          */
  92         virtual KeyInfo* getKeyInfo() const=0;
  93
  94         /**
  95          * Sets the ContentReference object to the Signature to be applied
  96          * when the signature is created.
  97          *
  98          * @param reference the reference to attach, or NULL
  99          */
 100         virtual void setContentReference(ContentReference* reference)=0;
 101
 102         /**
 103          * Gets the ContentReference object associated with the Signature.
 104          * This is <strong>NOT</strong> provided for access to the
 105          * data associated with an unmarshalled signature. It is
 106          * used only in the creation of signatures. Access to data
 107          * for validation purposes is provided through the native
 108          * DSIGSignature object.
 109          *
 110          * @return  pointer to a ContentReference object, or NULL
 111          */
 112         virtual ContentReference* getContentReference() const=0;
 113
 114
 115         /**
 116          * Gets the native Apache signature object, if present.
 117          *
 118          * @return  the native Apache signature interface
 119          */
 120         virtual DSIGSignature* getXMLSignature() const=0;
 121
 122         /**
 123          * Compute and append the signature based on the assigned
 124          * ContentReference, KeyInfo, and signing key.
 125          */
 126         virtual void sign()=0;
 127
 128         /**
 129          * Type-safe clone operation.
 130          *
 131          * @return  copy of object
 132          */
 133         virtual Signature* cloneSignature() const=0;
 134
 135     protected:
 136         Signature() {}
 137     };
 138
 139     /**
 140      * Builder for Signature objects.
 141      */
 142     class XMLTOOL_API SignatureBuilder : public xmltooling::XMLObjectBuilder
 143     {
 144     public:
 145         virtual Signature* buildObject(
 146             const XMLCh* nsURI, const XMLCh* localName, const XMLCh* prefix=NULL, const xmltooling::QName* schemaType=NULL
 147             ) const;
 148
 149         /**
 150          * Default builder
 151          *
 152          * @return empty Signature object
 153          */
 154         virtual Signature* buildObject() const;
 155
 156         static Signature* buildSignature() {
 157             const SignatureBuilder* b = dynamic_cast<const SignatureBuilder*>(
 158                 xmltooling::XMLObjectBuilder::getBuilder(
 159                     xmltooling::QName(xmltooling::XMLConstants::XMLSIG_NS,Signature::LOCAL_NAME)
 160                     )
 161                 );
 162             if (b)
 163                 return b->buildObject();
 164             throw xmltooling::XMLObjectException("Unable to obtain typed builder for Signature.");
 165         }
 166     };
 167
 168     DECL_XMLTOOLING_EXCEPTION(SignatureException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmlsignature,xmltooling::XMLSecurityException,Exceptions in signature processing);
 169
 170 };
 171
 172 #endif /* __xmltooling_sig_h__ */