CryptMsgControl 関数 (wincrypt.h)
CryptMsgControl 関数は、メッセージが CryptMsgUpdate 関数の最後の呼び出しによってデコードされた後に制御操作を実行します。 この関数によって提供される制御操作は、暗号化解除、署名とハッシュ検証、および証明書、 証明書失効リスト (CRL)、署名者、認証されていない属性の追加と削除に使用されます。
Secure /Multipurpose Internet Mail Extensions (S/MIME) 電子メールの相互運用性をサポートするために、エンベロープされたメッセージの処理に影響を与える重要な変更が CryptoAPI に加えられています。 詳細については、「 CryptMsgOpenToEncode 関数の備考」を参照してください。
構文
BOOL CryptMsgControl(
[in] HCRYPTMSG hCryptMsg,
[in] DWORD dwFlags,
[in] DWORD dwCtrlType,
[in] void const *pvCtrlPara
);
パラメーター
[in] hCryptMsg
コントロールを適用する暗号化メッセージのハンドル。
[in] dwFlags
dwCtrlType パラメーターが次のいずれかである場合、次の値が定義されます。
- CMSG_CTRL_DECRYPT
- CMSG_CTRL_KEY_TRANS_DECRYPT
- CMSG_CTRL_KEY_AGREE_DECRYPT
- CMSG_CTRL_MAIL_LIST_DECRYPT
| 値 | 意味 |
|---|---|
|
暗号化プロバイダーへのハンドルは、 CryptMsgClose 関数の最後の呼び出しで解放されます。 CryptMsgControl 関数が失敗した場合、このハンドルは解放されません。 |
dwCtrlType パラメーターで暗号化解除操作が指定されていない場合は、この値を 0 に設定します。
[in] dwCtrlType
実行する操作の種類。 現在定義されているメッセージ コントロールの型と、 pvCtrlPara パラメーターに渡す必要がある構造体の型を次の表に示します。
| 値 | 意味 |
|---|---|
|
属性証明書のエンコードされたバイト数を含む BLOB 。 |
|
メッセージ に 追加する証明書のエンコードされたバイトを含むCRYPT_INTEGER_BLOB構造体。 |
|
署名者情報を含む CMSG_CMS_SIGNER_INFO 構造体。 署名者情報 に署名が 含まれているため、この操作はCMSG_CTRL_ADD_SIGNERとは異なります。 |
|
メッセージに追加する CRL のエンコードされたバイトを含む BLOB。 |
|
メッセージ に 追加する署名者情報を含むCMSG_SIGNER_ENCODE_INFO構造体。 |
|
署名者のインデックスを含む CMSG_CTRL_ADD_SIGNER_UNAUTH_ATTR_PARA 構造と、メッセージに追加する認証されていない属性情報を含む BLOB。 |
|
指定したキー トランスポート受信者のメッセージの暗号化を解除するために使用される CMSG_CTRL_DECRYPT_PARA 構造体。 この値は RSA 受信者に適用されます。 この操作では、 CryptMsgControl 関数が受信者インデックスを検索して、キー トランスポート受信者情報を取得するように指定します。 関数が失敗した場合、キー トランスポート受信者が見つからない場合、 GetLastError は CRYPT_E_INVALID_INDEX を返します。 |
|
削除する属性証明書のインデックス。 |
|
メッセージから削除する証明書のインデックス。 |
|
メッセージから削除する CRL のインデックス。 |
|
削除する署名者のインデックス。 |
|
署名者を指定するインデックスと、削除する署名者の認証されていない属性を指定するインデックスを含むCMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR_PARA構造体。 |
|
厳密な署名チェックを実行するために使用される CERT_STRONG_SIGN_PARA 構造体。
厳密な署名をチェックするには、CryptMsgGetAndVerifySigner を呼び出す前に、または次のコントロール型を設定して CryptMsgControl を呼び出す前に、このコントロールの種類を指定します。
|
|
指定したキー アグリーメント セッション キーのメッセージの暗号化を解除するために使用される CMSG_CTRL_KEY_AGREE_DECRYPT_PARA 構造体。 キー アグリーメントは、Diffie-Hellman 暗号化/暗号化解除で使用されます。 |
|
指定したキー トランスポート受信者のメッセージの暗号化を解除するために使用される CMSG_CTRL_KEY_TRANS_DECRYPT_PARA 構造体。 キー トランスポートは、RSA 暗号化/暗号化解除と共に使用されます。 |
|
以前に分散されたキー暗号化キー (KEK) を使用して、指定した受信者のメッセージの暗号化を解除するために使用される CMSG_CTRL_MAIL_LIST_DECRYPT_PARA 構造。 |
|
この値は使用されません。 |
|
署名を検証するメッセージの署名者を識別するCERT_INFO構造体。 |
|
メッセージ署名を検証するための署名者インデックスと公開キーを指定する CMSG_CTRL_VERIFY_SIGNATURE_EX_PARA 構造体。 署名者の公開キーには、 CERT_PUBLIC_KEY_INFO 構造、証明書コンテキスト、または証明書チェーン コンテキストを指定できます。 |
[in] pvCtrlPara
dwCtrlType の値によって決定される構造体へのポインター。
| dwCtrlType 値 | 意味 |
|---|---|
|
デコードは、ストリーミングされたコンテンツが復号化されているかのように実行されます。 この呼び出しの前に暗号化されたストリーミング コンテンツが蓄積されている場合、暗号テキストの暗号化解除の結果として得られた プレーンテキスト の一部またはすべてが 、CryptMsgOpenToDecode 関数の呼び出しで指定されたコールバック関数を介してアプリケーションに返されます。
メモ エンベロープ メッセージをストリーミングする場合、CMSG_ENVELOPE_ALGORITHM_PARAMの可用性のポーリングが成功するまで 、CryptMsgControl 関数は呼び出されません。 ポーリングが成功しない場合は、エラーが発生します。 そのポーリングの説明については、 CryptMsgOpenToDecode 関数を参照してください。
|
|
メッセージの内容から計算された ハッシュ は、メッセージに含まれるハッシュと比較されます。 |
|
pvCtrlPara は 、メッセージに追加する署名者情報を含む CMSG_SIGNER_ENCODE_INFO 構造体を指します。 |
|
削除が行われた後、このメッセージに使用されている他の署名者インデックスは無効になり、 CryptMsgGetParam 関数を呼び出して再取得する必要があります。 |
|
削除が行われた後、この署名者に使用されている他の認証されていない属性インデックスは無効になり、 CryptMsgGetParam 関数を呼び出して再取得する必要があります。 |
|
削除が行われた後、このメッセージに使用されている他の証明書インデックスは無効になり、 CryptMsgGetParam 関数を呼び出して再取得する必要があります。 |
|
削除が行われた後、このメッセージに使用されている他の CRL インデックスは無効になり、 CryptMsgGetParam 関数を呼び出して再取得する必要があります。 |
戻り値
関数が成功すると、戻り値は 0 以外になります。
関数が失敗した場合、戻り値は 0 で、 GetLastError 関数は 抽象構文表記 1 (ASN.1) エンコード/デコード エラーを返します。 これらのエラーの詳細については、「 ASN.1 エンコード/デコードの戻り値」を参照してください。
ストリーミングされたエンベロープ メッセージがデコードされると、 の pStreamInfo パラメーターで指定されたアプリケーション定義のコールバック関数でエラーが発生します。
CryptMsgOpenToDecode 関数は 、CryptMsgControl 関数に反映される場合があります。 この場合、コールバック関数が戻った後、 SetLastError 関数は CryptMsgControl 関数によって呼び出されません。 これにより、アプリケーションの制御下で発生したエラーが保持されます。 アプリケーションでストリームデータの処理中にエラーが発生した場合に SetLastError 関数を呼び出すには、コールバック関数 (または呼び出す API の 1 つ) が必要です。
伝達されたエラーは、次の関数から発生する可能性があります。
- CryptCreateHash
- CryptDecrypt
- CryptGetHashParam
- CryptGetUserKey
- CryptHashData
- CryptImportKey
- CryptSignHash
- CryptVerifySignature
次のエラー コードが最も一般的に返されます。
| リターン コード | 説明 |
|---|---|
|
メッセージの内容は既に暗号化解除されています。 dwCtrlType パラメーターが CMSG_CTRL_DECRYPT に設定されている場合、このエラーを返すことができます。 |
|
メッセージに、想定される認証済み属性が含まれていません。 dwCtrlType パラメーターが CMSG_CTRL_VERIFY_SIGNATURE に設定されている場合、このエラーが返される可能性があります。 |
|
エンコードまたはデコード中にエラーが発生しました。 dwCtrlType パラメーターが CMSG_CTRL_VERIFY_SIGNATURE に設定されている場合、このエラーが返される可能性があります。 |
|
コントロールの種類が無効です。 |
|
ハッシュ値が正しくありません。 |
|
インデックス値が無効です。 |
|
メッセージ型が無効です。 |
|
オブジェクト識別子の形式が正しくありません。 dwCtrlType パラメーターが CMSG_CTRL_ADD_SIGNER に設定されている場合、このエラーが返される可能性があります。 |
|
エンベロープ されたデータ メッセージには、指定された受信者が含まれていません。 dwCtrlType パラメーターが CMSG_CTRL_DECRYPT に設定されている場合、このエラーを返すことができます。 |
|
メッセージの指定された署名者が見つかりませんでした。 dwCtrlType パラメーターが CMSG_CTRL_VERIFY_SIGNATURE に設定されている場合、このエラーが返される可能性があります。 |
|
暗号化アルゴリズムが不明です。 |
|
メッセージが想定どおりにエンコードされていません。 dwCtrlType パラメーターが CMSG_CTRL_VERIFY_SIGNATURE に設定されている場合、このエラーが返される可能性があります。 |
|
1 つ以上の引数が無効です。 dwCtrlType パラメーターが CMSG_CTRL_DECRYPT に設定されている場合、このエラーを返すことができます。 |
|
操作を完了するのに十分なメモリが使用できませんでした。 |
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows XP [デスクトップ アプリ | UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2003 [デスクトップ アプリのみ | UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | wincrypt.h |
| Library | Crypt32.lib |
| [DLL] | Crypt32.dll |