Marshal.SecureStringToCoTaskMemUnicode(SecureString) Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Important
This API is not CLS-compliant.
Copies the contents of a managed SecureString object to a block of memory allocated from the unmanaged COM task allocator.
public:
static IntPtr SecureStringToCoTaskMemUnicode(System::Security::SecureString ^ s);public static IntPtr SecureStringToCoTaskMemUnicode(System.Security.SecureString s);[System.CLSCompliant(false)]
public static IntPtr SecureStringToCoTaskMemUnicode(System.Security.SecureString s);[System.Security.SecurityCritical]
public static IntPtr SecureStringToCoTaskMemUnicode(System.Security.SecureString s);static member SecureStringToCoTaskMemUnicode : System.Security.SecureString -> nativeint[<System.CLSCompliant(false)>]
static member SecureStringToCoTaskMemUnicode : System.Security.SecureString -> nativeint[<System.Security.SecurityCritical>]
static member SecureStringToCoTaskMemUnicode : System.Security.SecureString -> nativeintPublic Shared Function SecureStringToCoTaskMemUnicode (s As SecureString) As IntPtrParameters
The managed object to copy.
Returns
nativeint
The address, in unmanaged memory, where the s parameter was copied to, or 0 if a null object was supplied.
- Attributes
Exceptions
The s parameter is null.
There is insufficient memory available.
Examples
The following example uses the SecureStringToCoTaskMemUnicode method to marshal and decrypt the contents of a SecureString object to a block of unmanaged memory. It then uses the ZeroFreeCoTaskMemUnicode method to zero out and dispose the unmanaged block.
using System;
using System.Runtime.InteropServices;
using System.Security;
class Example
{
static void Main()
{
IntPtr unmanagedRef = IntPtr.Zero;
// Ask the user for a password.
Console.Write("Please enter your password: ");
SecureString passWord = GetPassword();
Console.WriteLine("Copying and decrypting the string to unmanaged memory...");
// Copy the Secure string to unmanaged memory (and decrypt it).
unmanagedRef = Marshal.SecureStringToCoTaskMemUnicode(passWord);
passWord.Dispose();
if (unmanagedRef != IntPtr.Zero) {
Console.WriteLine("Zeroing out unmanaged memory...");
Marshal.ZeroFreeCoTaskMemUnicode(unmanagedRef);
}
Console.WriteLine("Done.");
}
public static SecureString GetPassword()
{
SecureString password = new SecureString();
// get the first character of the password
ConsoleKeyInfo nextKey = Console.ReadKey(true);
while (nextKey.Key != ConsoleKey.Enter) {
if (nextKey.Key == ConsoleKey.Backspace) {
if (password.Length > 0) {
password.RemoveAt(password.Length - 1);
// erase the last * as well
Console.Write(nextKey.KeyChar);
Console.Write(" ");
Console.Write(nextKey.KeyChar);
}
}
else {
password.AppendChar(nextKey.KeyChar);
Console.Write("*");
}
nextKey = Console.ReadKey(true);
}
Console.WriteLine();
// Lock the password down.
password.MakeReadOnly();
return password;
}
}
// The example displays output like the following:
// Please enter your password: **********
// Copying and decrypting the string to unmanaged memory...
// Zeroing out unmanaged memory...
// Done.
Imports System.Runtime.InteropServices
Imports System.Security
Module Example
Public Sub Main()
Dim unmanagedRef As IntPtr
' Ask the user for a password.
Console.Write("Please enter your password: ")
Dim passWord As SecureString = GetPassword()
Console.WriteLine("Copying and decrypting the string to unmanaged memory...")
' Copy the Secure string to unmanaged memory (and decrypt it).
unmanagedRef = Marshal.SecureStringToCoTaskMemUnicode(passWord)
passWord.Dispose()
If unmanagedRef <> IntPtr.Size Then
Console.WriteLine("Zeroing out unmanaged memory...")
Marshal.ZeroFreeCoTaskMemUnicode(unmanagedRef)
End If
Console.WriteLine("Done.")
End Sub
Function GetPassword() As SecureString
Dim password As New SecureString()
' Get the first character of the password.
Dim nextKey As ConsoleKeyInfo = Console.ReadKey(True)
While nextKey.Key <> ConsoleKey.Enter
If nextKey.Key = ConsoleKey.BackSpace Then
If password.Length > 0 Then
password.RemoveAt(password.Length - 1)
' Erase the last * as well.
Console.Write(nextKey.KeyChar)
Console.Write(" ")
Console.Write(nextKey.KeyChar)
End If
Else
password.AppendChar(nextKey.KeyChar)
Console.Write("*")
End If
nextKey = Console.ReadKey(True)
End While
Console.WriteLine()
' lock the password down
password.MakeReadOnly()
Return password
End Function
End Module
' The example displays output like the following:
' Please enter your password: **********
' Copying and decrypting the string to unmanaged memory...
' Zeroing out unmanaged memory...
' Done.
Remarks
The SecureStringToCoTaskMemUnicode method is useful for custom marshaling or when mixing managed and unmanaged code. Because this method allocates the unmanaged memory required for a string, always free the memory by calling the ZeroFreeCoTaskMemUnicode method. The characters of the string are copied as Unicode characters.
