IOpcDigitalSignatureManager::Sign method (msopc.h)

Article
10/13/2021

Signs the package by generating a signature by using the specified certificate and IOpcSigningOptions interface pointer. The resultant signature is represented by an IOpcDigitalSignature interface pointer.

Syntax

HRESULT Sign(
  [in]          const CERT_CONTEXT   *certificate,
  [in]          IOpcSigningOptions   *signingOptions,
  [out, retval] IOpcDigitalSignature **digitalSignature
);

Parameters

[in] certificate

A pointer to a CERT_CONTEXT structure that contains the certificate.

[in] signingOptions

An IOpcSigningOptions interface pointer that is used to generate the signature.

[out, retval] digitalSignature

A new IOpcDigitalSignature interface pointer that represents the signature.

Return value

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code/value	Description
S_OK	The method succeeded.
E_POINTER	At least one of the certificate, signingOptions, and digitalSignature parameters is NULL.
OPC_E_DS_DEFAULT_DIGEST_METHOD_NOT_SET 0x80510047	The default digest method has not been set; to set it, call IOpcSigningOptions::SetDefaultDigestMethod.
OPC_E_DS_DIGEST_VALUE_ERROR 0x8051001A	Cannot get the digest value of a package component or an element in the signature markup that was referenced for signing.
OPC_E_DS_INVALID_OPC_SIGNATURE_TIME_FORMAT 0x80510024	The signature's time format is not a valid OPC_SIGNATURE_TIME_FORMAT enumeration value.
OPC_E_DS_INVALID_RELATIONSHIPS_SIGNING_OPTION 0x80510023	An indicated relationship signing option is not a valid OPC_RELATIONSHIPS_SIGNING_OPTION enumeration value.
OPC_E_DS_SIGNATURE_CORRUPT 0x80510019	A signature in the package is not properly formed. Cannot get the signature value.
OPC_E_DS_SIGNATURE_METHOD_NOT_SET 0x80510046	The signature method has not been set. Call IOpcSigningOptions::SetSignatureMethod to set the signature method.
OPC_E_NO_SUCH_PART 0x80510018	The specified part does not exist.
Cryptography error	An HRESULT error code from a Cryptography API.
Windows Web Services error	An HRESULT error code from a Windows Web Services API.

Remarks

This method uses Packaging objects to make changes to a package. The resultant changes are not saved until the package itself is saved.

Before this method is called to generate a signature, call the IOpcSigningOptions::SetDefaultDigestMethod and IOpcSigningOptions::SetSignatureMethod methods.

To create an IOpcSigningOptions interface pointer, which is required by this method, call the CreateSigningOptions method.

Important If the package is modified while this method is being executed, Sign may fail or generate an inconsistent signature. To avoid corruption of the package, use the APIs to save the package prior to calling Sign. For information about how to save a package, see Saving a Package.

This method may create the following parts and relationships:

The Digital Signature Origin part
The package relationship of the digital signature origin relationship type
One signature part that contains signature markup
One or more part that contains a certificate
One relationship that targets a signature part and that has the Digital Signature Origin part as its source
One or more relationship that targets a signature part that contains a certificate and that has another signature part as its source

If Sign fails, any of the above parts and relationships may be represented, in the package, by Packaging objects. If the method returns the OPC_E_DS_SIGNATURE_METHOD_NOT_SET or OPC_E_DS_DEFAULT_DIGEST_METHOD_NOT_SET error code, the package has not been altered.

If Sign is successful, digest values are calculated for signed entities, and the generated signature is serialized as signature markup. Possible signed entities include the Signature element, references, parts, relationships, and package-specific and application-specific Object elements.

Errors that are introduced into a package signature when the caller is using the IOpcSigningOptions interface to set signature information may not be exposed until Sign is called.

Thread Safety

Packaging objects are not thread-safe.

For more information, see the Getting Started with the Packaging API.

Requirements

Requirement	Value
Minimum supported client	Windows 7 [desktop apps only]
Minimum supported server	Windows Server 2008 R2 [desktop apps only]
Target Platform	Windows
Header	msopc.h