xmltooling/signature/Signature.h

   1 /*
   2  *  Copyright 2001-2010 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 xmltooling/signature/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/ConcreteXMLObjectBuilder.h>
  28
  29 class DSIGSignature;
  30 class XSECCryptoKey;
  31
  32 /**
  33  * @namespace xmlsignature
  34  * Public namespace of XML Signature classes
  35  */
  36 namespace xmlsignature {
  37
  38     class XMLTOOL_API ContentReference;
  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          * Gets the canonicalization method for the ds:SignedInfo element.
  56          *
  57          * @return the canonicalization method
  58          */
  59         virtual const XMLCh* getCanonicalizationMethod() const=0;
  60
  61         /**
  62          * Gets the signing algorithm for the signature.
  63          *
  64          * @return    the signature algorithm, or NULL if indeterminate
  65          */
  66         virtual const XMLCh* getSignatureAlgorithm() const=0;
  67
  68         /**
  69          * Sets the canonicalization method for the ds:SignedInfo element.
  70          *
  71          * @param c14n  the canonicalization method
  72          */
  73         virtual void setCanonicalizationMethod(const XMLCh* c14n)=0;
  74
  75         /**
  76          * Sets the signing algorithm for the signature.
  77          *
  78          * @param sm    the signature algorithm
  79          */
  80         virtual void setSignatureAlgorithm(const XMLCh* sm)=0;
  81
  82         /**
  83          * Sets the signing key used to create the signature.
  84          *
  85          * @param signingKey the secret/private key used to create the signature
  86          */
  87         virtual void setSigningKey(XSECCryptoKey* signingKey)=0;
  88
  89         /**
  90          * Sets a KeyInfo object to embed in the Signature.
  91          *
  92          * @param keyInfo   pointer to a KeyInfo object, or NULL
  93          */
  94         virtual void setKeyInfo(KeyInfo* keyInfo)=0;
  95
  96         /**
  97          * Gets the KeyInfo object associated with the Signature.
  98          * This is <strong>NOT</strong> provided for access to the
  99          * data associated with an unmarshalled signature. It is
 100          * used only in the creation of signatures. Access to data
 101          * for validation purposes is provided through the native
 102          * DSIGSignature object.
 103          *
 104          * @return  pointer to a KeyInfo object, or NULL
 105          */
 106         virtual KeyInfo* getKeyInfo() const=0;
 107
 108         /**
 109          * Sets the ContentReference object to the Signature to be applied
 110          * when the signature is created.
 111          *
 112          * @param reference the reference to attach, or NULL
 113          */
 114         virtual void setContentReference(ContentReference* reference)=0;
 115
 116         /**
 117          * Gets the ContentReference object associated with the Signature.
 118          * This is <strong>NOT</strong> provided for access to the
 119          * data associated with an unmarshalled signature. It is
 120          * used only in the creation of signatures. Access to data
 121          * for validation purposes is provided through the native
 122          * DSIGSignature object.
 123          *
 124          * @return  pointer to a ContentReference object, or NULL
 125          */
 126         virtual ContentReference* getContentReference() const=0;
 127
 128
 129         /**
 130          * Gets the native Apache signature object, if present.
 131          *
 132          * @return  the native Apache signature interface
 133          */
 134         virtual DSIGSignature* getXMLSignature() const=0;
 135
 136         /**
 137          * Compute and append the signature based on the assigned
 138          * ContentReference, KeyInfo, and signing key.
 139          *
 140          * @param credential    optional source of signing key and KeyInfo
 141          */
 142         virtual void sign(const xmltooling::Credential* credential=NULL)=0;
 143
 144         /**
 145          * Type-safe clone operation.
 146          *
 147          * @return  copy of object
 148          */
 149         virtual Signature* cloneSignature() const=0;
 150
 151         /**
 152          * Sign the input data and return a base64-encoded signature. The signature value
 153          * <strong>MUST NOT</strong> contain any embedded linefeeds.
 154          *
 155          * <p>Allows specialized applications to create raw signatures over any input using
 156          * the same cryptography layer as XML Signatures use.
 157          *
 158          * @param key               key to sign with, will <strong>NOT</strong> be freed
 159          * @param sigAlgorithm      XML signature algorithm identifier
 160          * @param in                input data
 161          * @param in_len            size of input data in bytes
 162          * @param out               output buffer
 163          * @param out_len           size of output buffer in bytes
 164          * @return  size in bytes of base64-encoded signature
 165          */
 166         static unsigned int createRawSignature(
 167             XSECCryptoKey* key,
 168             const XMLCh* sigAlgorithm,
 169             const char* in,
 170             unsigned int in_len,
 171             char* out,
 172             unsigned int out_len
 173             );
 174
 175         /**
 176          * Verifies a base-64 encoded signature over the input data.
 177          *
 178          * <p>Allows specialized applications to verify raw signatures over any input using
 179          * the same cryptography layer as XML Signatures use.
 180          *
 181          * @param key               key to verify with, will <strong>NOT</strong> be freed
 182          * @param sigAlgorithm      XML signature algorithm identifier
 183          * @param signature         base64-encoded signature value
 184          * @param in                input data
 185          * @param in_len            size of input data in bytes
 186          * @return  true iff signature verifies
 187          */
 188         static bool verifyRawSignature(
 189             XSECCryptoKey* key,
 190             const XMLCh* sigAlgorithm,
 191             const char* signature,
 192             const char* in,
 193             unsigned int in_len
 194             );
 195
 196     protected:
 197         /** Default constructor. */
 198         Signature();
 199     };
 200
 201     /**
 202      * Builder for Signature objects.
 203      */
 204     class XMLTOOL_API SignatureBuilder : public xmltooling::ConcreteXMLObjectBuilder
 205     {
 206     public:
 207 #ifdef HAVE_COVARIANT_RETURNS
 208         virtual Signature* buildObject(
 209 #else
 210         virtual xmltooling::XMLObject* buildObject(
 211 #endif
 212             const XMLCh* nsURI, const XMLCh* localName, const XMLCh* prefix=NULL, const xmltooling::QName* schemaType=NULL
 213             ) const;
 214
 215         /**
 216          * Default builder
 217          *
 218          * @return empty Signature object
 219          */
 220 #ifdef HAVE_COVARIANT_RETURNS
 221         virtual Signature* buildObject() const;
 222 #else
 223         virtual xmltooling::XMLObject* buildObject() const;
 224 #endif
 225         /** Singleton builder. */
 226         static Signature* buildSignature();
 227     };
 228
 229     DECL_XMLTOOLING_EXCEPTION(SignatureException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmlsignature,xmltooling::XMLSecurityException,Exceptions in signature processing);
 230
 231 };
 232
 233 #endif /* __xmltooling_sig_h__ */