ホーム › Security.Cryptography › CertAddStoreToCollection

CertAddStoreToCollection

関数

コレクションストアに兄弟ストアを追加する。

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

シグネチャ

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

BOOL CertAddStoreToCollection(
    HCERTSTORE hCollectionStore,
    HCERTSTORE hSiblingStore,   // optional
    DWORD dwUpdateFlags,
    DWORD dwPriority
);

パラメーター

名前	型	方向	説明
hCollectionStore	HCERTSTORE	in	証明書ストアのハンドル。
hSiblingStore	HCERTSTORE	inoptional	コレクションストアに追加する兄弟ストアのハンドル。詳細については「解説」を参照してください。
dwUpdateFlags	DWORD	in	新しい兄弟ストアメンバー(コレクションストアの一員)に証明書、CRL、CTL を追加できるかどうかを示します。追加を有効にするには、dwUpdateFlag を CERT_PHYSICAL_STORE_ADD_ENABLE_FLAG に設定します。追加を無効にするには、dwUpdateFlag をゼロに設定します。
dwPriority	DWORD	in	コレクション内における新しいストアの優先度レベルを設定します。ゼロが最も低い優先度です。このパラメーターにゼロを渡すと、指定したストアはコレクション内の最後のストアとして追加されます。コレクション内のストアの優先度レベルは、ストアを列挙する順序、および証明書、CRL、CTL を取得しようとする際のストアの検索順序を決定します。優先度レベルはまた、新しい証明書、CRL、CTL がコレクションのどのストアに追加されるかも決定します。詳細については「解説」を参照してください。

戻り値の型: BOOL

公式ドキュメント

CertAddStoreToCollection 関数は、コレクション証明書ストアに兄弟証明書ストアを追加します。

戻り値

関数が成功すると、関数はゼロ以外を返し、ストアのコレクションに新しいストアが追加されます。

関数が失敗すると、ゼロを返し、ストアは追加されません。

解説(Remarks)

コレクションストアは単一のストアと同じ HCERTSTORE ハンドルを持ちます。したがって、任意の証明書ストアに適用されるほぼすべての関数は、任意のコレクションストアにも適用されます。列挙および検索の処理はコレクションストア内のすべてのストアにまたがって行われますが、 CertAddCertificateLinkToStore のようにストアにリンクを追加する関数は、コレクションストアでは使用できません。

証明書、CRL、CTL がコレクションストアに追加されると、追加を許可する最初のストアを見つけるために、コレクション内の兄弟ストアのリストが優先度順に検索されます。追加は、CertAddStoreToCollection の呼び出しで CERT_PHYSICAL_STORE_ADD_ENABLE_FLAG が設定されている場合に有効になります。ストアに要素を追加するいずれの関数においても、追加を許可するストアが成功を返さない場合、追加関数は通知を行わずに次のストアへ処理を続行します。

コレクションストアとその兄弟ストアを CertCloseStore で CERT_CLOSE_STORE_FORCE_FLAG を使用して閉じる場合、コレクションストアは兄弟ストアより前に閉じる必要があります。CERT_CLOSE_STORE_FORCE_FLAG を使用しない場合は、任意の順序でストアを閉じることができます。

例

次の例は、コレクション証明書ストアに兄弟証明書ストアを追加する方法を示します。この例の完全なコンテキストを含む完全な例については、 Example C Program: Collection and Sibling Certificate Store Operations を参照してください。

//-------------------------------------------------------------------
// Declare and initialize variables.

HCERTSTORE  hCollectionStore = NULL;     // The collection store 
                                         // handle
HCERTSTORE  hMemoryStore = NULL;         // A memory store handle
LPCSTR pszFileName = "TestStor.sto";     // Output file name
LPWSTR pswzFirstCert = L"Full Test Cert";// Subject of the first
                                         // certificate
LPWSTR pswzSecondCert = L"Microsoft";    // Subject of the second 
                                         // certificate
//-------------------------------------------------------------------
// Open a collection certificate store.

if(hCollectionStore = CertOpenStore(
    CERT_STORE_PROV_COLLECTION, // A collection store
    0,                          // Encoding type; not used with a
                                // collection store
    NULL,                       // Use the default provider
    0,                          // No flags
    NULL))                      // Not needed

{
    printf("The collection store was opened. \n");
}
else
{
    printf( "There was an error while opening the "
        "collection store! \n");
    exit(1);
}
//-------------------------------------------------------------------
// Open a new certificate store in memory.

if(hMemoryStore = CertOpenStore(
    CERT_STORE_PROV_MEMORY,    // A memory store
    0,                         // Encoding type; not used with a
                               // memory store
    NULL,                      // Use the default provider
    0,                         // No flags
    NULL))                     // Not needed
{
    printf("The memory store was opened. \n");
}
else
{
    printf( "There was an error while opening the memory store! \n");
    exit(1);
}
//-------------------------------------------------------------------
// Add the memory store as a sibling to the collection store. 
// All certificates in the memory store and any new certificate
// added to the memory store will also be available in the 
// collection
// store.

if(CertAddStoreToCollection(
    hCollectionStore,
    hMemoryStore,
    CERT_PHYSICAL_STORE_ADD_ENABLE_FLAG,  // New certificates can be
                                          // added to the sibling
                                          // store.
    1))                                   // The sibling store's 
                                          // priority.
                                          // Because this is the 
                                          // store with the highest
                                          // priority, certificates
                                          // added to the collection
                                          // store will actually be
                                          // stored in this store.
{
    printf("The memory store was added to the collection store.\n");
}
else
{
    printf("The memory store was not added to the "
        "collection store.\n");
    exit(1);
}


//-------------------------------------------------------------------
// The store handles must be closed.

if(CertCloseStore(hCollectionStore,
                  0))
{
    printf("The collection store was closed. \n");
}
else
{
    printf("There was an error while closing the "
        "collection store! \n");
}

if(CertCloseStore(hMemoryStore, 0))
{
    printf("The memory store was closed. \n");
}
else
{
    printf("There was an error while closing the memory store! \n");
}

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

各言語での呼び出し定義

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

BOOL CertAddStoreToCollection(
    HCERTSTORE hCollectionStore,
    HCERTSTORE hSiblingStore,   // optional
    DWORD dwUpdateFlags,
    DWORD dwPriority
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("CRYPT32.dll", ExactSpelling = true)]
static extern bool CertAddStoreToCollection(
    IntPtr hCollectionStore,   // HCERTSTORE
    IntPtr hSiblingStore,   // HCERTSTORE optional
    uint dwUpdateFlags,   // DWORD
    uint dwPriority   // DWORD
);

<DllImport("CRYPT32.dll", ExactSpelling:=True)>
Public Shared Function CertAddStoreToCollection(
    hCollectionStore As IntPtr,   ' HCERTSTORE
    hSiblingStore As IntPtr,   ' HCERTSTORE optional
    dwUpdateFlags As UInteger,   ' DWORD
    dwPriority As UInteger   ' DWORD
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' hCollectionStore : HCERTSTORE
' hSiblingStore : HCERTSTORE optional
' dwUpdateFlags : DWORD
' dwPriority : DWORD
Declare PtrSafe Function CertAddStoreToCollection Lib "crypt32" ( _
    ByVal hCollectionStore As LongPtr, _
    ByVal hSiblingStore As LongPtr, _
    ByVal dwUpdateFlags As Long, _
    ByVal dwPriority As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

CertAddStoreToCollection = ctypes.windll.crypt32.CertAddStoreToCollection
CertAddStoreToCollection.restype = wintypes.BOOL
CertAddStoreToCollection.argtypes = [
    wintypes.HANDLE,  # hCollectionStore : HCERTSTORE
    wintypes.HANDLE,  # hSiblingStore : HCERTSTORE optional
    wintypes.DWORD,  # dwUpdateFlags : DWORD
    wintypes.DWORD,  # dwPriority : DWORD
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('CRYPT32.dll')
CertAddStoreToCollection = Fiddle::Function.new(
  lib['CertAddStoreToCollection'],
  [
    Fiddle::TYPE_VOIDP,  # hCollectionStore : HCERTSTORE
    Fiddle::TYPE_VOIDP,  # hSiblingStore : HCERTSTORE optional
    -Fiddle::TYPE_INT,  # dwUpdateFlags : DWORD
    -Fiddle::TYPE_INT,  # dwPriority : DWORD
  ],
  Fiddle::TYPE_INT)

#[link(name = "crypt32")]
extern "system" {
    fn CertAddStoreToCollection(
        hCollectionStore: *mut core::ffi::c_void,  // HCERTSTORE
        hSiblingStore: *mut core::ffi::c_void,  // HCERTSTORE optional
        dwUpdateFlags: u32,  // DWORD
        dwPriority: u32  // DWORD
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("CRYPT32.dll")]
public static extern bool CertAddStoreToCollection(IntPtr hCollectionStore, IntPtr hSiblingStore, uint dwUpdateFlags, uint dwPriority);
"@
$api = Add-Type -MemberDefinition $sig -Name 'CRYPT32_CertAddStoreToCollection' -Namespace Win32 -PassThru
# $api::CertAddStoreToCollection(hCollectionStore, hSiblingStore, dwUpdateFlags, dwPriority)

#uselib "CRYPT32.dll"
#func global CertAddStoreToCollection "CertAddStoreToCollection" sptr, sptr, sptr, sptr
; CertAddStoreToCollection hCollectionStore, hSiblingStore, dwUpdateFlags, dwPriority   ; 戻り値は stat
; hCollectionStore : HCERTSTORE -> "sptr"
; hSiblingStore : HCERTSTORE optional -> "sptr"
; dwUpdateFlags : DWORD -> "sptr"
; dwPriority : DWORD -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

#uselib "CRYPT32.dll"
#cfunc global CertAddStoreToCollection "CertAddStoreToCollection" sptr, sptr, int, int
; res = CertAddStoreToCollection(hCollectionStore, hSiblingStore, dwUpdateFlags, dwPriority)
; hCollectionStore : HCERTSTORE -> "sptr"
; hSiblingStore : HCERTSTORE optional -> "sptr"
; dwUpdateFlags : DWORD -> "int"
; dwPriority : DWORD -> "int"

; BOOL CertAddStoreToCollection(HCERTSTORE hCollectionStore, HCERTSTORE hSiblingStore, DWORD dwUpdateFlags, DWORD dwPriority)
#uselib "CRYPT32.dll"
#cfunc global CertAddStoreToCollection "CertAddStoreToCollection" intptr, intptr, int, int
; res = CertAddStoreToCollection(hCollectionStore, hSiblingStore, dwUpdateFlags, dwPriority)
; hCollectionStore : HCERTSTORE -> "intptr"
; hSiblingStore : HCERTSTORE optional -> "intptr"
; dwUpdateFlags : DWORD -> "int"
; dwPriority : DWORD -> "int"

import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	crypt32 = windows.NewLazySystemDLL("CRYPT32.dll")
	procCertAddStoreToCollection = crypt32.NewProc("CertAddStoreToCollection")
)

// hCollectionStore (HCERTSTORE), hSiblingStore (HCERTSTORE optional), dwUpdateFlags (DWORD), dwPriority (DWORD)
r1, _, err := procCertAddStoreToCollection.Call(
	uintptr(hCollectionStore),
	uintptr(hSiblingStore),
	uintptr(dwUpdateFlags),
	uintptr(dwPriority),
)
_ = err  // syscall.Errno (valid when the call sets last-error)
_ = r1   // BOOL

function CertAddStoreToCollection(
  hCollectionStore: THandle;   // HCERTSTORE
  hSiblingStore: THandle;   // HCERTSTORE optional
  dwUpdateFlags: DWORD;   // DWORD
  dwPriority: DWORD   // DWORD
): BOOL; stdcall;
  external 'CRYPT32.dll' name 'CertAddStoreToCollection';

result := DllCall("CRYPT32\CertAddStoreToCollection"
    , "Ptr", hCollectionStore   ; HCERTSTORE
    , "Ptr", hSiblingStore   ; HCERTSTORE optional
    , "UInt", dwUpdateFlags   ; DWORD
    , "UInt", dwPriority   ; DWORD
    , "Int")   ; return: BOOL

●CertAddStoreToCollection(hCollectionStore, hSiblingStore, dwUpdateFlags, dwPriority) = DLL("CRYPT32.dll", "bool CertAddStoreToCollection(void*, void*, dword, dword)")
# 呼び出し: CertAddStoreToCollection(hCollectionStore, hSiblingStore, dwUpdateFlags, dwPriority)
# hCollectionStore : HCERTSTORE -> "void*"
# hSiblingStore : HCERTSTORE optional -> "void*"
# dwUpdateFlags : DWORD -> "dword"
# dwPriority : DWORD -> "dword"
# なでしこ1は32bit・ANSI(Shift_JIS)。文字列=char*(ANSI)、ポインタ/ハンドル=void*(4byte)。

const std = @import("std");

extern "crypt32" fn CertAddStoreToCollection(
    hCollectionStore: ?*anyopaque, // HCERTSTORE
    hSiblingStore: ?*anyopaque, // HCERTSTORE optional
    dwUpdateFlags: u32, // DWORD
    dwPriority: u32 // DWORD
) callconv(std.os.windows.WINAPI) i32;

proc CertAddStoreToCollection(
    hCollectionStore: pointer,  # HCERTSTORE
    hSiblingStore: pointer,  # HCERTSTORE optional
    dwUpdateFlags: uint32,  # DWORD
    dwPriority: uint32  # DWORD
): int32 {.importc: "CertAddStoreToCollection", stdcall, dynlib: "CRYPT32.dll".}

pragma(lib, "crypt32");
extern(Windows)
int CertAddStoreToCollection(
    void* hCollectionStore,   // HCERTSTORE
    void* hSiblingStore,   // HCERTSTORE optional
    uint dwUpdateFlags,   // DWORD
    uint dwPriority   // DWORD
);

ccall((:CertAddStoreToCollection, "CRYPT32.dll"), stdcall, Int32,
      (Ptr{Cvoid}, Ptr{Cvoid}, UInt32, UInt32),
      hCollectionStore, hSiblingStore, dwUpdateFlags, dwPriority)
# hCollectionStore : HCERTSTORE -> Ptr{Cvoid}
# hSiblingStore : HCERTSTORE optional -> Ptr{Cvoid}
# dwUpdateFlags : DWORD -> UInt32
# dwPriority : DWORD -> UInt32
# stdcall は 32bit のみ意味を持つ(x64 では無視)。

local ffi = require("ffi")
ffi.cdef[[
int32_t CertAddStoreToCollection(
    void* hCollectionStore,
    void* hSiblingStore,
    uint32_t dwUpdateFlags,
    uint32_t dwPriority);
]]
local crypt32 = ffi.load("crypt32")
-- crypt32.CertAddStoreToCollection(hCollectionStore, hSiblingStore, dwUpdateFlags, dwPriority)
-- hCollectionStore : HCERTSTORE
-- hSiblingStore : HCERTSTORE optional
-- dwUpdateFlags : DWORD
-- dwPriority : DWORD
-- 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。

const koffi = require('koffi');
const lib = koffi.load('CRYPT32.dll');
const CertAddStoreToCollection = lib.func('__stdcall', 'CertAddStoreToCollection', 'int32_t', ['void *', 'void *', 'uint32_t', 'uint32_t']);
// CertAddStoreToCollection(hCollectionStore, hSiblingStore, dwUpdateFlags, dwPriority)
// hCollectionStore : HCERTSTORE -> 'void *'
// hSiblingStore : HCERTSTORE optional -> 'void *'
// dwUpdateFlags : DWORD -> 'uint32_t'
// dwPriority : DWORD -> 'uint32_t'
// 出力ポインタは koffi.out(...) で包む。構造体は koffi.struct で定義。

const lib = Deno.dlopen("CRYPT32.dll", {
  CertAddStoreToCollection: { parameters: ["pointer", "pointer", "u32", "u32"], result: "i32" },
});
// lib.symbols.CertAddStoreToCollection(hCollectionStore, hSiblingStore, dwUpdateFlags, dwPriority)
// hCollectionStore : HCERTSTORE -> "pointer"
// hSiblingStore : HCERTSTORE optional -> "pointer"
// dwUpdateFlags : DWORD -> "u32"
// dwPriority : DWORD -> "u32"
// 文字列引数は "buffer"(NUL 終端のバイト列を Uint8Array で渡す)。
// 値渡し構造体は { struct: [ ...field types... ] } を使用。

<?php
$ffi = FFI::cdef(<<<C
int32_t CertAddStoreToCollection(
    void* hCollectionStore,
    void* hSiblingStore,
    uint32_t dwUpdateFlags,
    uint32_t dwPriority);
C, "CRYPT32.dll");
// $ffi->CertAddStoreToCollection(hCollectionStore, hSiblingStore, dwUpdateFlags, dwPriority);
// hCollectionStore : HCERTSTORE
// hSiblingStore : HCERTSTORE optional
// dwUpdateFlags : DWORD
// dwPriority : DWORD
// 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
// WINAPI(stdcall): x64 では呼出規約が統一されるため問題なし。x86 では __stdcall 対応のラッパが必要な場合あり。

import com.sun.jna.*;
import com.sun.jna.ptr.*;
import com.sun.jna.win32.StdCallLibrary;
import com.sun.jna.win32.W32APIOptions;

public interface Crypt32 extends StdCallLibrary {
    Crypt32 INSTANCE = Native.load("crypt32", Crypt32.class);
    boolean CertAddStoreToCollection(
        Pointer hCollectionStore,   // HCERTSTORE
        Pointer hSiblingStore,   // HCERTSTORE optional
        int dwUpdateFlags,   // DWORD
        int dwPriority   // DWORD
    );
}

@[Link("crypt32")]
lib LibCRYPT32
  fun CertAddStoreToCollection = CertAddStoreToCollection(
    hCollectionStore : Void*,   # HCERTSTORE
    hSiblingStore : Void*,   # HCERTSTORE optional
    dwUpdateFlags : UInt32,   # DWORD
    dwPriority : UInt32   # DWORD
  ) : Int32
end
# 構造体/GUID/enum は lib 内に対応する型定義が必要。
# 呼出規約: x64 は規約統一のため OK。x86(32bit)は WINAPI=stdcall だが Crystal の fun に stdcall 付与構文がなく非対応。

import 'dart:ffi';
import 'package:ffi/ffi.dart';

typedef CertAddStoreToCollectionNative = Int32 Function(Pointer<Void>, Pointer<Void>, Uint32, Uint32);
typedef CertAddStoreToCollectionDart = int Function(Pointer<Void>, Pointer<Void>, int, int);
final CertAddStoreToCollection = DynamicLibrary.open('CRYPT32.dll')
    .lookupFunction<CertAddStoreToCollectionNative, CertAddStoreToCollectionDart>('CertAddStoreToCollection');
// hCollectionStore : HCERTSTORE -> Pointer<Void>
// hSiblingStore : HCERTSTORE optional -> Pointer<Void>
// dwUpdateFlags : DWORD -> Uint32
// dwPriority : DWORD -> Uint32
// 文字列は package:ffi の "...".toNativeUtf16()/toNativeUtf8() で変換。

{$mode objfpc}{$H+}
function CertAddStoreToCollection(
  hCollectionStore: THandle;   // HCERTSTORE
  hSiblingStore: THandle;   // HCERTSTORE optional
  dwUpdateFlags: DWORD;   // DWORD
  dwPriority: DWORD   // DWORD
): BOOL; stdcall;
  external 'CRYPT32.dll' name 'CertAddStoreToCollection';

import Foreign
import Foreign.C.Types
import Foreign.C.String

foreign import stdcall safe "CertAddStoreToCollection"
  c_CertAddStoreToCollection :: Ptr () -> Ptr () -> Word32 -> Word32 -> IO CInt
-- hCollectionStore : HCERTSTORE -> Ptr ()
-- hSiblingStore : HCERTSTORE optional -> Ptr ()
-- dwUpdateFlags : DWORD -> Word32
-- dwPriority : DWORD -> Word32
-- 要 GHC(Windows)。stdcall は x64 では ccall として扱われる。ブロックする API は safe 呼び出し推奨。

open Ctypes
open Foreign

let certaddstoretocollection =
  foreign "CertAddStoreToCollection"
    ((ptr void) @-> (ptr void) @-> uint32_t @-> uint32_t @-> returning int32_t)
(* hCollectionStore : HCERTSTORE -> (ptr void) *)
(* hSiblingStore : HCERTSTORE optional -> (ptr void) *)
(* dwUpdateFlags : DWORD -> uint32_t *)
(* dwPriority : DWORD -> uint32_t *)
(* foreign は cdecl 前提。x64 Windows では WINAPI と一致。構造体は ctypes structure を定義のこと。 *)

(cffi:define-foreign-library crypt32 (t "CRYPT32.dll"))
(cffi:use-foreign-library crypt32)

(cffi:defcfun ("CertAddStoreToCollection" cert-add-store-to-collection :convention :stdcall) :int32
  (h-collection-store :pointer)   ; HCERTSTORE
  (h-sibling-store :pointer)   ; HCERTSTORE optional
  (dw-update-flags :uint32)   ; DWORD
  (dw-priority :uint32))   ; DWORD
; isize/usize(INT_PTR/SIZE_T)は x64 前提で :int64/:uint64。x86 では :int32/:uint32。

use Win32::API;
my $CertAddStoreToCollection = Win32::API::More->new('CRYPT32',
    'BOOL CertAddStoreToCollection(HANDLE hCollectionStore, HANDLE hSiblingStore, DWORD dwUpdateFlags, DWORD dwPriority)');
# my $ret = $CertAddStoreToCollection->Call($hCollectionStore, $hSiblingStore, $dwUpdateFlags, $dwPriority);
# hCollectionStore : HCERTSTORE -> HANDLE
# hSiblingStore : HCERTSTORE optional -> HANDLE
# dwUpdateFlags : DWORD -> DWORD
# dwPriority : DWORD -> DWORD
# 値渡し構造体は pack() した文字列、または Win32::API::Struct を使用。