saml/binding/SAMLArtifact.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 saml/binding/SAMLArtifact.h
  19  *
  20  * Base class for SAML 1.x and 2.0 artifacts
  21  */
  22
  23 #ifndef __saml_artifact_h__
  24 #define __saml_artifact_h__
  25
  26 #include <saml/base.h>
  27
  28 #include <string>
  29 #include <xmltooling/unicode.h>
  30
  31 namespace opensaml {
  32
  33     /**
  34      * Base class for SAML 1.x and 2.0 artifacts.
  35      */
  36     class SAML_API SAMLArtifact
  37     {
  38         SAMLArtifact& operator=(const SAMLArtifact& src);
  39     public:
  40         virtual ~SAMLArtifact() {}
  41
  42         /**
  43          * Returns artifact encoded into null-terminated base64 for transmission.
  44          */
  45         virtual std::string encode() const;
  46
  47         /**
  48          * Builds a duplicate, independent artifact of the same type.
  49          *
  50          * @return the new artifact
  51          */
  52         virtual SAMLArtifact* clone() const=0;
  53
  54         /**
  55          * Returns all of the raw binary data that makes up the artifact.
  56          * The result is NOT null-terminated.
  57          *
  58          * @return the binary artifact data
  59          */
  60         virtual std::string getBytes() const {
  61             return m_raw;
  62         }
  63
  64         /**
  65          * Returns the binary type code of the artifact.
  66          * The result MAY contain embedded null characters.
  67          *
  68          * @return the binary type code
  69          */
  70         virtual std::string getTypeCode() const {
  71             return m_raw.substr(0,TYPECODE_LENGTH);
  72         }
  73
  74         /**
  75          * Returns the binary artifact data following the type code.
  76          * The result MAY contain embedded null characters.
  77          *
  78          * @return the binary artifact data
  79          */
  80         virtual std::string getRemainingArtifact() const {
  81             return m_raw.substr(TYPECODE_LENGTH);
  82         }
  83
  84         /**
  85          * Returns a string that identifies the source of the artifact.
  86          * The exact form this takes depends on the type but should match
  87          * the syntax needed for metadata lookup.
  88          *
  89          * @return null-terminated source string
  90          */
  91         virtual std::string getSource() const=0;
  92
  93         /**
  94          * Returns the binary data that references the message (2.0) or assertion (1.x)
  95          * The exact form this takes depends on the type.
  96          * The result MAY contain embedded null characters.
  97          *
  98          * @return the binary reference data
  99          */
 100         virtual std::string getMessageHandle() const=0;
 101
 102         /** Length of type code */
 103         static const unsigned int TYPECODE_LENGTH;
 104
 105         /**
 106          * Parses a base64-encoded null-terminated string into an artifact,
 107          * if the type is known.
 108          *
 109          * @param s base64-encoded artifact
 110          * @return the decoded artifact
 111          */
 112         static SAMLArtifact* parse(const char* s);
 113
 114         /**
 115          * Parses a base64-encoded null-terminated string into an artifact,
 116          * if the type is known.
 117          *
 118          * @param s base64-encoded artifact
 119          * @return the decoded artifact
 120          */
 121         static SAMLArtifact* parse(const XMLCh* s) {
 122             xmltooling::auto_ptr_char temp(s);
 123             return parse(temp.get());
 124         }
 125
 126         /**
 127          * Converts binary data to hex notation.
 128          *
 129          * @param s the bytes to convert
 130          * @return  the data in hex form, 2 characters per byte
 131          */
 132         static std::string toHex(const std::string& s);
 133
 134     protected:
 135         SAMLArtifact() {}
 136
 137         /**
 138          * Decodes a base64-encoded artifact into its raw form.
 139          *
 140          * @param s NULL-terminated base64-encoded string
 141          */
 142         SAMLArtifact(const char* s);
 143
 144         SAMLArtifact(const SAMLArtifact& src) : m_raw(src.m_raw) {}
 145
 146         /** Raw binary data that makes up an artifact. */
 147         std::string m_raw;
 148     };
 149
 150     DECL_XMLTOOLING_EXCEPTION(ArtifactException,SAML_EXCEPTIONAPI(SAML_API),opensaml,xmltooling::XMLToolingException,Exceptions related to artifact parsing);
 151
 152     /**
 153      * Registers SAMLArtifact subclasses into the runtime.
 154      */
 155     void SAML_API registerSAMLArtifacts();
 156 };
 157
 158 #endif /* __saml_artifact_h__ */