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 #include <xmltooling/exceptions.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
  62         /**
  63          * Returns the binary type code of the artifact.
  64          * The result MAY contain embedded null characters.
  65          *
  66          * @return the binary type code
  67          */
  68         virtual std::string getTypeCode() const;
  69
  70         /**
  71          * Returns the binary artifact data following the type code.
  72          * The result MAY contain embedded null characters.
  73          *
  74          * @return the binary artifact data
  75          */
  76         virtual std::string getRemainingArtifact() const;
  77
  78         /**
  79          * Returns a string that identifies the source of the artifact.
  80          * The exact form this takes depends on the type but should match
  81          * the syntax needed for metadata lookup.
  82          *
  83          * @return null-terminated source string
  84          */
  85         virtual std::string getSource() const=0;
  86
  87         /**
  88          * Returns the binary data that references the message (2.0) or assertion (1.x)
  89          * The exact form this takes depends on the type.
  90          * The result MAY contain embedded null characters.
  91          *
  92          * @return the binary reference data
  93          */
  94         virtual std::string getMessageHandle() const=0;
  95
  96         /** Length of type code */
  97         static const unsigned int TYPECODE_LENGTH;
  98
  99         /**
 100          * Parses a base64-encoded null-terminated string into an artifact,
 101          * if the type is known.
 102          *
 103          * @param s base64-encoded artifact
 104          * @return the decoded artifact
 105          */
 106         static SAMLArtifact* parse(const char* s);
 107
 108         /**
 109          * Parses a base64-encoded null-terminated string into an artifact,
 110          * if the type is known.
 111          *
 112          * @param s base64-encoded artifact
 113          * @return the decoded artifact
 114          */
 115         static SAMLArtifact* parse(const XMLCh* s);
 116
 117         /**
 118          * Converts binary data to hex notation.
 119          *
 120          * @param s the bytes to convert
 121          * @return  the data in hex form, 2 characters per byte
 122          */
 123         static std::string toHex(const std::string& s);
 124
 125     protected:
 126         SAMLArtifact();
 127
 128         /**
 129          * Decodes a base64-encoded artifact into its raw form.
 130          *
 131          * @param s NULL-terminated base64-encoded string
 132          */
 133         SAMLArtifact(const char* s);
 134
 135         SAMLArtifact(const SAMLArtifact& src);
 136
 137         /** Raw binary data that makes up an artifact. */
 138         std::string m_raw;
 139     };
 140
 141     DECL_XMLTOOLING_EXCEPTION(ArtifactException,SAML_EXCEPTIONAPI(SAML_API),opensaml,xmltooling::XMLToolingException,Exceptions related to artifact parsing);
 142
 143     /**
 144      * Registers SAMLArtifact subclasses into the runtime.
 145      */
 146     void SAML_API registerSAMLArtifacts();
 147 };
 148
 149 #endif /* __saml_artifact_h__ */