protection_handler_cc.h File Reference

Defines C-Style ProtectionHandler interface. More...

#include <stdint.h>
#include "mip_cc/common_types_cc.h"
#include "mip_cc/error_cc.h"
#include "mip_cc/protection_descriptor_cc.h"
#include "mip_cc/protection/protection_crypto_types_cc.h"
#include "mip_cc/result_cc.h"
#include "mip_cc/string_list_cc.h"

Go to the source code of this file.

Typedefs
typedef mip_cc_handle *	mip_cc_protection_handler
typedef mip_cc_handle *	mip_cc_protection_handler_publishing_settings
typedef mip_cc_handle *	mip_cc_protection_handler_consumption_settings

Enumerations
enum	mip_cc_pre_license_format { MIP_PRE_LICENSE_FORMAT_XML = 0 , MIP_PRE_LICENSE_FORMAT_JSON = 1 }
	Defines pre-license format. More...

Functions
	MIP_CC_API (mip_cc_result) MIP_CC_CreateProtectionHandlerPublishingSettings(const mip_cc_protection_descriptor descriptor
	Create a settings object used to create a protection handler for publishing new content.
	MIP_CC_API (void) MIP_CC_ReleaseProtectionHandlerPublishingSettings(mip_cc_protection_handler_publishing_settings settings)
	Release resources associated with a protection handler settings.

Variables
mip_cc_protection_handler_publishing_settings *	settings
mip_cc_protection_handler_publishing_settings mip_cc_error *	errorInfo
const bool	isDeprecatedAlgorithmPreferred
const bool	isAuditedExtractionAllowed
const bool	isPublishingFormatJson
const char *	delegatedUserEmail
const char *	preLicenseUserEmail
const char *	applicationScenarioId
const mip_cc_dictionary	customSettings
const int64_t	publishingLicenseBufferSize
const int64_t	preLicenseBufferSize
const int64_t const uint8_t *	publishingLicenseBuffer
const bool	isOfflineOnly
uint8_t const int64_t int64_t *	actualPublishingLicenseSize
mip_cc_pre_license_format	format
mip_cc_pre_license_format uint8_t *	preLicenseBuffer
mip_cc_pre_license_format uint8_t const int64_t int64_t *	actualPreLicenseSize
mip_cc_protection_descriptor *	descriptor
mip_cc_string_list *	rights
const int64_t	unprotectedSize
const int64_t const bool	includesFinalBlock
const int64_t const bool int64_t *	protectedSize
int64_t *	blockSize
int64_t *	issuedUserSize
char *	issuedUserBuffer
char const int64_t	issuedUserBufferSize
char const int64_t int64_t *	actualIssuedUserSize
int64_t *	ownerSize
char *	ownerBuffer
char const int64_t	ownerBufferSize
char const int64_t int64_t *	actualOwnerSize
mip_cc_guid *	contentId
bool *	doesUseDeprecatedAlgorithm
const int64_t	offsetFromStart
const int64_t const uint8_t *	inputBuffer
const int64_t const uint8_t const int64_t	inputBufferSize
const int64_t const uint8_t const int64_t uint8_t *	outputBuffer
const int64_t const uint8_t const int64_t uint8_t const int64_t	outputBufferSize
const int64_t const uint8_t const int64_t uint8_t const int64_t const bool	isFinal
const int64_t const uint8_t const int64_t uint8_t const int64_t const bool int64_t *	actualEncryptedSize
const int64_t const uint8_t const int64_t uint8_t const int64_t const bool int64_t *	actualDecryptedSize
mip_cc_cipher_mode *	cipherMode
const char *	capability
const char bool *	removed
mip_cc_string_list *	capabilities

Detailed Description

Defines C-Style ProtectionHandler interface.

Typedef Documentation

mip_cc_protection_handler

typedef mip_cc_handle* mip_cc_protection_handler

mip_cc_protection_handler_consumption_settings

typedef mip_cc_handle* mip_cc_protection_handler_consumption_settings

mip_cc_protection_handler_publishing_settings

typedef mip_cc_handle* mip_cc_protection_handler_publishing_settings

Enumeration Type Documentation

mip_cc_pre_license_format

enum mip_cc_pre_license_format

Defines pre-license format.

Enumerator
MIP_PRE_LICENSE_FORMAT_XML	Legacy XML/SOAP format used by MSIPC
MIP_PRE_LICENSE_FORMAT_JSON	JSON/REST format used by MIP SDK and RMS SDK

Function Documentation

MIP_CC_API() [1/2]

MIP_CC_API

(

mip_cc_result

)

const

Create a settings object used to create a protection handler for publishing new content.

Gets the set of supported capabilities being passed to RMS.

Remove a capability from the set of capabilities supported when calling RMS.

Add a capability to the set of capabilities supported when calling RMS.

Gets the cipher mode of the protection handler.

Decrypt a buffer.

Encrypt a buffer.

Gets whether or not protection handler uses deprecated crypto algorithm (ECB) for backwards compatibility.

Gets the content IE of protected content.

Gets the owner of protected content.

Gets size of buffer required to store the owner of protected content.

Gets the user that has been granted access to protected content.

Gets size of buffer required to store user that has been granted access to protected content.

Gets the block size (in bytes) for the cipher mode used by a protection handler.

Calculates size of protected content, factoring in padding, etc.

Gets list of rights granted to a user.

Gets protection descriptor.

Gets pre-license.

Gets size of pre-license (in bytes)

Gets publishing license.

Gets size of publishing license (in bytes)

Sets whether or not protection handler creation permits online HTTP operations.

Create a settings object used to create a protection handler for consuming existing content.

Configures custom settings, used for feature gating and testing.

Sets application scenario Id.

Sets pre-license user.

Sets delegated user.

Sets whether or not PL is in JSON format (default is XML)

Sets whether or not non-MIP-aware applications are allowed to open protected content.

Sets whether or not deprecated crypto algorithm (ECB) is preferred for backwards compatibility.

Parameters

descriptor	Protection details
settings	[Output] Newly-created settings instance
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Parameters

settings	Protection handler settings
isDeprecatedAlgorithmPreferred	Whether or not deprecated algorithm is preferred
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Parameters

settings	Protection handler settings
isAuditedExtractionAllowed	Whether or not non-MIP-aware applications are allowed to open protected content
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Parameters

settings	Protection handler settings
isPublishingFormatJson	Whether or not resulting PL should be in JSON format
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Parameters

settings	Protection handler settings
delegatedUserEmail	Email address of delegated user
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Note

A delegated user is specified when the authenticating user/application is acting on behalf of another user

Parameters

settings	Protection handler settings
preLicenseUserEmail	Email address of pre-license user
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Note

A pre-license user is specified when a pre-license should be fetched when publishing

Parameters

settings	Protection handler settings
applicationScenarioId	application scenario Id
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Parameters

settings	Protection handler settings
customSettings	Key/value pairs of custom settings
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Parameters

publishingLicenseBuffer	Buffer containing raw publishing license
publishingLicenseBufferSize	Size of publishing license buffer
settings	[Output] Newly-created settings instance
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Parameters

preLicenseBuffer	Buffer containing raw pre license buffer
preLicenseBufferSize	Size of pre license buffer
publishingLicenseBuffer	Buffer containing raw publishing license
publishingLicenseBufferSize	Size of publishing license buffer
settings	[Output] Newly-created settings instance
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Parameters

settings	Protection handler settings
isOfflineOnly	True if HTTP operations are forbidden, else false
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Note

If this is set to true, protection handler creation will only succeed if content has already been previously decrypted and its unexpired license is cached. A MIP_RESULT_ERROR_NETWORK result will be returned if cached content is not found.

Parameters

handler	Handler representing protected content
publishingLicenseBufferSize	[Output] Size of publishing license (in bytes)
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Parameters

handler	Handler representing protected content
publishingLicenseBuffer	[Output] Buffer to which publishing license will be written
publishingLicenseBufferSize	Size of publishing license buffer
actualPublishingLicenseSize	[Output] Actual size of publishing license (in bytes)
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Note

If publishingLicenseBuffer is null or insufficient, MIP_RESULT_ERROR_INSUFFICIENT_BUFFER will be returned and actualPublishingLicenseSize will be set to the minimum required buffer size.

Parameters

handler	Handler representing protected content
format	Pre-license format
preLicenseBufferSize	[Output] Size of pre-license (in bytes)
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Parameters

handler	Handler representing protected content
format	Pre-license format
preLicenseBuffer	[Output] Buffer to which pre-license will be written
preLicenseBufferSize	Size of pre-license buffer
actualPreLicenseSize	[Output] Actual size of pre-license (in bytes)
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Note

If preLicenseBuffer is null or insufficient, MIP_RESULT_ERROR_INSUFFICIENT_BUFFER will be returned and actualPreLicenseSize will be set to the minimum required buffer size.

Parameters

handler	Handler representing protected content
descriptor	[Output] Protection descriptor
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Parameters

handler	Handler representing protected content
rights	[Output] List of rights granted to a user, memory owned by caller
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Note

The 'rights' variable must be released by the caller by calling MIP_CC_ReleaseStringList

Parameters

handler	Handler representing protected content
unprotectedSize	Size of unprotected/cleartext content (in bytes)
includesFinalBlock	Describes if the unprotected content in question includes the final block or not. For example, in CBC4k encryption mode, non-final protected blocks are the same size as unprotected blocks, but final protected blocks are larger than their unprotected counterparts.
protectedSize	[Output] Size of protected content
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Parameters

handler	Handler representing protected content
blockSize	[Output] Block size (in bytes)
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Parameters

handler	Handler representing protected content
issuedUserSize	[Output] Size of buffer to hold issued user (in number of chars)
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Parameters

handler	Handler representing protected content
issuedUserBuffer	[Output] Buffer the issued user will be copied into.
issuedUserBufferSize	Size (in number of chars) of the issuedUserBuffer.
actualIssuedUserSize	[Output] Number of chars written to the buffer
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Note

If issuedUserBuffer is null or insufficient, MIP_RESULT_ERROR_INSUFFICIENT_BUFFER will be returned and actualIssuedUserSize will be set to the minimum required buffer size.

Parameters

handler	Handler representing protected content
ownerSize	[Output] Size of buffer to hold issued user (in number of chars)
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Parameters

handler	Handler representing protected content
ownerBuffer	[Output] Buffer the issued user will be copied into.
ownerBufferSize	Size (in number of chars) of the ownerBuffer.
actualOwnerSize	[Output] Number of chars written to the buffer
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Note

If ownerBuffer is null or insufficient, MIP_RESULT_ERROR_INSUFFICIENT_BUFFER will be returned and actualOwnerSize will be set to the minimum required buffer size.

Parameters

handler	Handler representing protected content
contentId	[Output] Content ID
errorInfo	[Output] (Optional) Failure info if operation result is error

Note

Publishing licenses will have this identifier surrounded by curly braces "{}". Those braces are removed from the value stored in contentId

Returns

Result code indicating success or failure

Parameters

handler	Handler representing protected content
doesUseDeprecatedAlgorithm	[Output] Whether or not protection handler uses deprecated crypto algorithm
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Parameters

offsetFromStart	Relative position of inputBuffer from the very beginning of the cleartext content
inputBuffer	Buffer of cleartext content that will be encrypted
inputBufferSize	Size (in bytes) of input buffer
outputBuffer	[Output] Buffer into which encrypted content will be copied
outputBufferSize	Size (in bytes) of output buffer
isFinal	If input buffer contains the final cleartext bytes or not
actualEncryptedSize	[Output] Actual size of encrypted content (in bytes)
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Parameters

offsetFromStart	Relative position of inputBuffer from the very beginning of the encrypted content
inputBuffer	Buffer of encrypted content that will be decrypted
inputBufferSize	Size (in bytes) of input buffer
outputBuffer	[Output] Buffer into which decrypted content will be copied
outputBufferSize	Size (in bytes) of output buffer
isFinal	If input buffer contains the final encrypted bytes or not
actualDecryptedSize	[Output] Actual size of encrypted content (in bytes)
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Parameters

handler	Handler representing protected content
cipherMode	[Output] The cipher mode
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Parameters

consumptionSettings	Consumption handler settings
capability	The capability to add to indicate a supported feature to RMS
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Parameters

consumptionSettings	Consumption handler settings
capability	The capability to remove from the supported features in RMS
removed	[Output] A boolean indiciating if the supplied capability was removed.
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Parameters

consumptionSettings	Consumption handler settings
capabilities	[Output] Gets the list of capabilities being passed to RMS
errorInfo	[Output] (Optional) Failure info if operation result is error

Returns

Result code indicating success or failure

Note

The returned 'capabilities' (mip_cc_string_list*) must be freed by calling MIP_CC_ReleaseStringList.

MIP_CC_API() [2/2]

MIP_CC_API

(

void

)

Release resources associated with a protection handler settings.

Release resources associated with a protection handler.

Parameters

settings	Protection handler settings to be released
handler	Protection handler to be released

Variable Documentation

actualDecryptedSize

const int64_t const uint8_t const int64_t uint8_t const int64_t const bool int64_t* actualDecryptedSize

actualEncryptedSize

const int64_t const uint8_t const int64_t uint8_t const int64_t const bool int64_t* actualEncryptedSize

actualIssuedUserSize

char const int64_t int64_t* actualIssuedUserSize

actualOwnerSize

char const int64_t int64_t* actualOwnerSize

actualPreLicenseSize

mip_cc_pre_license_format uint8_t const int64_t int64_t* actualPreLicenseSize

actualPublishingLicenseSize

uint8_t const int64_t int64_t* actualPublishingLicenseSize

applicationScenarioId

const char * applicationScenarioId

blockSize

int64_t* blockSize

capabilities

mip_cc_string_list* capabilities

capability

const char* capability

cipherMode

mip_cc_cipher_mode* cipherMode

contentId

mip_cc_guid* contentId

customSettings

const mip_cc_dictionary customSettings

delegatedUserEmail

const char* delegatedUserEmail

descriptor

mip_cc_protection_descriptor* descriptor

doesUseDeprecatedAlgorithm

bool* doesUseDeprecatedAlgorithm

errorInfo

mip_cc_string_list mip_cc_error* errorInfo

format

mip_cc_pre_license_format format

includesFinalBlock

const int64_t const bool includesFinalBlock

inputBuffer

const int64_t const uint8_t * inputBuffer

inputBufferSize

const int64_t const uint8_t const int64_t inputBufferSize

isAuditedExtractionAllowed

const bool isAuditedExtractionAllowed

isDeprecatedAlgorithmPreferred

const bool isDeprecatedAlgorithmPreferred

isFinal

const int64_t const uint8_t const int64_t uint8_t const int64_t const bool isFinal

isOfflineOnly

const bool isOfflineOnly

isPublishingFormatJson

const bool isPublishingFormatJson

issuedUserBuffer

char* issuedUserBuffer

issuedUserBufferSize

char const int64_t issuedUserBufferSize

issuedUserSize

int64_t* issuedUserSize

offsetFromStart

const int64_t offsetFromStart

outputBuffer

const int64_t const uint8_t const int64_t uint8_t * outputBuffer

outputBufferSize

const int64_t const uint8_t const int64_t uint8_t const int64_t outputBufferSize

ownerBuffer

char* ownerBuffer

ownerBufferSize

char const int64_t ownerBufferSize

ownerSize

int64_t* ownerSize

preLicenseBuffer

mip_cc_pre_license_format uint8_t* preLicenseBuffer

preLicenseBufferSize

mip_cc_pre_license_format uint8_t const int64_t preLicenseBufferSize

preLicenseUserEmail

const char* preLicenseUserEmail

protectedSize

const int64_t const bool int64_t* protectedSize

publishingLicenseBuffer

uint8_t * publishingLicenseBuffer

publishingLicenseBufferSize

uint8_t const int64_t publishingLicenseBufferSize

removed

const char bool* removed

rights

mip_cc_string_list* rights

settings

const int64_t const uint8_t const int64_t mip_cc_protection_handler_consumption_settings* settings

unprotectedSize

const int64_t unprotectedSize