Enumerations | Functions
Digital Rights
Design Files

Enumerations

enum  DigitalRightsEncryptionPermissions {
  DIGITAL_RIGHTS_ENCRYPTION_PERMISSIONS_None =0, DIGITAL_RIGHTS_ENCRYPTION_PERMISSIONS_Password =1, DIGITAL_RIGHTS_ENCRYPTION_PERMISSIONS_Certificate =2, DIGITAL_RIGHTS_ENCRYPTION_PERMISSIONS_Everyone =4,
  DIGITAL_RIGHTS_ENCRYPTION_PERMISSIONS_Any =(DIGITAL_RIGHTS_ENCRYPTION_PERMISSIONS_Password|DIGITAL_RIGHTS_ENCRYPTION_PERMISSIONS_Certificate|DIGITAL_RIGHTS_ENCRYPTION_PERMISSIONS_Everyone)
}
 Values returned by digitalRights_getEncryptionPermissions and digitalRights_getLicenseAddPermissions. More...
 

Functions

StatusInt mdlDgnFileObj_checkRights (DgnFileP dgnFileObj, UInt32 rights, MessageDestination displayError)
 Check if the specified rights are granted to the current user for the specified file. More...
 
bool mdlDgnFileObj_isProtected (DgnFileP file)
 Check if the specified file is encrypted (e.g., for digital rights management) More...
 
DgnFileSupplyRightsP mdlDgnFileObj_getReloadContext (DgnFileP file)
 Get the "context" needed to reopen this file using the same password or other credentials used to open it previously. More...
 
void mdlDgnFileObj_freeReloadContext (DgnFileSupplyRightsP *pContext)
 Free the "context" returned by mdlDgnFileObj_getReloadContext. More...
 
StatusInt digitalRights_encryptFile (DgnFileP file, byte const *keyMaterial, ULong32 nkeyMaterial, int iterations)
 AssigningGraphicGroup Assigning a Group Group to Members of Selection Set More...
 
DigitalRightsEncryptionPermissions digitalRights_getEncryptionPermissions (DgnFileP file)
 Check to see if the current user is allowed to encrypt the file. More...
 
DigitalRightsEncryptionPermissions digitalRights_getLicenseAddPermissions (DgnFileP file)
 Check to see what type of licenses, if any, the the current user is allowed to create. More...
 
DgnFileSupplyRightsP digitalRights_createLoadContext (byte const *keyMaterial, ULong32 nkeyMaterial)
 Create a load context that can be passed into functions such as mdlWorkDgn_openFileWithRights in order to open a protected file. More...
 
void digitalRights_freeLoadContext (DgnFileSupplyRightsP *ppContext)
 free the pointer returned by digitalRights_createLoadContext More...
 
bool digitalRights_inRestrictedMode (MessageDestination displayError)
 Check if we are in restricted mode, i.e., where only authorized apps can run. More...
 
StatusInt digitalRights_checkRights (UInt32 rights, MessageDestination displayError)
 Check if the current user has been granted the specified rights to all of the currently open design files. More...
 
StatusInt digitalRights_scramblePassword (ScrambledPasswordP pw, byte const *rawPw, ULong32 rawPwChars)
 Run the raw password through a one-way transformation, producing a scrambled password. More...
 
DgnFileSupplyRightsP digitalRights_createCertificateLoadContext (DsigCertificateCP cert)
 Create a context that can be used to open a protected file using a certificate-based license. More...
 
DgnFileSupplyRightsP digitalRights_createPasswordLoadContext (ScrambledPasswordCP pw)
 Create a context that can be used to open a protected file using a password-based license. More...
 
DgnFileSupplyRightsP digitalRights_createPasswordPromptLoadContext ()
 Create a context that can be used to open a protected file using a password-based license. More...
 
void digitalRights_deleteLoadContext (DgnFileSupplyRightsP context)
 Free a context returned by digitalRights_createPasswordLoadContext. More...
 
int mdlSystem_getSecurityLevel ()
 Query the setting for MS_SECURITY_LEVEL. More...
 

Detailed Description

Enumeration Type Documentation

enum DigitalRightsEncryptionPermissions

Values returned by digitalRights_getEncryptionPermissions and digitalRights_getLicenseAddPermissions.

Enumerator
DIGITAL_RIGHTS_ENCRYPTION_PERMISSIONS_None 
DIGITAL_RIGHTS_ENCRYPTION_PERMISSIONS_Password 
DIGITAL_RIGHTS_ENCRYPTION_PERMISSIONS_Certificate 
DIGITAL_RIGHTS_ENCRYPTION_PERMISSIONS_Everyone 
DIGITAL_RIGHTS_ENCRYPTION_PERMISSIONS_Any 

Function Documentation

StatusInt digitalRights_checkRights ( UInt32  rights,
MessageDestination  displayError 
)

Check if the current user has been granted the specified rights to all of the currently open design files.

Remarks
This checks all open files including the master file, all reference files, and any file opened via workdgn.
If no open file is protected then this function returns SUCCESS. If the current user has the requested rights to all open protected files, this function returns SUCCESS. If even one currently open file is protected and denies any requested right to the current user, then this fuction returns MDLERR_RIGHT_NOT_GRANTED.
Parameters
[in]rightsthe rights to check. Use the DgnPlatform::DGNFILE_RIGHT_... constants to specify the rights you want to check.
[in]displayErrorfor no message, pass MESSAGE_DEST_None; else MESSAGE_DEST_WarningDialog or MESSAGE_DEST_MessageCenter.
Returns
SUCCESS if all requested rights are granted or no rights restrictions are in effect; MDLERR_RIGHT_NOT_GRANTED if a right is not granted.
Remarks
Required Library: mdlbltin.lib
DgnFileSupplyRightsP digitalRights_createCertificateLoadContext ( DsigCertificateCP  cert)

Create a context that can be used to open a protected file using a certificate-based license.

Parameters
[in]certA copy of the ceritificate to use
Returns
A context object
Remarks
You must call digitalRights_deleteLoadContext to free this context when you are done with it.
See also
digitalRights_createPasswordLoadContext
DgnFileSupplyRightsP digitalRights_createLoadContext ( byte const *  keyMaterial,
ULong32  nkeyMaterial 
)

Create a load context that can be passed into functions such as mdlWorkDgn_openFileWithRights in order to open a protected file.

Parameters
[in]keyMaterialthe bytes to use to generate the encryption key.
[in]nkeyMaterialthe number of bytes in keyMaterial.
Returns
a load context for decryption.
Remarks
Required Library: mdlbltin.lib
DgnFileSupplyRightsP digitalRights_createPasswordLoadContext ( ScrambledPasswordCP  pw)

Create a context that can be used to open a protected file using a password-based license.

The password is supplied by the caller.

Parameters
[in]pwThe password to use, in scrambled form
Returns
A context object
Remarks
You must call digitalRights_deleteLoadContext to free this context when you are done with it.
See also
digitalRights_scramblePassword
digitalRights_createCertificateLoadContext
digitalRights_createPasswordPromptLoadContext
DgnFileSupplyRightsP digitalRights_createPasswordPromptLoadContext ( )

Create a context that can be used to open a protected file using a password-based license.

MicroStation prompts the user for the password

Returns
A context object
Remarks
You must call digitalRights_deleteLoadContext to free this context when you are done with it.
See also
digitalRights_scramblePassword
void digitalRights_deleteLoadContext ( DgnFileSupplyRightsP  context)

Free a context returned by digitalRights_createPasswordLoadContext.

Parameters
[in]contextThe context object to destroy
Remarks
Required Library: mdlbltin.lib
StatusInt digitalRights_encryptFile ( DgnFileP  file,
byte const *  keyMaterial,
ULong32  nkeyMaterial,
int  iterations 
)

AssigningGraphicGroup Assigning a Group Group to Members of Selection Set

See also
mdlSelect_isActive
mdlSelect_numSelected
mdlSystem_updateGraphicGroup
mdlSelect_getElement
mdlElmdscr_read
mdlElement_setProperties
mdlElmdscr_rewrite
mdlElmdscr_freeAll
elementRef_getFilePos
void addToGG ()
{
int index;
int nSelected;
ElementRef elemRef;
DgnModelRefP modelRef;
unsigned long lGG;
if (mdlSelect_isActive () == 0)
{
mdlOutput_error ("ERROR -- no selection set!");
return;
}
nSelected = mdlSelect_numSelected ();
lGG = mdlSystem_updateGraphicGroup ();
for (index = 0; index < nSelected; index++)
{
int status;
status = mdlSelect_getElement(index, &elemRef, &modelRef);
if (0 == status)
{
MSElementDescr *pDescr;
UInt32 startFilePos;
if (mdlElmdscr_read (&pDescr, elementRef_getFilePos (elemRef), modelRef, false, &startFilePos) != 0)
{
mdlElement_setProperties (&pDescr->el, NULL, &lGG, NULL, NULL, NULL, NULL, NULL, NULL);
mdlElmdscr_rewrite (pDescr, NULL, startFilePos);
mdlElmdscr_freeAll (&pDescr);
}
}
}
}
encrypt a file
Remarks
This function applies the following defaults: – the PBKDF1 key-generation algorithm is used, employing the SHA1 hashing algorithm. Random salt is automatically generated and added to the supplied keyMaterial. – a 128-bit RC4 key is generated. – thumbnails and document properties are encrypted
Any number of bytes of keyMaterial can be specified. However, the key-generation algorithm uses only 128 bits of information from the keyMaterial. An array of 16 randomly generated bytes contains approximately 128 bits of information. An array of ASCII characters must be much longer than 16 bytes in order to contain 128 bits of information.
Parameters
[in]filethe file to be encrypted. Must be open read-write.
[in]keyMaterialthe bytes to use to generate the encryption key.
[in]nkeyMaterialthe number of bytes in keyMaterial.
[in]iterationsthe number of PBKDF1 iterations to apply when generating the key from the key. Pass 0 if keyMaterial is composed of random bytes and cannot be guessed. Otherwise, a value of 1000 is recommended.
Returns
non-zero error status if: – the file is not in the V8 format. – the file is not open read-write.
Remarks
Test program:
char const* filename = "c:\\tmp\\encrypted.dgn";
byte* pwstr = (byte*)"abc"; // NOTE: In a real application, you should use an array of 32 randomly generated bytes. Or, you if you want to use a simple password, it should be a string of length >= 5, consisting of a mixture of mixed case letters and digits. Best practice is to run a text password through SHA1 to get its hash value and then use that as the password.
int npwstr = 3;
DgnModelRefP model;
if (mdlWorkDgn_createFile (&model, filename, DgnFileFormatType::V8, ACTIVEMODEL, SeedCopyFlags::DefaultData, NULL, NULL, tcb->ndices==3) != SUCCESS)
{
fprintf (stderr, "can't open %s\n", filename);
return;
}
digitalRights_encryptFile (mdlModelRef_getDgnFile(model), pwstr, npwstr, 0);
mdlWorkDgn_closeFile (model);
IDgnFileLoadContextP ctx = digitalRights_createLoadContext (pwstr, npwstr);
if (mdlWorkDgn_openFileWithRights (&model,NULL,NULL, filename,NULL, false, DgnPlatform::DGNFILE_RIGHT_Unlimited, MESSAGE_DEST_WarningDialog, ctx) != SUCCESS)
{
fprintf (stderr, "can't reopen %s!\n", filename);
return;
}
mdlWorkDgn_closeFile (model);
digitalRights_freeLoadContext (&ctx);
Required Library: mdlbltin.lib
void digitalRights_freeLoadContext ( DgnFileSupplyRightsP *  ppContext)

free the pointer returned by digitalRights_createLoadContext

Parameters
[in]ppContextpointer to variable that holds the pointer. Set to NULL on return.
Remarks
Required Library: mdlbltin.lib
DigitalRightsEncryptionPermissions digitalRights_getEncryptionPermissions ( DgnFileP  file)

Check to see if the current user is allowed to encrypt the file.

Check what kind of encryption is permitted.

Remarks
If the file is already encrypted, this function returns DIGITAL_RIGHTS_ENCRYPTION_PERMISSIONS_None.
For MASTERFILE, this function looks at the permissions set in the MS_PROTECTION_ENABLE config var. For all files, this function looks at the value set by dgnFileObj_setEncryptionPrefs and returns DIGITAL_RIGHTS_ENCRYPTION_PERMISSIONS_None if encryption is discouraged.
Parameters
[in]filethe file to be encrypted
Returns
a DigitalRightsEncryptionPermissions value.
Remarks
Required Library: mdlbltin.lib
DigitalRightsEncryptionPermissions digitalRights_getLicenseAddPermissions ( DgnFileP  file)

Check to see what type of licenses, if any, the the current user is allowed to create.

Remarks
For MASTERFILE, this function looks at the permissions set in the MS_PROTECTION_LICENSE_ENABLE config var. For all files, this function checks to see if the current user has Unlimited rights and returns DIGITAL_RIGHTS_ENCRYPTION_PERMISSIONS_None if not.
If the file is not encrypted, this function returns DIGITAL_RIGHTS_ENCRYPTION_PERMISSIONS_None.
Parameters
[in]filethe encrypted file to be modified
Returns
a DigitalRightsEncryptionPermissions value.
Remarks
Required Library: mdlbltin.lib
bool digitalRights_inRestrictedMode ( MessageDestination  displayError)

Check if we are in restricted mode, i.e., where only authorized apps can run.

If so, optionally identify and report the design files that have restricted access.

Parameters
[in]displayErrorfor no message, pass MESSAGE_DEST_None; else MESSAGE_DEST_WarningDialog or MESSAGE_DEST_MessageCenter.
Remarks
MicroStation may be in restricted mode because of digital rights restrictions imposed by the author of a protected file, or because the current user has set the security level to MEDIUM or HIGH, requesting that only signed apps can run. In the latter case, we return false, but we report no restricted files.
Returns
true if MicroStation is in restricted mode.
Remarks
Required Library: mdlbltin.lib
StatusInt digitalRights_scramblePassword ( ScrambledPasswordP  pw,
byte const *  rawPw,
ULong32  rawPwChars 
)

Run the raw password through a one-way transformation, producing a scrambled password.

Returns
non-zero error status if the transformation was not successful. This may happen if the computer is not set up to support strong encryption. Call the checkEncryptionCapabilities function to check this.
Parameters
[out]pwscrambled password
[in]rawPwraw password bytes to be scrambled
[in]rawPwCharsnumber of bytes of material to be scrambled
Remarks
Required Library: mdlbltin.lib
StatusInt mdlDgnFileObj_checkRights ( DgnFileP  dgnFileObj,
UInt32  rights,
MessageDestination  displayError 
)

Check if the specified rights are granted to the current user for the specified file.

Remarks
The rights parameter can be one or more of the following values OR'd together:
  • DgnPlatform::DGNFILE_RIGHT_Print – Print, print preview, e-plot, etc.
  • DgnPlatform::DGNFILE_RIGHT_Export – SaveAs, Export, Copy to clipboard, File Fence, etc.
  • DgnPlatform::DGNFILE_RIGHT_Edit – Modify file contents (implies not read-only)
  • DgnPlatform::DGNFILE_RIGHT_Unlimited – All rights, present and future
Parameters
[in]dgnFileObjthe DgnFileObj of interest.
[in]rightsthe rights to query
[in]displayErrordisplay error message in message center if rights not granted? Else return ERROR silently
Returns
SUCCESS if all of the rights are granted.
Remarks
Required Library: mdlbltin.lib
void mdlDgnFileObj_freeReloadContext ( DgnFileSupplyRightsP *  pContext)

Free the "context" returned by mdlDgnFileObj_getReloadContext.

Parameters
[in,out]pContextpointer to opaque reload context ptr to be freed
See also
dgnFileObj_getReloadContext
DgnFileSupplyRightsP mdlDgnFileObj_getReloadContext ( DgnFileP  file)

Get the "context" needed to reopen this file using the same password or other credentials used to open it previously.

You can pass this opaque pointer into functions such as mdlWorkDgn_openFileWithRights.

Parameters
[in]filea currently open file to be closed and reopened later
Remarks
You must call mdlDgnFileObj_freeReloadContext to free this context when you are done with it.
You can call digitalRights_createSuppliedPasswordContext to create a context if you already know the password.
Returns
opaque pointer to reload context
See also
digitalRights_createSuppliedPasswordContext
Remarks
Required Library: mdlbltin.lib
bool mdlDgnFileObj_isProtected ( DgnFileP  file)

Check if the specified file is encrypted (e.g., for digital rights management)

Parameters
[in]filethe DgnFileObj of interest.
Returns
true if file is encrypted
Remarks
Required Library: mdlbltin.lib
int mdlSystem_getSecurityLevel ( )

Query the setting for MS_SECURITY_LEVEL.

Returns
SECURITY_LEVEL_XXX (see msdefs.h)
Remarks
Required Library: mdlbltin.lib
Copyright © 2017 Bentley Systems, Incorporated. All rights reserved.