VBoxCredProvCredential.cpp@ 78425

Last change on this file since 78425 was 76553, checked in by vboxsync, 6 years ago
scm --update-copyright-year
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 40.7 KB

Line
1	/* $Id: VBoxCredProvCredential.cpp 76553 2019-01-01 01:45:53Z vboxsync $ */
2	/** @file
3	* VBoxCredProvCredential - Class for keeping and handling the passed credentials.
4	*/
5
6	/*
7	* Copyright (C) 2012-2019 Oracle Corporation
8	*
9	* This file is part of VirtualBox Open Source Edition (OSE), as
10	* available from http://www.virtualbox.org. This file is free software;
11	* you can redistribute it and/or modify it under the terms of the GNU
12	* General Public License (GPL) as published by the Free Software
13	* Foundation, in version 2 as it comes in the "COPYING" file of the
14	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16	*/
17
18
19	/*********************************************************************************************************************************
20	* Header Files *
21	*********************************************************************************************************************************/
22	#ifndef WIN32_NO_STATUS
23	# include <ntstatus.h>
24	# define WIN32_NO_STATUS
25	#endif
26	#include <iprt/win/intsafe.h>
27
28	#include "VBoxCredentialProvider.h"
29
30	#include "VBoxCredProvProvider.h"
31	#include "VBoxCredProvCredential.h"
32	#include "VBoxCredProvUtils.h"
33
34	#include <lm.h>
35
36	#include <iprt/initterm.h>
37	#include <iprt/mem.h>
38	#include <iprt/string.h>
39	#include <iprt/utf16.h>
40
41
42
43
44	VBoxCredProvCredential::VBoxCredProvCredential(void) :
45	m_enmUsageScenario(CPUS_INVALID),
46	m_cRefs(1),
47	m_pEvents(NULL),
48	m_fHaveCreds(false)
49	{
50	VBoxCredProvVerbose(0, "VBoxCredProvCredential: Created\n");
51	VBoxCredentialProviderAcquire();
52
53	for (unsigned i = 0; i < VBOXCREDPROV_NUM_FIELDS; i++)
54	{
55	const VBOXCREDPROV_FIELD *pField = &s_VBoxCredProvDefaultFields[i];
56
57	m_apwszFields[i] = RTUtf16Dup(pField->desc.pszLabel ? pField->desc.pszLabel : L"");
58	AssertPtr(m_apwszFields[i]);
59	}
60	}
61
62
63	VBoxCredProvCredential::~VBoxCredProvCredential(void)
64	{
65	VBoxCredProvVerbose(0, "VBoxCredProvCredential: Destroying\n");
66
67	Reset();
68
69	for (unsigned i = 0; i < VBOXCREDPROV_NUM_FIELDS; i++)
70	{
71	if (m_apwszFields[i])
72	{
73	RTUtf16Free(m_apwszFields[i]);
74	m_apwszFields[i] = NULL;
75	}
76	}
77
78	VBoxCredentialProviderRelease();
79	}
80
81
82	ULONG VBoxCredProvCredential::AddRef(void)
83	{
84	LONG cRefs = InterlockedIncrement(&m_cRefs);
85	VBoxCredProvVerbose(0, "VBoxCredProvCredential::AddRef: Returning refcount=%ld\n",
86	cRefs);
87	return cRefs;
88	}
89
90
91	ULONG VBoxCredProvCredential::Release(void)
92	{
93	LONG cRefs = InterlockedDecrement(&m_cRefs);
94	VBoxCredProvVerbose(0, "VBoxCredProvCredential::Release: Returning refcount=%ld\n",
95	cRefs);
96	if (!cRefs)
97	{
98	VBoxCredProvVerbose(0, "VBoxCredProvCredential: Calling destructor\n");
99	delete this;
100	}
101	return cRefs;
102	}
103
104
105	HRESULT VBoxCredProvCredential::QueryInterface(REFIID interfaceID, void **ppvInterface)
106	{
107	HRESULT hr = S_OK;;
108	if (ppvInterface)
109	{
110	if ( IID_IUnknown == interfaceID
111	\|\| IID_ICredentialProviderCredential == interfaceID)
112	{
113	ppvInterface = static_cast<IUnknown>(this);
114	reinterpret_cast<IUnknown>(ppvInterface)->AddRef();
115	}
116	else
117	{
118	*ppvInterface = NULL;
119	hr = E_NOINTERFACE;
120	}
121	}
122	else
123	hr = E_INVALIDARG;
124
125	return hr;
126	}
127
128
129	/**
130	* Assigns or copies a RTUTF16 string to a UNICODE_STRING.
131	*
132	* When fCopy is false, this does not copy its contents
133	* and only assigns its code points to the destination!
134	* When fCopy is true, the actual string buffer gets copied.
135	*
136	* Does not take terminating \0 into account.
137	*
138	* @return HRESULT
139	* @param pUnicodeDest Unicode string assigning the UTF16 string to.
140	* @param pwszSource UTF16 string to assign.
141	* @param fCopy Whether to just assign or copy the actual buffer
142	* contents from source -> dest.
143	*/
144	HRESULT VBoxCredProvCredential::RTUTF16ToUnicode(PUNICODE_STRING pUnicodeDest, PRTUTF16 pwszSource, bool fCopy)
145	{
146	AssertPtrReturn(pUnicodeDest, E_POINTER);
147	AssertPtrReturn(pwszSource, E_POINTER);
148
149	size_t cbLen = RTUtf16Len(pwszSource) * sizeof(RTUTF16);
150	AssertReturn(cbLen <= USHORT_MAX, E_INVALIDARG);
151
152	HRESULT hr;
153
154	if (fCopy)
155	{
156	if (cbLen <= pUnicodeDest->MaximumLength)
157	{
158	memcpy(pUnicodeDest->Buffer, pwszSource, cbLen);
159	pUnicodeDest->Length = (USHORT)cbLen;
160	hr = S_OK;
161	}
162	else
163	hr = E_INVALIDARG;
164	}
165	else /* Just assign the buffer. */
166	{
167	pUnicodeDest->Buffer = pwszSource;
168	pUnicodeDest->Length = (USHORT)cbLen;
169	hr = S_OK;
170	}
171
172	return hr;
173	}
174
175
176	/**
177	* Copies an UTF16 string into a PUNICODE_STRING by allocating space for it.
178	*
179	* @return HRESULT
180	* @param pUnicodeDest Where to store the copied (allocated) unicode string.
181	* @param pwszSource UTF16 string to copy.
182	*/
183	HRESULT VBoxCredProvCredential::RTUTF16ToUnicodeA(PUNICODE_STRING pUnicodeDest, PRTUTF16 pwszSource)
184	{
185	AssertPtrReturn(pUnicodeDest, E_POINTER);
186	AssertPtrReturn(pwszSource, E_POINTER);
187
188	size_t cbLen = RTUtf16Len(pwszSource) * sizeof(RTUTF16);
189
190	pUnicodeDest->Buffer = (LPWSTR)CoTaskMemAlloc(cbLen);
191
192	if (!pUnicodeDest->Buffer)
193	return E_OUTOFMEMORY;
194
195	pUnicodeDest->MaximumLength = (USHORT)cbLen;
196	pUnicodeDest->Length = 0;
197
198	return RTUTF16ToUnicode(pUnicodeDest, pwszSource, true /* fCopy */);
199	}
200
201
202	/**
203	* Frees a formerly allocated PUNICODE_STRING.
204	*
205	* @param pUnicode String to free.
206	*/
207	void VBoxCredProvCredential::UnicodeStringFree(PUNICODE_STRING pUnicode)
208	{
209	if (!pUnicode)
210	return;
211
212	if (pUnicode->Buffer)
213	{
214	Assert(pUnicode->MaximumLength);
215
216	/* Make sure to wipe contents before free'ing. */
217	RTMemWipeThoroughly(pUnicode->Buffer, pUnicode->MaximumLength /* MaximumLength is bytes! /, 3 / Passes */);
218
219	CoTaskMemFree(pUnicode->Buffer);
220	pUnicode->Buffer = NULL;
221	}
222
223	pUnicode->Length = 0;
224	pUnicode->MaximumLength = 0;
225	}
226
227
228	/**
229	* Creates a KERB_INTERACTIVE_LOGON structure with the given parameters.
230	* Must be destroyed with kerberosLogonDestroy().
231	*
232	* @return HRESULT
233	* @param pLogon Structure to create.
234	* @param enmUsage Intended usage of the structure.
235	* @param pwszUser User name to use.
236	* @param pwszPassword Password to use.
237	* @param pwszDomain Domain to use. Optional and can be NULL.
238	*/
239	HRESULT VBoxCredProvCredential::kerberosLogonCreate(KERB_INTERACTIVE_LOGON *pLogon,
240	CREDENTIAL_PROVIDER_USAGE_SCENARIO enmUsage,
241	PRTUTF16 pwszUser, PRTUTF16 pwszPassword, PRTUTF16 pwszDomain)
242	{
243	AssertPtrReturn(pLogon, E_INVALIDARG);
244	AssertPtrReturn(pwszUser, E_INVALIDARG);
245	AssertPtrReturn(pwszPassword, E_INVALIDARG);
246	/* pwszDomain is optional. */
247
248	HRESULT hr;
249
250	/* Do we have a domain name set? */
251	if ( pwszDomain
252	&& RTUtf16Len(pwszDomain))
253	{
254	hr = RTUTF16ToUnicodeA(&pLogon->LogonDomainName, pwszDomain);
255	}
256	else /* No domain (FQDN) given, try local computer name. */
257	{
258	WCHAR wszComputerName[MAX_COMPUTERNAME_LENGTH + 1];
259	DWORD cch = ARRAYSIZE(wszComputerName);
260	if (GetComputerNameW(wszComputerName, &cch))
261	{
262	/* Is a domain name missing? Then use the name of the local computer. */
263	hr = RTUTF16ToUnicodeA(&pLogon->LogonDomainName, wszComputerName);
264
265	VBoxCredProvVerbose(0, "VBoxCredProvCredential::kerberosLogonInit: Local computer name=%ls\n",
266	wszComputerName);
267	}
268	else
269	hr = HRESULT_FROM_WIN32(GetLastError());
270	}
271
272	/* Fill in the username and password. */
273	if (SUCCEEDED(hr))
274	{
275	hr = RTUTF16ToUnicodeA(&pLogon->UserName, pwszUser);
276	if (SUCCEEDED(hr))
277	{
278	hr = RTUTF16ToUnicodeA(&pLogon->Password, pwszPassword);
279	if (SUCCEEDED(hr))
280	{
281	/* Set credential type according to current usage scenario. */
282	switch (enmUsage)
283	{
284	case CPUS_UNLOCK_WORKSTATION:
285	pLogon->MessageType = KerbWorkstationUnlockLogon;
286	break;
287
288	case CPUS_LOGON:
289	pLogon->MessageType = KerbInteractiveLogon;
290	break;
291
292	case CPUS_CREDUI:
293	pLogon->MessageType = (KERB_LOGON_SUBMIT_TYPE)0; /* No message type required here. */
294	break;
295
296	default:
297	VBoxCredProvVerbose(0, "VBoxCredProvCredential::kerberosLogonInit: Unknown usage scenario=%ld\n",
298	enmUsage);
299	hr = E_FAIL;
300	break;
301	}
302	}
303	}
304	}
305
306	return hr;
307	}
308
309
310	/**
311	* Destroys a formerly created KERB_INTERACTIVE_LOGON structure.
312	*
313	* @param pLogon Structure to destroy.
314	*/
315	void VBoxCredProvCredential::kerberosLogonDestroy(KERB_INTERACTIVE_LOGON *pLogon)
316	{
317	if (!pLogon)
318	return;
319
320	UnicodeStringFree(&pLogon->UserName);
321	UnicodeStringFree(&pLogon->Password);
322	UnicodeStringFree(&pLogon->LogonDomainName);
323	}
324
325
326	HRESULT VBoxCredProvCredential::kerberosLogonSerialize(const KERB_INTERACTIVE_LOGON *pLogonIn,
327	PBYTE ppPackage, DWORD pcbPackage)
328	{
329	AssertPtrReturn(pLogonIn, E_INVALIDARG);
330	AssertPtrReturn(ppPackage, E_INVALIDARG);
331	AssertPtrReturn(pcbPackage, E_INVALIDARG);
332
333	/*
334	* First, allocate enough space for the logon structure itself and separate
335	* string buffers right after it to store the actual user, password and domain
336	* credentials.
337	*/
338	DWORD cbLogon = sizeof(KERB_INTERACTIVE_UNLOCK_LOGON)
339	+ pLogonIn->LogonDomainName.Length
340	+ pLogonIn->UserName.Length
341	+ pLogonIn->Password.Length;
342
343	#ifdef DEBUG /* Do not reveal any hints to credential data in release mode. */
344	VBoxCredProvVerbose(1, "VBoxCredProvCredential::AllocateLogonPackage: Allocating %ld bytes (%zu bytes credentials)\n",
345	cbLogon, cbLogon - sizeof(KERB_INTERACTIVE_UNLOCK_LOGON));
346	#endif
347
348	KERB_INTERACTIVE_UNLOCK_LOGON pLogon = (KERB_INTERACTIVE_UNLOCK_LOGON)CoTaskMemAlloc(cbLogon);
349	if (!pLogon)
350	return E_OUTOFMEMORY;
351
352	/* Make sure to zero everything first. */
353	RT_BZERO(pLogon, cbLogon);
354
355	/* Let our byte buffer point to the end of our allocated structure so that it can
356	* be used to store the credential data sequentially in a binary blob
357	* (without terminating \0). */
358	PBYTE pbBuffer = (PBYTE)pLogon + sizeof(KERB_INTERACTIVE_UNLOCK_LOGON);
359
360	/* The buffer of the packed destination string does not contain the actual
361	* string content but a relative offset starting at the given
362	* KERB_INTERACTIVE_UNLOCK_LOGON structure. */
363	#define KERB_CRED_INIT_PACKED(StringDst, StringSrc, LogonOffset) \
364	StringDst.Length = StringSrc.Length; \
365	StringDst.MaximumLength = StringSrc.Length; \
366	if (StringDst.Length) \
367	{ \
368	StringDst.Buffer = (PWSTR)pbBuffer; \
369	memcpy(StringDst.Buffer, StringSrc.Buffer, StringDst.Length); \
370	StringDst.Buffer = (PWSTR)(pbBuffer - (PBYTE)LogonOffset); \
371	pbBuffer += StringDst.Length; \
372	}
373
374	KERB_INTERACTIVE_LOGON *pLogonOut = &pLogon->Logon;
375
376	pLogonOut->MessageType = pLogonIn->MessageType;
377
378	KERB_CRED_INIT_PACKED(pLogonOut->LogonDomainName, pLogonIn->LogonDomainName, pLogon);
379	KERB_CRED_INIT_PACKED(pLogonOut->UserName , pLogonIn->UserName, pLogon);
380	KERB_CRED_INIT_PACKED(pLogonOut->Password , pLogonIn->Password, pLogon);
381
382	*ppPackage = (PBYTE)pLogon;
383	*pcbPackage = cbLogon;
384
385	#undef KERB_CRED_INIT_PACKED
386
387	return S_OK;
388	}
389
390
391	/**
392	* Returns the current value of a specific credential provider field.
393	*
394	* @return Pointer (const) to the credential provider field requested, or NULL if not found / invalid.
395	* @param dwFieldID Field ID of the credential provider field to get.
396	*/
397	PCRTUTF16 VBoxCredProvCredential::getField(DWORD dwFieldID)
398	{
399	if (dwFieldID >= VBOXCREDPROV_NUM_FIELDS)
400	return NULL;
401
402	/* Paranoia: Don't ever reveal passwords. */
403	if (dwFieldID == VBOXCREDPROV_FIELDID_PASSWORD)
404	return NULL;
405
406	return m_apwszFields[dwFieldID];
407	}
408
409
410	/**
411	* Sets a credential provider field by first zero'ing out its current content in a (hopefully) secure manner,
412	* then applying either the field's default or a new value.
413	*
414	* @return HRESULT
415	* @param dwFieldID Field ID of the credential provider field to reset.
416	* @param pcwszString String to set for the given field. Specify NULL for setting the provider's default value.
417	* @param fNotifyUI Whether to notify the LogonUI about the reset.
418	*/
419	HRESULT VBoxCredProvCredential::setField(DWORD dwFieldID, const PRTUTF16 pcwszString, bool fNotifyUI)
420	{
421	if (dwFieldID >= VBOXCREDPROV_NUM_FIELDS)
422	return E_INVALIDARG;
423
424	HRESULT hr = S_OK;
425
426	PRTUTF16 pwszField = m_apwszFields[dwFieldID];
427	if (pwszField)
428	{
429	/* First, wipe the existing value thoroughly. */
430	RTMemWipeThoroughly(pwszField, (RTUtf16Len(pwszField) + 1) * sizeof(RTUTF16), 3 /* Passes */);
431
432	/* Second, free the string. */
433	RTUtf16Free(pwszField);
434	}
435
436	/* Either fill in the default value or the one specified in pcwszString. */
437	pwszField = RTUtf16Dup(pcwszString ? pcwszString : s_VBoxCredProvDefaultFields[dwFieldID].desc.pszLabel);
438	if (pwszField)
439	{
440	m_apwszFields[dwFieldID] = pwszField; /* Update the pointer. */
441
442	if ( m_pEvents
443	&& fNotifyUI) /* Let the logon UI know if wanted. */
444	{
445	hr = m_pEvents->SetFieldString(this, dwFieldID, pwszField);
446	}
447	}
448	else
449	hr = E_OUTOFMEMORY;
450
451	VBoxCredProvVerbose(0, "VBoxCredProvCredential::setField: Setting field dwFieldID=%ld to '%ls', fNotifyUI=%RTbool, hr=0x%08x\n",
452	dwFieldID,
453	#ifdef DEBUG
454	pwszField,
455	#else
456	/* Don't show any passwords in release mode. */
457	dwFieldID == VBOXCREDPROV_FIELDID_PASSWORD ? L"XXX" : pwszField,
458	#endif
459	fNotifyUI, hr);
460	return hr;
461	}
462
463	/**
464	* Resets (wipes) stored credentials.
465	*
466	* @return HRESULT
467	*/
468	HRESULT VBoxCredProvCredential::Reset(void)
469	{
470	VBoxCredProvVerbose(0, "VBoxCredProvCredential::Reset: Wiping credentials user=%ls, pw=%ls, domain=%ls\n",
471	m_apwszFields[VBOXCREDPROV_FIELDID_USERNAME] ? m_apwszFields[VBOXCREDPROV_FIELDID_USERNAME] : L"<NULL>",
472	#ifdef DEBUG
473	m_apwszFields[VBOXCREDPROV_FIELDID_PASSWORD] ? m_apwszFields[VBOXCREDPROV_FIELDID_PASSWORD] : L"<NULL>",
474	#else
475	L"XXX" /* Don't show any passwords in release mode. */,
476	#endif
477	m_apwszFields[VBOXCREDPROV_FIELDID_DOMAINNAME] ? m_apwszFields[VBOXCREDPROV_FIELDID_DOMAINNAME] : L"<NULL>");
478
479	/* Note: Do not reset the user name and domain name here,
480	* as they could still being queried (again) by LogonUI on failed login attempts. */
481	HRESULT hr = setField(VBOXCREDPROV_FIELDID_PASSWORD, NULL /* Use default value /, true / fNotifyUI */);
482
483	m_fIsSelected = false;
484
485	VBoxCredProvVerbose(0, "VBoxCredProvCredential::Reset\n");
486	return hr;
487	}
488
489
490	/**
491	* Checks and retrieves credentials provided by the host + does account lookup on eventually
492	* renamed user accounts.
493	*
494	* @return IPRT status code.
495	*/
496	int VBoxCredProvCredential::RetrieveCredentials(void)
497	{
498	PRTUTF16 pwszUser = NULL;
499	PRTUTF16 pwszPassword = NULL;
500	PRTUTF16 pwszDomain = NULL;
501
502	int rc = VbglR3CredentialsQueryAvailability();
503	if (RT_SUCCESS(rc))
504	{
505	/*
506	* Set status to "terminating" to let the host know this module now
507	* tries to receive and use passed credentials so that credentials from
508	* the host won't be sent twice.
509	*/
510	VBoxCredProvReportStatus(VBoxGuestFacilityStatus_Terminating);
511
512	rc = VbglR3CredentialsRetrieveUtf16(&pwszUser, &pwszPassword, &pwszDomain);
513
514	VBoxCredProvVerbose(0, "VBoxCredProvCredential::RetrieveCredentials: Retrieved credentials with rc=%Rrc\n", rc);
515	}
516
517	if (RT_SUCCESS(rc))
518	{
519	VBoxCredProvVerbose(0, "VBoxCredProvCredential::RetrieveCredentials: Received credentials for user '%ls'\n", pwszUser);
520
521	/*
522	* In case we got a "display name" (e.g. "John Doe")
523	* instead of the real user name (e.g. "jdoe") we have
524	* to translate the data first ...
525	*/
526	PWSTR pwszExtractedName = NULL;
527	if ( TranslateAccountName(pwszUser, &pwszExtractedName)
528	&& pwszExtractedName)
529	{
530	VBoxCredProvVerbose(0, "VBoxCredProvCredential::RetrieveCredentials: Translated account name '%ls' -> '%ls'\n",
531	pwszUser, pwszExtractedName);
532
533	RTMemWipeThoroughly(pwszUser, (RTUtf16Len(pwszUser) + 1) * sizeof(RTUTF16), 3 /* Passes */);
534	RTUtf16Free(pwszUser);
535
536	pwszUser = RTUtf16Dup(pwszExtractedName);
537
538	CoTaskMemFree(pwszExtractedName);
539	pwszExtractedName = NULL;
540	}
541	else
542	{
543	/*
544	* Okay, no display name, but maybe it's a
545	* principal name from which we have to extract the domain from?
546	* ([email protected] -> jdoe in domain my-domain.sub.net.com.)
547	*/
548	PWSTR pwszExtractedDomain = NULL;
549	if (ExtractAccoutData(pwszUser, &pwszExtractedName, &pwszExtractedDomain))
550	{
551	/* Update user name. */
552	if (pwszExtractedName)
553	{
554	if (pwszUser)
555	{
556	RTMemWipeThoroughly(pwszUser, (RTUtf16Len(pwszUser) + 1) * sizeof(RTUTF16), 3 /* Passes */);
557	RTUtf16Free(pwszUser);
558	}
559
560	pwszUser = RTUtf16Dup(pwszExtractedName);
561
562	CoTaskMemFree(pwszExtractedName);
563	pwszExtractedName = NULL;
564	}
565
566	/* Update domain. */
567	if (pwszExtractedDomain)
568	{
569	if (pwszDomain)
570	{
571	RTMemWipeThoroughly(pwszDomain, (RTUtf16Len(pwszDomain) + 1) * sizeof(RTUTF16), 3 /* Passes */);
572	RTUtf16Free(pwszDomain);
573	}
574
575	pwszDomain = RTUtf16Dup(pwszExtractedDomain);
576
577	CoTaskMemFree(pwszExtractedDomain);
578	pwszExtractedDomain = NULL;
579	}
580
581	VBoxCredProvVerbose(0, "VBoxCredProvCredential::RetrieveCredentials: Extracted account name '%ls' + domain '%ls'\n",
582	pwszUser ? pwszUser : L"<NULL>", pwszDomain ? pwszDomain : L"<NULL>");
583	}
584	}
585
586	m_fHaveCreds = true;
587	}
588
589	if (m_fHaveCreds)
590	{
591	VBoxCredProvVerbose(0, "VBoxCredProvCredential::RetrieveCredentials: Setting fields\n");
592
593	setField(VBOXCREDPROV_FIELDID_USERNAME, pwszUser, true /* fNotifyUI */);
594	setField(VBOXCREDPROV_FIELDID_PASSWORD, pwszPassword, true /* fNotifyUI */);
595	setField(VBOXCREDPROV_FIELDID_DOMAINNAME, pwszDomain, true /* fNotifyUI */);
596	}
597
598	VBoxCredProvVerbose(0, "VBoxCredProvCredential::RetrieveCredentials: Wiping ...\n");
599
600	VbglR3CredentialsDestroyUtf16(pwszUser, pwszPassword, pwszDomain, 3 /* cPasses */);
601
602	VBoxCredProvVerbose(0, "VBoxCredProvCredential::RetrieveCredentials: Returned rc=%Rrc\n", rc);
603	return rc;
604	}
605
606
607	/**
608	* Initializes this credential with the current credential provider
609	* usage scenario.
610	*/
611	HRESULT VBoxCredProvCredential::Initialize(CREDENTIAL_PROVIDER_USAGE_SCENARIO enmUsageScenario)
612	{
613	VBoxCredProvVerbose(0, "VBoxCredProvCredential::Initialize: enmUsageScenario=%ld\n", enmUsageScenario);
614	m_enmUsageScenario = enmUsageScenario;
615	return S_OK;
616	}
617
618
619	/**
620	* Called by LogonUI when it needs this credential's advice.
621	*
622	* At the moment we only grab the credential provider events so that we can
623	* trigger a re-enumeration of the credentials later.
624	*/
625	HRESULT VBoxCredProvCredential::Advise(ICredentialProviderCredentialEvents *pEvents)
626	{
627	VBoxCredProvVerbose(0, "VBoxCredProvCredential::Advise: pEvents=0x%p\n", pEvents);
628
629	if (m_pEvents)
630	{
631	m_pEvents->Release();
632	m_pEvents = NULL;
633	}
634
635	return pEvents->QueryInterface(IID_PPV_ARGS(&m_pEvents));
636	}
637
638
639	/**
640	* Called by LogonUI when it's finished with handling this credential.
641	*
642	* We only need to release the credential provider events, if any.
643	*/
644	HRESULT VBoxCredProvCredential::UnAdvise(void)
645	{
646	VBoxCredProvVerbose(0, "VBoxCredProvCredential::UnAdvise\n");
647
648	if (m_pEvents)
649	{
650	m_pEvents->Release();
651	m_pEvents = NULL;
652	}
653
654	return S_OK;
655	}
656
657
658	/**
659	* Called by LogonUI when a user profile (tile) has been selected.
660	*
661	* As we don't want Winlogon to try logging in immediately we set pfAutoLogon
662	* to FALSE (if set).
663	*/
664	HRESULT VBoxCredProvCredential::SetSelected(PBOOL pfAutoLogon)
665	{
666	VBoxCredProvVerbose(0, "VBoxCredProvCredential::SetSelected\n");
667
668	/*
669	* Don't do auto logon here because it would retry too often with
670	* every credential field (user name, password, domain, ...) which makes
671	* winlogon wait before new login attempts can be made.
672	*/
673	if (pfAutoLogon)
674	*pfAutoLogon = FALSE;
675
676	m_fIsSelected = true;
677
678	return S_OK;
679	}
680
681
682	/**
683	* Called by LogonUI when a user profile (tile) has been unselected again.
684	*/
685	HRESULT VBoxCredProvCredential::SetDeselected(void)
686	{
687	VBoxCredProvVerbose(0, "VBoxCredProvCredential::SetDeselected\n");
688
689	Reset();
690
691	return S_OK;
692	}
693
694
695	/**
696	* Called by LogonUI to retrieve the (interactive) state of a UI field.
697	*/
698	HRESULT VBoxCredProvCredential::GetFieldState(DWORD dwFieldID, CREDENTIAL_PROVIDER_FIELD_STATE *pFieldState,
699	CREDENTIAL_PROVIDER_FIELD_INTERACTIVE_STATE *pFieldstateInteractive)
700	{
701	VBoxCredProvVerbose(0, "VBoxCredProvCredential::GetFieldState: dwFieldID=%ld\n", dwFieldID);
702
703	HRESULT hr = S_OK;
704
705	if (dwFieldID < VBOXCREDPROV_NUM_FIELDS)
706	{
707	if (pFieldState)
708	*pFieldState = s_VBoxCredProvDefaultFields[dwFieldID].state;
709
710	if (pFieldstateInteractive)
711	*pFieldstateInteractive = s_VBoxCredProvDefaultFields[dwFieldID].stateInteractive;
712	}
713	else
714	hr = E_INVALIDARG;
715
716	return hr;
717	}
718
719
720	/**
721	* Searches the account name based on a display (real) name (e.g. "John Doe" -> "jdoe").
722	*
723	* @return TRUE if translation of the account name was successful, FALSE if not.
724	* @param pwszDisplayName Display name to extract account name from.
725	* @param ppwszAccoutName Where to store the extracted account name on success.
726	* Needs to be free'd with CoTaskMemFree().
727	*/
728	BOOL VBoxCredProvCredential::TranslateAccountName(PWSTR pwszDisplayName, PWSTR *ppwszAccoutName)
729	{
730	AssertPtrReturn(pwszDisplayName, FALSE);
731	VBoxCredProvVerbose(0, "VBoxCredProvCredential::TranslateAccountName: Getting account name for \"%ls\" ...\n",
732	pwszDisplayName);
733
734	/** @todo Do we need ADS support (e.g. TranslateNameW) here? */
735	BOOL fFound = FALSE; /* Did we find the desired user? */
736	NET_API_STATUS rcStatus;
737	DWORD dwLevel = 2; /* Detailed information about user accounts. */
738	DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
739	DWORD dwEntriesRead = 0;
740	DWORD dwTotalEntries = 0;
741	DWORD dwResumeHandle = 0;
742	LPUSER_INFO_2 pBuf = NULL;
743	LPUSER_INFO_2 pCurBuf = NULL;
744	do
745	{
746	rcStatus = NetUserEnum(NULL, /* Server name, NULL for localhost. */
747	dwLevel,
748	FILTER_NORMAL_ACCOUNT,
749	(LPBYTE*)&pBuf,
750	dwPrefMaxLen,
751	&dwEntriesRead,
752	&dwTotalEntries,
753	&dwResumeHandle);
754	if ( rcStatus == NERR_Success
755	\|\| rcStatus == ERROR_MORE_DATA)
756	{
757	if ((pCurBuf = pBuf) != NULL)
758	{
759	for (DWORD i = 0; i < dwEntriesRead; i++)
760	{
761	/*
762	* Search for the "display name" - that might be
763	* "John Doe" or something similar the user recognizes easier
764	* and may not the same as the "account" name (e.g. "jdoe").
765	*/
766	if ( pCurBuf
767	&& pCurBuf->usri2_full_name
768	&& StrCmpI(pwszDisplayName, pCurBuf->usri2_full_name) == 0)
769	{
770	/*
771	* Copy the real user name (e.g. "jdoe") to our
772	* output buffer.
773	*/
774	LPWSTR pwszTemp;
775	HRESULT hr = SHStrDupW(pCurBuf->usri2_name, &pwszTemp);
776	if (hr == S_OK)
777	{
778	*ppwszAccoutName = pwszTemp;
779	fFound = TRUE;
780	}
781	else
782	VBoxCredProvVerbose(0, "VBoxCredProvCredential::TranslateAccountName: Error copying data, hr=%08x\n", hr);
783	break;
784	}
785	pCurBuf++;
786	}
787	}
788	if (pBuf != NULL)
789	{
790	NetApiBufferFree(pBuf);
791	pBuf = NULL;
792	}
793	}
794	} while (rcStatus == ERROR_MORE_DATA && !fFound);
795
796	if (pBuf != NULL)
797	{
798	NetApiBufferFree(pBuf);
799	pBuf = NULL;
800	}
801
802	VBoxCredProvVerbose(0, "VBoxCredProvCredential::TranslateAccountName returned rcStatus=%ld, fFound=%RTbool\n",
803	rcStatus, fFound);
804	return fFound;
805
806	#if 0
807	DWORD dwErr = NO_ERROR;
808	ULONG cbLen = 0;
809	if ( TranslateNameW(pwszName, NameUnknown, NameUserPrincipal, NULL, &cbLen)
810	&& cbLen > 0)
811	{
812	VBoxCredProvVerbose(0, "VBoxCredProvCredential::GetAccountName: Translated ADS name has %u characters\n", cbLen));
813
814	ppwszAccoutName = (PWSTR)RTMemAlloc(cbLen * sizeof(WCHAR));
815	AssertPtrReturn(pwszName, FALSE);
816	if (TranslateNameW(pwszName, NameUnknown, NameUserPrincipal, ppwszAccoutName, &cbLen))
817	{
818	VBoxCredProvVerbose(0, "VBoxCredProvCredential::GetAccountName: Real ADS account name of '%ls' is '%ls'\n",
819	pwszName, ppwszAccoutName));
820	}
821	else
822	{
823	RTMemFree(ppwszAccoutName);
824	dwErr = GetLastError();
825	}
826	}
827	else
828	dwErr = GetLastError();
829	/* The above method for looking up in ADS failed, try another one. */
830	if (dwErr != NO_ERROR)
831	{
832	dwErr = NO_ERROR;
833
834	}
835	#endif
836	}
837
838
839	/**
840	* Extracts the actual account name & domain from a (raw) account data string.
841	*
842	* This might be a principal or FQDN string.
843	*
844	* @return TRUE if extraction of the account name was successful, FALSE if not.
845	* @param pwszAccountData (Raw) account data string to extract data from.
846	* @param ppwszAccoutName Where to store the extracted account name on success.
847	* Needs to be free'd with CoTaskMemFree().
848	* @param ppwszDomain Where to store the extracted domain name on success.
849	* Needs to be free'd with CoTaskMemFree().
850	*/
851	BOOL VBoxCredProvCredential::ExtractAccoutData(PWSTR pwszAccountData, PWSTR ppwszAccoutName, PWSTR ppwszDomain)
852	{
853	AssertPtrReturn(pwszAccountData, FALSE);
854	VBoxCredProvVerbose(0, "VBoxCredProvCredential::ExtractAccoutData: Getting account name for \"%ls\" ...\n",
855	pwszAccountData);
856	HRESULT hr = E_FAIL;
857
858	/* Try to figure out whether this is a principal name (user@domain). */
859	LPWSTR pPos = NULL;
860	if ( (pPos = StrChrW(pwszAccountData, L'@')) != NULL
861	&& pPos != pwszAccountData)
862	{
863	size_t cbSize = (pPos - pwszAccountData) * sizeof(WCHAR);
864	LPWSTR pwszName = (LPWSTR)CoTaskMemAlloc(cbSize + sizeof(WCHAR)); /* Space for terminating zero. */
865	LPWSTR pwszDomain = NULL;
866	AssertPtr(pwszName);
867	hr = StringCbCopyN(pwszName, cbSize + sizeof(WCHAR), pwszAccountData, cbSize);
868	if (SUCCEEDED(hr))
869	{
870	*ppwszAccoutName = pwszName;
871	pPos++; /* Skip @, point to domain name (if any). */
872	if ( pPos != NULL
873	&& *pPos != L'\0')
874	{
875	hr = SHStrDupW(pPos, &pwszDomain);
876	if (SUCCEEDED(hr))
877	{
878	*ppwszDomain = pwszDomain;
879	}
880	else
881	VBoxCredProvVerbose(0, "VBoxCredProvCredential::ExtractAccoutData: Error copying domain data, hr=%08x\n", hr);
882	}
883	else
884	{
885	hr = E_FAIL;
886	VBoxCredProvVerbose(0, "VBoxCredProvCredential::ExtractAccoutData: No domain name found!\n");
887	}
888	}
889	else
890	VBoxCredProvVerbose(0, "VBoxCredProvCredential::ExtractAccoutData: Error copying account data, hr=%08x\n", hr);
891
892	if (hr != S_OK)
893	{
894	CoTaskMemFree(pwszName);
895	if (pwszDomain)
896	CoTaskMemFree(pwszDomain);
897	}
898	}
899	else
900	VBoxCredProvVerbose(0, "VBoxCredProvCredential::ExtractAccoutData: No valid principal account name found!\n");
901
902	return (hr == S_OK);
903	}
904
905
906	/**
907	* Returns the current value of a specified LogonUI field.
908	*
909	* @return IPRT status code.
910	* @param dwFieldID Field ID to get value for.
911	* @param ppwszString Pointer that receives the actual value of the specified field.
912	*/
913	HRESULT VBoxCredProvCredential::GetStringValue(DWORD dwFieldID, PWSTR *ppwszString)
914	{
915	HRESULT hr;
916
917	PWSTR pwszString = NULL;
918
919	if (dwFieldID < VBOXCREDPROV_NUM_FIELDS)
920	{
921	switch (dwFieldID)
922	{
923	case VBOXCREDPROV_FIELDID_SUBMIT_BUTTON:
924	{
925	/* Fill in standard value to make Winlogon happy. */
926	hr = SHStrDupW(L"Submit", &pwszString);
927	break;
928	}
929
930	default:
931	{
932	if ( m_apwszFields[dwFieldID]
933	&& RTUtf16Len(m_apwszFields[dwFieldID]))
934	{
935	hr = SHStrDupW(m_apwszFields[dwFieldID], &pwszString);
936	}
937	else /* Fill in an empty value. */
938	hr = SHStrDupW(L"", &pwszString);
939	break;
940	}
941	}
942	}
943	else
944	hr = E_INVALIDARG;
945
946	VBoxCredProvVerbose(0, "VBoxCredProvCredential::GetStringValue: m_fIsSelected=%RTbool, dwFieldID=%ld, pwszString=%ls, hr=%Rhrc\n",
947	m_fIsSelected, dwFieldID,
948	#ifdef DEBUG
949	pwszString ? pwszString : L"<NULL>",
950	#else
951	/* Don't show any passwords in release mode. */
952	dwFieldID == VBOXCREDPROV_FIELDID_PASSWORD ? L"XXX" : (pwszString ? pwszString : L"<NULL>"),
953	#endif
954	hr);
955
956	if (ppwszString)
957	{
958	*ppwszString = pwszString;
959	}
960	else if (pwszString)
961	CoTaskMemFree(pwszString);
962
963	return hr;
964	}
965
966
967	/**
968	* Returns back the field ID of which the submit button should be put next to.
969	*
970	* We always want to be the password field put next to the submit button
971	* currently.
972	*
973	* @return HRESULT
974	* @param dwFieldID Field ID of the submit button.
975	* @param pdwAdjacentTo Field ID where to put the submit button next to.
976	*/
977	HRESULT VBoxCredProvCredential::GetSubmitButtonValue(DWORD dwFieldID, DWORD *pdwAdjacentTo)
978	{
979	VBoxCredProvVerbose(0, "VBoxCredProvCredential::GetSubmitButtonValue: dwFieldID=%ld\n",
980	dwFieldID);
981
982	HRESULT hr = S_OK;
983
984	/* Validate parameters. */
985	if ( dwFieldID == VBOXCREDPROV_FIELDID_SUBMIT_BUTTON
986	&& pdwAdjacentTo)
987	{
988	/* pdwAdjacentTo is a pointer to the fieldID you want the submit button to appear next to. */
989	*pdwAdjacentTo = VBOXCREDPROV_FIELDID_PASSWORD;
990	VBoxCredProvVerbose(0, "VBoxCredProvCredential::GetSubmitButtonValue: dwFieldID=%ld, *pdwAdjacentTo=%ld\n",
991	dwFieldID, *pdwAdjacentTo);
992	}
993	else
994	hr = E_INVALIDARG;
995
996	return hr;
997	}
998
999
1000	/**
1001	* Sets the value of a specified field. Currently not used.
1002	*
1003	* @return HRESULT
1004	* @param dwFieldID Field to set value for.
1005	* @param pwszValue Actual value to set.
1006	*/
1007	HRESULT VBoxCredProvCredential::SetStringValue(DWORD dwFieldID, PCWSTR pwszValue)
1008	{
1009	RT_NOREF(dwFieldID, pwszValue);
1010
1011	/* Do more things here later. */
1012	HRESULT hr = S_OK;
1013
1014	VBoxCredProvVerbose(0, "VBoxCredProvCredential::SetStringValue: dwFieldID=%ld, pcwzString=%ls, hr=%Rhrc\n",
1015	dwFieldID,
1016	#ifdef DEBUG
1017	pwszValue ? pwszValue : L"<NULL>",
1018	#else /* Never show any (sensitive) data in release mode! */
1019	L"XXX",
1020	#endif
1021	hr);
1022
1023	return hr;
1024	}
1025
1026
1027	HRESULT VBoxCredProvCredential::GetBitmapValue(DWORD dwFieldID, HBITMAP *phBitmap)
1028	{
1029	NOREF(dwFieldID);
1030	NOREF(phBitmap);
1031
1032	/* We don't do own bitmaps. */
1033	return E_NOTIMPL;
1034	}
1035
1036
1037	HRESULT VBoxCredProvCredential::GetCheckboxValue(DWORD dwFieldID, BOOL pfChecked, PWSTR ppwszLabel)
1038	{
1039	NOREF(dwFieldID);
1040	NOREF(pfChecked);
1041	NOREF(ppwszLabel);
1042	return E_NOTIMPL;
1043	}
1044
1045
1046	HRESULT VBoxCredProvCredential::GetComboBoxValueCount(DWORD dwFieldID, DWORD pcItems, DWORD pdwSelectedItem)
1047	{
1048	NOREF(dwFieldID);
1049	NOREF(pcItems);
1050	NOREF(pdwSelectedItem);
1051	return E_NOTIMPL;
1052	}
1053
1054
1055	HRESULT VBoxCredProvCredential::GetComboBoxValueAt(DWORD dwFieldID, DWORD dwItem, PWSTR *ppwszItem)
1056	{
1057	NOREF(dwFieldID);
1058	NOREF(dwItem);
1059	NOREF(ppwszItem);
1060	return E_NOTIMPL;
1061	}
1062
1063
1064	HRESULT VBoxCredProvCredential::SetCheckboxValue(DWORD dwFieldID, BOOL fChecked)
1065	{
1066	NOREF(dwFieldID);
1067	NOREF(fChecked);
1068	return E_NOTIMPL;
1069	}
1070
1071
1072	HRESULT VBoxCredProvCredential::SetComboBoxSelectedValue(DWORD dwFieldId, DWORD dwSelectedItem)
1073	{
1074	NOREF(dwFieldId);
1075	NOREF(dwSelectedItem);
1076	return E_NOTIMPL;
1077	}
1078
1079
1080	HRESULT VBoxCredProvCredential::CommandLinkClicked(DWORD dwFieldID)
1081	{
1082	NOREF(dwFieldID);
1083	return E_NOTIMPL;
1084	}
1085
1086
1087	/**
1088	* Does the actual authentication stuff to attempt a login.
1089	*
1090	* @return HRESULT
1091	* @param pcpGetSerializationResponse Credential serialization response.
1092	* @param pcpCredentialSerialization Details about the current credential.
1093	* @param ppwszOptionalStatusText Text to set. Optional.
1094	* @param pcpsiOptionalStatusIcon Status icon to set. Optional.
1095	*/
1096	HRESULT VBoxCredProvCredential::GetSerialization(CREDENTIAL_PROVIDER_GET_SERIALIZATION_RESPONSE *pcpGetSerializationResponse,
1097	CREDENTIAL_PROVIDER_CREDENTIAL_SERIALIZATION *pcpCredentialSerialization,
1098	PWSTR *ppwszOptionalStatusText,
1099	CREDENTIAL_PROVIDER_STATUS_ICON *pcpsiOptionalStatusIcon)
1100	{
1101	NOREF(ppwszOptionalStatusText);
1102	NOREF(pcpsiOptionalStatusIcon);
1103
1104	KERB_INTERACTIVE_UNLOCK_LOGON KerberosUnlockLogon;
1105	RT_BZERO(&KerberosUnlockLogon, sizeof(KerberosUnlockLogon));
1106
1107	/* Save a pointer to the interactive logon struct. */
1108	KERB_INTERACTIVE_LOGON *pLogon = &KerberosUnlockLogon.Logon;
1109
1110	#ifdef DEBUG /* Note: NEVER print this in release mode! */
1111	VBoxCredProvVerbose(0, "VBoxCredProvCredential::GetSerialization: Username=%ls, Password=%ls, Domain=%ls\n",
1112	m_apwszFields[VBOXCREDPROV_FIELDID_USERNAME],
1113	m_apwszFields[VBOXCREDPROV_FIELDID_PASSWORD],
1114	m_apwszFields[VBOXCREDPROV_FIELDID_DOMAINNAME]);
1115	#endif
1116
1117	HRESULT hr = kerberosLogonCreate(pLogon,
1118	m_enmUsageScenario,
1119	m_apwszFields[VBOXCREDPROV_FIELDID_USERNAME],
1120	m_apwszFields[VBOXCREDPROV_FIELDID_PASSWORD],
1121	m_apwszFields[VBOXCREDPROV_FIELDID_DOMAINNAME]);
1122	if (SUCCEEDED(hr))
1123	{
1124	hr = kerberosLogonSerialize(pLogon,
1125	&pcpCredentialSerialization->rgbSerialization,
1126	&pcpCredentialSerialization->cbSerialization);
1127	if (SUCCEEDED(hr))
1128	{
1129	HANDLE hLSA;
1130	NTSTATUS s = LsaConnectUntrusted(&hLSA);
1131	hr = HRESULT_FROM_NT(s);
1132
1133	if (SUCCEEDED(hr))
1134	{
1135	LSA_STRING lsaszKerberosName;
1136	size_t cchKerberosName;
1137	hr = StringCchLengthA(NEGOSSP_NAME_A, USHORT_MAX, &cchKerberosName);
1138	if (SUCCEEDED(hr))
1139	{
1140	USHORT usLength;
1141	hr = SizeTToUShort(cchKerberosName, &usLength);
1142	if (SUCCEEDED(hr))
1143	{
1144	lsaszKerberosName.Buffer = (PCHAR)NEGOSSP_NAME_A;
1145	lsaszKerberosName.Length = usLength;
1146	lsaszKerberosName.MaximumLength = lsaszKerberosName.Length + 1;
1147
1148	ULONG ulAuthPackage = 0;
1149
1150	s = LsaLookupAuthenticationPackage(hLSA, &lsaszKerberosName, &ulAuthPackage);
1151	hr = HRESULT_FROM_NT(s);
1152
1153	if (SUCCEEDED(hr))
1154	{
1155	pcpCredentialSerialization->ulAuthenticationPackage = ulAuthPackage;
1156	pcpCredentialSerialization->clsidCredentialProvider = CLSID_VBoxCredProvider;
1157
1158	/* We're done -- let the logon UI know. */
1159	*pcpGetSerializationResponse = CPGSR_RETURN_CREDENTIAL_FINISHED;
1160
1161	VBoxCredProvVerbose(1, "VBoxCredProvCredential::GetSerialization: Finished for user '%ls' (domain '%ls')\n",
1162	m_apwszFields[VBOXCREDPROV_FIELDID_USERNAME],
1163	m_apwszFields[VBOXCREDPROV_FIELDID_DOMAINNAME]);
1164	}
1165	else
1166	VBoxCredProvVerbose(1, "VBoxCredProvCredential::GetSerialization: LsaLookupAuthenticationPackage failed with ntStatus=%ld\n", s);
1167	}
1168	}
1169
1170	LsaDeregisterLogonProcess(hLSA);
1171	}
1172	else
1173	VBoxCredProvVerbose(1, "VBoxCredProvCredential::GetSerialization: LsaConnectUntrusted failed with ntStatus=%ld\n", s);
1174	}
1175	else
1176	VBoxCredProvVerbose(1, "VBoxCredProvCredential::GetSerialization: kerberosLogonSerialize failed with hr=0x%08x\n", hr);
1177
1178	kerberosLogonDestroy(pLogon);
1179	pLogon = NULL;
1180	}
1181	else
1182	VBoxCredProvVerbose(1, "VBoxCredProvCredential::GetSerialization: kerberosLogonCreate failed with hr=0x%08x\n", hr);
1183
1184	VBoxCredProvVerbose(1, "VBoxCredProvCredential::GetSerialization returned hr=0x%08x\n", hr);
1185	return hr;
1186	}
1187
1188
1189	/**
1190	* Called by LogonUI after a logon attempt was made -- here we could set an additional status
1191	* text and/or icon.
1192	*
1193	* Currently not used.
1194	*
1195	* @return HRESULT
1196	* @param ntStatus NT status of logon attempt reported by Winlogon.
1197	* @param ntSubStatus NT substatus of logon attempt reported by Winlogon.
1198	* @param ppwszOptionalStatusText Pointer that receives the optional status text.
1199	* @param pcpsiOptionalStatusIcon Pointer that receives the optional status icon.
1200	*/
1201	HRESULT VBoxCredProvCredential::ReportResult(NTSTATUS ntStatus,
1202	NTSTATUS ntSubStatus,
1203	PWSTR *ppwszOptionalStatusText,
1204	CREDENTIAL_PROVIDER_STATUS_ICON *pcpsiOptionalStatusIcon)
1205	{
1206	RT_NOREF(ntStatus, ntSubStatus, ppwszOptionalStatusText, pcpsiOptionalStatusIcon);
1207	VBoxCredProvVerbose(0, "VBoxCredProvCredential::ReportResult: ntStatus=%ld, ntSubStatus=%ld\n",
1208	ntStatus, ntSubStatus);
1209	return E_NOTIMPL;
1210	}
1211

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/VBox/Additions/WINNT/VBoxCredProv/VBoxCredProvCredential.cpp@ 78425

Download in other formats: