NAME

Win32::CryptData - Perl wrapper for Win32 CryptProtectData and CryptUnprotectData functions.

SYNOPSIS

 use Win32::CryptData;

 $ret = Win32::CryptProtect::CryptProtectData();

 $ret = Win32::CryptProtect::CryptUnprotectData();

DESCRIPTION

Interface to Win32 Crypto API functions and data structures, needed to perform data encryption and decrtyption. Typically, only a user with logon credentials matching those of the encrypter can decrypt the data. In addition, decryption usually can only be done on the computer where the data was encrypted. However, a user with a roaming profile can decrypt the data from another computer on the network.

This module covers a small subset of the functions and data structures provided by the Win32 Crypto API.

Purpose

This documentation provides information about services, components, and tools that enable application developers to add cryptographic security to their applications. This includes CryptoAPI 2.0, Cryptographic Service Providers (CSP), CryptoAPI Tools, CAPICOM, WinTrust, issuing and managing certificates, and developing customizable public-key infrastructures. Certificate and smart card enrollment, certificate management, and custom module development are also described.

Developer Audience

CryptoAPI is intended for use by developers of applications based on the Microsoft® Windows® and Microsoft Windows NT® operating systems that will enable users to create and exchange documents and other data in a secure environment, especially over nonsecure media such as the Internet. Developers should be familiar with the C and C++ programming languages and the Windows programming environment. Although not required, an understanding of cryptography or security-related subjects is advised.

CAPICOM is intended for use by developers who are creating applications using the Microsoft Visual Basic® development system, the Visual Basic Scripting Edition (VBScript) programming language, or the C++ programming language.

Run-time Requirements

The Crypto API is supported on:

• Windows Server 2003

• Windows XP

• Windows 2000

• Microsoft Windows 2000

• Microsoft Windows NT, version 4.0, with Service Pack 4 or later

• Windows 98 with Microsoft Internet Explorer 5 or later

Note

CAPICOM 1.0 is supported by the same operating systems, with the addition of Windows 95 with Microsoft Internet Explorer 5 or later.

CAPICOM is available as a redistributable file that can be downloaded from the Platform SDK Redistributables Web site.

EXPORT

None by default.

FUNCTIONS

CryptProtectData(\$DataIn,\$DataDescr,\$OptionalEntropy,\$Reserved,\%PromptStruct,$Flags,\$DataOut)

The CryptProtectData function performs encryption on the data in $DataIn. Typically, only a user with the same logon credential as the encrypter can decrypt the data. In addition, the encryption and decryption usually must be done on the same computer.

Parameters

$DataIn

Reference to a scalar that contains the plaintext to be encrypted.

\$DataDescr

Reference to a scalar with a readable description of the data to be encrypted. This description string is included with the encrypted data. This parameter is optional and can be set to undef.

\$OptionalEntropy

Reference to a scalar that contains a password or other additional entropy used to encrypt the data. The value used in the encryption phase must also be used in the decryption phase. This parameter can be set to undef for no additional entropy.

\$Reserved

Reserved for future use and must be set to a reference to undef.

\%PromptStruct

Reference to a %PromptStruct structure that provides information about where and when prompts are to be displayed and what the content of those prompts should be. This parameter can be set to NULL in both the encryption and decryption phases

$Flags

This parameter can be one or more of the following flags:

 CRYPTPROTECT_LOCAL_MACHINE
   When this flag is set, it associates the data encrypted with the current computer instead of with an individual user.
   Any user on the computer on which CryptProtectData is called can use CryptUnprotectData to decrypt the data.

 CRYPTPROTECT_UI_FORBIDDEN
   This flag is used for remote situations where presenting a user interface (UI) is not an option.
   When this flag is set and UI is specified for either the protect or unprotect operation, the operation fails.

 CRYPTPROTECT_AUDIT
   This flag generates an audit on protect and unprotect operations.

 CRYPTPROTECT_VERIFY_PROTECTION
   This flag verifies the protection of a protected item.

\$DataOut

Reference to a scalar that receives the encrypted data.

Example

  use strict;
  use Win32::CryptData qw(:flags);

  my $DataIn = 'This is plain data';
  my $DataDescr = 'This is the description';
  my $OptionalEntropy = 'mysecret';
  my $Reserved = undef;
  my %PromptStruct = (
    PromptFlags => CRYPTPROTECT_PROMPT_ON_PROTECT | CRYPTPROTECT_PROMPT_ON_UNPROTECT | CRYPTPROTECT_PROMPT_STRONG,
    hwndApp => undef,
    Prompt => 'This is the caption'
  );
  my $Flags = CRYPTPROTECT_AUDIT;
  my $DataOut;

  my $ret = Win32::CryptData::CryptProtectData(\$DataIn, \$DataDescr, \$OptionalEntropy, \$Reserved, \%PromptStruct, $Flags, \$DataOut);

  if($ret)
  {
    print "Encrypted data (hex): " . unpack("H*", $DataOut) . "\n";
  }
  else
  {
    print "Error: $^E\n";
  }

Return Values

If the function succeeds, the return value is 1.

If the function fails, the error code is contained in $^E.

Remarks

Typically, only a user with logon credentials matching those of the encrypter can decrypt the data. In addition, decryption usually can only be done on the computer where the data was encrypted. However, a user with a roaming profile can decrypt the data from another computer on the network.

If the CRYPTPROTECT_LOCAL_MACHINE flag is set when the data is encrypted, any user on the computer where the encryption was done can decrypt the data.

The function creates a session key to perform the encryption. The session key is re-derived when the data is to be decrypted.

The function also adds a MAC (keyed integrity check) to the encrypted data to guard against data tampering.

Requirements

Client: Included in Windows XP, Windows 2000 Professional. Server: Included in Windows Server 2003, Windows 2000 Server. Header: Declared in Wincrypt.h. Library: Use Crypt32.lib.

CryptUnprotectData(\$DataIn,\$DataDescr,\$OptionalEntropy,\$Reserved,\%PromptStruct,$Flags,\$DataOut)

The CryptUnprotectData function decrypts and does an integrity check of the data in $DataIn. Usually, only a user with the same logon credentials as the encrypter can decrypt the data. In addition, the encryption and decryption must be done on the same computer.

Parameters

\$DataIn

Reference to a scalar that contains the encrypted data.

\$DataDescr

Reference to a scaral that will receive a string-readable description of the encrypted data included with the encrypted data. This parameter can be set to undef.

\$OptionalEntropy

Reference to a scalar that contains a password or other additional entropy used when the data was encrypted.

\$Reserved

Reserved for future use and must be set to a reference to undef.

\%PromptStruct

Reference to a %PromptStruct structure that provides information about where and when prompts are to be displayed and what the content of those prompts should be. This parameter can be set to NULL.

$Flags

This parameter can be one or more of the following flags:

 CRYPTPROTECT_UI_FORBIDDEN
   This flag is used for remote situations where the user interface (UI) is not an option.
   When this flag is set and UI is specified for either the protect or unprotect operation, the operation fails.

\$DataOut

Reference to a scalar where the function stores the decrypted data.

Examples

  use strict;
  use Win32::CryptData qw(:all);

  my $DataIn = 'This is encrypted data';
  my $DataDescr = undef;
  my $OptionalEntropy = 'mysecret';
  my $Reserved = undef;
  my %PromptStruct = (
    PromptFlags => undef,
    hwndApp => undef,
    Prompt => 'This is the caption'
  );
  my $Flags = undef;
  my $DataOut;

  my $ret = Win32::CryptData::CryptUnprotectData(\$DataIn, \$DataDescr, \$OptionalEntropy, \$Reserved, \%PromptStruct, $Flags, \$DataOut);

  if($ret)
  {
    print "Decrypted data: $DataOut\n";
    print "Description: $DataDescr\n";
  }
  else
  {
    print "Error: $^E\n";
  }

Return Values

If the function succeeds, the return value is 1.

If the function fails, the error code is contained in $^E.

Remarks

The CryptProtectData function creates a session key when the data is encrypted. That key is re-derived and used to decrypt the data BLOB.

The MAC hash added to the encrypted data can be used to determine whether the encrypted data was altered in any way. Any tampering results in the return of the ERROR_INVALID_DATA code.

Requirements

Client: Included in Windows XP, Windows 2000 Professional. Server: Included in Windows Server 2003, Windows 2000 Server. Header: Declared in Wincrypt.h. Library: Use Crypt32.lib.

DATA Structures

%PromptStruct

The %PromptStruct hash defines the behaviour of the prompting dialog box, the valid keys are:

PromptFlags

any of the valid flags:

  CRYPTPROTECT_PROMPT_ON_PROTECT
    This flag is used to provide the prompt for the protect phase.

  CRYPTPROTECT_PROMPT_ON_UNPROTECT
    This flag can be combined with CRYPTPROTECT_PROMPT_ON_PROTECT to enforce the UI (user interface) policy of the caller.
    When CryptUnprotectData is called, the dwPromptFlags specified in the CryptProtectData call are enforced.

  CRYPTPROTECT_PROMPT_STRONG
    This flag forces user to provide an encryption password

hwndApp

Window handle to the parent window

Prompt

A string containing the text of a prompt to be displayed

CREDITS

Thanks to Aldo Calpini for the powerful Win32::API module that makes this thing work.

AUTHOR

Luigino Masarati, <lmasarati@hotmail.com>

cpanm Win32::CryptData

perl -MCPAN -e shell
install Win32::CryptData