ホーム › Security.Authentication.Identity › MakeSignature

MakeSignature

関数

メッセージに暗号署名を付与して改ざん検出を可能にする。

DLLSECUR32.dll呼出規約winapi対応OSWindows XP 以降

シグネチャ

// SECUR32.dll
#include <windows.h>

HRESULT MakeSignature(
    SecHandle* phContext,
    DWORD fQOP,
    SecBufferDesc* pMessage,
    DWORD MessageSeqNo
);

パラメーター

名前

型

方向

説明

phContext

SecHandle*

メッセージの署名に使用するセキュリティコンテキストへのハンドル。

fQOP

DWORD

保護品質を示すパッケージ固有のフラグ。セキュリティパッケージは、このパラメーターを使用して暗号アルゴリズムを選択できるようにすることができます。

Digest SSP を使用する場合、このパラメーターは 0 に設定する必要があります。

pMessage

SecBufferDesc*

SecBufferDesc 構造体へのポインター。入力時、この構造体は署名対象のメッセージを格納する 1 つ以上の SecBuffer 構造体を参照します。この関数は、SECBUFFER_READONLY_WITH_CHECKSUM 属性を持つバッファーを処理しません。

SecBufferDesc 構造体は、署名を受け取る SECBUFFER_TOKEN 型の SecBuffer 構造体も参照します。

Digest SSP を HTTP 認証プロトコルとして使用する場合、バッファーは次のように構成します。

バッファー番号/バッファーの種類	意味
0 SECBUFFER_TOKEN	空。
1 SECBUFFER_PKG_PARAMS	メソッド。
2 SECBUFFER_PKG_PARAMS	URL。
3 SECBUFFER_PKG_PARAMS	HEntity。詳細については、ダイジェストチャレンジ応答の入力バッファーを参照してください。
4 SECBUFFER_PADDING	空。署名を受け取ります。

Digest SSP を SASL メカニズムとして使用する場合、バッファーは次のように構成します。

バッファー番号/バッファーの種類	意味
0 SECBUFFER_TOKEN	空。署名を受け取ります。このバッファーは、想定される最大の署名を格納できる大きさが必要です。必要なサイズは、 QueryContextAttributes (General) 関数に SECPKG_ATTR_SIZES を指定して呼び出すことで確認します。返された SecPkgContext_Sizes 構造体のメンバー cbMaxSignature を確認してください。
1 SECBUFFER_DATA	署名対象のメッセージ。
2 SECBUFFER_PADDING	空。

MessageSeqNo

DWORD

トランスポートアプリケーションがメッセージに割り当てたシーケンス番号。トランスポートアプリケーションがシーケンス番号を管理していない場合、このパラメーターは 0 です。

Digest SSP を使用する場合、このパラメーターは 0 に設定する必要があります。Digest SSP はシーケンス番号を内部で管理します。

戻り値の型: HRESULT

公式ドキュメント

メッセージの暗号化チェックサムを生成します。メッセージの消失や挿入を防ぐためのシーケンス情報も併せて含めます。

戻り値

関数が成功した場合、SEC_E_OK を返します。

関数が失敗した場合、次のいずれかのエラーコードを返します。

リターンコード	説明
SEC_I_RENEGOTIATE	リモート側が新しいハンドシェイクシーケンスを必要としているか、アプリケーションがシャットダウンを開始したところです。ネゴシエーションループに戻り、 AcceptSecurityContext (General) または InitializeSecurityContext (General) を再度呼び出してください。最初の呼び出しでは、空の入力バッファーを渡します。
SEC_E_INVALID_HANDLE	phContext で指定されたコンテキストハンドルが無効です。
SEC_E_INVALID_TOKEN	pMessage に有効な SECBUFFER_TOKEN バッファーが含まれていないか、バッファーの数が不足しています。
SEC_E_OUT_OF_SEQUENCE	nonce カウントの順序が正しくありません。
SEC_E_NO_AUTHENTICATING_AUTHORITY	セキュリティコンテキスト (phContext) を再検証する必要があります。
STATUS_INVALID_PARAMETER	nonce カウントが数値ではありません。
SEC_E_QOP_NOT_SUPPORTED	クライアントとサーバーの間でネゴシエートされた保護品質に、整合性チェックが含まれていませんでした。

解説(Remarks)

MakeSignature 関数は、メッセージとコンテキストのセッションキーに基づく署名を生成します。

VerifySignature 関数は、MakeSignature 関数で署名されたメッセージを検証します。

トランスポートアプリケーションがシーケンス検出をサポートするセキュリティコンテキストを作成し、呼び出し元がシーケンス番号を指定した場合、この関数はその情報を署名に含めます。これにより、メッセージの再送、挿入、抑止から保護されます。セキュリティパッケージは、トランスポートアプリケーションから渡されたシーケンス番号を組み込みます。

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

各言語での呼び出し定義

// SECUR32.dll
#include <windows.h>

HRESULT MakeSignature(
    SecHandle* phContext,
    DWORD fQOP,
    SecBufferDesc* pMessage,
    DWORD MessageSeqNo
);

[DllImport("SECUR32.dll", ExactSpelling = true)]
static extern int MakeSignature(
    IntPtr phContext,   // SecHandle*
    uint fQOP,   // DWORD
    IntPtr pMessage,   // SecBufferDesc*
    uint MessageSeqNo   // DWORD
);

<DllImport("SECUR32.dll", ExactSpelling:=True)>
Public Shared Function MakeSignature(
    phContext As IntPtr,   ' SecHandle*
    fQOP As UInteger,   ' DWORD
    pMessage As IntPtr,   ' SecBufferDesc*
    MessageSeqNo As UInteger   ' DWORD
) As Integer
End Function

' phContext : SecHandle*
' fQOP : DWORD
' pMessage : SecBufferDesc*
' MessageSeqNo : DWORD
Declare PtrSafe Function MakeSignature Lib "secur32" ( _
    ByVal phContext As LongPtr, _
    ByVal fQOP As Long, _
    ByVal pMessage As LongPtr, _
    ByVal MessageSeqNo As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

MakeSignature = ctypes.windll.secur32.MakeSignature
MakeSignature.restype = ctypes.c_int
MakeSignature.argtypes = [
    ctypes.c_void_p,  # phContext : SecHandle*
    wintypes.DWORD,  # fQOP : DWORD
    ctypes.c_void_p,  # pMessage : SecBufferDesc*
    wintypes.DWORD,  # MessageSeqNo : DWORD
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('SECUR32.dll')
MakeSignature = Fiddle::Function.new(
  lib['MakeSignature'],
  [
    Fiddle::TYPE_VOIDP,  # phContext : SecHandle*
    -Fiddle::TYPE_INT,  # fQOP : DWORD
    Fiddle::TYPE_VOIDP,  # pMessage : SecBufferDesc*
    -Fiddle::TYPE_INT,  # MessageSeqNo : DWORD
  ],
  Fiddle::TYPE_INT)

#[link(name = "secur32")]
extern "system" {
    fn MakeSignature(
        phContext: *mut SecHandle,  // SecHandle*
        fQOP: u32,  // DWORD
        pMessage: *mut SecBufferDesc,  // SecBufferDesc*
        MessageSeqNo: u32  // DWORD
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("SECUR32.dll")]
public static extern int MakeSignature(IntPtr phContext, uint fQOP, IntPtr pMessage, uint MessageSeqNo);
"@
$api = Add-Type -MemberDefinition $sig -Name 'SECUR32_MakeSignature' -Namespace Win32 -PassThru
# $api::MakeSignature(phContext, fQOP, pMessage, MessageSeqNo)

#uselib "SECUR32.dll"
#func global MakeSignature "MakeSignature" sptr, sptr, sptr, sptr
; MakeSignature varptr(phContext), fQOP, varptr(pMessage), MessageSeqNo   ; 戻り値は stat
; phContext : SecHandle* -> "sptr"
; fQOP : DWORD -> "sptr"
; pMessage : SecBufferDesc* -> "sptr"
; MessageSeqNo : DWORD -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "SECUR32.dll"
#cfunc global MakeSignature "MakeSignature" var, int, var, int
; res = MakeSignature(phContext, fQOP, pMessage, MessageSeqNo)
; phContext : SecHandle* -> "var"
; fQOP : DWORD -> "int"
; pMessage : SecBufferDesc* -> "var"
; MessageSeqNo : DWORD -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "SECUR32.dll"
#cfunc global MakeSignature "MakeSignature" sptr, int, sptr, int
; res = MakeSignature(varptr(phContext), fQOP, varptr(pMessage), MessageSeqNo)
; phContext : SecHandle* -> "sptr"
; fQOP : DWORD -> "int"
; pMessage : SecBufferDesc* -> "sptr"
; MessageSeqNo : DWORD -> "int"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。