ibm-cloud-docs / hs-crypto Goto Github PK

View Code? Open in Web Editor NEW

3.0 9.0 22.0 86.16 MB

hs-crypto

hs-crypto's People

Stargazers

Watchers

hs-crypto's Issues

Add "storage-device" integration with HPCS

We are now able to integrate HPCS with storage devices. This is going to be useful for the "Stratos" projects under the "Enterprise Data Architecture as a Service" effort.

I think we should update this document with an introduction to "storage device integration" and a pointer to the detailed documentation here: https://developer.ibm.com/tutorials/awb-protect-storage-systems-with-ibm-hpcs-and-gklm/

@TiffanyLiIBM

HSM initialisation by key part files : Needs document updates

I am going through TKE by key part files and see it points to pre-requisites page. There, it shows this.

This expects the user to get to another link to login to IBM cloud, and the text below shows to point to the right target. So, in my view, it's not clear. It would be clean if we only gave the command here showing logging into IBM cloud too. Can the document be updated to contain this

Best would be, if we could keep all this in here itself

At the least, this-link needs a Pre-requisite section. The way it is now. it's right after the video and is very easy for someone to just miss it.

Having its own section for pre-requisites would help make it clear.

KP CLI plugin should be documented in CLI docs

Currently, the only docs for the kp CLI plugin are here: https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-set-up-cli

They should also be added to the IBM Cloud CLI reference: https://cloud.ibm.com/docs/cli?topic=analytics-engine-cli-plugin-CLI_analytics_engine

Another update on page Setting up PKCS #11 API user types

Under https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-best-practice-pkcs11-access#create-key-operator
add the following action to the list under (7):

hs-crypto.discovery.listservers

In addition, on the same page, it seems the UI and the Docu do not match 100%:
Proposed change

Old:
(4) Click Assign service ID additional access, and then click the IAM services button.

New / proposed update:
(4) Click Assign access to the service ID, and then click the IAM services button.

here:

https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-best-practice-pkcs11-access#1-assign-the-custom-roles-to-the-so-user-service-id
and
https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-best-practice-pkcs11-access#2-assign-the-custom-roles-to-the-normal-user-service-id
and
https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-best-practice-pkcs11-access#3-assign-the-custom-roles-to-the-anonymous-user-service-id

Staging API docs do not match production API docs

The staging python example is incorrect and causes an error when followed exactly. The production docs are mostly correct except for the False keyword not being capitalized. Could we change the staging python example to be like the production example?

staging -> https://test.cloud.ibm.com/apidocs/hs-crypto?code=python#create-a-key
production -> https://cloud.ibm.com/apidocs/hs-crypto?code=python#create-a-new-key

Add recommendation to setup Acitivity Tracker for HPCS

Add a strong and easy to read recommendation - on this page https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-provision&interface=ui - to enable IBM Cloud Activity Tracker for the Hyper Protect Crypto Services instance.

See following sentence here: https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-at-events
"To enable IBM Cloud Activity Tracker for your Hyper Protect Crypto Services instance, you need to provision an instance of the IBM Cloud Activity Tracker service in the same region where your Hyper Protect Crypto Services instance is located."

Goal: Avoid that customer does a key ceremony which is not audited in his AT.

Typo in key ceremony docs

"Hyper Protect Crypto Services sets up signature keys for crypto unit administrators during the service initialization process to ensure that the master key parts are loaded to the HSM with no one can intercept."

page design broken

Hello HPCS docu team,
there is an error in the page at https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm
in step 2:

Incorrect statement about availability of recovery crypto units

https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm-recovery-crypto-unit

This sentence is not correct anymore:
"Currently, only the us-south and us-east regions are enabled with the recovery crypto units, which means, when a service instance is provisioned in either regions, you are by default enabled with the option to back up your master keys in the recovery crypto units located in both regions."

Recovery crypto units are no longer limited to us-south and us-east (I do not know if they are available gobally now or still limited to certain regions, but they are available at least in syd and tok, too).

Update and enhance page Setting up PKCS #11 API user types

The following seems outdated and a bit confusing:
(5) "Click No service access under What type of access do you want to assign? and select Hyper Protect Crypto Services."

Proposed change:
(5) Under Which service do you want to assign access to? select Hyper Protect Crypto Services.

Between (5) and (6) there is one step missing:
Proposed addition:
(5.1) Under How do you want to scope the access? select Resources based on selected attributes

Warn reader about risks of leaving NEW MASTER KEY REGISTER in Full Uncommitted state

Between step 5 "Load the new master key register" and step 6 "Commit the new master key register" the NEW MASTER KEY REGISTER is in "Full Uncommitted" state. Evidently with use of the GREP11 Server many EP11 operations fail while the NEW MASTER KEY REGISTER is in this "Full Uncommited" state.

Since this is not documented, there is a risk of an outage if an administrator does step 5, and then, for whatever reason, unwittingly stops at this step and leaves it in this state for an extended period of time because they were not aware of this situation.

I would suggest that if there can't be a code change to avoid this situation, that at least the documentation be changed to add a warning to the reader about the need to quickly perform step 6 right after step 5 (unless of course they have their reasons to pause in between, but they should be aware of the risk).

I am referring to these steps:

https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm#step5-load-master-key
https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm#step6-commit-master-key

"Type of key" and "Envelope encryption" links

...are linking to Key Protect content.

show multiple places where the smartcard reader can be purchased

Based on customer feedback the shown location does not ship the reader to all places.
The reader itself is not only available from this place.
SPR332 v2.0 Secure Class 2 PIN Pad Reader could be bought at multiple other places.

We should at least mention the reader class, name and that it is available on other shops and may mention those shops

Review note on availability of recovery crypto units

Review the following note
Currently, only the us-south and us-east regions support recovery crypto units. Only service instances in these regions can use this command. For more information about supported regions, see [Regions and locations](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regions).

This note is contained in multiple HPCS documentation pages, e.g. https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm-recovery-crypto-unit and https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-recover-master-key-recovery-crypto-unit

But today recovery units can be created for HPCS instances in other locations apparently, at least if one uses Terraform.

Please work with Heidi and the HPCS development team to review and - if required - update this note.

There is also a similar note in the Terraform provider registry https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs/resources/hpcs which also needs to be reviewed.

Key Rotation guidance update

Hi, we have had several questions on key-rotation with VMware and other services that HPCS integrates with.
ZCAT has tested and documented various scenarios and this needs to be updated into the official documentation as well.

Please use this Box-note to create a single document for all key-rotation use cases.

Reach out if you have any questions

Need to add a Smart-Card Calculator

The smart-card requirements documents linked to at https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-tke-procedures will need to be supported by a Calculator that will help determine how many "Smart Card Readers" and "Smart Cards" are required.

Timo Kussmaul from our team has developed a simple calculator, which needs to be added to the documentation: https://ibm.ent.box.com/file/984688389180

Clarify HPCS AWS & Azure support.

Currently this question in the Q&A implies an AWS cloud service such as S3 Storage could use HPCS.

Can I use Hyper Protect Crypto Services along with other cloud provider services such as AWS and Azure?
Yes. Any application can connect to Hyper Protect Crypto Services and use our APIs from anywhere on the internet.

I suggest replacing the Q&A with:

Can I use Hyper Protect Crypto Services for applications hosted in other cloud service providers such as AWS, Azure and GCP?
Yes, An application hosted in other cloud service providers could call the public APIs for BYOK or PKCS#11 with an appropriate network connection.

Broken Link in Documentation

There are two links on this page, each with the text "virtual routing and forwarding (VRF) and service endpoints". The first occurrence of the link works but the second occurrence of the link sends you to a "Document not found" page.

The need for the directory to be created/pre-exist should be made explicit

https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm-prerequisite

point (3) says to set the variable CLOUDTKEFILES to a directory name. It should be made clear to the reader that the directory must exist before they run any TKE commands.

Link to the documentation for initializing instance is missing

After you create a service instance you are provided the following error message with no indication or link to documentation on what to do:

Please add a link to steps to follow to complete the configuration.

change order of steps

Following the instruction on getting started I encountered an issue in the order.

If you look at the part below

Leave imprint mode in the target domain

A domain in imprint mode is not considered secure. You cannot run most of the administrative commands, such as loading the new master key register, in imprint mode.

After you install one or more domain administrators, exit imprint mode by using the command:

I followed the instructions mentioned
ibmcloud tke domain-exit-impr
{: pre}

The command to exit imprint mode must be signed by one of the installed domain administrators.

To select the administrator to sign the command, use the command:

Tip: The command to exit imprint mode must be signed by a domain administrator. After the domain leaves imprint mode, all commands to the domain must be signed.

```
ibmcloud tke sigkey-sel
```
{: pre}

A list of signature key files found on the workstation is displayed.

When prompted, enter the key number of the signature key file to select for signing subsequent administrative commands.

The steps indicate that you can leave the imprint mode without an additional step. What I faced was that it is needed, required to use

ibmcloud tke sigkey-sel

first and then I can leave the imprint mode. I think the order should be changed or it should be better visible to first select a key and then leave imprint mode

HPCS Integrated service list is not up2date

The list of services for HP Crypto which are interated with this service are not up2date
https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-integrate-services

services like ICD and others are missing which leads to customer confusion
https://cloud.ibm.com/docs/databases-for-postgresql?topic=cloud-databases-hpcs

Update this doc to include TKE and SmartCard Documents

This issue is to update this doc: https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-tke-procedures

Current document-link https://cloud.ibm.com/media/docs/downloads/hs-crypto/IBM_Cloud_HyperProtectCryptoSevices_TKE_Procedures.pdf contains only the smart-card procedure.

For TKE Key-part file procedure, please use this doc: https://github.ibm.com/ZaaS/zcat-assets/blob/main/docs/HPCS%20Key%20Ceremony%20Document%20-%20v0.1.docx
For TKE Smart-Card procedure, @timo will update / refresh the existing document to reflect experiences gained from client engagements.

@TiffanyLiIBM pls share the DOC version of the existing PDF doc on this page, if you have access to it

Typo in email address on page hs-crypto-prepare-management-utilities

https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-prepare-management-utilities

Step 1 -> (2) -> There is a typo in the email address "zcat@[email protected] "

There isn't a KMS keys section on my UI

I can't follow this instruction:

"On the KMS keys page, use the Keys table to browse the keys in your service."

Document common possible cause for no visible crypto units on TKE setup

If the I work with multiple users it might happen that the owner of the crypto instance is not the one who setup the
Root Key.
In this case the Roles and Permissions are important.
The error case shown is as following, but does not indicate that it could be a permission issue.

ibmcloud tke cryptounits
API endpoint:     https://cloud.ibm.com
Region:           XX-XX
User:             [email protected]
Account:         myaccount (GUID)
Resource group:   Default

No service instances were found for the current resource group.

Please add this condition and the multiple cases why this could happen
-> wrong region, wrong account, missing roles

Depiction of KeyStores in Fig2 needs an update

Fig.2 suggests that you will need “separate” HPCS instances for each Application.
It should be modified to indicate that each Application can have it’s own KeyStore under the same HPCS instance

Update doc to add Permissions required for HPCS operations

The Doc at https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-manage-access needs more details on the minimum access requirements for various HPCS operations like:

View the HPCS UI Dashboard on cloud.ibm.com
Create Keys
Rotate Keys
Delete Keys

with the granular roles that have been added to IAM:

text indicates destroyed keys can't be recovered, table differs

The text says that destroyed keys cannot be recovered, but the table shows "recovery" as a valid action against destroyed keys.

Instruction Incorrect for Initializing Hyper Protect Crypto Services with IBM Cloud TKE CLI

From the UI Link to getting started

https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-started#initialize-crypto
The link to Video: Initializing Hyper Protect Crypto Services with IBM Cloud TKE CLI https://mediacenter.ibm.com/media/0_z5c589ou Has what seems to be an outdated command. It says to exit imprint mode with ibmcloud tke cryptounit-exit-impr This not a valid command in the latest plugin version.

> ibmcloud plugin show tke
                                                                                                                                                                                                                                                                                                                     
Plugin Name                              tke
Plugin Version                           1.3.1
Plugin SDK Version                       0.11.0
Minimal IBM Cloud CLI version required   N/A
Private endpoints supported              true

Commands:
 tke                           Manage crypto units in the IBM Cloud
 tke mks                       Lists EP11 master key parts stored on this workstation.
 tke mk-add                    Creates and saves a new EP11 master key part.
 tke mk-rm                     Removes an EP11 master key part from this workstation.
 tke sigkeys                   Lists the signature keys stored on this workstation.
 tke sigkey-add                Generates and saves a new signature key.
 tke sigkey-rm                 Removes a signature key from this workstation.
 tke sigkey-sel                Selects the signature keys to use to sign commands.
 tke cryptounits               Displays the crypto units for the current resource group.
 tke cryptounit-add            Adds crypto units to the set of crypto units to work with.
 tke cryptounit-rm             Removes crypto units from the set of crypto units to work with.
 tke cryptounit-admins         Lists administrators installed in the selected crypto units.
 tke cryptounit-admin-add      Adds a crypto unit administrator to the selected crypto units.
 tke cryptounit-admin-rm       Removes a crypto unit administrator from the selected crypto units.
 tke cryptounit-compare        Compares configuration settings of the selected crypto units.
 tke cryptounit-thrhlds        Displays signature thresholds for the selected crypto units.
 tke cryptounit-thrhld-set     Sets the signature thresholds for the selected crypto units.
 tke cryptounit-zeroize        Zeroizes the selected crypto units.
 tke cryptounit-mks            Displays master key registers for the selected crypto units.
 tke cryptounit-mk-clrcur      Clears the current master key register.
 tke cryptounit-mk-clrnew      Clears the new master key register.
 tke cryptounit-mk-commit      Commits the new master key register.
 tke cryptounit-mk-rotate      Promotes the master key in the new key register to the current key register after rewrapping root keys in the key management keystore.
 tke cryptounit-mk-setimm      Promotes the master key in the new key register to the current key register immediately.
 tke cryptounit-mk-load        Loads the new master key register.
 tke cryptounit-cp-btc         Enables BTC-related functionality in the selected crypto units.
 tke cryptounit-cp-eddsa       Enables Edwards-curve DSA functionality in the selected crypto units.
 tke cryptounit-cp-sig-other   Enables non-ECDSA, non-Edwards-curve signature functionality in the selected crypto units.
 tke auto-init                 Automated initialization of service instances including loading administrators, setting signature thresholds, and random master key generation.
 tke auto-mk-recover           Copies the current master key value in a recovery crypto unit to other crypto units.
 tke auto-mk-rotate            Automated master key rotate using a new randomly generated master key value.
 tke failover-enable           Enables failover cryptounits for an instance. Affects billing, see https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-pricing

Code vs. Encode

In the What's Next section, should "keys to code your apps and service" be changed to "keys to encode your apps and service"?

Typo on https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-started#manage-data-key

Under: Importing your own keys > Description of Key type setting is: "The type of key that you would like to manage in Hyper Protect Crypto Services. You can seletct Root key or Standard key."

There is a typo: seletct.
Please correct to be select.

need update on links

The last 2 links on this page points to test.cloud.ibm.com rather than the public doc:
https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm-prerequisite

Broken link

In https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-master-key-rotation-intro
the link in this sentence
For detailed instructions, see [Rotating master keys by using key parts](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-rotate-master-key-key-parts).

is broken.

Links in document need to be updated

There are several links in https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-integrate-services#database-integration
section for integration that link to nowhere. That needs to be updated correctly so that integration can be done correctly.

Lack of useful error message in the UI when deleting service instance

when deleting the Crypto Services, I get:

I have to look at the console to find the real problem: "details: "[{"description":"There are still domains configured with a master key. Use the IBM Cloud CLI tke plugin to zeroize the domains.","error":"HsmStateError"}]""

Granting access to Vaults

In the Doc https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-grant-access-vaults

Step-2, Sub-Step 7,

Vault ID attribute does not appear in the Attribute Type drop-down

What should be selected instead? The options that I see are:

KeyRing ID
Region
Resource ID
Resource Type
Resource Group

Clarify HPCS instance type for KMIP

Please clarify in "Before you begin" section to provision a Standard Instance of HPCS.

Customer provisioned a UKO instance as that is the first option on the provisioning panel on IBM Cloud and tried to go through the KMIP provisioning process and went through multiple trouble shooting discussions, before it came to me.

For KMIP / VMware services, a Standard Instance is required.

Hyper Crypto Protect Documentation missing section Cloud Image Templates

There is integration between KeyProtect and IMAGE TEMPLATE:
https://cloud.ibm.com/docs/key-protect?topic=key-protect-integrate-services&interface=ui#compute-integrations

In the IMPORT CUSTOM IMAGE there are 3 choices for encryption: Provider managed, KP and HPCS.

In the HPCS page in section Compute service integrations there is a missing table entry IBM Cloud Image Templates

https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-integrate-services

Production API docs python example has incorrect syntax

The keyword False is capitalized in python. In the documentation it is lowercase.

"extractable": false -> "extractable": False

Here is the link to the API docs where it should be updated.
https://cloud.ibm.com/apidocs/hs-crypto?code=python#create-a-new-key

Prohibited term: master

Replace "master" in "master key" with an approved alternative. Options: controller, primary, parent.
@TiffanyLiIBM Please work with a technical SME for input on the proposed update.

This term is included in our product glossary. We're working with IBM Terminology to update the term in the DB so we can then refresh the glossary.

Need some more detail on Key Format

Hi,
I am following ths doc here: https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-signing-service-signature-key&interface=ui
to work with a signing service. Getting this error:

asn1: structure error: tags don't match (2 vs {class:0 tag:16 length:356 isCompound:true}) {optional:false explicit:false application:false private:false defaultValue:<nil> tag:<nil> stringType:0 timeType:0 set:false omitEmpty:false}  @4

I am looking for the following details to see if my Signing Service can be configured properly:

a sample certificate, if you can, so we can get an idea about the format for the Public Key
which Elliptic Curve format must be used by the Signing Service to generate the Keys?

Clarify in more detail how the HPCS instance ID drop down works

https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-tutorial-kmip-vmware#tutorial-vmware-configure

4.) Select the Initialize service instance option and Hyper Protect as the key management type.

Select the Hyper Protect Crypto Services instance ID that stores your root key and key encryption key. You can click the Retrieve button to get a list of Hyper Protect Crypto Services instances under your IBM Cloud account.
Add a note like: "(Only IDs of Hyper Protect Crypto Services instances that contain at least one root key will be displayed in this list.)"

Reason: If a HPCS instance exists, but a root key is not yet created in this instance, the instance id will not be listed in the drop down, which may be counter-intuitive.

Weird phrasing on IBM HPCS page

https://www.ibm.com/cloud/hyper-protect-crypto

At the above link this is the first sentence:
IBM Cloud™ Hyper Protect Crypto Services is a key management and cloud hardware security module (HSM).

I'm not sure, this isn't my area of expertise but the phrasing seems weird, and it doesn't match the cloud catalog description which is:
IBM Cloud Hyper Protect Crypto Services is a dedicated key management service and hardware security module (HSM).

It seems like it is missing a few words or something. The grammar is clunky. Maybe it could be changed to:
IBM Cloud™ Hyper Protect Crypto Services is a dedicated key management and cloud hardware security module (HSM) service.

If you removed the "key management and" in the first example or the "dedicated key management service" in the second example, the sentence would be:
IBM Cloud™ Hyper Protect Crypto Services is a cloud hardware security module (HSM).
I'm not sure if it is considered a cloud HSM or a cloud HSM service? I'll leave it up to you just thought I'd bring it to your attention.

Include links for UKO-Demos to this page

Please add links for HPCS-UKO demo to this page:

Since the deprecation of HPS DBaaS links should be updated

Some of the links to how to integrate HPCS with the service are not working, but the bigger concern is that integration for MongoDB still points to HP DBaaS MongoDB and states that it is deprecated. Shouldn't the links point to the non-deprecated information as is suggested in the text on each page. Otherwise the Alternative should be highlighted even more instead of just putting it in a colored box. Need to draw attention to it.

https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-integrate-services

This is the page that needs to be updated on the previous link and avoid going to the depreciated page:
https://cloud.ibm.com/docs/hyper-protect-dbaas-for-mongodb?topic=hyper-protect-dbaas-for-mongodb-hpcs-byok

Error trying to assign access to the same role

Following this doc to create IAM roles and service ID's for pkcs11 access: https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-best-practice-pkcs11-access

I have created two roles following the documentation:

key operator
keystore operator

Then I created the SO user service ID.

I was able to assign both key operator and keystore operator to the SO user service ID as documented.

However the next section it asks me to only assign key operator to the SO user for private keystore access. But this was already added in the previous assign access workflow. So when I try to add again I get the following error message:


Access could not be assigned. "The policy wasn't created because an access policy with identical attributes already exists. Please update the roles in the existing policy (37b892da-b353-4aaa-bdc7-e6eb7566b0d1), or update the one you're trying to assign to include a different attribute assignment." 
(Code: c3dc655c-20e0-49f6-ad8e-8d2e82b1174b)

Similar error is seen when assigning the same role key operator the second time to the Normal user.

How is it distinguishing between access to public keystore vs access to private keystore?

Clarify the instructions for ordering smart card readers

https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-prepare-management-utilities#ordering-smart-card-readers

Current text:
The supported smart card reader type is SPR332 v2.0 Secure Class 2 PIN Pad Reader (part number 905127-1). The following are a few third-party online shops where you can order a smart card reader. The deliver policy might vary depending on your geographical locations:

Proposed change:
You need two smart card readers of type Identiv SPR332 v2.0 Secure Class 2 PIN Pad Reader (part number 905127-1). You can order the smart card readers from third-party online shops. For illustration there is a list of example links to various online shops below:

ibm-cloud-docs / hs-crypto Goto Github PK

hs-crypto's People

Stargazers

Watchers

Forkers

hs-crypto's Issues

Recommend Projects

Recommend Topics

Recommend Org