From 7005c3ba1dd5cb3f611531908f242a27dd9f60a8 Mon Sep 17 00:00:00 2001 From: Govardhan Yadava Date: Tue, 25 Apr 2023 07:52:11 +0530 Subject: [PATCH 1/2] Adding READMEs --- dukpt/README.md | 138 ++++++++++ jws-jwe-decrypt/README.md | 58 ++++ jws-jwe-encrypt/README.md | 67 +++++ salesforce-automated/README.md | 469 +++++++++++++++++++++++++++++++++ ssh-ca/README.md | 154 +++++++++++ 5 files changed, 886 insertions(+) create mode 100644 dukpt/README.md create mode 100644 jws-jwe-decrypt/README.md create mode 100644 jws-jwe-encrypt/README.md create mode 100644 salesforce-automated/README.md create mode 100644 ssh-ca/README.md diff --git a/dukpt/README.md b/dukpt/README.md new file mode 100644 index 0000000..2a91259 --- /dev/null +++ b/dukpt/README.md @@ -0,0 +1,138 @@ +# Derived Unique Key Per Transaction (DUKPT) + +## Introduction +DUKPT plugin is an DSM implementation of the Derived Unique Key Per +Transaction process that's described in Annex A of ANS X9.24-2009. This module +provides DUKPT decryption using the 3DES scheme. It decrypts the encrypted card +information using the KSN and BDK-ID as inputs to the plugin and generates +decrypted/plain card information. + +Initially there is a Base Derivation Key (BDK) that is used to generate the +"Initial PIN Encryption Key" (IPEK). The BDK always stays in the HSM and is +never injected into the devices. It is known only by the manufacturer and the +merchant. The "Key Serial Number" (KSN) and IPEK are injected into each device. +The KSN is sent with the "crypt" material so that the receiving end can also +decrypt it. The last 21 bits of the KSN are a counter that gets incremented +every transaction. + +There is a single DUKPT plugin, with three supported operations: `import`, +`encrypt`, and `decrypt`. + +## Use Cases +As described above in the Introduction, the value of DUKPT is the ability to +secure many independent messages in such a way that compromising the keys for +any individual message doesn't endanger other messages while still minimizing +the number of keys that need to be stored and managed. The canonical example of +this, and the use case for which this procedure was developed, is to encrypt +payment information during transactions. + +## Setup +### Using DSM Plugins +* Plugins are an independent and secure subsystem where business logic can be + executed inside DSM. +* Plugins are invoked using a REST API similar to the cryptographic and key + management APIs. +* Plugins are identified by UUID, like apps and security objects. +* To invoke a plugin, make a POST request to `https:///sys/v1/plugins/`. + The POST request body must be either valid + JSON or empty. The exact structure is defined by the plugin. +* The request may return: + - 200 OK with a JSON response body, + - 204 No Content with empty response body, or + - a 4xx/5xx error with a plain text error message response body. + +### Invoking DSM plugins from DSM Python CLI +Check the DSM CLI README for information on setting up the CLI. + +Login to sdkms inorder to invoke plugin: + +`$ sdkms-cli user-login` + +To invoke a plugin: + +`$ sdkms-cli invoke-plugin --name dukpt --in ` + +* Plugins can either be invoked using `--name` or `--id`, taking the plugin's + name or UUID respectively. +* `in` : Path to input json file. + +## DUKPT Input/Output JSON Formats +The following sections specify the fields in the inputs and outputs of the +plugin's operations, which are JSON maps. + +### DUKPT Import Operation +#### Input +* `operation` : Must be the string `import` for importing BDKs. +* `name` : A string to be used as the name of the key in DSM. Must be unique. +* `material` : A string containing the 16 hex encoded bytes of the key material. + +#### Output +* `key_id` : The UUID of the imported key in DSM. Referred to in the other + operations as `bdk_id`. + +### DUKPT Encrypt and Decrypt +#### Input +* `operation` : Either `encrypt` or `decrypt`, for encryption and decryption + respectively. +* `bdk_id` : The UUID of the imported BDK key to use. +* `ksn` : Key serial number, hex encoded. +* `key_mode` : The method used for deriving the session key from the IPEK. + Possible values are: + - `datakey` + - `pinkey` + - `mackey` +* `card_data` : The data to be encrypted or decrypted, encoded in a string in + accordance with the encoding specified below. +* `encoding` : For the `encrypt` operation this is the encoding of the data to + be encrypted. For `decrypt`, this is the encoding that the data should be + returned in. + Possible values are: + - `base64` + - `hex` + +#### Output +* `card_data` : The result of the encryption or decryption. + +## Example Usages +### DUKPT Import +Imports a BDK into DSM for use with the other operations. + +#### Example Input +```json + { "operation": "import", + "name": "my_bdk", + "material": "0123456789ABCDEFFEDCBA9876543210" } +``` + +#### Example Output +```json + { "key_id": "d17e7c0c-3246-41c4-9824-c98d2c6515fb" } +``` + +### DUKPT Encrypt and Decrypt +Encrypts or decrypts data with a key derived from the given BDK and KSN. + +#### Example Input +Below is a sample input json to the DSM DUKPT plugin's decrypt operation. The +structure is the same for encryption, though the semantics change slightly as +described above. +```json + { "operation": "decrypt", + "bdk_id": "fd1fbe76-6d64-4d30-b351-e79449e1eb77", + "ksn": "FFFF9876543210E00008", + "key_mode": "datakey", + "card_data": "y07Fue/gKW7x9yDM06LZBg==", + "encoding": "base64" } +``` + +#### Example Output +```json + { "card_data": "Zm9ydGFuaXg=" } +``` + +## References + +* [NodeJS DUKPT implementation](https://github.com/dpjayasekara/node-dukpt) +* [C# DUKPT implementation](https://github.com/sgbj/Dukpt.NET) +* [Fortanix Self-Defending KMS developers guide plugin](https://support.fortanix.com/sdkms/developers-guide-plugin.html) +* [Fortanix Self-Defending KMS plugins API](https://support.fortanix.com/api/#/Plugins) diff --git a/jws-jwe-decrypt/README.md b/jws-jwe-decrypt/README.md new file mode 100644 index 0000000..fc0675b --- /dev/null +++ b/jws-jwe-decrypt/README.md @@ -0,0 +1,58 @@ +# JWS+JWE Decrypt + +## Introduction +This plugin performs decrypt using JWE standards: `enc: A256CBC-HS512 alg: RSA-OAEP-256`. + +It performs the following steps: + +1. It takes the JWE as input and splits it to get the parts i.e. encrypted key material, iv, ciphertext, and tag. +2. Decrypts the encrypted composite transient key using the RSA private key (provided in input), and generate AES, HMAC transient keys from the decrypted key-material. +3. Computes the `aad` from the header in the input and `al` to store the size of `aad`. +4. Using `iv` from the input, and the generated AES key, it decrypts the cipher provided in the input in `CBC` mode. We receive the plaintext after decryption, which is correct only after the verification is successful. +5. For verification, it creates an input payload for HMAC consisting of `aad, iv, cipher, al`. +6. Creates a HMAC of the payload created above using HMAC key using `SHA-512` as the hashing algorithm. +7. It truncates the digest generated above to half the length and compares it to the tag in the input. +8. If the generated digest matches the tag, then it verifies the plaintext which is a JWS. +9. It takes the JWS and splits it to get the parts i.e. header, payload, and signature. +10. From the header and payload, it re-constructs the `Jws Signing input`. +11. Decodes the signature from Base64URL to Base64, so as to use for verifying the signature. +12. Imports the `certificate` as a transient key. +13. Verifies the above constructed `Jws Signing input` and the decoded `signature` by `certificate` using `SHA-256` and mode as `PKCS1-v1_5`. +14. The plugin output is `VERIFIED` and the actual `payload` (inside the JWS) in case signature is correctly verified and `VERIFICATION FAILED` otherwise. + +## Use cases +1. Assert one’s identity, given that the recipient of the JWE trusts the asserting party. +2. Transfer data securely between interested parties over a unsecured channel. + +## Setup +1. For these plugin, we need a RSA private key already imported in DSM, and its corresponding public key as a certificate which the user should provide as input. + +## Input/Output JSON object format +Input parameters details: + +1. **`jwe`** corresponds to JWE generated by `Encrypt` plugin. +2. **`key`** is the name of `RSA` private key which should be already imported in `DSM`. This is used for decrypting the payload. +3. **`cert`** contains the contents of the certificate (`pem` file) in base64 encoding. This is used to verify the signature. + +## Example usages +Sample Input format: (The certificate value should be provided as a base-64 encoded string). +``` +{ + "jwe": "...", + "key" : "keyname", + "cert" : "..." +} +``` + +Sample output format: +``` +{ + "payload": "...", + "output": "VERIFIED" +} +``` + +## References + +1. https://tools.ietf.org/html/rfc7515 +2. https://tools.ietf.org/html/rfc7516 \ No newline at end of file diff --git a/jws-jwe-encrypt/README.md b/jws-jwe-encrypt/README.md new file mode 100644 index 0000000..0128891 --- /dev/null +++ b/jws-jwe-encrypt/README.md @@ -0,0 +1,67 @@ +# JWS+JWE Encrypt + +## Introduction +This plugin, performs encrypt using JWE standards: enc: A256CBC-HS512 alg: RSA-OAEP-256. + +This plugin performs the following steps: + +1. It generates a JWS from the `payload`. +2. Generates a header for JWS containing `alg` and `typ`, as: + ``` + {typ : "JWT", "alg" : "RS256"} + ``` +3. Encodes header and input payload to the Base64URL format. +4. Constructs the JWS Signing input by concatenating header and payload. +5. Sign the above constructed `Jws Signing input` by RSA private key (provided in input) using SHA-256 and mode as PKCS1-v1_5. +6. Encodes the signature in the Base64URL format and constructs JWS by concatenating header, payload, and signature by using `"."` as a separator. It will use this `jws` as input payload to `JWE`. +7. Generate the header for JWE, containing `alg, enc, typ`. + ``` + {alg = "RSA-OAEP-256", enc = "A256CBC-HS512", typ = "JWT"} + ``` +8. Generate an exportable `transient` `AES` key of size `256` bits and an exportable `transient` `HMAC` key of size `256` bits. +9. Encrypts the above generated JWS using the transient AES key in `CBC` mode. +10. Generate `aad` using the `header` and `al` to store the size of `aad`. +11. Creates an input payload for HMAC consisting of `aad, iv, cipher, al`. +12. Creates a HMAC of the payload created above using HMAC key using `SHA-512` as the hashing algorithm. +13. Truncate the digest generated above to half the length and use as authentication-tag. +14. Import the `certificate` as a transient key. +15. Encrypt the combined transient AES key and HMAC key with the `certificate` given as input, using `OAEP_MGF1_SHA256` as the mode and `RSA` is the algorithm. +16. Returns the header, encrypted transient key, encrypted input payload, iv (used for encrypting input payload), the authentication-tag and JWE. + +## Use cases +1. Assert one’s identity, given that the recipient of the JWE trusts the asserting party. +2. Transfer data securely between interested parties over a unsecured channel. + +## Setup +1. For these plugin, we need a RSA private key already imported in DSM, and its corresponding public key as a certificate which the user should provide as input. + +## Input/Output JSON object format +1. **`payload`** corresponds to input data, which is first signed and then encrypted. +2. **`key`** is the name of `RSA` private key which should be already imported in `DSM`. This is used for signing the payload. +3. **`cert`** contains the contents of the certificate (`pem` file) in base64 encoding. This is used to encrypt and verify the signature. + +## Example usages +Sample Input format: (The certificate value should be supplied as base64 encoded string) +``` +{ + "payload" : "hello world", + "key" : "keyname", + "cert" : "...." +} +``` + +Sample Output format: +``` + { + header : header, + encrypted_key : encrypt_trans_key, + cipher : cipher, + iv : iv, + tag : digest, + jwe : jwe, + } +``` + +## References +1. https://tools.ietf.org/html/rfc7515 +2. https://tools.ietf.org/html/rfc7516 \ No newline at end of file diff --git a/salesforce-automated/README.md b/salesforce-automated/README.md new file mode 100644 index 0000000..1798a66 --- /dev/null +++ b/salesforce-automated/README.md @@ -0,0 +1,469 @@ +# Automated BYOK for Salesforce Cloud + +## Introduction + +This plugin implements the Bring your own key (BYOK) model for Salesforce. Using this plugin, you can keep your key inside Fortanix DSM and use Shield Platform Encryption features of Salesforce. + +## Use cases + +The plugin can be used to + +- Upload a key from Fortanix Data Security Manager to Salesforce +- Search tenant secrets (Salesforce encryption keys) using Salesforce Sobject Query Language (SSQL) +- Check current status of any key or key version +- Destroy the archived keys in Salesforce +- Restore a previously destroyed key + +## Fortanix Data Security Manager Setup + +1. Log in to Fortanix Data Security Manager (https://sdkms.fortanix.com) +2. Create an account in Fortanix Data Security Manager +3. Create a group in Fortanix Data Security Manager +4. Create a plugin in Fortanix Data Security Manager + +## Configure Salesforce + +1. Create a New Profile under Setup >> Profiles. + Note: Select “Manage Encryption Keys” under “Administrative Permissions" +2. Create a New User under Setup >> Users with these inputs – + Name: arbitrarily input + Profiles: choose the KMS role created in previous step + Note the credentials to securely import into Data Security Manager secret +3. Create a Connected App under “Apps >> App Manager” with the following inputs – + Label: arbitrarily input + Check the “Enable OAuth Settings” + Check the “Enable Device Flow” for automated access + Note the credentials to securely import into Data Security Manager secret +4. Whitelist the Fortanix Data Security Manager application IP range (CIDR) +5. Create a Certificate under “Setup >> Certificate and Key Management” – + Label: arbitrarily input, but note it for later use + Uncheck the “Exportable Private Key” + Check the option to "Use Platform Encryption" +6. Verify the Salesforce credentials + Client/Consumer Key (Created in step 3) + Client/Consumer Secret (Created in step 3) + OAuth username (Created in step 2) + OAuth password (Created in step 2) + Tenant URI + API version (Fortanix Plugin tested against version 50.0) + +## Input/Output JSON object format + +### Configure operation + +This operation configures Salesforce credentials in Fortanix Data Security Manager and returns a UUID. You need to pass this UUID for other operations. This is a one time process. + +### parameters + +* `operation`: The operation which you want to perform. A valid value is `configure`. +* `consumer_key`: Consumer Key of the connected app +* `consumer_secret`: Consumer Secret of the connected app +* `username`: OAuth username +* `password`: OAuth password +* `tenant`: Salesforce tenant URI +* `version`: API version (Fortanix Plugin tested against version 50.0) +* `name`: Name of the sobject. This sobject will be created in fortanix Data Security Manager and will have Salesforce credential information + +#### Example + +Input JSON +``` +{ + "operation": "configure", + "consumer_key": "CBK...................D", + "consumer_secret": "DMV................D", + "username" : "ft......x@", + "password" : "fy....K", + "tenant" : "", + "version" : "v50.0", + "name" : "Salesforce NamedCred Dev" +} +``` +Output +``` +"3968218b-72c3-4ada-922a-8a917323f27d" +``` + + +### Check operation + +This operation is to test whether plugin can import wrapping certificate from salesforce into Fortanix Data Security Manager. (This certificate is required by plugin to authenticate itself to salesforce) + +### parameters + +* `operation`: The operation which you want to perform. A valid value is `check` +* `secret_id`: The response of `configuration` operation +* `wrapper`: Name of the wrapping certificate in salesforce + +#### Example + +Input JSON +``` +{ + "operation": "check", + "secret_id": "3968218b-72c3-4ada-922a-8a917323f27d", + "wrapper" : "SFBYOK_FTX_Wrapper" +} +``` +Output JSON +``` +{ + "group_id": "ff2............................c", + "public_only": true, + "key_ops": [ + "VERIFY", + "ENCRYPT", + "WRAPKEY", + "EXPORT" + ], + "enabled": true, + "rsa": { + "signature_policy": [ + { + "padding": null + } + ], + "encryption_policy": [ + { + "padding": { + "OAEP": { + "mgf": null + } + } + } + ], + "key_size": 4096 + }, + "state": "Active", + "created_at": "20201229T183553Z", + "key_size": 4096, + "kid": "6de........................4", + "origin": "External", + "lastused_at": "19700101T000000Z", + "obj_type": "CERTIFICATE", + "name": "SFBYOK_FTX_Wrapper", + "acct_id": "ec9.......................7", + "compliant_with_policies": true, + "creator": { + "plugin": "654.......................1" + }, + "value": "MII........................9", + "activation_date": "20201229T183553Z", + "pub_key": "MII......................8", + "never_exportable": false +} +``` + + +### Query operation + +This operation allows you to search tenant secrets (Salesforce encryption keys) using Salesforce Sobject Query Language (SSQL) + +### parameters + +* `operation`: The operation which you want to perform. A valid value is `query` or `search` +* `secret_id`: The response of `configuration` operation +* `query`: SSQL query +* `tooling`: +* `sandbox`: To indicate, whether to use test or production tenant. + +#### Example + +Input JSON +``` +{ + "operation": "search", + "secret_id": "3968218b-72c3-4ada-922a-8a917323f27d", + "query" : "select Id, Status, Version from TenantSecret where Type = `Data`", + "tooling" : false, + "sandbox" : false +} +``` +Output JSON +``` +{ + "done": true, + "totalSize": 5, + "records": [ + { + "attributes": { + "type": "TenantSecret", + "url": "/services/data/v50.0/sobjects/TenantSecret/02G..........O" + }, + "Status": "ARCHIVED", + "Id": "02G.............D", + "Version": 3 + }, + { + "Version": 1, + "attributes": { + "url": "/services/data/v50.0/sobjects/TenantSecret/02G...........W", + "type": "TenantSecret" + }, + "Id": "02G...........W", + "Status": "ARCHIVED" + }, + { + "Version": 2, + "Id": "02G..........O", + "attributes": { + "type": "TenantSecret", + "url": "/services/data/v50.0/sobjects/TenantSecret/02G............O" + }, + "Status": "ARCHIVED" + }, + { + "Id": "02G...........4", + "attributes": { + "url": "/services/data/v50.0/sobjects/TenantSecret/02G...........4", + "type": "TenantSecret" + }, + "Version": 4, + "Status": "DESTROYED" + }, + { + "attributes": { + "type": "TenantSecret", + "url": "/services/data/v50.0/sobjects/TenantSecret/02G............O" + }, + "Id": "02G..........O", + "Version": 5, + "Status": "ACTIVE" + } + ] +} +``` + +### Upload operation + +This operation allows you to create a key material in Fortanix Data Security Manager and upload to salesforce + +### parameters + +* `operation`: The operation which you want to perform. A valid value is `upload`. +* `secret_id`: The response of `configuration` operation +* `wrapper`: Name of the wrapping certificate in salesforce +* `type`: A valid values are `Data|EventBus|SearchIndex` +* `mode`: Key derivation mode. It can be blank which defaults to “PBKDF2” or can also be "NONE" to disable key derivation in Salesforce. +* `name`: Prefix of the name +* `sandbox`: To indicate, whether to use test or production tenant. + +#### Example + +Input JSON +``` +{ + "operation": "upload", + "secret_id": "3968218b-72c3-4ada-922a-8a917323f27d", + "wrapper" : "SFBYOK_FTX_Wrapper", + "type" : "Data", + "mode" : "", + "name" : "Salesforce Data Key", + "sandbox" : false +} + +``` +Output JSON +``` +{ + "obj_type": "AES", + "custom_metadata": { + "SF_HASH": "ESP.......................=", + "SF_UPLOAD": "EDF.....................=", + "SF_WRAPPER": "SFBYOK_FTX_Wrapper", + "SF_MODE": "", + "SF_KID": "02G...........O", + "SF_TYPE": "Data" + }, + "acct_id": "ec9...................7", + "creator": { + "plugin": "654....................1" + }, + "public_only": false, + "origin": "Transient", + "kid": "bb7................3", + "lastused_at": "19700101T000000Z", + "activation_date": "20201229T185549Z", + "key_size": 256, + "kcv": "b5...9", + "name": "Salesforce Data Key 20201229T185546Z", + "state": "Active", + "enabled": true, + "key_ops": [ + "EXPORT" + ], + "compliant_with_policies": true, + "created_at": "20201229T185549Z", + "aes": { + "tag_length": null, + "key_sizes": null, + "random_iv": null, + "fpe": null, + "iv_length": null, + "cipher_mode": null + }, + "never_exportable": false, + "group_id": "ff2..............b" +} +``` + +### status operation + +This operation allows you to obtain current status of a salesforce key + +### parameters + +* `operation`: The operation which you want to perform. A valid value is `status`. +* `secret_id`: The response of `configuration` operation +* `wrapper`: Name of the wrapping certificate in salesforce +* `name`: "name of corresponding sobject in Fortanix Data Security Manager" +* `sandbox`: To indicate, whether to use test or production tenant. + +#### Example + +Input JSON +``` +{ + "operation" : "status", + "secret_id": "3968218b-72c3-4ada-922a-8a917323f27d", + "wrapper" : "SFBYOK_FTX_Wrapper", + "name" : "Salesforce Data Key 20201229T185546Z", + "sandbox" : false +} +``` +Output JSON +``` +{ + "RemoteKeyIdentifier": null, + "CreatedDate": "2020-12-29T18:55:49.000+0000", + "SecretValueHash": "ESP........................=", + "CreatedById": "005..........2", + "KeyDerivationMode": "PBKDF2", + "attributes": { + "url": "/services/data/v50.0/sobjects/TenantSecret/02G..........O", + "type": "TenantSecret" + }, + "LastModifiedDate": "2020-12-29T18:55:49.000+0000", + "IsDeleted": false, + "SecretValue": "CgM.............................=", + "SecretValueCertificate": null, + "Type": "Data", + "RemoteKeyServiceId": null, + "Version": 6, + "Id": "02G..........O", + "Status": "ACTIVE", + "SystemModstamp": "2020-12-29T18:55:49.000+0000", + "RemoteKeyCertificate": null, + "Source": "UPLOADED", + "Description": "Salesforce Data Key 20201229T185546Z", + "LastModifiedById": "005............2" +} +``` +### sync operation + +This operation allows you to sync Fortanix self-Defending key object with salesforce key. + +### parameters + +* `operation`: The operation which you want to perform. A valid value is `sync`. +* `secret_id`: The response of `configuration` operation +* `wrapper`: Name of the wrapping certificate in salesforce +* `name`: "name of corresponding sobject in Fortanix Data Security Manager" +* `sandbox`: To indicate, whether to use test or production tenant. + +#### Example + +Input JSON +``` +{ + "operation" : "sync", + "secret_id": "3968218b-72c3-4ada-922a-8a917323f27d", + "wrapper" : "SFBYOK_FTX_Wrapper", + "name" : "Salesforce Data Key 20201229T185546Z", + "sandbox" : false +} +``` +Output JSON +``` +{ + "RemoteKeyCertificate": null, + "IsDeleted": false, + "CreatedById": "005..............2", + "Status": "ACTIVE", + "Type": "Data", + "LastModifiedById": "005............2", + "CreatedDate": "2020-12-29T18:55:49.000+0000", + "SystemModstamp": "2020-12-29T18:55:49.000+0000", + "Source": "UPLOADED", + "SecretValueHash": "ESP.................c", + "LastModifiedDate": "2020-12-29T18:55:49.000+0000", + "Version": 6, + "RemoteKeyServiceId": null, + "RemoteKeyIdentifier": null, + "attributes": { + "type": "TenantSecret", + "url": "/services/data/v50.0/sobjects/TenantSecret/02G............O" + }, + "KeyDerivationMode": "PBKDF2", + "Id": "02G...........O", + "SecretValueCertificate": null, + "Description": "Salesforce Data Key 20201229T185546Z", + "SecretValue": "CgM........................M" +} +``` +### destroy operation + +This operation allows you to destroy an archived salesforce key. + +### parameters + +* `operation`: The operation which you want to perform. A valid value is `destroy`. +* `secret_id`: The response of `configuration` operation +* `wrapper`: Name of the wrapping certificate in salesforce +* `name`: "name of corresponding sobject in Fortanix Data Security Manager" +* `sandbox`: To indicate, whether to use test or production tenant. + +#### Example + +Input JSON +``` +{ + "operation" : "destroy", + "secret_id": "3968218b-72c3-4ada-922a-8a917323f27d", + "wrapper" : "SFBYOK_FTX_Wrapper", + "name" : "Salesforce Data Key 20201229T185546Z", + "sandbox" : false +} +``` +Output +``` +output is empty, with http status indicating success. +``` +### restore operation + +This operation allows you to restore a destroyed salesforce key. + +### parameters + +* `operation`: The operation which you want to perform. A valid value is `restore`. +* `secret_id`: The response of `configuration` operation +* `wrapper`: Name of the wrapping certificate in salesforce +* `name`: "name of corresponding sobject in Fortanix Data Security Manager" +* `sandbox`: To indicate, whether to use test or production tenant. + +#### Example + +Input JSON +``` +{ + "operation" : "restore", + "secret_id": "3968218b-72c3-4ada-922a-8a917323f27d", + "wrapper" : "SFBYOK_FTX_Wrapper", + "name" : "Salesforce Data Key 20201229T185546Z", + "sandbox" : false +} +``` +Output +``` +output is empty, with http status indicating success. +``` diff --git a/ssh-ca/README.md b/ssh-ca/README.md new file mode 100644 index 0000000..0c133e4 --- /dev/null +++ b/ssh-ca/README.md @@ -0,0 +1,154 @@ +# SSH CA + +## Introduction + +SSH certificates are a method for authenticating users and/or servers in the SSH protocol. +Instead of bare public keys (the usual method of SSH authentication) an authority +issues a certificate which can then be used to authenticate to an SSH server. +SSH certificates were originally added to OpenSSH in version 5.6 (released in 2010). + +## Use Cases + +Authenticate clients to servers or servers to clients using an trusted third party +hosted on DSM. + +## Setup + +### Creating CA key with DSM + +The initial step is to create a key for the SSH CA. Generate an RSA +key with suitable parameters on DSM, and then download the public key. + +Converting the public to the OpenSSH format requires a two-step process. +First, use OpenSSL to convert the RSA key to "RSAPublicKey" format: + +`$ openssl rsa -pubin -RSAPublicKey_out -in sdkms_rsa.pub > sdkms_rsa_conv.pem` + +Then use `ssh-keygen` to convert this to the SSH format + +`$ ssh-keygen -m PEM -i -f sdkms_rsa_conv.pem > ssh_ca.pub` + +### Creating CA key with OpenSSH + +Alternatively, the key can be created on a trusted machine using OpenSSH +tools, then transferred to DSM: + +`$ ssh-keygen -f ssh_ca` + +This will create two files, `ssh_ca.pub` (public key in SSH format) +and `ssh_ca` (private key in PKCS #8 format). + +``` +-----BEGIN RSA PRIVATE KEY----- +MIIEpAI... +-----END RSA PRIVATE KEY----- +``` + +To import the SSH private key in DSM, copy the base64 encoded block +(but *not* the PEM headers starting with "-----") and paste it into +the Security Object import field. Make sure Sign and Verify operations +are enabled. Disable Export unless required. + +### Server Configuration + +Set up sshd configuration for accepting SSH certificates. In your `sshd_config` add + +`TrustedUserCAKeys /path/to/ssh_ca.pub` + +and restart `sshd` + +### Issue Client Cert + +Generate an RSA key pair that the user will use: + +`ssh-keygen -f ~/.ssh/user_key` + +This will again generate two keys, `user_key` (PKCS#8 private key) and +`user_key.pub` (the SSH format public key). The `user_key.pub` should look like + +`ssh-rsa AAAAB3 username@hostname` + +## Input/Output JSON + +``` +{ +"cert_lifetime":, +"valid_principals":"", +"cert_type":"user", +"ca_key":"", +"extensions":{}, +"critical_extensions":{}, +"pubkey":"" +} +``` + +"`cert_lifetime`" specifies the lifetime of the certificate in seconds. + +"`valid_principals`" specifies what username this certificate can be used for. + +"`cert_type`" can be "user" or "server". + +"`ca_key`" gives the name of the private key that was used when the RSA key was +imported into DSM earlier. + +"`extensions`" specifies operations the certificate can be used for. Values +OpenSSH supports include "`permit-X11-forwarding`", "`permit-agent-forwarding`" +"`permit-port-forwarding`", "`permit-pty`", and "`permit-user-rc`". In theory, +extensions can take values, but all currently defined extensions use an empty +string. Unknown values will be ignored by the server. + +"`critical_extensions`" specifies operations which if the server does not +understand the value, then the login attempt will be rejected. The values OpenSSH +supports are "`force-command`" and "`source-address`". "`force-command`" specifies a +single command which the certificate can be used for. "`source-address`" gives a +list of host/mask pairs, login is only allowed from an IP matching one of the +listed values. + +"`pubkey`" gives the contents of the `user_key.pub` file with the leading "`ssh-rsa `" and +trailing "` username@hostname`" removed. + +## Example Usage + +``` +{ +"cert_lifetime":86400, +"valid_principals":"desired_username", +"cert_type":"user", +"ca_key":"SSH CA Key", +"extensions":{"permit-pty":""}, +"critical_extensions":{"source-address":"10.2.0.0/16,127.0.0.1"}, +"pubkey":"AAAAB3"} +} +``` + +When the plugin is invoked it will return a string that looks like + +`"ssh-rsa-cert-v01@openssh.com AAAAHHNza...."` + +Copy the entire contents to `~/.ssh/user_key-cert.pub` + +Now test the output using `ssh-keygen`: + +``` +$ ssh-keygen -L -f user_key-cert.pub +user_key-cert.pub: + Type: ssh-rsa-cert-v01@openssh.com user certificate +... +``` + +Now run + +`$ ssh -i ~/.ssh/user_key server_host whoami` + +The login should succeed with the command executed on the remote host. + +If you use `-v` option when using a certificate you should see something like + +``` +debug1: Offering public key: RSA-CERT SHA256:Hcb9trzeAptUdTgqWj9VEncbkAGOpAglGnUrYGq4/Vo user_key +debug1: Server accepts key: pkalg ssh-rsa-cert-v01@openssh.com blen 1029 +``` + +## References + +[Annotation of src/usr.bin/ssh/PROTOCOL.certkeys, Revision HEAD](https://cvsweb.openbsd.org/src/usr.bin/ssh/PROTOCOL.certkeys?annotate=HEAD) \ No newline at end of file From 8aed3c1abc1bff199c20b4e7ccf62e71479b2d1f Mon Sep 17 00:00:00 2001 From: Govardhan Yadava Date: Tue, 25 Apr 2023 14:38:07 +0530 Subject: [PATCH 2/2] Revert "Adding READMEs" This reverts commit 7005c3ba1dd5cb3f611531908f242a27dd9f60a8. --- dukpt/README.md | 138 ---------- jws-jwe-decrypt/README.md | 58 ---- jws-jwe-encrypt/README.md | 67 ----- salesforce-automated/README.md | 469 --------------------------------- ssh-ca/README.md | 154 ----------- 5 files changed, 886 deletions(-) delete mode 100644 dukpt/README.md delete mode 100644 jws-jwe-decrypt/README.md delete mode 100644 jws-jwe-encrypt/README.md delete mode 100644 salesforce-automated/README.md delete mode 100644 ssh-ca/README.md diff --git a/dukpt/README.md b/dukpt/README.md deleted file mode 100644 index 2a91259..0000000 --- a/dukpt/README.md +++ /dev/null @@ -1,138 +0,0 @@ -# Derived Unique Key Per Transaction (DUKPT) - -## Introduction -DUKPT plugin is an DSM implementation of the Derived Unique Key Per -Transaction process that's described in Annex A of ANS X9.24-2009. This module -provides DUKPT decryption using the 3DES scheme. It decrypts the encrypted card -information using the KSN and BDK-ID as inputs to the plugin and generates -decrypted/plain card information. - -Initially there is a Base Derivation Key (BDK) that is used to generate the -"Initial PIN Encryption Key" (IPEK). The BDK always stays in the HSM and is -never injected into the devices. It is known only by the manufacturer and the -merchant. The "Key Serial Number" (KSN) and IPEK are injected into each device. -The KSN is sent with the "crypt" material so that the receiving end can also -decrypt it. The last 21 bits of the KSN are a counter that gets incremented -every transaction. - -There is a single DUKPT plugin, with three supported operations: `import`, -`encrypt`, and `decrypt`. - -## Use Cases -As described above in the Introduction, the value of DUKPT is the ability to -secure many independent messages in such a way that compromising the keys for -any individual message doesn't endanger other messages while still minimizing -the number of keys that need to be stored and managed. The canonical example of -this, and the use case for which this procedure was developed, is to encrypt -payment information during transactions. - -## Setup -### Using DSM Plugins -* Plugins are an independent and secure subsystem where business logic can be - executed inside DSM. -* Plugins are invoked using a REST API similar to the cryptographic and key - management APIs. -* Plugins are identified by UUID, like apps and security objects. -* To invoke a plugin, make a POST request to `https:///sys/v1/plugins/`. - The POST request body must be either valid - JSON or empty. The exact structure is defined by the plugin. -* The request may return: - - 200 OK with a JSON response body, - - 204 No Content with empty response body, or - - a 4xx/5xx error with a plain text error message response body. - -### Invoking DSM plugins from DSM Python CLI -Check the DSM CLI README for information on setting up the CLI. - -Login to sdkms inorder to invoke plugin: - -`$ sdkms-cli user-login` - -To invoke a plugin: - -`$ sdkms-cli invoke-plugin --name dukpt --in ` - -* Plugins can either be invoked using `--name` or `--id`, taking the plugin's - name or UUID respectively. -* `in` : Path to input json file. - -## DUKPT Input/Output JSON Formats -The following sections specify the fields in the inputs and outputs of the -plugin's operations, which are JSON maps. - -### DUKPT Import Operation -#### Input -* `operation` : Must be the string `import` for importing BDKs. -* `name` : A string to be used as the name of the key in DSM. Must be unique. -* `material` : A string containing the 16 hex encoded bytes of the key material. - -#### Output -* `key_id` : The UUID of the imported key in DSM. Referred to in the other - operations as `bdk_id`. - -### DUKPT Encrypt and Decrypt -#### Input -* `operation` : Either `encrypt` or `decrypt`, for encryption and decryption - respectively. -* `bdk_id` : The UUID of the imported BDK key to use. -* `ksn` : Key serial number, hex encoded. -* `key_mode` : The method used for deriving the session key from the IPEK. - Possible values are: - - `datakey` - - `pinkey` - - `mackey` -* `card_data` : The data to be encrypted or decrypted, encoded in a string in - accordance with the encoding specified below. -* `encoding` : For the `encrypt` operation this is the encoding of the data to - be encrypted. For `decrypt`, this is the encoding that the data should be - returned in. - Possible values are: - - `base64` - - `hex` - -#### Output -* `card_data` : The result of the encryption or decryption. - -## Example Usages -### DUKPT Import -Imports a BDK into DSM for use with the other operations. - -#### Example Input -```json - { "operation": "import", - "name": "my_bdk", - "material": "0123456789ABCDEFFEDCBA9876543210" } -``` - -#### Example Output -```json - { "key_id": "d17e7c0c-3246-41c4-9824-c98d2c6515fb" } -``` - -### DUKPT Encrypt and Decrypt -Encrypts or decrypts data with a key derived from the given BDK and KSN. - -#### Example Input -Below is a sample input json to the DSM DUKPT plugin's decrypt operation. The -structure is the same for encryption, though the semantics change slightly as -described above. -```json - { "operation": "decrypt", - "bdk_id": "fd1fbe76-6d64-4d30-b351-e79449e1eb77", - "ksn": "FFFF9876543210E00008", - "key_mode": "datakey", - "card_data": "y07Fue/gKW7x9yDM06LZBg==", - "encoding": "base64" } -``` - -#### Example Output -```json - { "card_data": "Zm9ydGFuaXg=" } -``` - -## References - -* [NodeJS DUKPT implementation](https://github.com/dpjayasekara/node-dukpt) -* [C# DUKPT implementation](https://github.com/sgbj/Dukpt.NET) -* [Fortanix Self-Defending KMS developers guide plugin](https://support.fortanix.com/sdkms/developers-guide-plugin.html) -* [Fortanix Self-Defending KMS plugins API](https://support.fortanix.com/api/#/Plugins) diff --git a/jws-jwe-decrypt/README.md b/jws-jwe-decrypt/README.md deleted file mode 100644 index fc0675b..0000000 --- a/jws-jwe-decrypt/README.md +++ /dev/null @@ -1,58 +0,0 @@ -# JWS+JWE Decrypt - -## Introduction -This plugin performs decrypt using JWE standards: `enc: A256CBC-HS512 alg: RSA-OAEP-256`. - -It performs the following steps: - -1. It takes the JWE as input and splits it to get the parts i.e. encrypted key material, iv, ciphertext, and tag. -2. Decrypts the encrypted composite transient key using the RSA private key (provided in input), and generate AES, HMAC transient keys from the decrypted key-material. -3. Computes the `aad` from the header in the input and `al` to store the size of `aad`. -4. Using `iv` from the input, and the generated AES key, it decrypts the cipher provided in the input in `CBC` mode. We receive the plaintext after decryption, which is correct only after the verification is successful. -5. For verification, it creates an input payload for HMAC consisting of `aad, iv, cipher, al`. -6. Creates a HMAC of the payload created above using HMAC key using `SHA-512` as the hashing algorithm. -7. It truncates the digest generated above to half the length and compares it to the tag in the input. -8. If the generated digest matches the tag, then it verifies the plaintext which is a JWS. -9. It takes the JWS and splits it to get the parts i.e. header, payload, and signature. -10. From the header and payload, it re-constructs the `Jws Signing input`. -11. Decodes the signature from Base64URL to Base64, so as to use for verifying the signature. -12. Imports the `certificate` as a transient key. -13. Verifies the above constructed `Jws Signing input` and the decoded `signature` by `certificate` using `SHA-256` and mode as `PKCS1-v1_5`. -14. The plugin output is `VERIFIED` and the actual `payload` (inside the JWS) in case signature is correctly verified and `VERIFICATION FAILED` otherwise. - -## Use cases -1. Assert one’s identity, given that the recipient of the JWE trusts the asserting party. -2. Transfer data securely between interested parties over a unsecured channel. - -## Setup -1. For these plugin, we need a RSA private key already imported in DSM, and its corresponding public key as a certificate which the user should provide as input. - -## Input/Output JSON object format -Input parameters details: - -1. **`jwe`** corresponds to JWE generated by `Encrypt` plugin. -2. **`key`** is the name of `RSA` private key which should be already imported in `DSM`. This is used for decrypting the payload. -3. **`cert`** contains the contents of the certificate (`pem` file) in base64 encoding. This is used to verify the signature. - -## Example usages -Sample Input format: (The certificate value should be provided as a base-64 encoded string). -``` -{ - "jwe": "...", - "key" : "keyname", - "cert" : "..." -} -``` - -Sample output format: -``` -{ - "payload": "...", - "output": "VERIFIED" -} -``` - -## References - -1. https://tools.ietf.org/html/rfc7515 -2. https://tools.ietf.org/html/rfc7516 \ No newline at end of file diff --git a/jws-jwe-encrypt/README.md b/jws-jwe-encrypt/README.md deleted file mode 100644 index 0128891..0000000 --- a/jws-jwe-encrypt/README.md +++ /dev/null @@ -1,67 +0,0 @@ -# JWS+JWE Encrypt - -## Introduction -This plugin, performs encrypt using JWE standards: enc: A256CBC-HS512 alg: RSA-OAEP-256. - -This plugin performs the following steps: - -1. It generates a JWS from the `payload`. -2. Generates a header for JWS containing `alg` and `typ`, as: - ``` - {typ : "JWT", "alg" : "RS256"} - ``` -3. Encodes header and input payload to the Base64URL format. -4. Constructs the JWS Signing input by concatenating header and payload. -5. Sign the above constructed `Jws Signing input` by RSA private key (provided in input) using SHA-256 and mode as PKCS1-v1_5. -6. Encodes the signature in the Base64URL format and constructs JWS by concatenating header, payload, and signature by using `"."` as a separator. It will use this `jws` as input payload to `JWE`. -7. Generate the header for JWE, containing `alg, enc, typ`. - ``` - {alg = "RSA-OAEP-256", enc = "A256CBC-HS512", typ = "JWT"} - ``` -8. Generate an exportable `transient` `AES` key of size `256` bits and an exportable `transient` `HMAC` key of size `256` bits. -9. Encrypts the above generated JWS using the transient AES key in `CBC` mode. -10. Generate `aad` using the `header` and `al` to store the size of `aad`. -11. Creates an input payload for HMAC consisting of `aad, iv, cipher, al`. -12. Creates a HMAC of the payload created above using HMAC key using `SHA-512` as the hashing algorithm. -13. Truncate the digest generated above to half the length and use as authentication-tag. -14. Import the `certificate` as a transient key. -15. Encrypt the combined transient AES key and HMAC key with the `certificate` given as input, using `OAEP_MGF1_SHA256` as the mode and `RSA` is the algorithm. -16. Returns the header, encrypted transient key, encrypted input payload, iv (used for encrypting input payload), the authentication-tag and JWE. - -## Use cases -1. Assert one’s identity, given that the recipient of the JWE trusts the asserting party. -2. Transfer data securely between interested parties over a unsecured channel. - -## Setup -1. For these plugin, we need a RSA private key already imported in DSM, and its corresponding public key as a certificate which the user should provide as input. - -## Input/Output JSON object format -1. **`payload`** corresponds to input data, which is first signed and then encrypted. -2. **`key`** is the name of `RSA` private key which should be already imported in `DSM`. This is used for signing the payload. -3. **`cert`** contains the contents of the certificate (`pem` file) in base64 encoding. This is used to encrypt and verify the signature. - -## Example usages -Sample Input format: (The certificate value should be supplied as base64 encoded string) -``` -{ - "payload" : "hello world", - "key" : "keyname", - "cert" : "...." -} -``` - -Sample Output format: -``` - { - header : header, - encrypted_key : encrypt_trans_key, - cipher : cipher, - iv : iv, - tag : digest, - jwe : jwe, - } -``` - -## References -1. https://tools.ietf.org/html/rfc7515 -2. https://tools.ietf.org/html/rfc7516 \ No newline at end of file diff --git a/salesforce-automated/README.md b/salesforce-automated/README.md deleted file mode 100644 index 1798a66..0000000 --- a/salesforce-automated/README.md +++ /dev/null @@ -1,469 +0,0 @@ -# Automated BYOK for Salesforce Cloud - -## Introduction - -This plugin implements the Bring your own key (BYOK) model for Salesforce. Using this plugin, you can keep your key inside Fortanix DSM and use Shield Platform Encryption features of Salesforce. - -## Use cases - -The plugin can be used to - -- Upload a key from Fortanix Data Security Manager to Salesforce -- Search tenant secrets (Salesforce encryption keys) using Salesforce Sobject Query Language (SSQL) -- Check current status of any key or key version -- Destroy the archived keys in Salesforce -- Restore a previously destroyed key - -## Fortanix Data Security Manager Setup - -1. Log in to Fortanix Data Security Manager (https://sdkms.fortanix.com) -2. Create an account in Fortanix Data Security Manager -3. Create a group in Fortanix Data Security Manager -4. Create a plugin in Fortanix Data Security Manager - -## Configure Salesforce - -1. Create a New Profile under Setup >> Profiles. - Note: Select “Manage Encryption Keys” under “Administrative Permissions" -2. Create a New User under Setup >> Users with these inputs – - Name: arbitrarily input - Profiles: choose the KMS role created in previous step - Note the credentials to securely import into Data Security Manager secret -3. Create a Connected App under “Apps >> App Manager” with the following inputs – - Label: arbitrarily input - Check the “Enable OAuth Settings” - Check the “Enable Device Flow” for automated access - Note the credentials to securely import into Data Security Manager secret -4. Whitelist the Fortanix Data Security Manager application IP range (CIDR) -5. Create a Certificate under “Setup >> Certificate and Key Management” – - Label: arbitrarily input, but note it for later use - Uncheck the “Exportable Private Key” - Check the option to "Use Platform Encryption" -6. Verify the Salesforce credentials - Client/Consumer Key (Created in step 3) - Client/Consumer Secret (Created in step 3) - OAuth username (Created in step 2) - OAuth password (Created in step 2) - Tenant URI - API version (Fortanix Plugin tested against version 50.0) - -## Input/Output JSON object format - -### Configure operation - -This operation configures Salesforce credentials in Fortanix Data Security Manager and returns a UUID. You need to pass this UUID for other operations. This is a one time process. - -### parameters - -* `operation`: The operation which you want to perform. A valid value is `configure`. -* `consumer_key`: Consumer Key of the connected app -* `consumer_secret`: Consumer Secret of the connected app -* `username`: OAuth username -* `password`: OAuth password -* `tenant`: Salesforce tenant URI -* `version`: API version (Fortanix Plugin tested against version 50.0) -* `name`: Name of the sobject. This sobject will be created in fortanix Data Security Manager and will have Salesforce credential information - -#### Example - -Input JSON -``` -{ - "operation": "configure", - "consumer_key": "CBK...................D", - "consumer_secret": "DMV................D", - "username" : "ft......x@", - "password" : "fy....K", - "tenant" : "", - "version" : "v50.0", - "name" : "Salesforce NamedCred Dev" -} -``` -Output -``` -"3968218b-72c3-4ada-922a-8a917323f27d" -``` - - -### Check operation - -This operation is to test whether plugin can import wrapping certificate from salesforce into Fortanix Data Security Manager. (This certificate is required by plugin to authenticate itself to salesforce) - -### parameters - -* `operation`: The operation which you want to perform. A valid value is `check` -* `secret_id`: The response of `configuration` operation -* `wrapper`: Name of the wrapping certificate in salesforce - -#### Example - -Input JSON -``` -{ - "operation": "check", - "secret_id": "3968218b-72c3-4ada-922a-8a917323f27d", - "wrapper" : "SFBYOK_FTX_Wrapper" -} -``` -Output JSON -``` -{ - "group_id": "ff2............................c", - "public_only": true, - "key_ops": [ - "VERIFY", - "ENCRYPT", - "WRAPKEY", - "EXPORT" - ], - "enabled": true, - "rsa": { - "signature_policy": [ - { - "padding": null - } - ], - "encryption_policy": [ - { - "padding": { - "OAEP": { - "mgf": null - } - } - } - ], - "key_size": 4096 - }, - "state": "Active", - "created_at": "20201229T183553Z", - "key_size": 4096, - "kid": "6de........................4", - "origin": "External", - "lastused_at": "19700101T000000Z", - "obj_type": "CERTIFICATE", - "name": "SFBYOK_FTX_Wrapper", - "acct_id": "ec9.......................7", - "compliant_with_policies": true, - "creator": { - "plugin": "654.......................1" - }, - "value": "MII........................9", - "activation_date": "20201229T183553Z", - "pub_key": "MII......................8", - "never_exportable": false -} -``` - - -### Query operation - -This operation allows you to search tenant secrets (Salesforce encryption keys) using Salesforce Sobject Query Language (SSQL) - -### parameters - -* `operation`: The operation which you want to perform. A valid value is `query` or `search` -* `secret_id`: The response of `configuration` operation -* `query`: SSQL query -* `tooling`: -* `sandbox`: To indicate, whether to use test or production tenant. - -#### Example - -Input JSON -``` -{ - "operation": "search", - "secret_id": "3968218b-72c3-4ada-922a-8a917323f27d", - "query" : "select Id, Status, Version from TenantSecret where Type = `Data`", - "tooling" : false, - "sandbox" : false -} -``` -Output JSON -``` -{ - "done": true, - "totalSize": 5, - "records": [ - { - "attributes": { - "type": "TenantSecret", - "url": "/services/data/v50.0/sobjects/TenantSecret/02G..........O" - }, - "Status": "ARCHIVED", - "Id": "02G.............D", - "Version": 3 - }, - { - "Version": 1, - "attributes": { - "url": "/services/data/v50.0/sobjects/TenantSecret/02G...........W", - "type": "TenantSecret" - }, - "Id": "02G...........W", - "Status": "ARCHIVED" - }, - { - "Version": 2, - "Id": "02G..........O", - "attributes": { - "type": "TenantSecret", - "url": "/services/data/v50.0/sobjects/TenantSecret/02G............O" - }, - "Status": "ARCHIVED" - }, - { - "Id": "02G...........4", - "attributes": { - "url": "/services/data/v50.0/sobjects/TenantSecret/02G...........4", - "type": "TenantSecret" - }, - "Version": 4, - "Status": "DESTROYED" - }, - { - "attributes": { - "type": "TenantSecret", - "url": "/services/data/v50.0/sobjects/TenantSecret/02G............O" - }, - "Id": "02G..........O", - "Version": 5, - "Status": "ACTIVE" - } - ] -} -``` - -### Upload operation - -This operation allows you to create a key material in Fortanix Data Security Manager and upload to salesforce - -### parameters - -* `operation`: The operation which you want to perform. A valid value is `upload`. -* `secret_id`: The response of `configuration` operation -* `wrapper`: Name of the wrapping certificate in salesforce -* `type`: A valid values are `Data|EventBus|SearchIndex` -* `mode`: Key derivation mode. It can be blank which defaults to “PBKDF2” or can also be "NONE" to disable key derivation in Salesforce. -* `name`: Prefix of the name -* `sandbox`: To indicate, whether to use test or production tenant. - -#### Example - -Input JSON -``` -{ - "operation": "upload", - "secret_id": "3968218b-72c3-4ada-922a-8a917323f27d", - "wrapper" : "SFBYOK_FTX_Wrapper", - "type" : "Data", - "mode" : "", - "name" : "Salesforce Data Key", - "sandbox" : false -} - -``` -Output JSON -``` -{ - "obj_type": "AES", - "custom_metadata": { - "SF_HASH": "ESP.......................=", - "SF_UPLOAD": "EDF.....................=", - "SF_WRAPPER": "SFBYOK_FTX_Wrapper", - "SF_MODE": "", - "SF_KID": "02G...........O", - "SF_TYPE": "Data" - }, - "acct_id": "ec9...................7", - "creator": { - "plugin": "654....................1" - }, - "public_only": false, - "origin": "Transient", - "kid": "bb7................3", - "lastused_at": "19700101T000000Z", - "activation_date": "20201229T185549Z", - "key_size": 256, - "kcv": "b5...9", - "name": "Salesforce Data Key 20201229T185546Z", - "state": "Active", - "enabled": true, - "key_ops": [ - "EXPORT" - ], - "compliant_with_policies": true, - "created_at": "20201229T185549Z", - "aes": { - "tag_length": null, - "key_sizes": null, - "random_iv": null, - "fpe": null, - "iv_length": null, - "cipher_mode": null - }, - "never_exportable": false, - "group_id": "ff2..............b" -} -``` - -### status operation - -This operation allows you to obtain current status of a salesforce key - -### parameters - -* `operation`: The operation which you want to perform. A valid value is `status`. -* `secret_id`: The response of `configuration` operation -* `wrapper`: Name of the wrapping certificate in salesforce -* `name`: "name of corresponding sobject in Fortanix Data Security Manager" -* `sandbox`: To indicate, whether to use test or production tenant. - -#### Example - -Input JSON -``` -{ - "operation" : "status", - "secret_id": "3968218b-72c3-4ada-922a-8a917323f27d", - "wrapper" : "SFBYOK_FTX_Wrapper", - "name" : "Salesforce Data Key 20201229T185546Z", - "sandbox" : false -} -``` -Output JSON -``` -{ - "RemoteKeyIdentifier": null, - "CreatedDate": "2020-12-29T18:55:49.000+0000", - "SecretValueHash": "ESP........................=", - "CreatedById": "005..........2", - "KeyDerivationMode": "PBKDF2", - "attributes": { - "url": "/services/data/v50.0/sobjects/TenantSecret/02G..........O", - "type": "TenantSecret" - }, - "LastModifiedDate": "2020-12-29T18:55:49.000+0000", - "IsDeleted": false, - "SecretValue": "CgM.............................=", - "SecretValueCertificate": null, - "Type": "Data", - "RemoteKeyServiceId": null, - "Version": 6, - "Id": "02G..........O", - "Status": "ACTIVE", - "SystemModstamp": "2020-12-29T18:55:49.000+0000", - "RemoteKeyCertificate": null, - "Source": "UPLOADED", - "Description": "Salesforce Data Key 20201229T185546Z", - "LastModifiedById": "005............2" -} -``` -### sync operation - -This operation allows you to sync Fortanix self-Defending key object with salesforce key. - -### parameters - -* `operation`: The operation which you want to perform. A valid value is `sync`. -* `secret_id`: The response of `configuration` operation -* `wrapper`: Name of the wrapping certificate in salesforce -* `name`: "name of corresponding sobject in Fortanix Data Security Manager" -* `sandbox`: To indicate, whether to use test or production tenant. - -#### Example - -Input JSON -``` -{ - "operation" : "sync", - "secret_id": "3968218b-72c3-4ada-922a-8a917323f27d", - "wrapper" : "SFBYOK_FTX_Wrapper", - "name" : "Salesforce Data Key 20201229T185546Z", - "sandbox" : false -} -``` -Output JSON -``` -{ - "RemoteKeyCertificate": null, - "IsDeleted": false, - "CreatedById": "005..............2", - "Status": "ACTIVE", - "Type": "Data", - "LastModifiedById": "005............2", - "CreatedDate": "2020-12-29T18:55:49.000+0000", - "SystemModstamp": "2020-12-29T18:55:49.000+0000", - "Source": "UPLOADED", - "SecretValueHash": "ESP.................c", - "LastModifiedDate": "2020-12-29T18:55:49.000+0000", - "Version": 6, - "RemoteKeyServiceId": null, - "RemoteKeyIdentifier": null, - "attributes": { - "type": "TenantSecret", - "url": "/services/data/v50.0/sobjects/TenantSecret/02G............O" - }, - "KeyDerivationMode": "PBKDF2", - "Id": "02G...........O", - "SecretValueCertificate": null, - "Description": "Salesforce Data Key 20201229T185546Z", - "SecretValue": "CgM........................M" -} -``` -### destroy operation - -This operation allows you to destroy an archived salesforce key. - -### parameters - -* `operation`: The operation which you want to perform. A valid value is `destroy`. -* `secret_id`: The response of `configuration` operation -* `wrapper`: Name of the wrapping certificate in salesforce -* `name`: "name of corresponding sobject in Fortanix Data Security Manager" -* `sandbox`: To indicate, whether to use test or production tenant. - -#### Example - -Input JSON -``` -{ - "operation" : "destroy", - "secret_id": "3968218b-72c3-4ada-922a-8a917323f27d", - "wrapper" : "SFBYOK_FTX_Wrapper", - "name" : "Salesforce Data Key 20201229T185546Z", - "sandbox" : false -} -``` -Output -``` -output is empty, with http status indicating success. -``` -### restore operation - -This operation allows you to restore a destroyed salesforce key. - -### parameters - -* `operation`: The operation which you want to perform. A valid value is `restore`. -* `secret_id`: The response of `configuration` operation -* `wrapper`: Name of the wrapping certificate in salesforce -* `name`: "name of corresponding sobject in Fortanix Data Security Manager" -* `sandbox`: To indicate, whether to use test or production tenant. - -#### Example - -Input JSON -``` -{ - "operation" : "restore", - "secret_id": "3968218b-72c3-4ada-922a-8a917323f27d", - "wrapper" : "SFBYOK_FTX_Wrapper", - "name" : "Salesforce Data Key 20201229T185546Z", - "sandbox" : false -} -``` -Output -``` -output is empty, with http status indicating success. -``` diff --git a/ssh-ca/README.md b/ssh-ca/README.md deleted file mode 100644 index 0c133e4..0000000 --- a/ssh-ca/README.md +++ /dev/null @@ -1,154 +0,0 @@ -# SSH CA - -## Introduction - -SSH certificates are a method for authenticating users and/or servers in the SSH protocol. -Instead of bare public keys (the usual method of SSH authentication) an authority -issues a certificate which can then be used to authenticate to an SSH server. -SSH certificates were originally added to OpenSSH in version 5.6 (released in 2010). - -## Use Cases - -Authenticate clients to servers or servers to clients using an trusted third party -hosted on DSM. - -## Setup - -### Creating CA key with DSM - -The initial step is to create a key for the SSH CA. Generate an RSA -key with suitable parameters on DSM, and then download the public key. - -Converting the public to the OpenSSH format requires a two-step process. -First, use OpenSSL to convert the RSA key to "RSAPublicKey" format: - -`$ openssl rsa -pubin -RSAPublicKey_out -in sdkms_rsa.pub > sdkms_rsa_conv.pem` - -Then use `ssh-keygen` to convert this to the SSH format - -`$ ssh-keygen -m PEM -i -f sdkms_rsa_conv.pem > ssh_ca.pub` - -### Creating CA key with OpenSSH - -Alternatively, the key can be created on a trusted machine using OpenSSH -tools, then transferred to DSM: - -`$ ssh-keygen -f ssh_ca` - -This will create two files, `ssh_ca.pub` (public key in SSH format) -and `ssh_ca` (private key in PKCS #8 format). - -``` ------BEGIN RSA PRIVATE KEY----- -MIIEpAI... ------END RSA PRIVATE KEY----- -``` - -To import the SSH private key in DSM, copy the base64 encoded block -(but *not* the PEM headers starting with "-----") and paste it into -the Security Object import field. Make sure Sign and Verify operations -are enabled. Disable Export unless required. - -### Server Configuration - -Set up sshd configuration for accepting SSH certificates. In your `sshd_config` add - -`TrustedUserCAKeys /path/to/ssh_ca.pub` - -and restart `sshd` - -### Issue Client Cert - -Generate an RSA key pair that the user will use: - -`ssh-keygen -f ~/.ssh/user_key` - -This will again generate two keys, `user_key` (PKCS#8 private key) and -`user_key.pub` (the SSH format public key). The `user_key.pub` should look like - -`ssh-rsa AAAAB3 username@hostname` - -## Input/Output JSON - -``` -{ -"cert_lifetime":, -"valid_principals":"", -"cert_type":"user", -"ca_key":"", -"extensions":{}, -"critical_extensions":{}, -"pubkey":"" -} -``` - -"`cert_lifetime`" specifies the lifetime of the certificate in seconds. - -"`valid_principals`" specifies what username this certificate can be used for. - -"`cert_type`" can be "user" or "server". - -"`ca_key`" gives the name of the private key that was used when the RSA key was -imported into DSM earlier. - -"`extensions`" specifies operations the certificate can be used for. Values -OpenSSH supports include "`permit-X11-forwarding`", "`permit-agent-forwarding`" -"`permit-port-forwarding`", "`permit-pty`", and "`permit-user-rc`". In theory, -extensions can take values, but all currently defined extensions use an empty -string. Unknown values will be ignored by the server. - -"`critical_extensions`" specifies operations which if the server does not -understand the value, then the login attempt will be rejected. The values OpenSSH -supports are "`force-command`" and "`source-address`". "`force-command`" specifies a -single command which the certificate can be used for. "`source-address`" gives a -list of host/mask pairs, login is only allowed from an IP matching one of the -listed values. - -"`pubkey`" gives the contents of the `user_key.pub` file with the leading "`ssh-rsa `" and -trailing "` username@hostname`" removed. - -## Example Usage - -``` -{ -"cert_lifetime":86400, -"valid_principals":"desired_username", -"cert_type":"user", -"ca_key":"SSH CA Key", -"extensions":{"permit-pty":""}, -"critical_extensions":{"source-address":"10.2.0.0/16,127.0.0.1"}, -"pubkey":"AAAAB3"} -} -``` - -When the plugin is invoked it will return a string that looks like - -`"ssh-rsa-cert-v01@openssh.com AAAAHHNza...."` - -Copy the entire contents to `~/.ssh/user_key-cert.pub` - -Now test the output using `ssh-keygen`: - -``` -$ ssh-keygen -L -f user_key-cert.pub -user_key-cert.pub: - Type: ssh-rsa-cert-v01@openssh.com user certificate -... -``` - -Now run - -`$ ssh -i ~/.ssh/user_key server_host whoami` - -The login should succeed with the command executed on the remote host. - -If you use `-v` option when using a certificate you should see something like - -``` -debug1: Offering public key: RSA-CERT SHA256:Hcb9trzeAptUdTgqWj9VEncbkAGOpAglGnUrYGq4/Vo user_key -debug1: Server accepts key: pkalg ssh-rsa-cert-v01@openssh.com blen 1029 -``` - -## References - -[Annotation of src/usr.bin/ssh/PROTOCOL.certkeys, Revision HEAD](https://cvsweb.openbsd.org/src/usr.bin/ssh/PROTOCOL.certkeys?annotate=HEAD) \ No newline at end of file