xmltooling/signature/Signature.h

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