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]	modelRef	a signature element
[in]	sigel	a signature element
[in]	dsig	digital signature data associted with this element
[in]	callbackArg	additional 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] file file 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]	rootmodel	the 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]	model	the 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]	refP	IN: element to represent the signature; OUT: augmented to represent a digital signature
[in]	certcc	copy of signer's digital certificate
[in]	name	informal name of signer (optional, annotation purposes only)
[in]	purpose	intended purpose of signature (optional, annotation purposes only)
[in]	location	computer or location of signer (optional, annotation purposes only)
[in]	expiry	time at which signature should become invalid or 0 for no expiry
[in]	__reserved1	reserved for future use. Must be zero.
[in]	prereqs	signature(s) required by this signature
[in]	nprereqs	number of signature(s) required by this signature
[in]	scope	DIGITAL_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]	sig	optional: digital signature data
[out]	sigsz	optional: size in bytes of signature data that was or would be extracted
[out]	expired	optional: set to true if signature is found and is expired
[in]	ref	element to query
[in]	maxsz	max 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;

if (dgnDigitalSignature_extractFromElementEx (NULL, &dsigsz, NULL, el, 0) == SUCCESS)

{

DsigDigitalSignature* dsig = (DsigDigitalSignature*) _alloca (dsigsz);

dgnDigitalSignature_extractFromElementEx (dsig, NULL, NULL, el, 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]	sig	optional: digital signature data
[out]	sigsz	optional: size of digital signature
[out]	expired	optional: set to true if signature is found and is expired
[in]	el	element to query
[in]	maxsz	max 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]	prereqs	optional: prerequisite signature elements
[in,out]	nprereqs	optional: IN: max # elements to return; OUT: # prerequisites
[in]	sigel	signature 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]	prereqs	optional: prerequisite signature elements
[in,out]	nprereqs	optional: IN: max # elements to return; OUT: # prerequisites
[in]	modelref	model containing signature element
[in]	sigel	signature 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] sigel signature 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]	rootmodel	the model to scan for signatures and references
[in]	callbackFunc	callback function to invoke on each signature in scope
[in]	callbackArg	additional 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]	file	the file to scan for signatures
[in]	callbackFunc	callback function to invoke on each signature in scope
[in]	callbackArg	additional 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]	modelRef	the model to scan for signatures
[in]	callbackFunc	callback function to invoke on each signature in scope
[in]	callbackArg	additional 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] ref signature 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]	cache	cache containing the signature
[in]	sigel	signature element to test

Returns: SUCCESS if signature is verified

See also: dgnDigitalSignature_verify

Remarks: Required Library: mdlbltin.lib

Typedefs

Functions

Detailed Description

Digital Signature API

Typedef Documentation

Function Documentation