Instructions for Partner- Signing Key Generation and Certificate Creation and Renewal

Transcription

1 Instructions for Partner- Signing Key Generation and Certificate Creation and Renewal Document Version: Page 1 of 13

2 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws. This product is covered by one or more patents listed in the patent.txt file found at Page 2 of 13

3 Introduction This document contains instructions for an Authorized Administrator at a VMware Partner to generate a key pair and request/process a certificate for purposes of signing ESX-executable modules, scripts, and data. This document is intended for authorized release management engineers at the Partner who normally handle private keys and certificates used to sign release artifacts. The instructions and commands apply starting with ESX/vSphere 4.x and are valid through ESX 5.x. Successful execution of these steps will result in a private key and certificate that can be used to sign modules that will properly install into ESX without error as partner-signedand-supported. This private key and certificate must be used in accordance with the VMware Code Signing Certificate Use Agreement which is mentioned below in the first step in these instructions. The private key must be kept secret and treated as high-security information in accordance with your company s security policies. Here is an outline of the steps defined in this document: 1. Submit Project Tracker or Execute Use Agreement 2. Generate Public/Private Key Pair 3. Generate Certificate Signing Request 4. Enroll for a Certificate 5. Download the Certificate 6. Convert the Certificate to x Test-Sign a Module 1. Execute Use Agreement Before performing any of the steps below, the partner company must generate a project tracker in their private vmdev.net project related to the product being signed. The project tracker must name a private key administrator who has specific security responsibilities for the signing keys and certificate. If this is a special case and there is no related program or vmdev.net project, the partner company must execute a VMware Code Signing Certificate Use Agreement. This agreement provides the legal basis for VMware to allow the partner to have a certificate in VMware s certificate hierarchy. The Use Agreement is also where the partner identifies the individual who will act as the Primary Administrator, and gives official contact information about that person to VMware so VMware can initiate the certificate generation process. Contact your program manager for a copy of the Use Agreement. Note that in most normal cases this agreement may be included in the Program Guide associated with your development and/or certification effort, so all that is needed is to provide the following information in a project tracker. Primary Designated Administrator Name: Title: Telephone: Upon receipt of a project tracker or fully executed Use Agreement, the VMware PKI Administrator will generate a passcode and initialize the certificate data for the person Page 3 of 13

4 named in the Use Agreement, and the passcode to that person using the listed in the Use Agreement. The information in this section of the User Agreement is considered the master copy, so check it carefully. Note that the certificate application requires an unambiguous First Name and Last Name so simplify the administrators name if need be. 2. Generate Public/Private Key Pair After the Use Agreement is executed, you must generate a public/private key pair according to your corporate policies and following industry-recognized security practices. These include: Generating the keys entirely inside a physically secure environment Never copying the private key in the clear on any media generate it where it will be stored Never allowing key data or passwords to key stores to be used in scripts or config files The key pair must be generated using the RSA algorithm at a 2048-bit key length. The VMware signing software checks for these characteristics, and will reject any key using a different algorithm or key length. This will cause VMware to have to revoke the certificate and this process to start over. You can use any industry-standard cryptographic software or hardware system to generate the key pair and CSR in this process, according to your corporate security policies. The following example uses openssl on an RHEL system. Note if you use openssl, use version or later. That version supports SHA256, which you ll need for CSR request generation. $ openssl version OpenSSL 0.9.8b 04 May 2006 To generate a key pair: $ openssl genrsa 2048 > private.key Generating RSA private key, 2048 bit long modulus e is (0x10001) $ chmod 400 private.key 3. Generate Certificate Signing Request Next you must generate a Certificate Signing Request or CSR, which will contain the public key from the key pair you just generated, along with information that will be used in the certificate. VMware requires that the signature algorithm use the SHA256 hashing algorithm. In openssl, the command to generate a certificate request prompts you for information on the command line. None of this information is used in the certification creation, so you Page 4 of 13

5 don t have to enter the data here as carefully as you will later. You can just accept the defaults. $ openssl req -new -x509 -nodes -sha256 -days key private.key > partner.csr (accept defaults) If all went well, a partner.csr file was created in your current directory. You can display the information in the file with the following command, so you can verify it. Be sure to verify that the Signature Algorithm is listed as: sha256withrsaencryption. The VMware signing software checks for this algorithm, and will reject any certificate using another algorithm. To fix this would require revoking the certificate and starting over. $ openssl x509 -in partner.csr -text -noout Certificate: Data: Version: 3 (0x2) Serial Number: af:1d:d4:76:2e:71:36:43 Signature Algorithm: sha256withrsaencryption 4. Enroll for a Certificate Now that you have generated a private key and CSR, once you receive the with your passcode from VMware, you are ready to create and download your certificate. Go to the following URL: You will see a display that looks something like this: Page 5 of 13

6 Select this link: Enroll for a Digital ID using a CSR. Do not select the larger Enroll link above it. This will get you the wrong type of certificate that you cannot use for code signing. If you select the correct link, you will see a page titled, Submit CSR which has one field for you to enter the path to the CSR file you generated above. Enter or browse to the file path and select the Submit button. Page 6 of 13

7 Next you will see a page titled Complete Enrollment Form. The data you enter in this form will be used in your certificate, so check it carefully. Page 7 of 13

8 The First Name and Last Name fields must match what you entered in the Use Agreement, including capitalization, or the enrollment will be rejected and you will be asked to re-enter the information. There is a field for information about your company, the passcode VMware sent you by (which by the way is not case sensitive), and your location. Note the form you see may be slightly different with not as many fields. There is also a Challenge Phrase field that is private to you. Enter a phrase or password here that you will remember. You use this to revoke or renew your certificate. Once you have carefully checked the information you entered, select the Submit button at the bottom of page. Page 8 of 13

9 Note if there is a problem with any of the input, the error messages coming back are not the most intuitive. If you put anything for either the first or last name that is different than what was on the Use Agreement, you may be warned of an error in the passcode, rather than in the name. If the information checks out, you should see a message that says the certificate was successfully created and installed. Note that the certificate has been created, but it was not installed anywhere. Now you have to go get it, and that is the next step. 5. Download the Certificate Navigate back to the Digital ID Center page as you did at the beginning of the last step, at this URL: Select the Search link, and you will see a page like this: Page 9 of 13

10 Enter your address in the Search by Address box, then hit the Search button in that box. If all is well, you should see a reference to your certificate come up next like this: Select the link for your name, and a page like this will come up: Page 10 of 13

11 Select the Download button at the bottom of the page, and the next page will come up. Page 11 of 13

12 In the ID Format dropdown, select S/MIME Format (Binary PKCS#7) and select the Submit button. A browser-specific box will come up allowing you to save the file. You re almost done. 6. Convert the Certificate to x509 The certificate file, as downloaded from VeriSign, is in the wrong format for ESX, so you have to convert it from pkcs7 DER format to x509 PEM format. In openssl, the command to do that is as follows: $ openssl pkcs7 -inform DER -in cert.p7b -print_certs > signing.cert The certificate is now done and ready to use. It does not contain a direct reference or any other information about your private key, so the certificate does not have to be treated as a corporate secret. However, you will want to have a copy close to where you store your private key for convenience. 7. Test-Sign a Module To verify your new private key and certificate work together properly, copy a VIB you have created into your secure build environment, sign it using the following command, copy it over to an ESX server, and see if it installs properly. $ vibauthor -v my.vib -s -k private.key -r signing.cert ( on ESX box after copying VIB for 5.x ) esxcli acceptance set --level PartnerSuported esxcli software vib install -v my.vib ( on ESX box after copying VIB for 4.x ) # esxupdate -b my.vib If neither vibauthor nor esxupdate/esxcli reports an error, then your new certificate and private key are ready to go into production. Maintenance VMware strongly recommends that our partners adhere to the following best practices for maintaining the private key: Store your selected challenge phrase, which you will need to renew or revoke your certificate, in a secure location. Note that you can select any password or phrase for this field. Note too that the passcode provided to you by VMware and the challenge phrase are two different fields. Treat the private key you generate as private information and ensure it is kept in a physically secure location. The best practice is to generate the private key on an isolated server used for production signing only, have physical and password access to that server only by designated administrators, and never copy the private Page 12 of 13

13 key or transfer it to any other media, and never let anyone other than a designated administrator have access to the server where the key is stored. Ensure that only a designated administrator and any backup administrators are allowed to access the private key. Designate a backup administrator and implement a succession plan in advance. Though the certificate will have the original administrator s name assigned to it, VMware does not require the certificate to be updated or reissued when you change administrators, only that you inform VMware of the identity of the new administrator. Educate your broader team on the implications of breaching the security of the private key. The private key is considered breached if it is allowed to be accessed by anyone other than a designated administrator in any way. This includes allowing someone other than a designated administrator to log into a computer or storage array where the key is stored, allowing the system to be accessed over an intranet or internet without restricted login protection, copying the key to any media that can be accessed without password by a non-administrator, or sending the key as an attachment to any . If any of these key breaches occur, the certificate will be revoked. If any security breach occurs or if the signing certificate is misused in any way, VMware will revoke the certificate, which invalidates all previous partner products signed with that certificate. The revokation process incurs significant expense and inconvenience to both VMware and the partner, so it is important to keep the private key secure and follow all VMware policies on code signing. Renewal VMware has engineered ESX installation and validation software such that these VeriSign code signing certificates never have to be renewed. Code signing certificates are meant to be treated as long-lived and valid for any version of ESX/vSphere from 4.x onward. If you receive a renewal notice from VeriSign, you should ignore it and not attempt to renew the certificate. These certificates do have an end-date, but should be ignored. Page 13 of 13