ConvertTo-SecureString

Tworzy bezpieczny łańcuch (SecureString) z hasła lub danych wrażliwych.

ConvertTo-SecureString to polecenie z modułu Microsoft.PowerShell.Security, które zamienia zwykły tekst lub wcześniej zaszyfrowany łańcuch w obiekt typu SecureString. SecureString trzyma dane (najczęściej hasło) w pamięci w postaci zaszyfrowanej, dzięki czemu nie wisi sobie jako goły string w zmiennej. Najczęściej użyjesz go, gdy jakiś cmdlet (np. New-PSSession, Get-Credential, połączenie do bazy czy API) oczekuje hasła właśnie w tym formacie, a Ty masz je w postaci tekstowej albo zapisanej wcześniej do pliku.

Składnia i najważniejsze opcje

Podstawowe wywołanie wygląda tak: ConvertTo-SecureString [-String] [-AsPlainText] [-Force]

  • -String — tekst do zamiany; parametr pozycyjny, więc zwykle podajesz go pierwszy bez nazwy.
  • -AsPlainText — mówi, że na wejściu jest zwykły, niezaszyfrowany tekst (np. hasło wpisane wprost). Bez tego polecenie zakłada, że dostaje zaszyfrowany standardowy łańcuch.
  • -Force — potwierdza, że świadomie konwertujesz jawny tekst. W PowerShell 5.1 jest wymagany razem z -AsPlainText; od PowerShell 7 nie jest już potrzebny (zostawiony tylko dla zgodności).
  • -Key — klucz szyfrujący jako tablica bajtów (AES). Używasz go, gdy odszyfrowujesz łańcuch zapisany wcześniej z tym samym kluczem.
  • -SecureKey — to samo co wyżej, ale klucz podany jako SecureString zamiast tablicy bajtów.

Przykłady użycia

  • $haslo = ConvertTo-SecureString "Tajne123" -AsPlainText -Force — najszybszy sposób na zrobienie SecureString z jawnego hasła (działa w 5.1 i 7+).
  • $cred = New-Object System.Management.Automation.PSCredential("admin", $haslo) — budujesz obiekt poświadczeń z gotowego SecureString, by przekazać go do cmdletów z parametrem -Credential.
  • "Tajne123" | ConvertTo-SecureString -AsPlainText -Force — to samo, tylko z tekstem przekazanym przez potok.
  • $enc = Get-Content .\haslo.txt; $sec = ConvertTo-SecureString $enc — odtwarzasz SecureString z pliku zapisanego przez ConvertFrom-SecureString (DPAPI, ten sam użytkownik i maszyna).
  • $sec = ConvertTo-SecureString $enc -Key $klucz — odszyfrowujesz łańcuch zaszyfrowany własnym kluczem AES, gdy chcesz przenosić plik między maszynami.

Częste błędy i pułapki

To nie jest szyfrowanie godne hasła produkcyjnego. Wpisanie hasła wprost w skrypcie z -AsPlainText niczego nie ukrywa — tekst i tak leży w pliku .ps1. SecureString chroni dane w pamięci, a nie w Twoim repo.

Drugi klasyk: SecureString zapisany przez ConvertFrom-SecureString bez klucza używa DPAPI i da się go odszyfrować tylko na tym samym koncie i tej samej maszynie. Przeniesiesz plik na inny serwer i dostaniesz błąd. Jeśli potrzebujesz przenośności, użyj -Key lub -SecureKey.

Pamiętaj też o różnicy wersji: w PowerShell 5.1 pominięcie -Force przy -AsPlainText wywali błąd; w 7+ przejdzie bez problemu. Dla zgodności skryptów bezpieczniej zostawić -Force. Warto wiedzieć, że SecureString jest też uznawany za przestarzały na nie-Windowsowych platformach — pod Linuksem czy macOS nie daje realnej ochrony.

Powiązane polecenia: ConvertFrom-SecureString (operacja odwrotna), Get-Credential, New-Object PSCredential, Read-Host -AsSecureString.