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