saml/binding/SAMLArtifact.h

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