Marshal.SecureStringToGlobalAllocAnsi(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 into unmanaged memory, converting into ANSI format as it copies.
public:
static IntPtr SecureStringToGlobalAllocAnsi(System::Security::SecureString ^ s);public static IntPtr SecureStringToGlobalAllocAnsi (System.Security.SecureString s);[System.CLSCompliant(false)]
public static IntPtr SecureStringToGlobalAllocAnsi (System.Security.SecureString s);[System.Security.SecurityCritical]
public static IntPtr SecureStringToGlobalAllocAnsi (System.Security.SecureString s);static member SecureStringToGlobalAllocAnsi : System.Security.SecureString -> nativeint[<System.CLSCompliant(false)>]
static member SecureStringToGlobalAllocAnsi : System.Security.SecureString -> nativeint[<System.Security.SecurityCritical>]
static member SecureStringToGlobalAllocAnsi : System.Security.SecureString -> nativeintPublic Shared Function SecureStringToGlobalAllocAnsi (s As SecureString) As IntPtrParameters
The managed object to copy.
Returns
nativeint
The address, in unmanaged memory, to where the s parameter was copied, 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 SecureStringToGlobalAllocAnsi method to marshal and decrypt the contents of a SecureString object to a block of unmanaged memory. It then uses the ZeroFreeGlobalAllocAnsi 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.SecureStringToGlobalAllocAnsi(passWord);
passWord.Dispose();
if (unmanagedRef != IntPtr.Zero) {
Console.WriteLine("Zeroing out unmanaged memory...");
Marshal.ZeroFreeGlobalAllocAnsi(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
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.SecureStringToGlobalAllocAnsi(passWord)
passWord.Dispose()
If unmanagedRef <> IntPtr.Zero Then
Console.WriteLine("Zeroing out unmanaged memory...")
Marshal.ZeroFreeGlobalAllocAnsi(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 SecureStringToGlobalAllocAnsi 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 ZeroFreeGlobalAllocAnsi method.
