test

Sun Java System Access Manager 7.1 Federation and SAML Administration Guide

Appendix B Key Management

A public key infrastructure enables users on a public network to securely and privately exchange data through the use of a public and a private key pair that is shared using a trusted authority. For example, the PKI allows the data from a client, such as a web browser, to be encrypted prior to transmission. The private key is used to decrypt text that has been encrypted with the public key. The public key is made publicly available (as part of a digital certificate) in a directory which all parties can access. This appendix contains information on how to create a keystore and generate public and private keys. It includes the following sections:

Public Key Infrastructure Basics

Web containers support the use of keystores to manage keys and certificates. The keystore file is a database that contains both public and private keys. Public and private keys are created simultaneously using the same algorithm (for example, RSA). A public key is used for encrypting or decrypting information. This key is made known to the world with no restrictions, but it cannot be used to decrypt information that the same key has encrypted. A private key is never revealed to anyone except it's owner and does not need to be communicated to third parties. The private key might never leave the machine or hardware token that originally generated it. The private key can encrypt information that can later be decrypted by using the public key. Also the private key can be used to decrypt information that was previously encrypted using the public key.

A public key infrastructure (PKI) is a framework for creating a secure method of exchanging information on an unsecure network. This ensures that the information being sent is not open to eavesdropping, tampering, or impersonation. It supports the distribution, management, expiration, rollover, backup, and revoking of the public and private keys used for public key cryptography. Public key cryptography is the most common method for encrypting and decrypting a message. It secures the data involved in the communications by using a private key and its public counterpart. Each entity protects its own private key while disseminating its public key for all to use. Public and private keys operate inversely; an operation performed by one key can be reversed, or checked, only by its partner key.

Note –

The Internet X.509 Public Key Infrastructure Certificate and CRL Profile is a PKI.

Digital Signatures

So, a private key and a public key can be used for simple message encryption and decryption. This ensures that the message can not be read (as in eavesdropping) but, it does not ensure that the message has not been tampered with. For this, a one-way hash (a number of fixed length that is unique for the data to be hashed) is used to generate a digital signature. A digital signature is basically data that has been encrypted using a one-way hash and the signer's private key. To validate the integrity of the data, the server receiving the communication uses the signer's public key to decrypt the hash. It then uses the same hashing algorithm that generated the original hash (sent with the digital signature) to generate a new one-way hash of the same data. Finally, the new hash and the received hash are compared. If the two hashes match, the data has not changed since it was signed and the recipient can be certain that the public key used to decrypt the digital signature corresponds to the private key used to create the digital signature. If they don't match, the data may have been tampered with since it was signed, or the signature may have been created with a private key that doesn't correspond to the public key presented by the signer. This interaction ensures that any change in the data, even deleting or altering a single character, results in a different value.

Digital Certificates

A digital certificate is an electronic document used to identify an individual, a server, a company, or other entity and to bind that entity to a public key by providing information regarding the entity, the validity of the certificate, and applications and services that can use the certificate. The process of signing the certificate involves tying the private key to the data being signed using a mathematical formula. The widely disseminated public counterpart can then be used to verify that the data is associated with the sender of the data. Digital certificates are issued by a certificate authority (CA) to authenticate the identity of the certificate-holder both before the certificate is issued and when the certificate is used. The CA can be either independent third parties or certificate-issuing server software specific to an enterprise. (Both types issue, verify, revoke and distribute digital certificates.) The methods used to authenticate an identity are dependant on the policies of the specific CA. In general, before issuing a certificate, the CA must use its published verification procedures for that type of certificate to ensure that an entity requesting a certificate is in fact who it claims to be.

Certificates help prevent the use of fake public keys for impersonation. Only the public key certified by the certificate will work with the corresponding private key possessed by the entity identified by the certificate. Digital certificates automate the process of distributing public keys and exchanging secure information. When one is installed on your machine, the public key is freely available. When another computer wants to exchange information with your computer, it accesses your digital certificate, which contains your public key, and uses it to validate your identity and to encrypt the information it wants to share with you. Only your private key can decrypt this information, so it remains secure from interception or tampering while traveling across the Internet.

Note –

You can get a digital certificate by sending a request for one to a CA. Certificate requests are generated by the certificate management tool used. In this case, we are using the keytool command line interface. When keytool generates a certificate request, it also generates a private key.

keytool Command Line Interface

keytool is a key and certificate management utility used to create the keys. It also manages a .keystore file containing private keys and the associated X.509 certificate chains authenticating the corresponding public keys, issues certificate requests (which you send to the appropriate CA), imports certificate replies (obtained from the contacted CA), designates public keys belonging to other parties as trusted, and generates a unique key alias for each keystore entry. There are two types of entries in a keystore:

To create a keystore and default key entry in .keystore, you must use keytool, available from the Java Development Kit (JDK), version 1.3.1 and above. For more details, see keytool — Key and Certificate Management Tool.

Setting Up a Keystore

The following procedure illustrates how to create a keystore file and default key entry using keytool.

ProcedureTo Set Up a Keystore

Be sure to use the keytool provided with the JDK bundled with Access Manager. It is located in JAVA_HOME/bin/keytool. When installed using the Java Enterprise System installer, JAVA_HOME is AccessManager-baseSUNWam/java.

Note –

The italicized option values in the commands used in this procedure may be changed to reflect your deployment.

  1. Generate a certificate using one of the following procedures.

    • Generate a keystore with a public and private key pair and a self-signed certificate for your server using the following command.

      keytool -genkey -keyalg rsa -alias test -dname "cn=sun-unix,ou=SUN Java System Access Manager,o=Sun,c=US" -keypass 11111111 -keystore .mykeystore -storepass 11111111 -validity 180

      This command will generate a keystore called .mykeystore in the directory from which it is run. A private key entry with the alias test is created and stored in .mykeystore. If you do not specify a path to the keystore, a file named .keystore will be generated in your home directory. If you do not specify an alias for the default key entry, mykey is created as the default alias. To generate a DSA key, change the value of -keyalg to dsa. This step generates a self-signed certificate.

    • Create a request and import a signed certificate from a CA (to authenticate your public key) using the following procedure.

      1. Create a request to retrieve a signed certificate from a CA (to authenticate your public key) using the following command:

        keytool -certreq -alias test -file request.csr -keypass 11111111 -keystore .mykeystore -storepass 11111111 -storetype JKS

        .mykeystore must also contain a self-signed certificate authenticating the server's generated public key. This step will generate the certificate request file, request.csr, under the directory from which the command is run. By submitting request.csr to a CA, the requestor will be authenticated and a signed certificate authenticating the public key will be returned. Save this root certificate to a file named myroot.cer and save the server certificate generated in the previous step to a file named mycert.cer.

      2. Import the certificate returned from the CA using the following command:

        keytool -import -alias test -trustcacerts -file mycert.cer -keypass 11111111 -keystore .mykeystore -storepass 11111111

      3. Import the certificates of any trusted sites (from which you will receive assertions, requests and responses) into your keystore using the following command:

        keytool -import -file myroot.cer -keypass 11111111 -keystore .mykeystore -storepass 11111111

        The data to be imported must be provided either in binary encoding format, or in printable encoding format (also known as Base64) as defined by the Internet RFC 1421 standard. In the latter case, the encoding must be bounded at the beginning by a string that starts with -----BEGIN and bounded at the end by a string that starts with -----END.

  2. Change to the AccessManager-base/SUNWam/bin directory and run the following command:

    ampassword -e original password

    This encrypts the password. The command will return something like AQICKuNVNc9WXxiUyd8j9o/BR22szk8u69ME.

  3. Create a new file named .storepass and put the encrypted password in it.

  4. Create a new file named .keypass and put the encrypted password in it.

  5. Copy .mykeystore to the location specified in AMConfig.properties.

    For example, if com.sun.identity.saml.xmlsig.keystore=/etc/opt/SUNWam/lib/keystore.jks, copy .mykeystore to /etc/opt/SUNWam/lib/ and rename the file to keystore.jks.

  6. Copy .storepass and .keypass to the location specified in AMConfig.properties.

    For example, if com.sun.identity.saml.xmlsig.storepass=/etc/opt/SUNWam/config/.storepass and com.sun.identity.saml.xmlsig.keypass=/etc/opt/SUNWam/config/.keypass, copy both files to /etc/opt/SUNWam/config/.

  7. Define a value for the com.sun.identity.saml.xmlsig.certalias property in AMConfig.properties.

    For this example, the value would be test.

  8. (Optional) If the private key was encrypted using the DSA algorithm, change xmlsigalgorithm=http://www.w3.org/2000/09/xmldsig#rsa-sha1 in AccessManager-base/locale/amSAML.properties to xmlsigalgorithm=http://www.w3.org/2000/09/xmldsig#dsa-sha1.

  9. (Optional) Change the canonicalization method for signing or the transform algorithm for signing by modifying amSAML.properties, located in AccessManager-base/locale/.

    1. Change canonicalizationMethod=http://www.w3.org/2001/10/xml-exc-c14n# to any valid canonicalization method specified in Apache XML security package Version 1.0.5.

      Note –

      If this entry is deleted or left empty, we will use SAMLConstants.ALGO_ID_C14N_OMIT_COMMENTS (required by the XML Signature specification) will be used.

    2. Change transformAlgorithm=http://www.w3.org/2001/10/xml-exc-c14n# to any valid transform algorithm specified in Apache XML security package Version 1.0.5.

      Note –

      If this entry is deleted or left empty, the operation will not be performed.

  10. Restart Access Manager.