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/ArtifactMap.h
23  *
24  * Helper class for SAMLArtifact mapping and retrieval.
25  */
26 
27 #ifndef __saml_artmap_h__
28 #define __saml_artmap_h__
29 
30 #include <saml/base.h>
31 
32 #include <string>
33 #include <boost/scoped_ptr.hpp>
34 #include <xercesc/dom/DOM.hpp>
35 
36 namespace xmltooling {
37     class XMLTOOL_API StorageService;
38     class XMLTOOL_API XMLObject;
39 };
40 
41 namespace opensaml {
42 
43     class SAML_API SAMLArtifact;
44     class SAML_DLLLOCAL ArtifactMappings;
45 
46 #if defined (_MSC_VER)
47     #pragma warning( push )
48     #pragma warning( disable : 4251 )
49 #endif
50 
51     /**
52      * Helper class for SAMLArtifact mapping and retrieval.
53      */
54     class SAML_API ArtifactMap
55     {
56         MAKE_NONCOPYABLE(ArtifactMap);
57     public:
58 
59         /**
60          * Creates a map on top of a particular storage service context, or in-memory.
61          *
62          * @param storage       pointer to a StorageService, or nullptr to keep map in memory
63          * @param context       optional label for storage context
64          * @param artifactTTL   time to live in seconds, determines how long artifact remains valid
65          */
66         ArtifactMap(xmltooling::StorageService* storage=nullptr, const char* context=nullptr, unsigned int artifactTTL=180);
67 
68         /**
69          * Creates a map on top of a particular storage service context, or in-memory.
70          *
71          * @param e         root of a DOM with optional XML attributes for context and artifactTTL
72          * @param storage   pointer to a StorageService, or nullptr to keep map in memory
73          */
74         ArtifactMap(const xercesc::DOMElement* e, xmltooling::StorageService* storage=nullptr);
75 
76         virtual ~ArtifactMap();
77 
78         /**
79          * Associates XML content with an artifact and optionally a specific relying party.
80          * Specifying no relying party means that the first attempt to resolve the artifact
81          * will succeed. The XML content cannot have a parent object, and any existing references
82          * to the content will be invalidated.
83          *
84          * @param content       the XML content to map to an artifact
85          * @param artifact      the artifact representing the XML content
86          * @param relyingParty  entityID of the party authorized to resolve the artifact
87          * @return the generated artifact
88          */
89         virtual void storeContent(xmltooling::XMLObject* content, const SAMLArtifact* artifact, const char* relyingParty=nullptr);
90 
91         /**
92          * Retrieves the XML content represented by the artifact. The identity of the
93          * relying party can be supplied, if known. If the wrong party tries to resolve
94          * an artifact, an exception will be thrown and the mapping will be removed.
95          * The caller is responsible for freeing the XML content returned.
96          *
97          * @param artifact      the artifact representing the XML content
98          * @param relyingParty  entityID of the party trying to resolve the artifact
99          * @return the XML content
100          */
101         virtual xmltooling::XMLObject* retrieveContent(const SAMLArtifact* artifact, const char* relyingParty=nullptr);
102 
103         /**
104          * Retrieves the relying party to whom the artifact was issued.
105          *
106          * @param artifact  the artifact to check
107          * @return  entityID of the party to whom the artifact was issued, if any
108          */
109         virtual std::string getRelyingParty(const SAMLArtifact* artifact);
110 
111     private:
112         xmltooling::StorageService* m_storage;
113         std::string m_context;
114         boost::scoped_ptr<ArtifactMappings> m_mappings;
115         unsigned int m_artifactTTL;
116     };
117 
118 #if defined (_MSC_VER)
119     #pragma warning( pop )
120 #endif
121 
122 };
123 
124 #endif /* __saml_artmap_h__ */
125