Typedefs | Functions
DigitalSignatureAPI

Typedefs

typedef int(* DgnSignatureScanCallback )(DgnModelRefP modelRef, ElementRefP sigel, const DsigDigitalSignature *dsig, CallbackArgP callbackArg)
 Callback for scanning digital signatures. More...
 

Functions

ElementRefP dgnDigitalSignature_addFileSignatureElement (DgnFileP file)
 Creates a cell element that can be used to to create a digital signature with file scope. More...
 
StatusInt dgnDigitalSignature_create (ElementRefP *refP, const DsigCertificate *certcc, const WChar *name, const WChar *purpose, const WChar *location, double expiry, int __reserved1, ElementRefP *prereqs, UInt16 nprereqs, UInt32 scope)
 Converts a cell element into a digital signature. More...
 
StatusInt dgnDigitalSignature_extractFromElementEx (DsigDigitalSignature *sig, ULong32 *sigsz, bool *expired, MSElementCP el, ULong32 maxsz)
 Query the digital signature data associated with the specified element. More...
 
StatusInt dgnDigitalSignature_extractEx (DsigDigitalSignature *sig, ULong32 *sigsz, bool *expired, ElementRefP ref, ULong32 maxsz)
 Query the digital signature data associated with the specified element. More...
 
Public StatusInt dgnDigitalSignature_getPrerequisitesFromElement (ElementRefP *prereqs, UInt16 *nprereqs, DgnModelRefP modelref, MSElementCP sigel)
 Query the signatures on which this signature depends. More...
 
StatusInt dgnDigitalSignature_getPrerequisites (ElementRefP *prereqs, UInt16 *nprereqs, ElementRefP sigel)
 Query the signatures on which this signature depends. More...
 
StatusInt dgnDigitalSignature_verifyFromElement (DgnModelP cache, MSElementDescrCP sigel)
 Verify a digital signature. More...
 
StatusInt dgnDigitalSignature_verify (ElementRefP ref)
 Verify a digital signature. More...
 
DONTINCLUDEINDOC bool dgnDigitalSignature_isSigner (ElementRefP sigel)
 Query if the currently logged in user owns the certificate that was used to create this digital signature. More...
 
StatusInt dgnDigitalSignature_scanModelSignatures (DgnModelRefP modelRef, DgnSignatureScanCallback callbackFunc, CallbackArgP callbackArg)
 Detect all model signatures in the specified model. More...
 
StatusInt dgnDigitalSignature_scanFileSignatures (DgnFileP file, DgnSignatureScanCallback callbackFunc, CallbackArgP callbackArg)
 Detect all file signatures in the specified file. More...
 
StatusInt dgnDigitalSignature_scanApplicableSignatures (DgnModelRefP rootmodel, DgnSignatureScanCallback callbackFunc, CallbackArgP callbackArg)
 Detect all model signatures in the specified model, all file signatures in the file containing the model, and apply recursively to all references attached to this model. More...
 
bool dgnDigitalSignature_areAllApplicableSignaturesVerified (UInt32 *trustproblems, DgnModelRefP rootmodel)
 Query if all applicable signatures are verified. More...
 
bool dgnDigitalSignature_areAllApplicableSignaturesVerifiedEx (size_t *signatureCount, UInt32 *trustproblems, DgnModelRefP model)
 Query if all applicable signatures are verified. More...
 

Detailed Description

Digital Signature API

The DGN Digital Signature API allows MDL and native code applications to create and manage digital signatures in V8 design files.

Typedef Documentation

typedef int(* DgnSignatureScanCallback)(DgnModelRefP modelRef, ElementRefP sigel, const DsigDigitalSignature *dsig, CallbackArgP callbackArg)

Callback for scanning digital signatures.

Remarks
The scan is cancelled if this callback returns SCANALL_ABORT_SCAN.
Parameters
[in]modelRefa signature element
[in]sigela signature element
[in]dsigdigital signature data associted with this element
[in]callbackArgadditional callback argument passed to dgnDigitalSignature_scanSignatures
Returns
SUCCESS to continue the scan or SCANALL_ABORT_SCAN to stop.
See also
dgnDigitalSignature_scanSignatures

Function Documentation

ElementRefP dgnDigitalSignature_addFileSignatureElement ( DgnFileP  file)

Creates a cell element that can be used to to create a digital signature with file scope.

Remarks
Pass the result of this function into ConvertToSignatureElement to create a file signature.
See also
ConvertToSignatureElement
Parameters
[in]filefile that will be signed
Returns
ElementRefP representing the new element
Remarks
Required Library: mdlbltin.lib
bool dgnDigitalSignature_areAllApplicableSignaturesVerified ( UInt32 trustproblems,
DgnModelRefP  rootmodel 
)

Query if all applicable signatures are verified.

Parameters
[in]rootmodelthe model to scan for signatures and references
[out]trustproblems[optional] CERTIFICATE_QUERY_TRUST_... if certificate is flawed | 0x80000000 if signature is expired
Returns
true if all signatures are verified
See also
dgnDigitalSignature_scanApplicableSignatures
Remarks
Required Library: mdlbltin.lib
bool dgnDigitalSignature_areAllApplicableSignaturesVerifiedEx ( size_t *  signatureCount,
UInt32 trustproblems,
DgnModelRefP  model 
)

Query if all applicable signatures are verified.

Parameters
[in]modelthe model to scan for signatures and references
[out]signatureCount[optional] The number of applicable signatures found.
[out]trustproblems[optional] CERTIFICATE_QUERY_TRUST_... if certificate is flawed | 0x80000000 if signature is expired
Returns
true if all signatures are verified
See also
dgnDigitalSignature_scanApplicableSignatures
Remarks
Required Library: mdlbltin.lib
StatusInt dgnDigitalSignature_create ( ElementRefP *  refP,
const DsigCertificate *  certcc,
const WChar *  name,
const WChar *  purpose,
const WChar *  location,
double  expiry,
int  __reserved1,
ElementRefP *  prereqs,
UInt16  nprereqs,
UInt32  scope 
)

Converts a cell element into a digital signature.

Remarks

This function normally creates signatures with model scope. The element should previously have been added to the model which is being signed.

If the element was created using dgnDigitalSignature_addFileSignatureElement, then it will become a signature with file scope.

The element is modified and rewritten directly to the file. This conversion is not undoable.

The caller can make the signature "hidden" by setting the element's hdr.dhdr.props.b.invisible flag before calling this function.

Note The element must be a cell. The element can contain any graphic and non-graphic components that you wish. The element can have any user data linkages that you wish. All components and user data linkages are included in the signature (i.e., they become tamper-evident).

This function can be used to create new signatures and to recreate existing signatures. If the element is already a digital signature, then the current signature data is removed and is replaced by new signature data.

Parameters
[in,out]refPIN: element to represent the signature; OUT: augmented to represent a digital signature
[in]certcccopy of signer's digital certificate
[in]nameinformal name of signer (optional, annotation purposes only)
[in]purposeintended purpose of signature (optional, annotation purposes only)
[in]locationcomputer or location of signer (optional, annotation purposes only)
[in]expirytime at which signature should become invalid or 0 for no expiry
[in]__reserved1reserved for future use. Must be zero.
[in]prereqssignature(s) required by this signature
[in]nprereqsnumber of signature(s) required by this signature
[in]scopeDIGITAL_SIGNATURE_SCOPE_FILE_FLAG to include all of the content of the file that contains sigEh (this is implied when element is in dictionary model), DIGITAL_SIGNATURE_SCOPE_MODEL_FLAG to include the content of the model that contains sigEh DIGITAL_SIGNATURE_SCOPE_REFERENCES_FLAG to include the content of the model and all referenced models
Returns
SUCCESS if element was converted to a signature and rewritten to the file
See also
dgnDigitalSignature_extractEx
dgnDigitalSignature_scanSignatures
dgnDigitalSignature_isSigner
dgnDigitalSignature_addFileSignatureElement
Remarks
Required Library: mdlbltin.lib
StatusInt dgnDigitalSignature_extractEx ( DsigDigitalSignature *  sig,
ULong32 sigsz,
bool *  expired,
ElementRefP  ref,
ULong32  maxsz 
)

Query the digital signature data associated with the specified element.

Remarks
To extract a signature of an unknown size, first query the size of the digital signature by passing NULL for sig and the address of an integer as sigsz. Then use the size returned to allocate a buffer. Finally, call this function again, passing the buffer pointer for sign and the size allocated for maxsize.
ULong32 dsigsz;
if (dgnDigitalSignature_extractEx (NULL, &dsigsz, NULL, ref, 0) == SUCCESS)
{
DsigDigitalSignature* dsig = (DsigDigitalSignature*) _alloca (dsigsz);
dgnDigitalSignature_extractEx (dsig, NULL, NULL, ref, dsigsz);
...
To query if this is a digital signature element, call this function passing NULL for sig and expired. Then check that return value for SUCCESS.
Parameters
[out]sigoptional: digital signature data
[out]sigszoptional: size in bytes of signature data that was or would be extracted
[out]expiredoptional: set to true if signature is found and is expired
[in]refelement to query
[in]maxszmax number bytes to copy into sig
Returns
SUCCESS if element is a signature element
MDLERR_TOOLARGE if sig is non-NULL and maxsz is less than the size of the digital signature.
See also
dgnDigitalSignature_extractFromElement
Remarks
Required Library: mdlbltin.lib
StatusInt dgnDigitalSignature_extractFromElementEx ( DsigDigitalSignature *  sig,
ULong32 sigsz,
bool *  expired,
MSElementCP  el,
ULong32  maxsz 
)

Query the digital signature data associated with the specified element.

Remarks
To extract a signature of an unknown size, first query the size of the digital signature by passing NULL for sig and the address of an integer as sigsz. Then use the size returned to allocate a buffer. Finally, call this function again, passing the buffer pointer for sign and the size allocated for maxsize.
ULong32 dsigsz;
{
DsigDigitalSignature* dsig = (DsigDigitalSignature*) _alloca (dsigsz);
...
To query if this is a digital signature element, call this function passing NULL for sig and expired. Then check that return value for SUCCESS.

Use the digitalSignature_getInfo function to query the signature data.

Parameters
[out]sigoptional: digital signature data
[out]sigszoptional: size of digital signature
[out]expiredoptional: set to true if signature is found and is expired
[in]elelement to query
[in]maxszmax number bytes to copy into sig
Returns
SUCCESS if element is a signature element
MDLERR_TOOLARGE if sig is non-NULL and maxsz is less than the size of the digital signature.
See also
dgnDigitalSignature_extractEx
dgnDigitalSignature_isSigner
digitalSignature_getInfo
Remarks
Required Library: mdlbltin.lib
StatusInt dgnDigitalSignature_getPrerequisites ( ElementRefP *  prereqs,
UInt16 nprereqs,
ElementRefP  sigel 
)

Query the signatures on which this signature depends.

Remarks
To query if this is signature has prerequisites, call this function passing NULL for prereqs and nprereqs. Then check that return value for SUCCESS.

To query how many prerequisites this signature has, call this function passing NULL for prereqs and the address of an integer for nprereqs. If the return value is SUCCESS, the number of prerequisites will be stored in *nprereqs.

To query the prerequisites, pass the address of the output buffer in prereqs and the address of the count in nprereqs. On input, the value pointed to by nprereqs should be the maximum number of items that prereqs can hold. On return, the count value will be changed to the number of items actually copied into prereqs.

Parameters
[out]prereqsoptional: prerequisite signature elements
[in,out]nprereqsoptional: IN: max # elements to return; OUT: # prerequisites
[in]sigelsignature element to query
Returns
SUCCESS if signature has prerequisites
See also
dgnDigitalSignature_getPrerequisitesFromElement
Remarks
Required Library: mdlbltin.lib
Public StatusInt dgnDigitalSignature_getPrerequisitesFromElement ( ElementRefP *  prereqs,
UInt16 nprereqs,
DgnModelRefP  modelref,
MSElementCP  sigel 
)

Query the signatures on which this signature depends.

Remarks
To query if this is signature has prerequisites, call this function passing NULL for prereqs and nprereqs. Then check that return value for SUCCESS.

To query how many prerequisites this signature has, call this function passing NULL for prereqs and the address of an integer for nprereqs. If the return value is SUCCESS, the number of prerequisites will be stored in *nprereqs.

To query the prerequisites, pass the address of the output buffer in prereqs and the address of the count in nprereqs. On input, the value pointed to by nprereqs should be the maximum number of items that prereqs can hold. On return, the count value will be changed to the number of items actually copied into prereqs.

Parameters
[out]prereqsoptional: prerequisite signature elements
[in,out]nprereqsoptional: IN: max # elements to return; OUT: # prerequisites
[in]modelrefmodel containing signature element
[in]sigelsignature element to query
Returns
SUCCESS if signature has prerequisites
See also
dgnDigitalSignature_getPrerequisites
DONTINCLUDEINDOC bool dgnDigitalSignature_isSigner ( ElementRefP  sigel)

Query if the currently logged in user owns the certificate that was used to create this digital signature.

Remarks
The currently logged in user and certificate ownership are normally determined by the operating system.
Parameters
[in]sigelsignature element to test
Returns
true if current user owns certificate used to create signature
See also
ConvertToSignatureElement
Remarks
Required Library: mdlbltin.lib
StatusInt dgnDigitalSignature_scanApplicableSignatures ( DgnModelRefP  rootmodel,
DgnSignatureScanCallback  callbackFunc,
CallbackArgP  callbackArg 
)

Detect all model signatures in the specified model, all file signatures in the file containing the model, and apply recursively to all references attached to this model.

Remarks
This function differs from dgnDigitalSignature_scanModelSignatures in two ways: 1) This function also scans file signatures in the file of the model. 1) This function also scans applicable signatures in all references attached to the specified model. Note that the callback will be invoked on both model and file signatures in the attachments.
Signatures detected are passed to the callback function. The callback function may delete or modify the signatures.

Only signatures with model scope in the specified model are processed.

Use the digitalSignature_getInfo function to query the signature data.

Parameters
[in]rootmodelthe model to scan for signatures and references
[in]callbackFunccallback function to invoke on each signature in scope
[in]callbackArgadditional callback argument passed to dgnDigitalSignature_scanSignatures
Returns
SUCCESS to continue the scan or SCANALL_ABORT_SCAN to stop.
See also
DgnSignatureScanCallback
ConvertToSignatureElement
digitalSignature_getInfo
Remarks
Required Library: mdlbltin.lib
StatusInt dgnDigitalSignature_scanFileSignatures ( DgnFileP  file,
DgnSignatureScanCallback  callbackFunc,
CallbackArgP  callbackArg 
)

Detect all file signatures in the specified file.

Remarks
Signatures detected are passed to the callback function. The callback function may delete or modify the signatures.

Only signatures with file scope in the specified file are processed.

Use the digitalSignature_getInfo function to query the signature data.

Parameters
[in]filethe file to scan for signatures
[in]callbackFunccallback function to invoke on each signature in scope
[in]callbackArgadditional callback argument passed to dgnDigitalSignature_scanSignatures
Returns
SUCCESS to continue the scan or SCANALL_ABORT_SCAN to stop.
See also
DgnSignatureScanCallback
ConvertToSignatureElement
digitalSignature_getInfo
Remarks
Required Library: mdlbltin.lib
StatusInt dgnDigitalSignature_scanModelSignatures ( DgnModelRefP  modelRef,
DgnSignatureScanCallback  callbackFunc,
CallbackArgP  callbackArg 
)

Detect all model signatures in the specified model.

Remarks
Signatures detected are passed to the callback function. The callback function may delete or modify the signatures.

Only signatures with model scope in the specified model are processed.

Use the digitalSignature_getInfo function to query the signature data.

Parameters
[in]modelRefthe model to scan for signatures
[in]callbackFunccallback function to invoke on each signature in scope
[in]callbackArgadditional callback argument passed to dgnDigitalSignature_scanSignatures
Returns
SUCCESS to continue the scan or SCANALL_ABORT_SCAN to stop.
See also
DgnSignatureScanCallback
ConvertToSignatureElement
digitalSignature_getInfo
Remarks
Required Library: mdlbltin.lib
StatusInt dgnDigitalSignature_verify ( ElementRefP  ref)

Verify a digital signature.

Remarks
A signature is verified if the contents to which it applies are unchanged since the signature was created and if the signature itself it unchanged. If the signature has prerequisites, it is verified only of those required signatures are also verified.
Parameters
[in]refsignature element to test
Returns
SUCCESS if signature is verified
See also
dgnDigitalSignature_verifyFromElement
Remarks
Required Library: mdlbltin.lib
StatusInt dgnDigitalSignature_verifyFromElement ( DgnModelP  cache,
MSElementDescrCP  sigel 
)

Verify a digital signature.

Remarks
A signature is "verified" if the contents to which it applies are unchanged since the signature was created and if the signature itself it unchanged. If the signature has prerequisites, it is verified only of those required signatures are also verified.
Parameters
[in]cachecache containing the signature
[in]sigelsignature element to test
Returns
SUCCESS if signature is verified
See also
dgnDigitalSignature_verify
Remarks
Required Library: mdlbltin.lib

Copyright © 2017 Bentley Systems, Incorporated. All rights reserved.