xmltooling/signature/Signature.h

   1 /**
   2  * Licensed to the University Corporation for Advanced Internet
   3  * Development, Inc. (UCAID) under one or more contributor license
   4  * agreements. See the NOTICE file distributed with this work for
   5  * additional information regarding copyright ownership.
   6  *
   7  * UCAID licenses this file to you under the Apache License,
   8  * Version 2.0 (the "License"); you may not use this file except
   9  * in compliance with the License. You may obtain a copy of the
  10  * License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing,
  15  * software distributed under the License is distributed on an
  16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
  17  * either express or implied. See the License for the specific
  18  * language governing permissions and limitations under the License.
  19  */
  20
  21 /**
  22  * @file xmltooling/signature/Signature.h
  23  *
  24  * XMLObject representing XML Digital Signature, version 20020212, Signature element.
  25  */
  26
  27 #if !defined(__xmltooling_sig_h__) && !defined(XMLTOOLING_NO_XMLSEC)
  28 #define __xmltooling_sig_h__
  29
  30 #include <xmltooling/exceptions.h>
  31 #include <xmltooling/ConcreteXMLObjectBuilder.h>
  32
  33 class DSIGSignature;
  34 class XSECCryptoKey;
  35
  36 /**
  37  * @namespace xmlsignature
  38  * Public namespace of XML Signature classes
  39  */
  40 namespace xmlsignature {
  41
  42     class XMLTOOL_API ContentReference;
  43     class XMLTOOL_API KeyInfo;
  44
  45     /**
  46      * XMLObject representing XML Digital Signature, version 20020212, Signature element.
  47      * The default signature settings include Exclusive c14n w/o comments, SHA-1 digests,
  48      * and RSA-SHA1 signing.
  49      */
  50     class XMLTOOL_API Signature : public virtual xmltooling::XMLObject
  51     {
  52     public:
  53         virtual ~Signature();
  54
  55         /** Element local name */
  56         static const XMLCh LOCAL_NAME[];
  57
  58         /**
  59          * Gets the canonicalization method for the ds:SignedInfo element.
  60          *
  61          * @return the canonicalization method
  62          */
  63         virtual const XMLCh* getCanonicalizationMethod() const=0;
  64
  65         /**
  66          * Gets the signing algorithm for the signature.
  67          *
  68          * @return    the signature algorithm, or nullptr if indeterminate
  69          */
  70         virtual const XMLCh* getSignatureAlgorithm() const=0;
  71
  72         /**
  73          * Sets the canonicalization method for the ds:SignedInfo element.
  74          *
  75          * @param c14n  the canonicalization method
  76          */
  77         virtual void setCanonicalizationMethod(const XMLCh* c14n)=0;
  78
  79         /**
  80          * Sets the signing algorithm for the signature.
  81          *
  82          * @param sm    the signature algorithm
  83          */
  84         virtual void setSignatureAlgorithm(const XMLCh* sm)=0;
  85
  86         /**
  87          * Sets the signing key used to create the signature.
  88          *
  89          * @param signingKey the secret/private key used to create the signature
  90          */
  91         virtual void setSigningKey(XSECCryptoKey* signingKey)=0;
  92
  93         /**
  94          * Sets a KeyInfo object to embed in the Signature.
  95          *
  96          * @param keyInfo   pointer to a KeyInfo object, or nullptr
  97          */
  98         virtual void setKeyInfo(KeyInfo* keyInfo)=0;
  99
 100         /**
 101          * Gets the KeyInfo object associated with the Signature.
 102          * This is <strong>NOT</strong> provided for access to the
 103          * data associated with an unmarshalled signature. It is
 104          * used only in the creation of signatures. Access to data
 105          * for validation purposes is provided through the native
 106          * DSIGSignature object.
 107          *
 108          * @return  pointer to a KeyInfo object, or nullptr
 109          */
 110         virtual KeyInfo* getKeyInfo() const=0;
 111
 112         /**
 113          * Sets the ContentReference object to the Signature to be applied
 114          * when the signature is created.
 115          *
 116          * @param reference the reference to attach, or nullptr
 117          */
 118         virtual void setContentReference(ContentReference* reference)=0;
 119
 120         /**
 121          * Gets the ContentReference object associated with the Signature.
 122          * This is <strong>NOT</strong> provided for access to the
 123          * data associated with an unmarshalled signature. It is
 124          * used only in the creation of signatures. Access to data
 125          * for validation purposes is provided through the native
 126          * DSIGSignature object.
 127          *
 128          * @return  pointer to a ContentReference object, or nullptr
 129          */
 130         virtual ContentReference* getContentReference() const=0;
 131
 132
 133         /**
 134          * Gets the native Apache signature object, if present.
 135          *
 136          * @return  the native Apache signature interface
 137          */
 138         virtual DSIGSignature* getXMLSignature() const=0;
 139
 140         /**
 141          * Compute and append the signature based on the assigned
 142          * ContentReference, KeyInfo, and signing key.
 143          *
 144          * @param credential    optional source of signing key and KeyInfo
 145          */
 146         virtual void sign(const xmltooling::Credential* credential=nullptr)=0;
 147
 148         /**
 149          * Type-safe clone operation.
 150          *
 151          * @return  copy of object
 152          */
 153         virtual Signature* cloneSignature() const=0;
 154
 155         /**
 156          * Sign the input data and return a base64-encoded signature. The signature value
 157          * <strong>MUST NOT</strong> contain any embedded linefeeds.
 158          *
 159          * <p>Allows specialized applications to create raw signatures over any input using
 160          * the same cryptography layer as XML Signatures use.
 161          *
 162          * @param key               key to sign with, will <strong>NOT</strong> be freed
 163          * @param sigAlgorithm      XML signature algorithm identifier
 164          * @param in                input data
 165          * @param in_len            size of input data in bytes
 166          * @param out               output buffer
 167          * @param out_len           size of output buffer in bytes
 168          * @return  size in bytes of base64-encoded signature
 169          */
 170         static unsigned int createRawSignature(
 171             XSECCryptoKey* key,
 172             const XMLCh* sigAlgorithm,
 173             const char* in,
 174             unsigned int in_len,
 175             char* out,
 176             unsigned int out_len
 177             );
 178
 179         /**
 180          * Verifies a base-64 encoded signature over the input data.
 181          *
 182          * <p>Allows specialized applications to verify raw signatures over any input using
 183          * the same cryptography layer as XML Signatures use.
 184          *
 185          * @param key               key to verify with, will <strong>NOT</strong> be freed
 186          * @param sigAlgorithm      XML signature algorithm identifier
 187          * @param signature         base64-encoded signature value
 188          * @param in                input data
 189          * @param in_len            size of input data in bytes
 190          * @return  true iff signature verifies
 191          */
 192         static bool verifyRawSignature(
 193             XSECCryptoKey* key,
 194             const XMLCh* sigAlgorithm,
 195             const char* signature,
 196             const char* in,
 197             unsigned int in_len
 198             );
 199
 200     protected:
 201         /** Default constructor. */
 202         Signature();
 203     };
 204
 205     /**
 206      * Builder for Signature objects.
 207      */
 208     class XMLTOOL_API SignatureBuilder : public xmltooling::ConcreteXMLObjectBuilder
 209     {
 210     public:
 211 #ifdef HAVE_COVARIANT_RETURNS
 212         virtual Signature* buildObject(
 213 #else
 214         virtual xmltooling::XMLObject* buildObject(
 215 #endif
 216             const XMLCh* nsURI, const XMLCh* localName, const XMLCh* prefix=nullptr, const xmltooling::QName* schemaType=nullptr
 217             ) const;
 218
 219         /**
 220          * Default builder
 221          *
 222          * @return empty Signature object
 223          */
 224 #ifdef HAVE_COVARIANT_RETURNS
 225         virtual Signature* buildObject() const;
 226 #else
 227         virtual xmltooling::XMLObject* buildObject() const;
 228 #endif
 229         /** Singleton builder. */
 230         static Signature* buildSignature();
 231     };
 232
 233     DECL_XMLTOOLING_EXCEPTION(SignatureException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmlsignature,xmltooling::XMLSecurityException,Exceptions in signature processing);
 234
 235 };
 236
 237 #endif /* __xmltooling_sig_h__ */