From b6e791f70970920ecbd0f942b29f9c84c9d4b3bc Mon Sep 17 00:00:00 2001 From: Marco Blessing Date: Thu, 23 Jan 2020 13:06:16 +0100 Subject: [PATCH] adds security section (#47) - add security section - update content - fix github deployment state - update about page based on readme.md --- README.md | 32 ++++++++++++++++++++++++++++++++ appveyor.yml | 2 +- docs/about_PSCredentialStore.md | 32 +++++++++++++++++++++++++++++++- 3 files changed, 64 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 05a9ad2..5d14b26 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. You can't +decrypt and reuse such credentials from a different user account or even machine. This is caused by automatically +generated encryption key which, is used create a `Secure String` based encrypted 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 we decided to use the public and private keys from valid certificates as part of the custom encryption keys to encrypt your data. + +This means clearly: 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 ============ diff --git a/appveyor.yml b/appveyor.yml index 6f3197b..a1d8a37 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -61,7 +61,7 @@ deploy: secure: M+bBX5/nKdJB0eViP7xtrLVTwf3vGDUA9N2MMprZp2i+9ZR3CBVcJnSzJWUmalhB artifact: PSCredentialStore.zip # upload all NuGet packages to release assets draft: false - prerelease: true + prerelease: false on: branch: master # build release on master branch changes diff --git a/docs/about_PSCredentialStore.md b/docs/about_PSCredentialStore.md index 95db59b..e0f33cc 100644 --- a/docs/about_PSCredentialStore.md +++ b/docs/about_PSCredentialStore.md @@ -26,6 +26,36 @@ For more details read the [about_PSCredentialStore](/docs/about_PSCredentialStor - PowerShell >= `5.1` - .NET Framework >= `4.6` or .NET Core >= `1.0` +## 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. You can't +decrypt and reuse such credentials from a different user account or even machine. This is caused by automatically +generated encryption key which, is used create a `Secure String` based encrypted 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 we decided to use the public and private keys from valid certificates as part of the custom encryption keys to encrypt your data. + +This means clearly: 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` | + + ## Installation ## PowerShellGallery.com (Recommended Way) @@ -56,7 +86,7 @@ New-CredentialStore # Private credential store with certificate store usage New-CredentialStore -UseCertStore -# Shared credential rtore +# Shared credential store New-CredentialStore -Shared #Shared credential store in custom Location