saml/binding/SAMLArtifact.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 saml/binding/SAMLArtifact.h
  23  *
  24  * Base class for SAML 1.x and 2.0 artifacts.
  25  */
  26
  27 #ifndef __saml_artifact_h__
  28 #define __saml_artifact_h__
  29
  30 #include <saml/base.h>
  31
  32 #include <string>
  33 #include <xmltooling/exceptions.h>
  34
  35 namespace opensaml {
  36
  37 #if defined (_MSC_VER)
  38     #pragma warning( push )
  39     #pragma warning( disable : 4251 )
  40 #endif
  41
  42     /**
  43      * Base class for SAML 1.x and 2.0 artifacts.
  44      */
  45     class SAML_API SAMLArtifact
  46     {
  47         SAMLArtifact& operator=(const SAMLArtifact& src);
  48     public:
  49         virtual ~SAMLArtifact();
  50
  51         /**
  52          * Returns artifact encoded into null-terminated base64 for transmission.
  53          */
  54         virtual std::string encode() const;
  55
  56         /**
  57          * Builds a duplicate, independent artifact of the same type.
  58          *
  59          * @return the new artifact
  60          */
  61         virtual SAMLArtifact* clone() const=0;
  62
  63         /**
  64          * Returns all of the raw binary data that makes up the artifact.
  65          * The result is NOT null-terminated.
  66          *
  67          * @return the binary artifact data
  68          */
  69         virtual std::string getBytes() const;
  70
  71         /**
  72          * Returns the binary type code of the artifact.
  73          * The result MAY contain embedded null characters.
  74          *
  75          * @return the binary type code
  76          */
  77         virtual std::string getTypeCode() const;
  78
  79         /**
  80          * Returns the binary artifact data following the type code.
  81          * The result MAY contain embedded null characters.
  82          *
  83          * @return the binary artifact data
  84          */
  85         virtual std::string getRemainingArtifact() const;
  86
  87         /**
  88          * Returns a string that identifies the source of the artifact.
  89          * The exact form this takes depends on the type but should match
  90          * the syntax needed for metadata lookup.
  91          *
  92          * @return null-terminated source string
  93          */
  94         virtual std::string getSource() const=0;
  95
  96         /**
  97          * Returns the binary data that references the message (2.0) or assertion (1.x)
  98          * The exact form this takes depends on the type.
  99          * The result MAY contain embedded null characters.
 100          *
 101          * @return the binary reference data
 102          */
 103         virtual std::string getMessageHandle() const=0;
 104
 105         /** Length of type code */
 106         static const unsigned int TYPECODE_LENGTH;
 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 char* s);
 116
 117         /**
 118          * Parses a base64-encoded null-terminated string into an artifact,
 119          * if the type is known.
 120          *
 121          * @param s base64-encoded artifact
 122          * @return the decoded artifact
 123          */
 124         static SAMLArtifact* parse(const XMLCh* s);
 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);
 145
 146         /** Raw binary data that makes up an artifact. */
 147         std::string m_raw;
 148     };
 149
 150 #if defined (_MSC_VER)
 151     #pragma warning( pop )
 152 #endif
 153
 154     DECL_XMLTOOLING_EXCEPTION(ArtifactException,SAML_EXCEPTIONAPI(SAML_API),opensaml,xmltooling::XMLToolingException,Exceptions related to artifact parsing);
 155
 156     /**
 157      * Registers SAMLArtifact subclasses into the runtime.
 158      */
 159     void SAML_API registerSAMLArtifacts();
 160 };
 161
 162 #endif /* __saml_artifact_h__ */