From b60830d67c4a7721bcfb690ab4d4af1de6ee043f Mon Sep 17 00:00:00 2001 From: OCram85 Date: Fri, 18 Oct 2019 13:47:10 +0200 Subject: [PATCH 1/4] 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 ============ -- 2.40.1 From 85c7d968563128d506867d9a10375bd36fe0c54e Mon Sep 17 00:00:00 2001 From: OCram85 Date: Thu, 23 Jan 2020 11:37:36 +0100 Subject: [PATCH 2/4] update content --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index a7a1066..5d14b26 100644 --- a/README.md +++ b/README.md @@ -40,16 +40,16 @@ You can find the [reference](/docs/PSCredentialStore.md) in the /docs/ path as w >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. +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 +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. +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 everyone who has access to the `CredentialStore` needs also access to the certificate file to work with it. +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 -- 2.40.1 From 1192014a79e464ed65aff1363a54800e47a8b289 Mon Sep 17 00:00:00 2001 From: OCram85 Date: Thu, 23 Jan 2020 12:52:42 +0100 Subject: [PATCH 3/4] fix github deployment state --- appveyor.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 -- 2.40.1 From 8e152292457e657a8ac7ba76ca6fbe76a5d83c33 Mon Sep 17 00:00:00 2001 From: OCram85 Date: Thu, 23 Jan 2020 12:53:00 +0100 Subject: [PATCH 4/4] update about page based on readme.md --- docs/about_PSCredentialStore.md | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) 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 -- 2.40.1