Microsoft Information Protection (MIP) SDK for C++: Reference 1.15
Doxygen-generated documentation for MIP SDK written in C++
Loading...
Searching...
No Matches
protection_descriptor.h
Go to the documentation of this file.
1/*
2 *
3 * Copyright (c) Microsoft Corporation.
4 * All rights reserved.
5 *
6 * This code is licensed under the MIT License.
7 *
8 * Permission is hereby granted, free of charge, to any person obtaining a copy
9 * of this software and associated documentation files(the "Software"), to deal
10 * in the Software without restriction, including without limitation the rights
11 * to use, copy, modify, merge, publish, distribute, sublicense, and / or sell
12 * copies of the Software, and to permit persons to whom the Software is
13 * furnished to do so, subject to the following conditions :
14 *
15 * The above copyright notice and this permission notice shall be included in
16 * all copies or substantial portions of the Software.
17 *
18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE
21 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
24 * THE SOFTWARE.
25 *
26 */
27/**
28 * @brief Defines ProtectionDescriptor interface
29 *
30 * @file protection_descriptor.h
31 */
32
33#ifndef API_MIP_PROTECTION_DESCRIPTOR_H_
34#define API_MIP_PROTECTION_DESCRIPTOR_H_
35
36#include <chrono>
37#include <map>
38#include <memory>
39#include <string>
40
41#include "mip/mip_namespace.h"
42#include "mip/user_rights.h"
43#include "mip/user_roles.h"
45
46MIP_NAMESPACE_BEGIN
47
48/**
49 * @brief Describes whether protection is based off a template or ad-hoc (custom)
50 */
51enum class ProtectionType {
52 TemplateBased = 0, /**< Handle was created from a template */
53 Custom = 1, /**< Handle was created ad hoc */
54};
55
56/**
57 * @brief Label information for a template or ad-hoc (custom) protection.
58 *
59 */
60struct LabelInfo {
61 LabelInfo(const std::string& _labelId, const std::string& _tenantId) {
62 labelId = _labelId;
63 tenantId = _tenantId;
64 }
65 std::string labelId;
66 std::string tenantId;
67};
68
69/**
70* @brief Description of protection associated with a piece of content
71*/
73public:
74
75 /**
76 * @brief Gets type of protection, whether it originated from protection SDK template or not
77 *
78 * @return Type of protection
79 */
80 virtual ProtectionType GetProtectionType() const = 0;
81
82 /**
83 * @brief Gets owner for the protection
84 *
85 * @return Owner of protection
86 */
87 virtual std::string GetOwner() const = 0;
88
89 /**
90 * @brief Gets protection name
91 *
92 * @return Protection name
93 */
94 virtual std::string GetName() const = 0;
95
96 /**
97 * @brief Gets protection description
98 *
99 * @return Protection description
100 */
101 virtual std::string GetDescription() const = 0;
102
103 /**
104 * @brief Gets the protection template ID, if any
105 *
106 * @return Template ID
107 */
108 virtual std::string GetTemplateId() const = 0;
109
110 /**
111 * @brief Gets the label Info, if any
112 *
113 * @return Label Info
114 *
115 * @note This property will be populated in ProtectionDescriptors for preexisting protected content & for UDP label based protection. It is
116 * a field populated by the server at the moment protected content is consumed. For UDP label based protection, its populated from label and tenant id values set by client.
117 */
118 virtual LabelInfo GetLabelInfo() const = 0;
119
120 /**
121 * @brief Gets the label ID, if any
122 *
123 * @return Label ID
124 *
125 * @note This property will be populated in ProtectionDescriptors for preexisting protected content & for UDP label based protection. It is
126 * a field populated by the server at the moment protected content is consumed. For UDP label based protection, its populated from labelId value set by client.
127 */
128 virtual std::string GetLabelId() const = 0;
129
130 /**
131 * @brief Gets the Content ID, if any
132 *
133 * @return Content ID
134 *
135 * @note Publishing licenses will have this identifier surrounded by curly braces "{}".
136 * Those braces are removed from the value returned here
137 */
138 virtual std::string GetContentId() const = 0;
139
140 /**
141 * @brief Gets collection of users-to-rights mappings
142
143 * @return Collection of users-to-rights mappings
144 *
145 * @note The value of the UserRights property will be empty if the current user doesn't have access to this
146 * information (that is, if the user is not the owner and does not have the VIEWRIGHTSDATA right).
147 */
148 virtual std::vector<UserRights> GetUserRights() const = 0;
149
150 /**
151 * @brief Gets collection of users-to-roles mappings
152 *
153 * @return Collection of users-to-roles mappings
154 */
155 virtual std::vector<UserRoles> GetUserRoles() const = 0;
156
157 /**
158 * @brief Checks if content has an expiration time or not
159 *
160 * @return True if content can expire, else false
161 */
162 virtual bool DoesContentExpire() const = 0;
163
164 /**
165 * @brief Gets protection expiration time
166 *
167 * @return Protection expiration time
168 */
169 virtual std::chrono::time_point<std::chrono::system_clock> GetContentValidUntil() const = 0;
170
171 /**
172 * @brief Gets if protection allows offline content access or not
173 *
174 * @return If protection allows offline content access or not (default = true)
175 */
176 virtual bool DoesAllowOfflineAccess() const = 0;
177
178 /**
179 * @brief Gets protection referrer address
180 *
181 * @return Protection referrer address
182 *
183 * @note The referrer is a URI that is displayable to the user if they cannot unprotect the content. It contains
184 * information on how that user can gain permission to access the content.
185 */
186 virtual std::string GetReferrer() const = 0;
187
188 /**
189 * @brief Gets app-specific data that was encrypted
190 *
191 * @return App-specific data
192 *
193 * @note A ProtectionHandler may hold a dictionary of app-specific data that was encrypted by the protection
194 * service. This encrypted data is independent of the signed data accessible via ProtectionDescriptor::GetSignedAppData
195 */
196 virtual std::map<std::string, std::string> GetEncryptedAppData() const = 0;
197
198 /**
199 * @brief Gets the app-specific data that was signed
200 *
201 * @return App-specific data
202 *
203 * @note A ProtectionHandler may hold a dictionary of app-specific data that was signed by the protection service.
204 * This signed data is independent of the encrypted data accessible via ProtectionDescriptor::GetEncryptedAppData
205 */
206 virtual std::map<std::string, std::string> GetSignedAppData() const = 0;
207
208 /**
209 * @brief Gets the double key url to be used for custom protection
210 *
211 * @return Double key url
212 *
213 * @note The double key URL that is used in custom requests to protect information with a second key. Needed for key generation.
214 */
215 virtual std::string GetDoubleKeyUrl() const = 0;
216
217 /**
218 * @brief Gets the serialized template, if any
219 *
220 * @return Serialized template
221 */
222 virtual std::shared_ptr<const std::vector<uint8_t>> GetSerializedTemplate() const = 0;
223
224 /**
225 * @brief Gets the dynamic watermark configured for this content if any
226 *
227 * @return Shared pointer to the DynamicWatermark object
228 */
229 virtual std::shared_ptr<const DynamicWatermark> GetDynamicWatermark() const = 0;
230
231 /** @cond DOXYGEN_HIDE */
232 virtual ~ProtectionDescriptor() {}
233protected:
235 /** @endcond */
236};
237
238MIP_NAMESPACE_END
239
240#endif //API_MIP_PROTECTION_DESCRIPTOR_H_
Description of protection associated with a piece of content.
virtual std::map< std::string, std::string > GetSignedAppData() const =0
Gets the app-specific data that was signed.
virtual std::map< std::string, std::string > GetEncryptedAppData() const =0
Gets app-specific data that was encrypted.
virtual std::string GetContentId() const =0
Gets the Content ID, if any.
virtual std::shared_ptr< const std::vector< uint8_t > > GetSerializedTemplate() const =0
Gets the serialized template, if any.
virtual std::string GetReferrer() const =0
Gets protection referrer address.
virtual std::string GetDoubleKeyUrl() const =0
Gets the double key url to be used for custom protection.
virtual std::vector< UserRights > GetUserRights() const =0
Gets collection of users-to-rights mappings.
virtual LabelInfo GetLabelInfo() const =0
Gets the label Info, if any.
virtual std::shared_ptr< const DynamicWatermark > GetDynamicWatermark() const =0
Gets the dynamic watermark configured for this content if any.
virtual std::string GetDescription() const =0
Gets protection description.
virtual std::string GetOwner() const =0
Gets owner for the protection.
virtual std::string GetLabelId() const =0
Gets the label ID, if any.
virtual std::chrono::time_point< std::chrono::system_clock > GetContentValidUntil() const =0
Gets protection expiration time.
virtual std::string GetTemplateId() const =0
Gets the protection template ID, if any.
virtual ProtectionType GetProtectionType() const =0
Gets type of protection, whether it originated from protection SDK template or not.
virtual bool DoesContentExpire() const =0
Checks if content has an expiration time or not.
virtual std::vector< UserRoles > GetUserRoles() const =0
Gets collection of users-to-roles mappings.
virtual bool DoesAllowOfflineAccess() const =0
Gets if protection allows offline content access or not.
virtual std::string GetName() const =0
Gets protection name.
Defines DynamicWatermark interface.
MIP namespace macros.
ProtectionType
Describes whether protection is based off a template or ad-hoc (custom)
@ TemplateBased
Handle was created from a template.
@ Custom
Handle was created ad hoc.
Label information for a template or ad-hoc (custom) protection.
LabelInfo(const std::string &_labelId, const std::string &_tenantId)
std::string labelId
std::string tenantId
Defines UserRights class.
Defines UserRoles class.