27

I've heard conflicting information about the purpose of the alias attribute in Java keystore files. Can someone please clarify on what exactly this attribute is, and what it should be set to when creating a new java keystore for leaf and intermediate certs in a regular Web server chain?

I used to think that alias was just a unique identifier for each entry in a jks file, and as such the leaf would have a different alias from an intermediate cert. Now, I'm not so sure. Can someone clarify?

Mike B
  • 3,336
  • 4
  • 29
  • 39
  • Afaik (and according to the documentation https://docs.oracle.com/javase/8/docs/api/java/security/KeyStore.html) it is an identifier. Can you please add the source of confusion, i.e. what would be the other purpose of the alias? – bayo May 23 '16 at 07:08

4 Answers4

19

ALIAS

To answer your immediate question, the alias field should be a unique string to identify the key entry. This applies to all types such a trusted and intermediate.

Documentation

Keytool

KeyStore Aliases

All keystore entries (key and trusted certificate entries) are accessed via unique aliases.

An alias is specified when you add an entity to the keystore using the -genseckey command to generate a secret key, -genkeypair command to generate a key pair (public and private key) or the -importcert command to add a certificate or certificate chain to the list of trusted certificates. Subsequent keytool commands must use this same alias to refer to the entity.

For example, suppose you use the alias duke to generate a new public/private key pair and wrap the public key into a self-signed certificate (see Certificate Chains) via the following command:

keytool -genkeypair -alias duke -keypass dukekeypasswd

This specifies an initial password of "dukekeypasswd" required by subsequent commands to access the private key assocated with the alias duke. If you later want to change duke's private key password, you use a command like the following:

`keytool -keypasswd -alias duke -keypass dukekeypasswd -new newpass`

This changes the password from "dukekeypasswd" to "newpass".

Please note: A password should not actually be specified on a command line or in a script unless it is for testing purposes, or you are on a secure system. If you don't specify a required password option on a command line, you will be prompted for it

Standards and Practices

I don't think there is any set naming standard and I'm sure you can talk to 10 different people and get 10 different answers. You just want it unique and logical.

The API and Oracle's Keytool don't do a great job of checking for duplicates which is a particular oversight in my opinion considering it's used to identify each entry in a key store.

The best way to resolve duplicates is to generate a new keystore, and add each entry from the old keystore to the new one with unique alias'. You can iterate over the keystore and use its timestamp to identify different certs in a store.

Joel
  • 103
  • 2
Shane Andrie
  • 3,780
  • 1
  • 13
  • 16
  • How unique? Are we talking GUID unique? Or more like namespace unique? What is the scope of uniqueness? Knowing that would help in trying to figure out a naming convention. – morphatic Sep 17 '17 at 16:40
  • 1
    Unique enough that when a certificate is added, you can find it via KeyTool. I'd suggest starting with the FQDN or SAN of the cert. Unique is only unique to you and your team since Keytool and such don't check if the alias already exists. Remember you want to be able to pull it from Keytool with out having to decipher which cert is which, – Shane Andrie Sep 20 '17 at 14:20
  • 1
    Actually keyool does validate alias uniqueness; I get an error every time I use the an existing alias with something like a "-genkeypair" or "-import". – galaxis Nov 05 '18 at 16:07
3

I had exactly the same question, and you phrased the issue perfectly clearly. My understanding after experimentation (regrettable that the documentation doesn't state this clearly) is:

  1. Aliases are not single-object identifiers; you may use the same alias for a key and a cert entry in a keystore, without one wiping out the other.

  2. Indeed, you must use the same alias for a key and its associated cert, to tie them together. Other certs in the chain should have different aliases, with reasonable names of your choice to identify them.

I am not an expert at this, so take my answer with the right grain of salt, pls.

Clint Staley
  • 31
  • 2
1

in a keystore/truststore you can have more keys/certificates and every key has an alias. If you have to configure the SSL in a server, usually you configure the keystore, the keystore-password, the key password and the alias. Basically with the alias you refer which key you intend to use.

Example with jboss wildfly 8

<security-realm name="SSLClientCertRealm">    
    <server-identities>
        <ssl>
            <keystore path="server-ssl.keystore" relative-to="jboss.server.config.dir" keystore-password="keystore" alias="alias_name" key-password="keystore"/>
        </ssl>
    </server-identities>
Community
  • 1
rkn
  • 49
  • 3
1

Your question isn't very clear, but answering one possibility:

The KeyStore API abstractly and the JKS format concretely has two kinds of entries relevant to SSL/TLS: the privateKey entry for a server contains the privatekey and the cert chain (leaf and intermediate(s) and usually root) all under one alias; trustedCert entries (if any) contain certs for other parties, usually CAs, each under a different alias

Programmatically the different certs in the chain of a privateKey entry are obtained by keystore.getCertificateChain(alias)[0] = leaf, [1] = first intermediate, etc.

dave_thompson_085
  • 9,759
  • 1
  • 24
  • 28