From b60830d67c4a7721bcfb690ab4d4af1de6ee043f Mon Sep 17 00:00:00 2001 From: OCram85 Date: Fri, 18 Oct 2019 13:47:10 +0200 Subject: [PATCH] add security section --- README.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/README.md b/README.md index 05a9ad2..a7a1066 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,38 @@ You can find the [reference](/docs/PSCredentialStore.md) in the /docs/ path as w - PowerShell >= `5.1` - .NET Framework >= `4.6` or .NET Core >= `1.0` +:bomb: About Security +============ + +>This section explains some security topics and the the design decisions we made to balance the usage and security needs. + +To be able to delegate `PSCredentials` objects we can't exclusively rely on the `SecureString` cmdlets. If you try +to reuse a password encrypted in default `SecureString` with another user account or machine the password can't be +decrypted. This is caused automatically generated encryption key which is used to secure the string. + +In order to delegate a password while still using the underlying security framework we have to provide a custom +encryption key. This leads to the fact, that everyone who has access to the key could encrypt or decrypt your data. + +So de decided to use the certificate's public and private keys with custom encryption keys to encrypt your data. + +This means everyone who has access to the `CredentialStore` needs also access to the certificate file to work with it. + +Keep in mind you need to secure the access with your NTFS file permissions to avoid unwanted usage. Another option is +to import the certificate into your certification vaults of you operating system. In this case you can grand the +permission to the certificates itself. + +Here is s brief hierarchy description of the certificate location: *(First match wins)* + +| CredentialStore Type | Certificate Location | +| -------------------- | ---------------------- | +| Private | `CurrentUser`\\`My` | +| Shared (Windows) | `CurrentUser`\\`My` | +| | `LocalMachine`\\`Root` | +| Shared (Linux) | `LocalMachine`\\`My` | +| | `LocalMachine`\\`Root` | + + + :hammer_and_wrench: Installation ============