Marshal.SecureStringToCoTaskMemUnicode(SecureString) Method

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 -> nativeint

Public Shared Function SecureStringToCoTaskMemUnicode (s As SecureString) As IntPtr

Parameters

Returns

The address, in unmanaged memory, where the s parameter was copied to, or 0 if a null object was supplied.

Attributes

CLSCompliantAttribute SecurityCriticalAttribute

Exceptions

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.