IXpsSignature

COM

IID6ae4c93e-1ade-42fb-898b-3a5658284857継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

1 つのデジタル署名を表します。

解説(Remarks)

このインターフェイスは、それをインスタンス化した署名マネージャーに紐付けられており、単独で存在することはできません。

IXpsSignature インターフェイスは、XPS に準拠していない署名を表すこともあります。たとえば、カスタムパートのみを含む署名を表す場合がありますが、これは XML Paper Specification では許可されていません。

メソッド 12

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT GetSignatureId(LPWSTR* sigId)

Signature 要素の Id 属性の値を取得します。(IXpsSignature.GetSignatureId)

sigId

LPWSTR*

out

Signature 要素の Id 属性の値。Id 属性が存在しない場合は、NULL ポインターが返されます。

戻り値

このメソッドは HRESULT を返します。返される値には、次の表に示す値が含まれますが、これらに限定されません。この表に記載されていない戻り値については、XPS Digital Signature API Errors および XPS Document Errors を参照してください。

戻り値	説明
S_OK	メソッドは成功しました。
E_POINTER	sigId が NULL です。
E_UNEXPECTED	インターフェイスが署名マネージャーに接続されていません。

解説(Remarks)

このメソッドは、sigId で返される文字列が使用するメモリを割り当てます。 sigId が NULL でない場合は、CoTaskMemFree 関数を使用してメモリを解放してください。

vtbl 4 HRESULT GetSignatureValue(BYTE** signatureHashValue, DWORD* count)

署名の暗号化されたハッシュ値を取得します。

signatureHashValue	BYTE**	out	署名の暗号化されたハッシュ値を表すバイト配列。
count	DWORD*	out	signatureHashValue が参照するバイト配列の長さ。

戻り値

戻り値	説明
S_OK	メソッドは成功しました。
E_UNEXPECTED	インターフェイスが署名マネージャーに接続されていません。

解説(Remarks)

このメソッドは、signatureHashValue でポインターが返されるメモリバッファーを割り当てます。 signatureHashValue が NULL でない場合は、CoTaskMemFree 関数を使用してメモリを解放してください。

vtbl 5 HRESULT GetCertificateEnumerator(IOpcCertificateEnumerator** certificateEnumerator)

署名に添付されているパッケージ証明書を列挙する IOpcCertificateEnumerator インターフェイスへのポインターを取得します。

certificateEnumerator

IOpcCertificateEnumerator**

out

署名に添付されている証明書を列挙する IOpcCertificateEnumerator インターフェイスへのポインター。

戻り値

戻り値	説明
S_OK	メソッドは成功しました。
E_UNEXPECTED	インターフェイスが署名マネージャーに接続されていません。

解説(Remarks)

certificateEnumerator で返される IOpcCertificateEnumerator インターフェイスは空の場合もあります。ただし XML Paper Specification では、少なくとも署名証明書が XPS パッケージに含まれていることが必要です。パッケージの作成元は、追加の証明書を含めることもできます。たとえば、証明書の信頼チェーン全体を XPS パッケージに含めることができます。

vtbl 6 HRESULT GetSigningTime(LPWSTR* sigDateTimeString)

署名が作成された日時を取得します。

sigDateTimeString

LPWSTR*

out

日時情報を格納する文字列。

戻り値

戻り値	説明
S_OK	メソッドは成功しました。
E_UNEXPECTED	インターフェイスが署名マネージャーに接続されていません。

解説(Remarks)

sigDateTimeString で返される日時文字列は、http://www.w3.org/TR/NOTE-datetime で説明されている W3C の日時形式です。

sigDateTimeString で返される日時文字列の具体的な形式を取得するには、GetSigningTimeFormat を呼び出します。

このメソッドは、sigDateTimeString で返される文字列が使用するメモリを割り当てます。 sigDateTimeString が NULL でない場合は、CoTaskMemFree 関数を使用してメモリを解放してください。

vtbl 7 HRESULT GetSigningTimeFormat(OPC_SIGNATURE_TIME_FORMAT* timeFormat)

署名時刻の形式を取得します。

timeFormat

OPC_SIGNATURE_TIME_FORMAT*

out

署名時刻の形式を示す OPC_SIGNATURE_TIME_FORMAT の値。

戻り値

戻り値	説明
S_OK	メソッドは成功しました。
E_UNEXPECTED	インターフェイスが署名マネージャーに接続されていません。

解説(Remarks)

timeFormat で返される日時文字列の形式の詳細については、OPC_SIGNATURE_TIME_FORMAT を参照してください。

vtbl 8 HRESULT GetSignaturePartName(IOpcPartUri** signaturePartName)

署名パートのパート名を取得します。

signaturePartName

IOpcPartUri**

out

署名パートのパート名を格納する IOpcPartUri インターフェイスへのポインター。

戻り値

戻り値	説明
S_OK	メソッドは成功しました。
E_UNEXPECTED	インターフェイスが署名マネージャーに接続されていません。

vtbl 9 HRESULT Verify(CERT_CONTEXT* x509Certificate, XPS_SIGNATURE_STATUS* sigStatus)

指定された X.509 証明書に対して署名を検証します。

x509Certificate

CERT_CONTEXT*

検証に使用する X.509 証明書を格納する CERT_CONTEXT 構造体。

署名が不完全でも非準拠でもない場合、この証明書は XPS パッケージ内の署名済みデータが損なわれていないことを検証するためにのみ使用されます。証明書はそれ以外のチェックには使用されません。証明書を使用する前に、アプリケーション側で信頼チェーンやその他の要件を検証することが期待されます。

sigStatus

XPS_SIGNATURE_STATUS*

out

検証結果を示す XPS_SIGNATURE_STATUS の値。

戻り値

戻り値	説明
S_OK	メソッドは成功しました。
E_POINTER	x509Certificate または sigStatus が NULL です。
E_UNEXPECTED	インターフェイスが署名マネージャーに接続されていません。

解説(Remarks)

このメソッドは、XML Paper Specification のセクション 10.2.1.2 で規定された順序で署名の状態を検出します。検出の順序は、非準拠 (incompliant)、不完全 (incomplete)、破損 (broken)、疑わしい (questionable)、そして最後に有効 (valid) の順です。つまり、たとえば署名が非準拠であると判定された場合、その署名が破損していてもダイジェストは計算されません。

このメソッドで検出できる署名状態の種類の詳細については、XPS_SIGNATURE_STATUS を参照してください。

vtbl 10 HRESULT GetPolicy(XPS_SIGN_POLICY* policy)

署名の作成時に使用された署名ポリシーを表す XPS_SIGN_POLICY 値を取得します。

policy

XPS_SIGN_POLICY*

out

署名ポリシーを表す XPS_SIGN_POLICY 値の論理 OR。

戻り値

戻り値	説明
S_OK	メソッドは成功しました。
E_POINTER	policy が NULL です。
E_UNEXPECTED	インターフェイスが署名マネージャーに接続されていません。

解説(Remarks)

policy で返される署名ポリシーの値は、ドキュメント内の署名済みパートとリレーションシップを調べることで決定されます。

このメソッドは、署名済みのパートとリレーションシップの一覧を調べて署名ポリシーを推定します。たとえば、XPS パッケージのルートからの discard-control リレーションシップの種類が署名されている場合、XPS_SIGN_POLICY_DISCARD_CONTROL フラグが設定されます。

vtbl 11 HRESULT GetCustomObjectEnumerator(IOpcSignatureCustomObjectEnumerator** customObjectEnumerator)

署名のカスタムオブジェクトを列挙する IOpcSignatureCustomObjectEnumerator インターフェイスへのポインターを取得します。

customObjectEnumerator

IOpcSignatureCustomObjectEnumerator**

out

署名のカスタムオブジェクトを列挙する IOpcSignatureCustomObjectSet インターフェイスへのポインター。

戻り値

戻り値	説明
S_OK	メソッドは成功しました。
E_UNEXPECTED	インターフェイスが署名マネージャーに接続されていません。
XPS_E_OBJECT_DETACHED	インターフェイスが署名マネージャーに関連付けられていません。

vtbl 12 HRESULT GetCustomReferenceEnumerator(IOpcSignatureReferenceEnumerator** customReferenceEnumerator)

署名のカスタム参照を列挙する IOpcSignatureReferenceEnumerator インターフェイスへのポインターを取得します。

customReferenceEnumerator

IOpcSignatureReferenceEnumerator**

out

署名のカスタム参照を列挙する IOpcSignatureReferenceEnumerator インターフェイスへのポインター。

戻り値

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 13 HRESULT GetSignatureXml(BYTE** signatureXml, DWORD* count)

デジタル署名の XML マークアップを取得します。

signatureXml	BYTE**	out	デジタル署名の XML マークアップ。
count	DWORD*	out	signatureXml が参照するバッファーのサイズ (バイト単位)。

戻り値

戻り値	説明
S_OK	メソッドは成功しました。
E_UNEXPECTED	インターフェイスが署名マネージャーに接続されていません。

解説(Remarks)

このメソッドは、signatureXml でポインターが返されるメモリバッファーを割り当てます。 signatureXml が NULL でない場合は、CoTaskMemFree 関数を使用してメモリを解放してください。

vtbl 14 HRESULT SetSignatureXml(BYTE* signatureXml, DWORD count)

デジタル署名の XML マークアップを設定します。

signatureXml	BYTE*	in	デジタル署名の XML マークアップ。
count	DWORD	in	signatureXml が参照するバッファーのサイズ (バイト単位)。

戻り値

戻り値	説明
S_OK	メソッドは成功しました。
E_POINTER	signatureXml が NULL です。
E_UNEXPECTED	インターフェイスが署名マネージャーに接続されていません。

解説(Remarks)

このメソッドを呼び出す前に、アプリケーションは署名マークアップが有効であることを確認する必要があります。署名マークアップが有効でない場合、このメソッドは失敗し、署名パートの内容は変更されません。

警告

このメソッドを使用してデジタル署名を作成すると、このインターフェイスの他のメソッドが、もはや有効でない署名やデータを返す可能性があります。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数:

#define global IID_IXpsSignature "{6AE4C93E-1ADE-42FB-898B-3A5658284857}"
#usecom global IXpsSignature IID_IXpsSignature "{}"
#comfunc global IXpsSignature_GetSignatureId                3 var
#comfunc global IXpsSignature_GetSignatureValue             4 var,var
#comfunc global IXpsSignature_GetCertificateEnumerator      5 sptr
#comfunc global IXpsSignature_GetSigningTime                6 var
#comfunc global IXpsSignature_GetSigningTimeFormat          7 var
#comfunc global IXpsSignature_GetSignaturePartName          8 sptr
#comfunc global IXpsSignature_Verify                        9 var,var
#comfunc global IXpsSignature_GetPolicy                     10 var
#comfunc global IXpsSignature_GetCustomObjectEnumerator     11 sptr
#comfunc global IXpsSignature_GetCustomReferenceEnumerator  12 sptr
#comfunc global IXpsSignature_GetSignatureXml               13 var,var
#comfunc global IXpsSignature_SetSignatureXml               14 var,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IXpsSignature "{6AE4C93E-1ADE-42FB-898B-3A5658284857}"
#usecom global IXpsSignature IID_IXpsSignature "{}"
#comfunc global IXpsSignature_GetSignatureId                3 sptr
#comfunc global IXpsSignature_GetSignatureValue             4 sptr,sptr
#comfunc global IXpsSignature_GetCertificateEnumerator      5 sptr
#comfunc global IXpsSignature_GetSigningTime                6 sptr
#comfunc global IXpsSignature_GetSigningTimeFormat          7 sptr
#comfunc global IXpsSignature_GetSignaturePartName          8 sptr
#comfunc global IXpsSignature_Verify                        9 sptr,sptr
#comfunc global IXpsSignature_GetPolicy                     10 sptr
#comfunc global IXpsSignature_GetCustomObjectEnumerator     11 sptr
#comfunc global IXpsSignature_GetCustomReferenceEnumerator  12 sptr
#comfunc global IXpsSignature_GetSignatureXml               13 sptr,sptr
#comfunc global IXpsSignature_SetSignatureXml               14 sptr,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。