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
 ============