xmltooling/signature/Signature.h

   1 /*
   2  *  Copyright 2001-2007 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         /**
 136          * Sign the input data and return a base64-encoded signature. The signature value
 137          * <strong>MUST NOT</strong> contain any embedded linefeeds.
 138          *
 139          * <p>Allows specialized applications to create raw signatures over any input using
 140          * the same cryptography layer as XML Signatures use.
 141          *
 142          * @param key               key to sign with, will <strong>NOT</strong> be freed
 143          * @param sigAlgorithm      XML signature algorithm identifier
 144          * @param in                input data
 145          * @param in_len            size of input data in bytes
 146          * @param out               output buffer
 147          * @param out_len           size of output buffer in bytes
 148          * @return  size in bytes of base64-encoded signature
 149          */
 150         static unsigned int createRawSignature(
 151             XSECCryptoKey* key,
 152             const XMLCh* sigAlgorithm,
 153             const char* in,
 154             unsigned int in_len,
 155             char* out,
 156             unsigned int out_len
 157             );
 158
 159         /**
 160          * Verifies a base-64 encoded signature over the input data.
 161          *
 162          * <p>Allows specialized applications to verify raw signatures over any input using
 163          * the same cryptography layer as XML Signatures use.
 164          *
 165          * @param key               key to verify with, will <strong>NOT</strong> be freed
 166          * @param sigAlgorithm      XML signature algorithm identifier
 167          * @param signature         base64-encoded signature value
 168          * @param in                input data
 169          * @param in_len            size of input data in bytes
 170          * @return  true iff signature verifies
 171          */
 172         static bool verifyRawSignature(
 173             XSECCryptoKey* key,
 174             const XMLCh* sigAlgorithm,
 175             const char* signature,
 176             const char* in,
 177             unsigned int in_len
 178             );
 179
 180     protected:
 181         Signature() {}
 182     };
 183
 184     /**
 185      * Builder for Signature objects.
 186      */
 187     class XMLTOOL_API SignatureBuilder : public xmltooling::XMLObjectBuilder
 188     {
 189     public:
 190         virtual Signature* buildObject(
 191             const XMLCh* nsURI, const XMLCh* localName, const XMLCh* prefix=NULL, const xmltooling::QName* schemaType=NULL
 192             ) const;
 193
 194         /**
 195          * Default builder
 196          *
 197          * @return empty Signature object
 198          */
 199 #ifdef HAVE_COVARIANT_RETURNS
 200         virtual Signature* buildObject() const;
 201 #else
 202         virtual xmltooling::XMLObject* buildObject() const;
 203 #endif
 204         /** Singleton builder. */
 205         static Signature* buildSignature() {
 206             const SignatureBuilder* b = dynamic_cast<const SignatureBuilder*>(
 207                 xmltooling::XMLObjectBuilder::getBuilder(
 208                     xmltooling::QName(xmlconstants::XMLSIG_NS,Signature::LOCAL_NAME)
 209                     )
 210                 );
 211             if (b) {
 212 #ifdef HAVE_COVARIANT_RETURNS
 213                 return b->buildObject();
 214 #else
 215                 return dynamic_cast<Signature*>(b->buildObject());
 216 #endif
 217             }
 218             throw xmltooling::XMLObjectException("Unable to obtain typed builder for Signature.");
 219         }
 220     };
 221
 222     DECL_XMLTOOLING_EXCEPTION(SignatureException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmlsignature,xmltooling::XMLSecurityException,Exceptions in signature processing);
 223
 224 };
 225
 226 #endif /* __xmltooling_sig_h__ */