blib/lib/Win32/Credentials.pm untested

filter: Statementstmt 0.0% 0 / 80 Branchbran 0.0% 0 / 24 Conditioncond 0.0% 0 / 12 MC/DCmcdc 0.0% 0 / 6 Subroutinesub 0.0% 0 / 13 Podpod 0.0% 0 / 4 totaltotal 0.0% 0 / 139 CC 13 SCAR 30.8
CC
13
Cov
0%
_build_credential_struct
42.0
cred_read
42.0
cred_write
6.0
CRAP 21.8
1 package Win32::Credentials;
2  
3 use strict;
4 use warnings;
5  
6  
7 our $VERSION = '0.03';
8  
9 =head1 NAME
10  
11 Win32::Credentials - Read/Write Windows Credential Manager via Win32 API
12  
13 =head1 SYNOPSIS
14  
15 use Win32::Credentials qw(cred_write cred_read cred_delete);
16  
17 # Store a secret
18 cred_write('My_App/My_password', 'myapp', 'secret123');
19  
20 # Retrieve a secret
21 my $secret = cred_read('My_App/My_password');
22  
23 # Retrieve secret and username
24 my ($secret, $user) = cred_read('My_App/My_password');
25  
26 # Delete
27 cred_delete('My_App/My_password');
28  
29 =head1 DESCRIPTION
30  
31 Provides a simple Perl interface to the Windows Credential Manager
32 (CredWriteW, CredReadW, CredDeleteW) via Win32::API.
33 Secrets are protected by DPAPI (AES-256) tied to the current
34 Windows user account.
35  
36 No XS compilation required - uses Win32::API.
37  
38 =head1 FUNCTIONS
39  
40 =head2 cred_write($target, $username, $secret)
41  
42 Stores a secret in the Windows Credential Manager.
43 Maximum secret size: 512 bytes (CRED_TYPE_GENERIC limit).
44  
45 =head2 cred_read($target)
46  
47 Retrieves a secret. In list context returns ($secret, $username).
48  
49 =head2 cred_delete($target)
50  
51 Removes a credential from the vault.
52  
53 =head1 NOTES
54  
55 =over 4
56  
57 =item * Requires 64-bit Windows and 64-bit Perl
58  
59 =item * Uses CRED_TYPE_GENERIC and CRED_PERSIST_LOCAL_MACHINE
60  
61 =item * Secret is stored as UTF-16LE (native Windows format)
62  
63 =back
64  
65 =head1 AUTHOR
66  
67 Massimiliano Citterio E<lt>mcitterio@cmcps.itE<gt>
68  
69 =head1 LICENSE
70  
71 This library is free software; you can redistribute it and/or modify
72 it under the same terms as Perl itself.
73  
74 =cut
75  
76 use Exporter 'import';
77 use Encode qw(encode decode);
78 use Win32::API;
79 use Win32;
80  
81 our @EXPORT_OK = qw(cred_write cred_read cred_delete);
82  
83 # Constants
84 use constant CRED_TYPE_GENERIC => 1;
85 use constant CRED_PERSIST_LOCAL_MACHINE => 2;
86 use constant CRED_PERSIST_ENTERPRISE => 3;
87  
88 # Load from advapi32.dll
89 #
90 # BOOL CredWriteW(PCREDENTIALW Credential, DWORD Flags)
91 # BOOL CredReadW (LPCWSTR TargetName, DWORD Type, DWORD Flags, PCREDENTIALW *Credential)
92 # BOOL CredReadW (LPCWSTR TargetName, DWORD Type, DWORD Flags)
93 # VOID CredFree (PVOID Buffer)
94  
95 # L An unsigned long value.
96  
97 # Q An unsigned quad value.
98 # (Quads are available only if your system supports 64-bit
99 # integer values and if Perl has been compiled to support
100 # those. Raises an exception otherwise.)
101  
102  
103 # Windows API Loaders
104 my $CredWrite = Win32::API->new(
105 'advapi32', 'CredWriteW', 'PI', 'I'
106 ) or die "CredWriteW: $^E";
107  
108 my $CredRead = Win32::API->new(
109 'advapi32', 'CredReadW', 'PIIP', 'I'
110 ) or die "CredReadW: $^E";
111  
112 my $CredDelete = Win32::API->new(
113 'advapi32', 'CredDeleteW', 'PII', 'I'
114 ) or die "CredDeleteW: $^E";
115  
116 my $CredFree = Win32::API->new(
117 'advapi32', 'CredFree', 'N', 'V'
118 ) or die "CredFree: $^E";
119  
120 # Check if Perl is 64-bit
121 my $IS64 = (length(pack('P', 0)) == 8);
122  
123 # Build CREDENTIAL struct in memory
124 #
125 # Layout 64-bit (all pointers are Q = 8 byte):
126 # Flags DWORD L 4
127 # Type DWORD L 4
128 # TargetName PTR Q 8
129 # Comment PTR Q 8
130 # LastWritten.Low DWORD L 4
131 # LastWritten.High DWORD L 4
132 # CredentialBlobSz DWORD L 4
133 # (padding) 4 aligning to 64-bit
134 # CredentialBlob PTR Q 8
135 # Persist DWORD L 4
136 # AttributeCount DWORD L 4
137 # Attributes PTR Q 8
138 # TargetAlias PTR Q 8
139 # UserName PTR Q 8
140  
141 sub _build_credential_struct {
142 my (%args) = @_;
143  
144 # Convert strings into UTF-16LE (Wide char Windows)
145 my $target_w = encode('UTF-16LE', $args{target} . "\0");
146 my $user_w = encode('UTF-16LE', ($args{user}//'') . "\0");
147 my $comment_w = encode('UTF-16LE', ($args{comment}//'Win32-Credentials') . "\0");
148  
149 # The blob is the password bytes (UTF-16LE for Windows compatibilty)
150 my $blob_w = encode('UTF-16LE', $args{secret});
151 my $blob_size = length($blob_w);
152 die "Blob exceeds 512 byte (limit CRED_TYPE_GENERIC)\n"
153 if $blob_size > 512;
154  
155 # There is no way to test it on 32bit systems for the moment
156 if ($IS64) {
157 # Buuild the struct with Win32::API::Struct
158 # using pack with pointer as packed string
159 my $struct = pack(
160 'L L' . # Flags, Type
161 ($IS64 ? 'Q Q' : 'L L') . # TargetName, Comment (ptr)
162 'L L' . # LastWritten (FILETIME = 2x DWORD)
163 'L' . # CredentialBlobSize
164 'x4' . # padding 64-bit
165 ($IS64 ? 'Q' : 'L') . # CredentialBlob (ptr)
166 'L L' . # Persist, AttributeCount
167 ($IS64 ? 'Q Q Q' : 'L L L'), # Attributes, TargetAlias, UserName
168 # valori:
169 0, # Flags
170 CRED_TYPE_GENERIC, # Type
171 unpack('Q', pack('P', $target_w)), # TargetName ptr
172 unpack('Q', pack('P', $comment_w)), # Comment ptr
173 0, 0, # LastWritten
174 $blob_size, # CredentialBlobSize
175 unpack('Q', pack('P', $blob_w)), # CredentialBlob ptr
176 CRED_PERSIST_LOCAL_MACHINE, # Persist
177 0, # AttributeCount
178 0, # Attributes (NULL)
179 0, # TargetAlias (NULL)
180 unpack('Q', pack('P', $user_w)), # UserName ptr
181 );
182  
183 # Return buffers to the scope
184 return ($struct, $target_w, $comment_w, $blob_w, $user_w);
185 }else{
186 die "32Bit Mode is actually unsupported\n";
187 }
188 }
189  
190 # WRITE
191 sub cred_write {
192 my ($target, $user, $secret) = @_;
193  
194 my ($struct, @buffers) = _build_credential_struct(
195 target => $target,
196 user => $user,
197 secret => $secret,
198 );
199  
200 my $result = $CredWrite->Call($struct, 0);
201  
202 unless ($result) {
203 my $err = Win32::GetLastError();
204 die "CredWriteW Failed, error: $err\n";
205 }
206  
207 return 1;
208 }
209  
210 # READ
211 sub cred_read {
212 my ($target) = @_;
213  
214 # Buffer for pointer to struct
215 my $ptr_buf = "\0" x 8;
216  
217 my $target_w = encode('UTF-16LE', $target . "\0");
218  
219 my $result = $CredRead->Call(
220 $target_w, # TargetName (Wide)
221 CRED_TYPE_GENERIC, # Type
222 0, # Flags (reserved, must be 0)
223 $ptr_buf # output: PCREDENTIALW*
224 );
225  
226 unless ($result) {
227 my $err = Win32::GetLastError();
228 die "CredReadW failed, error: $err\n";
229 }
230  
231 # Extract the pointer
232 my $cred_ptr = unpack('Q', $ptr_buf);
233 die "CredReadW: Pointer NULL\n" unless $cred_ptr;
234  
235 # Read struct From Memory
236 # Offset CredentialBlob e CredentialBlobSize in struct 64-bit:
237 # 0: Flags DWORD L 4
238 # 4: Type DWORD L 4
239 # 8: TargetName ptr PTR Q 8
240 # 16: Comment ptr PTR Q 8
241 # 24: LastWritten.L DWORD L 4
242 # 28: LastWritten.H DWORD L 4
243 # 32: BlobSize DWORD L 4
244 # 36: padding DWORD L 4
245 # 40: Blob ptr PTR Q 8
246 # 48: Persist DWORD L 4
247 # 52: AttributeCount DWORD L 4
248 # 56: Attributes ptr PTR Q 8
249 # 64: TargetAlias ptr PTR Q 8
250 # 72: UserName ptr PTR Q 8
251  
252 # Use Win32::API::ReadMemory to read struct
253 my $struct = Win32::API::ReadMemory($cred_ptr, 80);
254  
255 # Extract fields
256 my $blob_size = unpack('L', substr($struct, 32, 4));
257 my $blob_ptr = unpack('Q', substr($struct, 40, 8));
258 my $user_ptr = unpack('Q', substr($struct, 72, 8));
259  
260 # Read blob (password)
261 my $blob_raw = Win32::API::ReadMemory($blob_ptr, $blob_size);
262 my $secret = decode('UTF-16LE', $blob_raw);
263  
264 # Read UserName (optional, null-terminated UTF-16LE string)
265 my $username = '';
266 if ($user_ptr) {
267 # Read till double \0 (max 512 char)
268 my $user_raw = Win32::API::ReadMemory($user_ptr, 512);
269 ($username) = ($user_raw =~ /^((?:..)*?)\x00\x00/s);
270 $username = decode('UTF-16LE', $username) if $username;
271 }
272  
273 # Free allocated memory from CredReadW
274 $CredFree->Call($cred_ptr);
275  
276 return wantarray ? ($secret, $username) : $secret;
277 }
278  
279 # DELETE
280 sub cred_delete {
281 my ($target) = @_;
282  
283 my $target_w = encode('UTF-16LE', $target . "\0");
284 my $result = $CredDelete->Call($target_w, CRED_TYPE_GENERIC, 0);
285  
286 unless ($result) {
287 die "CredDeleteW failed: " . Win32::GetLastError() . "\n";
288 }
289 return 1;
290 }
291  
292 1;