ホーム › Security.Cryptography › CryptBinaryToStringA

CryptBinaryToStringA

関数

バイナリデータをBase64などのANSI文字列に変換する。

DLLCRYPT32.dll文字セットANSI (-A)呼出規約winapi対応OSWindows XP 以降

シグネチャ

// CRYPT32.dll  (ANSI / -A)
#include <windows.h>

BOOL CryptBinaryToStringA(
    const BYTE* pbBinary,
    DWORD cbBinary,
    CRYPT_STRING dwFlags,
    LPSTR pszString,   // optional
    DWORD* pcchString
);

パラメーター

名前

型

方向

説明

pbBinary

BYTE*

文字列に変換するバイト配列へのポインター。

cbBinary

DWORD

pbBinary 配列の要素数。

dwFlags

CRYPT_STRING

変換後の書式付き文字列の形式を指定します。このパラメーターには次のいずれかの値を指定できます。

値	意味
CRYPT_STRING_BASE64HEADER 0x00000000	Base64。証明書の開始ヘッダーと終了ヘッダーを付加します。
CRYPT_STRING_BASE64 0x00000001	Base64。ヘッダーは付加しません。
CRYPT_STRING_BINARY 0x00000002	純粋なバイナリのコピー。
CRYPT_STRING_BASE64REQUESTHEADER 0x00000003	Base64。要求の開始ヘッダーと終了ヘッダーを付加します。
CRYPT_STRING_HEX 0x00000004	16 進数のみ。
CRYPT_STRING_HEXASCII 0x00000005	16 進数。ASCII 文字表示付き。
CRYPT_STRING_BASE64X509CRLHEADER 0x00000009	Base64。X.509 CRL の開始ヘッダーと終了ヘッダーを付加します。
CRYPT_STRING_HEXADDR 0x0000000a	16 進数。アドレス表示付き。
CRYPT_STRING_HEXASCIIADDR 0x0000000b	16 進数。ASCII 文字表示およびアドレス表示付き。
CRYPT_STRING_HEXRAW 0x0000000c	生の 16 進数文字列。 Windows Server 2003 および Windows XP: この値はサポートされていません。
CRYPT_STRING_BASE64URI 0x0000000d	Base64。ヘッダーなしで、RFC 4648 のセクション 5 に定義されているとおり "+" を "-" に、"/" を "_" に置き換えます。
CRYPT_STRING_STRICT 0x20000000	ASN.1 テキスト形式の厳密なデコードを強制します。一部の ASN.1 バイナリ BLOB では、BLOB の先頭数バイトが Base64 テキストとして誤って解釈されることがあります。この場合、残りのテキストは無視されます。このフラグを使用すると、BLOB の完全なデコードが強制されます。 Windows Server 2008、Windows Vista、Windows Server 2003 および Windows XP: この値はサポートされていません。

上記の値に加えて、次の値を 1 つ以上指定して関数の動作を変更できます。

値	意味
CRYPT_STRING_NOCRLF 0x40000000	エンコードされた文字列に改行文字を付加しません。既定の動作では、改行を表すためにキャリッジリターン/ラインフィード (CR/LF) のペア (0x0D/0x0A) が使用されます。 Windows Server 2003 および Windows XP: この値はサポートされていません。
CRYPT_STRING_NOCR 0x80000000	改行にラインフィード (LF) 文字 (0x0A) のみを使用します。既定の動作では、改行を表すために CR/LF のペア (0x0D/0x0A) が使用されます。

pszString

LPSTR

outoptional

変換後の文字列を受け取るバッファーへのポインター。返される文字列を格納するために割り当てる必要がある文字数を計算するには、このパラメーターを NULL に設定します。関数は、終端の NULL 文字を含む必要な文字数を、pcchString が指す値に格納します。

pcchString

DWORD*

inout

pszString バッファーのサイズを TCHAR 単位で格納する DWORD 変数へのポインター。pszString が NULL の場合、関数は返される文字列の長さ (終端の null 文字を含む) を TCHAR 単位で計算し、このパラメーターに返します。pszString が NULL でなく、かつ十分な大きさがある場合、関数はバイナリデータを終端の null 文字を含む指定した文字列形式に変換しますが、pcchString には終端の null 文字を含まない TCHAR 単位の長さが返されます。

戻り値の型: BOOL

公式ドキュメント

バイト配列を書式付き文字列に変換します。(ANSI)

戻り値

関数が成功した場合、関数は 0 以外の値 (TRUE) を返します。

関数が失敗した場合は、0 (FALSE) を返します。

解説(Remarks)

CRYPT_STRING_BINARY エンコードが使用される場合を除き、すべての文字列には改行シーケンスが付加されます。既定では、改行シーケンスは CR/LF のペア (0x0D/0x0A) です。dwFlags パラメーターに CRYPT_STRING_NOCR フラグが含まれている場合、改行シーケンスは LF 文字 (0x0A) になります。dwFlags パラメーターに CRYPT_STRING_NOCRLF フラグが含まれている場合、文字列に改行シーケンスは付加されません。

メモ

wincrypt.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいてこの関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして CryptBinaryToString を定義しています。エンコードに依存しないこのエイリアスを、エンコードに依存しないわけではないコードと混在させて使用すると、不一致が生じ、コンパイルエラーや実行時エラーの原因となることがあります。詳細については、「関数プロトタイプの規則」を参照してください。

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

各言語での呼び出し定義

// CRYPT32.dll  (ANSI / -A)
#include <windows.h>

BOOL CryptBinaryToStringA(
    const BYTE* pbBinary,
    DWORD cbBinary,
    CRYPT_STRING dwFlags,
    LPSTR pszString,   // optional
    DWORD* pcchString
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("CRYPT32.dll", CharSet = CharSet.Ansi, ExactSpelling = true)]
static extern bool CryptBinaryToStringA(
    IntPtr pbBinary,   // BYTE*
    uint cbBinary,   // DWORD
    uint dwFlags,   // CRYPT_STRING
    [MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder pszString,   // LPSTR optional, out
    ref uint pcchString   // DWORD* in/out
);

<DllImport("CRYPT32.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function CryptBinaryToStringA(
    pbBinary As IntPtr,   ' BYTE*
    cbBinary As UInteger,   ' DWORD
    dwFlags As UInteger,   ' CRYPT_STRING
    <MarshalAs(UnmanagedType.LPStr)> pszString As System.Text.StringBuilder,   ' LPSTR optional, out
    ByRef pcchString As UInteger   ' DWORD* in/out
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' pbBinary : BYTE*
' cbBinary : DWORD
' dwFlags : CRYPT_STRING
' pszString : LPSTR optional, out
' pcchString : DWORD* in/out
Declare PtrSafe Function CryptBinaryToStringA Lib "crypt32" ( _
    ByVal pbBinary As LongPtr, _
    ByVal cbBinary As Long, _
    ByVal dwFlags As Long, _
    ByVal pszString As String, _
    ByRef pcchString As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

CryptBinaryToStringA = ctypes.windll.crypt32.CryptBinaryToStringA
CryptBinaryToStringA.restype = wintypes.BOOL
CryptBinaryToStringA.argtypes = [
    ctypes.POINTER(ctypes.c_ubyte),  # pbBinary : BYTE*
    wintypes.DWORD,  # cbBinary : DWORD
    wintypes.DWORD,  # dwFlags : CRYPT_STRING
    wintypes.LPSTR,  # pszString : LPSTR optional, out
    ctypes.POINTER(wintypes.DWORD),  # pcchString : DWORD* in/out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('CRYPT32.dll')
CryptBinaryToStringA = Fiddle::Function.new(
  lib['CryptBinaryToStringA'],
  [
    Fiddle::TYPE_VOIDP,  # pbBinary : BYTE*
    -Fiddle::TYPE_INT,  # cbBinary : DWORD
    -Fiddle::TYPE_INT,  # dwFlags : CRYPT_STRING
    Fiddle::TYPE_VOIDP,  # pszString : LPSTR optional, out
    Fiddle::TYPE_VOIDP,  # pcchString : DWORD* in/out
  ],
  Fiddle::TYPE_INT)

#[link(name = "crypt32")]
extern "system" {
    fn CryptBinaryToStringA(
        pbBinary: *const u8,  // BYTE*
        cbBinary: u32,  // DWORD
        dwFlags: u32,  // CRYPT_STRING
        pszString: *mut u8,  // LPSTR optional, out
        pcchString: *mut u32  // DWORD* in/out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("CRYPT32.dll", CharSet = CharSet.Ansi)]
public static extern bool CryptBinaryToStringA(IntPtr pbBinary, uint cbBinary, uint dwFlags, [MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder pszString, ref uint pcchString);
"@
$api = Add-Type -MemberDefinition $sig -Name 'CRYPT32_CryptBinaryToStringA' -Namespace Win32 -PassThru
# $api::CryptBinaryToStringA(pbBinary, cbBinary, dwFlags, pszString, pcchString)

#uselib "CRYPT32.dll"
#func global CryptBinaryToStringA "CryptBinaryToStringA" sptr, sptr, sptr, sptr, sptr
; CryptBinaryToStringA varptr(pbBinary), cbBinary, dwFlags, varptr(pszString), varptr(pcchString)   ; 戻り値は stat
; pbBinary : BYTE* -> "sptr"
; cbBinary : DWORD -> "sptr"
; dwFlags : CRYPT_STRING -> "sptr"
; pszString : LPSTR optional, out -> "sptr"
; pcchString : DWORD* in/out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "CRYPT32.dll"
#cfunc global CryptBinaryToStringA "CryptBinaryToStringA" var, int, int, var, var
; res = CryptBinaryToStringA(pbBinary, cbBinary, dwFlags, pszString, pcchString)
; pbBinary : BYTE* -> "var"
; cbBinary : DWORD -> "int"
; dwFlags : CRYPT_STRING -> "int"
; pszString : LPSTR optional, out -> "var"
; pcchString : DWORD* in/out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "CRYPT32.dll"
#cfunc global CryptBinaryToStringA "CryptBinaryToStringA" sptr, int, int, sptr, sptr
; res = CryptBinaryToStringA(varptr(pbBinary), cbBinary, dwFlags, varptr(pszString), varptr(pcchString))
; pbBinary : BYTE* -> "sptr"
; cbBinary : DWORD -> "int"
; dwFlags : CRYPT_STRING -> "int"
; pszString : LPSTR optional, out -> "sptr"
; pcchString : DWORD* in/out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。