ホーム › System.Com › CoInitializeSecurity

CoInitializeSecurity

関数

プロセス全体のCOMセキュリティ設定を初期化する。

DLLOLE32.dll呼出規約winapi対応OSWindows 2000 以降

シグネチャ

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

HRESULT CoInitializeSecurity(
    PSECURITY_DESCRIPTOR pSecDesc,   // optional
    INT cAuthSvc,
    SOLE_AUTHENTICATION_SERVICE* asAuthSvc,   // optional
    void* pReserved1,   // optional
    RPC_C_AUTHN_LEVEL dwAuthnLevel,
    RPC_C_IMP_LEVEL dwImpLevel,
    void* pAuthList,   // optional
    DWORD dwCapabilities,
    void* pReserved3   // optional
);

パラメーター

名前	型	方向	説明
pSecDesc	PSECURITY_DESCRIPTOR	inoptional	サーバーが呼び出しを受信するために使用するアクセス許可です。このパラメーターは、サーバーが CoInitializeSecurity を呼び出す場合にのみ COM によって使用されます。値は、AppID、IAccessControl オブジェクト、または絶対形式の SECURITY_DESCRIPTOR の 3 種類のいずれかへのポインターです。詳細については「解説」を参照してください。
cAuthSvc	INT	in	asAuthSvc パラメーター内のエントリ数です。このパラメーターは、サーバーが CoInitializeSecurity を呼び出す場合にのみ COM によって使用されます。このパラメーターが 0 の場合、認証サービスは登録されず、サーバーはセキュアな呼び出しを受信できません。値が -1 の場合は、登録する認証サービスを COM に選択させます。その場合、asAuthSvc パラメーターは NULL でなければなりません。ただし、このパラメーターが -1 の場合、Schannel がサーバーの認証サービスとして選択されることはありません。
asAuthSvc	SOLE_AUTHENTICATION_SERVICE*	inoptional	サーバーが呼び出しを受信するために使用する認証サービスの配列です。このパラメーターは、サーバーが CoInitializeSecurity を呼び出す場合にのみ COM によって使用されます。詳細については SOLE_AUTHENTICATION_SERVICE を参照してください。
pReserved1	void*	inoptional	このパラメーターは予約されており、NULL でなければなりません。
dwAuthnLevel	RPC_C_AUTHN_LEVEL	in	プロセスの既定の認証レベルです。サーバーとクライアントの両方が、CoInitializeSecurity を呼び出すときにこのパラメーターを使用します。COM は、これより低い認証レベルで到着した呼び出しを失敗させます。既定では、すべてのプロキシは少なくともこの認証レベルを使用します。この値には、認証レベル定数のいずれかを指定する必要があります。既定では、IUnknown へのすべての呼び出しはこのレベルで行われます。
dwImpLevel	RPC_C_IMP_LEVEL	in	プロキシの既定の偽装レベルです。このパラメーターの値は、プロセスがクライアントである場合にのみ使用されます。偽装レベル定数の値を指定する必要がありますが、CoInitializeSecurity での使用が想定されていない RPC_C_IMP_LEVEL_DEFAULT は除きます。クライアントからの送信呼び出しは、常に指定された偽装レベルを使用します(ネゴシエートはされません)。クライアントへの受信呼び出しは任意の偽装レベルで行われる可能性があります。既定では、すべての IUnknown 呼び出しはこの偽装レベルで行われるため、セキュリティを意識したアプリケーションであってもこのレベルは慎重に設定する必要があります。各認証サービスがどの偽装レベルをサポートするかを確認するには、COM and Security Packages 内の認証サービスの説明を参照してください。偽装レベルの詳細については Impersonation を参照してください。
pAuthList	void*	inoptional	SOLE_AUTHENTICATION_LIST へのポインターで、これは SOLE_AUTHENTICATION_INFO 構造体の配列です。このリストは、クライアントがサーバーを呼び出すために使用できる各認証サービスの情報を示します。このパラメーターは、クライアントが CoInitializeSecurity を呼び出す場合にのみ COM によって使用されます。
dwCapabilities	DWORD	in	1 つ以上の EOLE_AUTHENTICATION_CAPABILITIES 値を設定して指定する、クライアントまたはサーバーの追加機能です。これらの値の中には同時に使用できないものや、特定の認証サービスの使用時には設定できないものがあります。これらのフラグの詳細については「解説」を参照してください。
pReserved3	void*	inoptional	このパラメーターは予約されており、NULL でなければなりません。

戻り値の型: HRESULT

公式ドキュメント

セキュリティを登録し、プロセスの既定のセキュリティ値を設定します。

戻り値

この関数は、標準の戻り値 E_INVALIDARG に加えて、次の値を返すことがあります。

戻り値	説明
S_OK	成功を示します。
RPC_E_TOO_LATE	CoInitializeSecurity は既に呼び出されています。
RPC_E_NO_GOOD_SECURITY_PACKAGES	asAuthSvc パラメーターが NULL ではなく、リスト内のどの認証サービスも登録できませんでした。認証サービス固有のエラーコードについては、asAuthSvc に保存された結果を確認してください。
E_OUT_OF_MEMORY	メモリ不足です。

解説(Remarks)

CoInitializeSecurity 関数は、セキュリティ層を初期化し、指定された値をセキュリティの既定値として設定します。プロセスが CoInitializeSecurity を呼び出さない場合、COM は最初にインターフェイスがマーシャリングまたはアンマーシャリングされたときに自動的にこの関数を呼び出し、システムの既定のセキュリティを登録します。それまでは、既定のセキュリティパッケージは登録されません。

この関数は、明示的または暗黙的に、プロセスごとに正確に 1 回だけ呼び出されます。クライアント、サーバー、またはその両方から呼び出すことができます。レガシーアプリケーションやその他の CoInitializeSecurity を明示的に呼び出さないアプリケーションの場合、COM はレジストリの値を使用してこの関数を暗黙的に呼び出します。レジストリを使用してプロセス全体のセキュリティを設定した後で CoInitializeSecurity を呼び出すと、AppID レジストリ値は無視され、CoInitializeSecurity の値が使用されます。

CoInitializeSecurity は、コンピューター全体のアクセス許可とアプリケーション固有のアクセス許可の両方を上書きするために使用できますが、コンピューター全体の制限ポリシーを上書きすることはできません。

pSecDesc が AppID を指している場合、dwCapabilities に EOAC_APPID フラグを設定する必要があります。EOAC_APPID フラグが設定されている場合、CoInitializeSecurity へのその他のすべてのパラメーターは無視されます。CoInitializeSecurity はレジストリの AppID キーの下にある認証レベルを探し、それを使用して既定のセキュリティを決定します。AppID キーを使用してセキュリティを設定する方法の詳細については、Setting Process-Wide Security Through the Registry を参照してください。

pSecDesc が IAccessControl オブジェクトへのポインターである場合、EOAC_ACCESS_CONTROL フラグを設定する必要があり、dwAuthnLevel を none にすることはできません。IAccessControl オブジェクトは、誰がプロセスを呼び出せるかを決定するために使用されます。DCOM は IAccessControl を AddRef し、CoUninitialize が呼び出されたときに Release します。IAccessControl オブジェクトの状態は変更しないでください。

pSecDesc が SECURITY_DESCRIPTOR へのポインターである場合、dwCapabilities に EOAC_APPID フラグも EOAC_ACCESS_CONTROL フラグも設定できません。SECURITY_DESCRIPTOR の所有者とグループを設定する必要があり、DCOM が監査をサポートするまではシステム ACL を NULL にする必要があります。SECURITY_DESCRIPTOR の随意 ACL (DACL) 内のアクセス制御エントリ (ACE) は、どの呼び出し元がプロセスのオブジェクトへの接続を許可されるかを判断するために使用されます。ACE のない DACL はアクセスを一切許可しませんが、NULL の DACL は誰からの呼び出しも許可します。ACL と ACE の詳細については Access Control Model を参照してください。アプリケーションは、CoInitializeSecurity を呼び出す前に、SECURITY_DESCRIPTOR が正しく形成されていることを確認するために、IsValidSecurityDescriptor ではなく AccessCheck を呼び出す必要があります。

pSecDesc を NULL として渡すことは強く推奨されません。適切な代替策としては、Everyone を許可する SECURITY_DESCRIPTOR を使用することが考えられます。pSecDesc が NULL の場合、dwCapabilities のフラグによって、CoInitializeSecurity がサーバーの使用するアクセス許可をどのように定義するかが、次のように決まります。

EOAC_APPID フラグが設定されている場合、CoInitializeSecurity はレジストリ内でアプリケーションの .exe 名を検索し、そこに格納されている AppID を使用します。
EOAC_ACCESS_CONTROL フラグが設定されている場合、CoInitializeSecurity はエラーを返します。
EOAC_APPID フラグも EOAC_ACCESS_CONTROL フラグも設定されていない場合、CoInitializeSecurity はローカルおよびリモートの匿名ユーザーを含むすべての呼び出し元を許可します。

CoInitializeSecurity 関数は、dwCapabilities に EOAC_APPID フラグと EOAC_ACCESS_CONTROL フラグの両方が設定されている場合、エラーを返します。

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

各言語での呼び出し定義

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

HRESULT CoInitializeSecurity(
    PSECURITY_DESCRIPTOR pSecDesc,   // optional
    INT cAuthSvc,
    SOLE_AUTHENTICATION_SERVICE* asAuthSvc,   // optional
    void* pReserved1,   // optional
    RPC_C_AUTHN_LEVEL dwAuthnLevel,
    RPC_C_IMP_LEVEL dwImpLevel,
    void* pAuthList,   // optional
    DWORD dwCapabilities,
    void* pReserved3   // optional
);

[DllImport("OLE32.dll", ExactSpelling = true)]
static extern int CoInitializeSecurity(
    IntPtr pSecDesc,   // PSECURITY_DESCRIPTOR optional
    int cAuthSvc,   // INT
    IntPtr asAuthSvc,   // SOLE_AUTHENTICATION_SERVICE* optional
    IntPtr pReserved1,   // void* optional
    uint dwAuthnLevel,   // RPC_C_AUTHN_LEVEL
    uint dwImpLevel,   // RPC_C_IMP_LEVEL
    IntPtr pAuthList,   // void* optional
    uint dwCapabilities,   // DWORD
    IntPtr pReserved3   // void* optional
);

<DllImport("OLE32.dll", ExactSpelling:=True)>
Public Shared Function CoInitializeSecurity(
    pSecDesc As IntPtr,   ' PSECURITY_DESCRIPTOR optional
    cAuthSvc As Integer,   ' INT
    asAuthSvc As IntPtr,   ' SOLE_AUTHENTICATION_SERVICE* optional
    pReserved1 As IntPtr,   ' void* optional
    dwAuthnLevel As UInteger,   ' RPC_C_AUTHN_LEVEL
    dwImpLevel As UInteger,   ' RPC_C_IMP_LEVEL
    pAuthList As IntPtr,   ' void* optional
    dwCapabilities As UInteger,   ' DWORD
    pReserved3 As IntPtr   ' void* optional
) As Integer
End Function

' pSecDesc : PSECURITY_DESCRIPTOR optional
' cAuthSvc : INT
' asAuthSvc : SOLE_AUTHENTICATION_SERVICE* optional
' pReserved1 : void* optional
' dwAuthnLevel : RPC_C_AUTHN_LEVEL
' dwImpLevel : RPC_C_IMP_LEVEL
' pAuthList : void* optional
' dwCapabilities : DWORD
' pReserved3 : void* optional
Declare PtrSafe Function CoInitializeSecurity Lib "ole32" ( _
    ByVal pSecDesc As LongPtr, _
    ByVal cAuthSvc As Long, _
    ByVal asAuthSvc As LongPtr, _
    ByVal pReserved1 As LongPtr, _
    ByVal dwAuthnLevel As Long, _
    ByVal dwImpLevel As Long, _
    ByVal pAuthList As LongPtr, _
    ByVal dwCapabilities As Long, _
    ByVal pReserved3 As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

CoInitializeSecurity = ctypes.windll.ole32.CoInitializeSecurity
CoInitializeSecurity.restype = ctypes.c_int
CoInitializeSecurity.argtypes = [
    wintypes.HANDLE,  # pSecDesc : PSECURITY_DESCRIPTOR optional
    ctypes.c_int,  # cAuthSvc : INT
    ctypes.c_void_p,  # asAuthSvc : SOLE_AUTHENTICATION_SERVICE* optional
    ctypes.POINTER(None),  # pReserved1 : void* optional
    wintypes.DWORD,  # dwAuthnLevel : RPC_C_AUTHN_LEVEL
    wintypes.DWORD,  # dwImpLevel : RPC_C_IMP_LEVEL
    ctypes.POINTER(None),  # pAuthList : void* optional
    wintypes.DWORD,  # dwCapabilities : DWORD
    ctypes.POINTER(None),  # pReserved3 : void* optional
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('OLE32.dll')
CoInitializeSecurity = Fiddle::Function.new(
  lib['CoInitializeSecurity'],
  [
    Fiddle::TYPE_VOIDP,  # pSecDesc : PSECURITY_DESCRIPTOR optional
    Fiddle::TYPE_INT,  # cAuthSvc : INT
    Fiddle::TYPE_VOIDP,  # asAuthSvc : SOLE_AUTHENTICATION_SERVICE* optional
    Fiddle::TYPE_VOIDP,  # pReserved1 : void* optional
    -Fiddle::TYPE_INT,  # dwAuthnLevel : RPC_C_AUTHN_LEVEL
    -Fiddle::TYPE_INT,  # dwImpLevel : RPC_C_IMP_LEVEL
    Fiddle::TYPE_VOIDP,  # pAuthList : void* optional
    -Fiddle::TYPE_INT,  # dwCapabilities : DWORD
    Fiddle::TYPE_VOIDP,  # pReserved3 : void* optional
  ],
  Fiddle::TYPE_INT)

#[link(name = "ole32")]
extern "system" {
    fn CoInitializeSecurity(
        pSecDesc: *mut core::ffi::c_void,  // PSECURITY_DESCRIPTOR optional
        cAuthSvc: i32,  // INT
        asAuthSvc: *mut SOLE_AUTHENTICATION_SERVICE,  // SOLE_AUTHENTICATION_SERVICE* optional
        pReserved1: *mut (),  // void* optional
        dwAuthnLevel: u32,  // RPC_C_AUTHN_LEVEL
        dwImpLevel: u32,  // RPC_C_IMP_LEVEL
        pAuthList: *mut (),  // void* optional
        dwCapabilities: u32,  // DWORD
        pReserved3: *mut ()  // void* optional
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("OLE32.dll")]
public static extern int CoInitializeSecurity(IntPtr pSecDesc, int cAuthSvc, IntPtr asAuthSvc, IntPtr pReserved1, uint dwAuthnLevel, uint dwImpLevel, IntPtr pAuthList, uint dwCapabilities, IntPtr pReserved3);
"@
$api = Add-Type -MemberDefinition $sig -Name 'OLE32_CoInitializeSecurity' -Namespace Win32 -PassThru
# $api::CoInitializeSecurity(pSecDesc, cAuthSvc, asAuthSvc, pReserved1, dwAuthnLevel, dwImpLevel, pAuthList, dwCapabilities, pReserved3)

#uselib "OLE32.dll"
#func global CoInitializeSecurity "CoInitializeSecurity" sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr
; CoInitializeSecurity pSecDesc, cAuthSvc, varptr(asAuthSvc), pReserved1, dwAuthnLevel, dwImpLevel, pAuthList, dwCapabilities, pReserved3   ; 戻り値は stat
; pSecDesc : PSECURITY_DESCRIPTOR optional -> "sptr"
; cAuthSvc : INT -> "sptr"
; asAuthSvc : SOLE_AUTHENTICATION_SERVICE* optional -> "sptr"
; pReserved1 : void* optional -> "sptr"
; dwAuthnLevel : RPC_C_AUTHN_LEVEL -> "sptr"
; dwImpLevel : RPC_C_IMP_LEVEL -> "sptr"
; pAuthList : void* optional -> "sptr"
; dwCapabilities : DWORD -> "sptr"
; pReserved3 : void* optional -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "OLE32.dll"
#cfunc global CoInitializeSecurity "CoInitializeSecurity" sptr, int, var, sptr, int, int, sptr, int, sptr
; res = CoInitializeSecurity(pSecDesc, cAuthSvc, asAuthSvc, pReserved1, dwAuthnLevel, dwImpLevel, pAuthList, dwCapabilities, pReserved3)
; pSecDesc : PSECURITY_DESCRIPTOR optional -> "sptr"
; cAuthSvc : INT -> "int"
; asAuthSvc : SOLE_AUTHENTICATION_SERVICE* optional -> "var"
; pReserved1 : void* optional -> "sptr"
; dwAuthnLevel : RPC_C_AUTHN_LEVEL -> "int"
; dwImpLevel : RPC_C_IMP_LEVEL -> "int"
; pAuthList : void* optional -> "sptr"
; dwCapabilities : DWORD -> "int"
; pReserved3 : void* optional -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "OLE32.dll"
#cfunc global CoInitializeSecurity "CoInitializeSecurity" sptr, int, sptr, sptr, int, int, sptr, int, sptr
; res = CoInitializeSecurity(pSecDesc, cAuthSvc, varptr(asAuthSvc), pReserved1, dwAuthnLevel, dwImpLevel, pAuthList, dwCapabilities, pReserved3)
; pSecDesc : PSECURITY_DESCRIPTOR optional -> "sptr"
; cAuthSvc : INT -> "int"
; asAuthSvc : SOLE_AUTHENTICATION_SERVICE* optional -> "sptr"
; pReserved1 : void* optional -> "sptr"
; dwAuthnLevel : RPC_C_AUTHN_LEVEL -> "int"
; dwImpLevel : RPC_C_IMP_LEVEL -> "int"
; pAuthList : void* optional -> "sptr"
; dwCapabilities : DWORD -> "int"
; pReserved3 : void* optional -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。