CryptoStream 類別

定義

命名空間:

System.Security.Cryptography

組件:

System.Security.Cryptography.dll

來源:

CryptoStream.cs

定義將數據流連結至密碼編譯轉換的數據流。

public ref class CryptoStream : System::IO::Stream

public class CryptoStream : System.IO.Stream

type CryptoStream = class
    inherit Stream
    interface IDisposable

Public Class CryptoStream
Inherits Stream

繼承

Object

MarshalByRefObject

Stream

CryptoStream

實作

IDisposable

範例

下列範例示範如何使用 CryptoStream 來加密字串。 這個方法會使用 Aes 類別搭配指定的 Key 和初始化向量 （IV）。

using System;
using System.IO;
using System.Security.Cryptography;

class AesExample
{
    public static void Main()
    {
        try
        {
            string original = "Here is some data to encrypt!";

            // Create a new instance of the Aes class.
            // This generates a new key and initialization vector (IV).
            using (Aes myAes = Aes.Create())
            {
                // Encrypt the string to an array of bytes.
                byte[] encrypted = EncryptStringToBytes(original, myAes.Key, myAes.IV);

                // Decrypt the bytes to a string.
                string roundtrip = DecryptStringFromBytes(encrypted, myAes.Key, myAes.IV);

                // Display the original data and the decrypted data.
                Console.WriteLine("Original:   {0}", original);
                Console.WriteLine("Round trip: {0}", roundtrip);
            }
        }
        catch (Exception e)
        {
            Console.WriteLine("Error: {0}", e.Message);
        }
    }

    static byte[] EncryptStringToBytes(string plainText, byte[] Key, byte[] IV)
    {
        // Check arguments.
        if (plainText == null || plainText.Length <= 0)
            throw new ArgumentNullException(nameof(plainText));
        if (Key == null || Key.Length <= 0)
            throw new ArgumentNullException(nameof(Key));
        if (IV == null || IV.Length <= 0)
            throw new ArgumentNullException(nameof(IV));
        byte[] encrypted;

        // Create a Aes object with the specified key and IV.
        using (Aes aesAlg = Aes.Create())
        {
            aesAlg.Key = Key;
            aesAlg.IV = IV;

            // Create an encryptor to perform the stream transform.
            ICryptoTransform encryptor = aesAlg.CreateEncryptor(aesAlg.Key, aesAlg.IV);

            // Create the streams used for encryption.
            using (MemoryStream msEncrypt = new())
            {
                using (CryptoStream csEncrypt = new(msEncrypt, encryptor, CryptoStreamMode.Write))
                {
                    using (StreamWriter swEncrypt = new(csEncrypt))
                    {
                        // Write all data to the stream.
                        swEncrypt.Write(plainText);
                    }
                    encrypted = msEncrypt.ToArray();
                }
            }
        }

        // Return the encrypted bytes from the memory stream.
        return encrypted;
    }

    static string DecryptStringFromBytes(byte[] cipherText, byte[] Key, byte[] IV)
    {
        // Check arguments.
        if (cipherText == null || cipherText.Length <= 0)
            throw new ArgumentNullException(nameof(cipherText));
        if (Key == null || Key.Length <= 0)
            throw new ArgumentNullException(nameof(Key));
        if (IV == null || IV.Length <= 0)
            throw new ArgumentNullException(nameof(IV));

        // Declare the string used to hold the decrypted text.
        string plaintext = null;

        // Create a Aes object with the specified key and IV.
        using (Aes aesAlg = Aes.Create())
        {
            aesAlg.Key = Key;
            aesAlg.IV = IV;

            // Create a decryptor to perform the stream transform.
            ICryptoTransform decryptor = aesAlg.CreateDecryptor(aesAlg.Key, aesAlg.IV);

            // Create the streams used for decryption.
            using (MemoryStream msDecrypt = new(cipherText))
            {
                using (CryptoStream csDecrypt = new(msDecrypt, decryptor, CryptoStreamMode.Read))
                {
                    using (StreamReader srDecrypt = new(csDecrypt))
                    {

                        // Read the decrypted bytes from the decrypting stream
                        // and place them in a string.
                        plaintext = srDecrypt.ReadToEnd();
                    }
                }
            }
        }

        return plaintext;
    }
}

Imports System.IO
Imports System.Security.Cryptography

Class AesExample

    Public Shared Sub Main()
        Try
            Dim original As String = "Here is some data to encrypt!"

            ' Create a new instance of the Aes class.
            ' This generates a new key and initialization vector (IV).
            Using myAes = Aes.Create()

                ' Encrypt the string to an array of bytes.
                Dim encrypted As Byte() = EncryptStringToBytes(original, myAes.Key, myAes.IV)

                ' Decrypt the bytes to a string.
                Dim roundtrip As String = DecryptStringFromBytes(encrypted, myAes.Key, myAes.IV)

                'Display the original data and the decrypted data.
                Console.WriteLine("Original:   {0}", original)
                Console.WriteLine("Round Trip: {0}", roundtrip)
            End Using
        Catch e As Exception
            Console.WriteLine("Error: {0}", e.Message)
        End Try
    End Sub

    Shared Function EncryptStringToBytes(ByVal plainText As String, ByVal Key() As Byte, ByVal IV() As Byte) As Byte()
        ' Check arguments.
        If plainText Is Nothing OrElse plainText.Length <= 0 Then
            Throw New ArgumentNullException(NameOf(plainText))
        End If
        If Key Is Nothing OrElse Key.Length <= 0 Then
            Throw New ArgumentNullException(NameOf(Key))
        End If
        If IV Is Nothing OrElse IV.Length <= 0 Then
            Throw New ArgumentNullException(NameOf(IV))
        End If
        Dim encrypted() As Byte

        ' Create an Aes object with the specified key and IV.
        Using aesAlg = Aes.Create()

            aesAlg.Key = Key
            aesAlg.IV = IV

            ' Create an encryptor to perform the stream transform.
            Dim encryptor As ICryptoTransform = aesAlg.CreateEncryptor(aesAlg.Key, aesAlg.IV)
            ' Create the streams used for encryption.
            Using msEncrypt As New MemoryStream()
                Using csEncrypt As New CryptoStream(msEncrypt, encryptor, CryptoStreamMode.Write)
                    Using swEncrypt As New StreamWriter(csEncrypt)

                        ' Write all data to the stream.
                        swEncrypt.Write(plainText)
                    End Using
                    encrypted = msEncrypt.ToArray()
                End Using
            End Using
        End Using

        ' Return the encrypted bytes from the memory stream.
        Return encrypted

    End Function 'EncryptStringToBytes

    Shared Function DecryptStringFromBytes(
        ByVal cipherText() As Byte,
        ByVal Key() As Byte,
        ByVal IV() As Byte) As String
        ' Check arguments.
        If cipherText Is Nothing OrElse cipherText.Length <= 0 Then
            Throw New ArgumentNullException(NameOf(cipherText))
        End If
        If Key Is Nothing OrElse Key.Length <= 0 Then
            Throw New ArgumentNullException(NameOf(Key))
        End If
        If IV Is Nothing OrElse IV.Length <= 0 Then
            Throw New ArgumentNullException(NameOf(IV))
        End If

        ' Declare the string used to hold the decrypted text.
        Dim plaintext As String = Nothing

        ' Create an Aes object with the specified key and IV.
        Using aesAlg = Aes.Create()
            aesAlg.Key = Key
            aesAlg.IV = IV

            ' Create a decryptor to perform the stream transform.
            Dim decryptor As ICryptoTransform = aesAlg.CreateDecryptor(aesAlg.Key, aesAlg.IV)

            ' Create the streams used for decryption.
            Using msDecrypt As New MemoryStream(cipherText)
                Using csDecrypt As New CryptoStream(msDecrypt, decryptor, CryptoStreamMode.Read)
                    Using srDecrypt As New StreamReader(csDecrypt)
                        ' Read the decrypted bytes from the decrypting stream
                        ' and place them in a string.
                        plaintext = srDecrypt.ReadToEnd()
                    End Using
                End Using
            End Using
        End Using

        Return plaintext

    End Function 'DecryptStringFromBytes 
End Class

備註

Common Language Runtime 使用串流導向的設計進行密碼編譯。 此設計的核心是 CryptoStream。 任何實作 CryptoStream 的密碼編譯物件都可以與任何實作 Stream的物件鏈結在一起，因此可以將某個對象的數據流輸出饋送至另一個對象的輸入。 中繼結果（第一個對象的輸出）不需要分開儲存。

重要

在 .NET 6 和更新版本中，當使用長度為 N的緩衝區呼叫 Stream.Read 或 Stream.ReadAsync 時，作業會在數據流中讀取至少 1 個字節時完成，或它包裝的基礎數據流會從呼叫傳回 0 Read，表示沒有可用的數據。 在 .NET 6 之前，Stream.Read 和 Stream.ReadAsync 直到從數據流讀取所有 N 個字節，或從呼叫 Read傳回 0 的基礎數據流，才會傳回 。 如果您的程式代碼假設 Read 方法在讀取所有 N 個字節之前不會傳回，則可能無法讀取所有內容。 如需詳細資訊，請參閱在資料流中 部分和零位元組讀取。

呼叫 Clear 方法之後，您應該一律明確地關閉 CryptoStream 物件。 這麼做會排清基礎數據流，並讓 CryptoStream 對象處理所有剩餘的數據區塊。 不過，如果您在呼叫 Close 方法之前發生例外狀況，則 CryptoStream 物件可能不會關閉。 為了確保一律會呼叫 Close 方法，請將呼叫放在 try/catch 語句的 finally 區塊內 Clear 方法。

此類型會實作 IDisposable 介面。 當您完成類型使用之後，應該藉由呼叫其 Clear 方法，直接或間接處置它，進而呼叫其 IDisposable 實作。 若要直接處置類型，請在 try/catch 區塊中呼叫其 Clear 方法。 若要間接處置它，請使用語言建構，例如 using （C#） 或 Using （在 Visual Basic 中）。

建構函式

CryptoStream(Stream, ICryptoTransform, CryptoStreamMode)	使用目標數據流、要使用的轉換，以及數據流模式，初始化 CryptoStream 類別的新實例。
CryptoStream(Stream, ICryptoTransform, CryptoStreamMode, Boolean)	初始化 CryptoStream 類別的新實例。

屬性

CanRead	取得值，指出目前 CryptoStream 是否可讀取。
CanSeek	取得值，指出您是否可以在目前 CryptoStream內搜尋 。
CanTimeout	取得值，這個值會判斷目前的數據流是否可以逾時。 (繼承來源 Stream)
CanWrite	取得值，指出目前 CryptoStream 是否可寫入。
HasFlushedFinalBlock	取得值，指出最終緩衝區區塊是否已寫入基礎數據流。
Length	取得數據流的位元組長度。
Position	取得或設定目前數據流中的位置。
ReadTimeout	取得或設定值，以毫秒為單位，決定數據流在逾時之前嘗試讀取的時間長度。 (繼承來源 Stream)
WriteTimeout	取得或設定值，以毫秒為單位，決定數據流在逾時之前嘗試寫入的時間長度。 (繼承來源 Stream)

方法

BeginRead(Byte[], Int32, Int32, AsyncCallback, Object)	開始異步讀取作業。 （請考慮改用 ReadAsync。
BeginWrite(Byte[], Int32, Int32, AsyncCallback, Object)	開始異步寫入作業。 （請考慮改用 WriteAsync。
Clear()	釋放 CryptoStream所使用的所有資源。
Close()	關閉目前的數據流，並釋放與目前數據流相關聯的任何資源（例如套接字和檔句柄）。 請確定已正確處置數據流，而不是呼叫此方法。 (繼承來源 Stream)
CopyTo(Stream)	從目前的數據流讀取位元組，並將其寫入另一個數據流。 這兩個數據流位置都會依複製的位元元組數目進階。 (繼承來源 Stream)
CopyTo(Stream, Int32)	從基礎數據流讀取位元組、套用相關的密碼編譯轉換，並將結果寫入目的地數據流。
CopyToAsync(Stream)	以異步方式從目前的數據流讀取位元組，並將其寫入另一個數據流。 這兩個數據流位置都會依複製的位元元組數目進階。 (繼承來源 Stream)
CopyToAsync(Stream, CancellationToken)	使用指定的取消標記，以異步方式從目前數據流讀取位元組，並將其寫入另一個數據流。 這兩個數據流位置都會依複製的位元元組數目進階。 (繼承來源 Stream)
CopyToAsync(Stream, Int32)	使用指定的緩衝區大小，以異步方式從目前數據流讀取位元組，並將其寫入另一個數據流。 這兩個數據流位置都會依複製的位元元組數目進階。 (繼承來源 Stream)
CopyToAsync(Stream, Int32, CancellationToken)	以異步方式從基礎數據流讀取位元組、套用相關的密碼編譯轉換，並將結果寫入目的地數據流。
CreateObjRef(Type)	建立物件，其中包含產生用來與遠端物件通訊之 Proxy 所需的所有相關信息。 (繼承來源 MarshalByRefObject)
CreateWaitHandle()	已淘汰. 配置 WaitHandle 物件。 (繼承來源 Stream)
Dispose()	釋放 Stream所使用的所有資源。 (繼承來源 Stream)
Dispose(Boolean)	釋放 CryptoStream 所使用的 Unmanaged 資源，並選擇性地釋放 Managed 資源。
DisposeAsync()	以異步方式釋放 CryptoStream所使用的 Unmanaged 資源。
EndRead(IAsyncResult)	等候暫止的異步讀取完成。 （請考慮改用 ReadAsync。
EndWrite(IAsyncResult)	結束異步寫入作業。 （請考慮改用 WriteAsync。
Equals(Object)	判斷指定的物件是否等於目前的物件。 (繼承來源 Object)
Flush()	清除目前數據流的所有緩衝區，並導致任何緩衝的數據寫入基礎裝置。
FlushAsync()	以異步方式清除此數據流的所有緩衝區，並導致任何緩衝的數據寫入基礎裝置。 (繼承來源 Stream)
FlushAsync(CancellationToken)	以異步方式清除目前數據流的所有緩衝區、導致任何緩衝的數據寫入基礎裝置，並監視取消要求。
FlushFinalBlock()	使用緩衝區的目前狀態來更新基礎數據源或存放庫，然後清除緩衝區。
FlushFinalBlockAsync(CancellationToken)	使用緩衝區的目前狀態，以異步方式更新基礎數據源或存放庫，然後清除緩衝區。
GetHashCode()	做為預設哈希函式。 (繼承來源 Object)
GetLifetimeService()	已淘汰. 擷取控制這個實例存留期原則的目前存留期服務物件。 (繼承來源 MarshalByRefObject)
GetType()	取得目前實例的 Type。 (繼承來源 Object)
InitializeLifetimeService()	已淘汰. 取得存留期服務物件，以控制這個實例的存留期原則。 (繼承來源 MarshalByRefObject)
MemberwiseClone()	建立目前 Object的淺層複本。 (繼承來源 Object)
MemberwiseClone(Boolean)	建立目前 MarshalByRefObject 對象的淺層複本。 (繼承來源 MarshalByRefObject)
ObjectInvariant()	已淘汰. 提供 Contract的支援。 (繼承來源 Stream)
Read(Byte[], Int32, Int32)	從目前數據流讀取位元組序列，並依讀取的位元元組數目將數據流中的位置往前移。
Read(Span<Byte>)	在衍生類別中覆寫時，從目前數據流讀取位元組序列，並將數據流中的位置依讀取的位元組數目往前移。 (繼承來源 Stream)
ReadAsync(Byte[], Int32, Int32)	以異步方式從目前數據流讀取位元組序列，並依讀取的位元元組數目將數據流中的位置往前移。 (繼承來源 Stream)
ReadAsync(Byte[], Int32, Int32, CancellationToken)	以異步方式從目前數據流讀取位元組序列、依讀取的位元元組數目將數據流中的位置往前移，並監視取消要求。
ReadAsync(Memory<Byte>, CancellationToken)	以異步方式從目前數據流讀取位元組序列、依讀取的位元元組數目將數據流中的位置往前移，並監視取消要求。
ReadAtLeast(Span<Byte>, Int32, Boolean)	從目前數據流讀取至少一個字節數目，並將數據流中的位置依讀取的位元組數目往前移。 (繼承來源 Stream)
ReadAtLeastAsync(Memory<Byte>, Int32, Boolean, CancellationToken)	以異步方式從目前數據流讀取至少一個字節數目、依讀取的位元組數目將數據流中的位置往前移，並監視取消要求。 (繼承來源 Stream)
ReadByte()	從數據流讀取位元組，並在數據流結尾處將數據流中的位置往前移一個字節，或在數據流結尾傳回 -1。
ReadExactly(Byte[], Int32, Int32)	從目前數據流讀取 count 位元組數，並將位置往前移。 (繼承來源 Stream)
ReadExactly(Span<Byte>)	從目前的數據流讀取位元組，並將位置往前移，直到填入 buffer 為止。 (繼承來源 Stream)
ReadExactlyAsync(Byte[], Int32, Int32, CancellationToken)	以異步方式從目前數據流讀取 count 位元組數目、推進數據流中的位置，以及監視取消要求。 (繼承來源 Stream)
ReadExactlyAsync(Memory<Byte>, CancellationToken)	以異步方式從目前數據流讀取位元組、將數據流中的位置往前移，直到填入 buffer，並監視取消要求。 (繼承來源 Stream)
Seek(Int64, SeekOrigin)	設定目前數據流中的位置。
SetLength(Int64)	設定目前數據流的長度。
ToString()	傳回表示目前 物件的字串。 (繼承來源 Object)
Write(Byte[], Int32, Int32)	將位元組序列寫入目前 CryptoStream，並以寫入的位元元組數將數據流中的目前位置往前移。
Write(ReadOnlySpan<Byte>)	在衍生類別中覆寫時，將位元組序列寫入目前數據流，並依寫入的位元組數目將這個數據流中的目前位置往前移。 (繼承來源 Stream)
WriteAsync(Byte[], Int32, Int32)	以異步方式將位元組序列寫入目前數據流，並依寫入的位元元組數目，將這個數據流中的目前位置往前移。 (繼承來源 Stream)
WriteAsync(Byte[], Int32, Int32, CancellationToken)	以異步方式將位元組序列寫入目前數據流、依寫入的位元組數目將數據流中的目前位置往前移，並監視取消要求。
WriteAsync(ReadOnlyMemory<Byte>, CancellationToken)	以異步方式將位元組序列寫入至目前的數據流、依寫入的位元組數目將這個數據流中的目前位置往前移，並監視取消要求。
WriteByte(Byte)	將位元組寫入數據流中的目前位置，並將數據流中的位置往前移一個字節。

擴充方法

CopyToAsync(Stream, PipeWriter, CancellationToken)	使用取消標記，以異步方式從 Stream 讀取位元組，並將其寫入指定的 PipeWriter。
ConfigureAwait(IAsyncDisposable, Boolean)	設定如何執行從異步可處置專案傳回的工作等候。

另請參閱

• 密碼編譯服務
• DeflateStream、GZipStream 和 CryptoStream 中的部分和零位元組讀取