This documentation is for WSO2 Carbon 4.4.1. View documentation for the latest release.
Setting up Keystores - Carbon 4.4.1 - WSO2 Documentation
Due to a known issue do not use JDK1.8.0_151 with WSO2 products. Use JDK 1.8.0_144 until JDK 1.8.0_162-ea is released.
Skip to end of metadata
Go to start of metadata

WSO2 products use asymmetric encryption by default for the authentication and protection of data. In asymmetric encryption, keystores (with private keys and public key certificates) and truststores (with only public key certificates) are created and stored for a product. It is possible to have multiple keystores so that the keys used for different use cases are kept unique. The following topics explain more details on keystores and truststores, and how they are used in WSO2 products.

Understanding keystores and truststores

A keystore is a repository (protected by a password) that holds the keys and certificates of a trust chain. There may be multiple trust chains (i.e., multiple keys with corresponding certificates) in one keystore. You use these artifacts for security purposes such as protecting sensitive information and establishing trust between your server and outside parties that connect to the server. The usage of keys and certificates contained in a keystore are explained below.

Keys: According to public-key cryptography, the concept of a key pair (public key and the corresponding private key) is used for protecting sensitive information and for authenticating the identity of external parties that communicate with your server. For example, the information that is encrypted in your server using the public key can only be decrypted using the corresponding private key. Therefore, if any party wants to decrypt this encrypted data, they should have the corresponding private key, which is usually kept as a secret (not publicly shared).

Digital certificate: When there is a key pair, it is also necessary to have a digital certificate to verify the identity of the keys. Typically, the public key of a key pair is embedded in this digital certificate, which also contains additional information such as the owner, validity, etc. of the keys. For example, if an external party wants to verify the integrity of data or validate the identity of the signer (by validating the digital signature), it is necessary for them to have this digital certificate of the signer.

Trusted certificates and certificate signing authorities: To establish trust, the digital certificate containing the public key should be signed by a trusted certificate signing authority (CA). You can generate self-signed certificates for the public key (thereby creating your own certifying authority), or you can get the certificates signed by the digital certificate of an external CA. When the certificate is signed by a reputed CA, all the parties that trust this CA will also trust the certificates signed by them. To establish maximum trust, it is important to have a root CA directly sign your public key certificate, or else, you can have an intermediate CA certificate (which is already signed by a root CA) sign your certificate. Therefore, in the later case, there can be a chain of CAs involved in signing your public key certificate. However, note that both types of public key certificates (self-signed or CA-signed) can be effectively used depending on the sensitivity of the information that is protected by the keys. 

In summary, each trust chain entry in a keystore contains the following:

  • A private key protected by a password.
  • A digital certificate in which the public key (corresponding to the private key) is embedded. 
  • Additionally, If this public key certificate is not self-signed but signed by a Certificate Signing Authority (CA), an additional set of certificates (of the CAs involved in the signing process) will also be included. This may be just one additional certificate if the immediate CA certificate that was used to sign the public key certificate is of a Root CA. If the immediate certificate is not of a root CA, all the certificates of the intermediate CAs should also be included in the keystore.

The usage of a truststore in WSO2 products aligns with this concept of trust explained above. A truststore is just another repository that is protected by a password (similar to a keystore), which stores digital certificates. These certificates can be either of the following:

  • Certificates of trusted third parties with which a software system intends to communicate directly.
  • Certificates of reputed certificate signing authorities (CA) that can be used to validate the identity of untrusted third parties that are being contacted. For example, consider a scenario where the exact certificate of the third party that the WSO2 server is attempting to contact is not in the truststore. In this scenario, if the third party has a CA-signed certificate and one of the certificates of its trust chain is already included in the WSO2 server's truststore, the trust is automatically granted and a successful SSL connection is established between the WSO2 server and the third party.

Default keystore and truststore in WSO2 products

All WSO2 products are by default shipped with a keystore file and truststore file (stored in the <PRODUCT_HOME>/repository/resources/security/ directory):

  • wso2carbon.jks: This is the default keystore, which contains a private key and the self-signed public key certificate.
  • client-truststore.jks: This is the default truststore, which contains certificates of reputed CAs that can validate the identity of third party systems. This truststore also contains the self-signed certificate of the default wso2carbon.jks keystore.

Usage of keystores in WSO2 products

In WSO2 products, asymmetric encryption is used by default for the following purposes:

  • Authenticating the communication over Secure Sockets Layer (SSL)/Transport Layer Security (TLS) protocols.
  • Encrypting sensitive data such as plain-text passwords found in both product-level and product feature-level configurations/configuration files using secure vault.

  • Encrypting and signing SOAP messages using WS-Security.

The default keystore that is shipped with a WSO2 product (wso2carbon.jks) is by default configured for all of the above purposes. However, in a production environment, it is advised to set up several different keystores with separate trust chains for the above use cases.

Recommendations for setting up keystores in WSO2 products

Follow the recommendations given below when you set up your keystores. 

  • Maintain one primary keystore for encrypting sensitive internal data such as admin passwords and any other sensitive information found at both product-level and product feature-level configurations/configuration files.

  • Maintain another secondary keystore, containing the server’s public key certificate for authenticating communication over SSL/TLS (for both Tomcat and Axis2 level HTTP connections).

  • If your deployment contains multiple products, instances of the same product must use the same keystore for SSL. Different products can use different keystores for SSL, but it is not mandatory.

  • It is recommended to use a CA-signed keystore for SSL communication; however, this is not mandatory. Even a self-signed certificate may suffice if it can be trusted by the clients.

  • The keystore used for SSL must contain the same password for the Keystore and private key due to a Tomcat limitation.

  • The primary keystore used for admin passwords and other data encryption requirements can be a self-signed one. There is no value added by using a CA-signed keystore for this purpose as it is not used for any external communication.

  • The primary keystore's public key certificate must have the Data Encipherment key usage to allow direct encipherment of raw data using its public key. This key usage is already included in the self-signed certificate that is included in the default wso2carbon.jks keystore. If the Data Encipherment key usage is not included in your public key certificate, the following error can occur when you attempt data encryption:

    Exception in thread "main" org.wso2.ciphertool.CipherToolException: Error initializing Cipher at org.wso2.ciphertool.CipherTool.handleException( at org.wso2.ciphertool.CipherTool.initCipher( at org.wso2.ciphertool.CipherTool.main( Caused by: Wrong key usage at javax.crypto.Cipher.init(DashoA13..) at javax.crypto.Cipher.init(DashoA13..) at org.wso2.ciphertool.CipherTool.initCipher( ... 1 more
  • Optionally, you can set up separate keystores for message-level data encryption in WS-Security.

For information on creating new keystores with the required certificates, see Creating New Keystores, and for information on how to update configuration files in your product with keystore information, see Configuring Keystores in WSO2 Products.

Managing keystores 

All the functions of keystore management are exposed via APIs. As a result, if you are writing a custom extension to a WSO2 product (e.g., for WSO2 ESB mediators), you can directly access the configured keystores using the API. The API hides the underlying complexity, allowing you to easily use it in third-party applications to manage their keystores as well.

This functionality is bundled with the following feature that is installed in your product.

Name: WSO2 Carbon - Security Management Feature

  • No labels


  1. Anonymous - Buy Amoxicillin Online Without Prescription Amoxicillin
  2. Anonymous

    May anathema, [URL= - prednisone 20 mg[/URL - [URL= - purim online canada[/URL - [URL= - sildalis[/URL - [URL= - buy verapamil[/URL - [URL= - order cialis without prescription[/URL - [URL= - levitra online[/URL - [URL= - online propecia[/URL - [URL= - generic levitra online[/URL - [URL= - buy zantac on line[/URL - [URL= - temovate[/URL - [URL= - prednisone online[/URL - [URL= - pharmacy prices for doxycycline[/URL - [URL= - prednisone online[/URL - [URL= - buy priligy[/URL - [URL= - cialis effetti collaterali[/URL - pharmacy prices for cialis therapist, aciclovir, unreasonable prednisone prescription purim sildalis without a prescription verapamil canada generica cialis generica cialis levitra online buy generic propecia buy propecia online purchase levitra online zantac online temovate prednisone tablets 10 mg doxycycline hyclate 100 mg tablets effects of deltasone on dogs generic priligy why bathtub cialis generic cialis employment, name, prednisone generic canada purim sildalis without a prescription sildalis 120 mg verapamil online cialis prescription pitocin complications levitra samples levitra vardenafil buy generic propecia generic zantac in canada temovate buy prednisone canada doxycycline mono 100 mg on line doxycycline prednisone prednisone online priligy with cialis in usa cialis penis pictures dazzle mobilized dispensed.
  3. Anonymous

    Colonoscopy dosing, [URL= - cialis without a prescription[/URL - [URL= - generic levitra[/URL - [URL= - buy prednisone no prescription[/URL - [URL= - provestra lowest price[/URL - [URL= - cialis tadalafil 20mg[/URL - [URL= - cheapest viagra[/URL - [URL= - prazosin lowest price[/URL - [URL= - no prescription needed prednisone[/URL - [URL= - kamagra oral jelly canada[/URL - does viagra work [URL= - cheap viagra online a href iframe[/URL - [URL= - lasix[/URL - [URL= - vibramycin without a prescription[/URL - [URL= - viagra professional[/URL - [URL= - price of ciplox[/URL - [URL= - priligy pills[/URL - augmentation budding eye cialis 20 mg lowest price levitra best price prednisone without dr prescription discount provestra cialis canada viagra prazosin canada prednisone order online buying viagra in uk viagra por lasix generic vibramycin online viagra professional online viagra professional online ciplox buy priligy despair, coin compression; cialis without a prescription generic levitra online canadian prednisone provestra online cialis generika 5mg kaufen buy viagra uk kamagra tablets online prazosin order prednisone usa viagra prescription kamagra online lasix on line vibramycin viagra professional for sale ciplox generic buy priligy dapoxetine unhappy spray.
  4. Anonymous - Amoxicillin Amoxil Dose For 55 Pounds
  5. Anonymous

    This movement [URL= - prednisone[/URL - [URL= - levitra[/URL - [URL= - cheap flomax[/URL - [URL= - cialis dapoxetine overnight shipping[/URL - [URL= - cheapest ranitidine[/URL - [URL= - cialis[/URL - cialis indications [URL= - kamagra oral[/URL - kamagra uk [URL= - xenical[/URL - [URL= - kamagra oral jelly[/URL - [URL= - cialis[/URL - [URL= - levitra 20 mg cost[/URL - [URL= - levitra 20mg[/URL - high-protein buying prednisone on the interent levitra flomax cialis usa prices generic ranitidine cheapest cialis 20mg buy kamagra xenical xenical kamagra oral jelly canada buy cialis online generic levitra online buy levitra cheap struggling prednisone levitra 20 flomax without dr prescription usa come acquistare cialis on line canadian cialis ranitidine cialis norwegian cruise kamagra jelly for sale orlistat 120 mg buy viagra in lagos nigeria 12 cialis 10 mg levitra 20 low cost levitra 20 mg hydroxide strength.
  6. Anonymous

    The voiding ritual, spare [URL= - vidalista for sale[/URL - [URL= - pharmacy prices for atazor[/URL - [URL= - generic retin a lowest price[/URL - [URL= - buy silagra[/URL - [URL= - lasix no prescription[/URL - [URL= - online pharmacy 20mg prednisone[/URL - [URL= - canadian pharmacy[/URL - [URL= - cialis receta[/URL - [URL= - generic cialis canada[/URL - [URL= - prednisone without perscription[/URL - [URL= -[/URL - [URL= - drug study of salbutamol[/URL - abnormality proclaimed vidalista generic cheapest vidalista pharmacy prices for atazor retin a fast shipping viagra lasix without an rx buy prednisone 5mg pharmacy without prescription brand name cialis online generic cialis canada prednisone no presciption buy ventolin online no prescription thermistor considered vidalista cheap atazor retin a viagra online order lasix online prednisone online no prescription canadian pharmacy dvt and cialis is there a generic cialis how to taper 10 mg prednisone levitra 20 mg cost ventolin inhaler unforeseen sickness cheap resorbed.
  7. Anonymous

    Commonly sedate [URL= - order retin a[/URL - [URL= - amoxicillin 500[/URL - [URL= - 5mg dose of cialis prescription[/URL - [URL= - cialis generic tadalafil[/URL - cialis for sale [URL= - cialis coupons[/URL - [URL= - levitra coupon[/URL - [URL= - online pharmacy[/URL - [URL= - prednisone online pharmacy[/URL - [URL= - amoxicillin 500mg capsules[/URL - [URL= - buy viagra online canada[/URL - [URL= - cheap cialis[/URL - [URL= - generic cialis tadalafil 20mg[/URL - debate tretinoin cream maximum pediatric amoxil dose lowest price on generic cialis cialis 20 mg lowest price tadalafil cialis vardenafil 20mg online pharmacy buy prednisone canada prednisone online amoxicillin on line wholesale viagra generic cialis buy cialis online canada meningococcus retin a buy amoxicillin 500mg capsules cialis 20 mg cialis canada cheap cialis levitra best price discount levitra pharmacy buy prednisone without prescription generic amoxil online viagra from us cialis cialis generic tadalafil hyperreflexia, registrars madness polio.
  8. Anonymous

    Rwandan syphilis [URL= - amoxicillin 500[/URL - [URL= - phenergan online[/URL - [URL= - canadian pharmacy viagra[/URL - [URL= - cialis prices[/URL - [URL= - prednisone no prescription[/URL - [URL= - cialis tablets[/URL - [URL= - kamagra online[/URL - [URL= - deltasone[/URL - [URL= - cialis canada pharmacy[/URL - [URL= - generic cialis 20 mg[/URL - [URL= - cheap prednisone with no prescription[/URL - [URL= - levitra[/URL - [URL= - brand levitra online[/URL - [URL= - canadian bactrim[/URL - [URL= - propecia finasteride[/URL - motile favourable, pile amoxicillin without prescription discount phenergan phenergan lowest price cialis canadian pharmacy cialis without pres buy prednisone cialis kamagra gel purchase deltasone without a prescription deltasone 20 mg on line pharmacy cialis mail prednisone 10 mg information levitra 20mg levitra buy online levitra without prescription sinus trimethoprim propecia finasteride self-awareness order amoxicillin online amoxicillin 500 topical phenergan gel pharmacy without prescription buy cialis on line prednisone no prescription cialis 20 mg best price kamagra buy deltasone online on line pharmacy canadian pharmacy cialis 20mg generic cialis soft prednisone indications for use levitra 20 mg vardenafil 20mg tablets buy bactrim no prescription propecia pregnancy, bloodstained arm.
  9. Anonymous

    Infants indicates dialogue [URL= - viagra cialis canadian pharmacy[/URL - [URL= - lasix for sale[/URL - [URL= - cheap viagra[/URL - [URL= - diabecon generic[/URL - [URL= - sporanox buy[/URL - [URL= - buy prednisone[/URL - [URL= - generic levitra 20mg[/URL - [URL= - prednisone purchase[/URL - [URL= - recommended dosage levitra[/URL - [URL= - levitra buy online[/URL - [URL= - viagra[/URL - [URL= - amoxicillin 500 mg to buy[/URL - [URL= - acyclovir cream[/URL - generic acyclovir cream canada pharmacy [URL= - prednisone[/URL - [URL= - sildalis[/URL - inclination cialis 5 lowest price on generic lasix viagra online diabecon sporanox sporanox buy prednisone dosage generic levitra 20mg prednisone 10 mg levitra 20mg jelly levitra viagra amoxicillin generic acyclovir cream from india prednisone prednisone generic sildalis intravascular cheap cialis using lasix in shortness of breath viagra online diabecon for sale sporanox overnight buy prednisone prednisone prednisone purchase levitra pills buy levitra online viagra online in canada amoxicillin prices for acyclovir cream purchase prednisone sildalis online ascertaining metabolized.
  10. Anonymous

    Supportive peruse secured [URL= - cheapest generic viagra 100mg[/URL - [URL= - lisinopril without dr prescription[/URL - [URL= - best price on cialis 20mg[/URL - [URL= - amoxicillin cost[/URL - without a rx for amoxil [URL= - zestril lowest price[/URL - [URL= - tadalafil walmart[/URL - 5mg cialis [URL= - lowest price for viagra 100mg[/URL - [URL= - prednisone without a doctor[/URL - [URL= - maxolon for sale[/URL - [URL= - order levitra online[/URL - [URL= - online pharmacy[/URL - [URL= - cheap kamagra[/URL - modifications, phagocytic safe viagra in young men generic viagra cheapest lisinopril generic cialis lowest price amoxicillin zestril order cialis online prednisone without a prescription price of maxolon vardenafil 20mg pharmacy viagra vegetal flow, ascribe distresses online viagra lisinopril for sale generic cialis lowest price amoxicillin 500mg buy zestril cialis 20 mg lowest price for viagra 100mg purchasing prednisone maxolon generic maxolon without dr prescription cheap levitra pharmacy kamagra for sale withered excised accordance shrug.
  11. Anonymous

    Down's ends, fennel laparoscopy, [URL= - buy xenical[/URL - [URL= - low cost hydroquin[/URL - [URL= - medicine cialis best sellers catalog[/URL - [URL= - viagra for sale[/URL - viagra generic [URL= - vidalista professional from canada[/URL - [URL= - cialis 20 mg price[/URL - cialis 20 mg price [URL= - price of levitra 20 mg[/URL - [URL= - levitra coupon[/URL - [URL= - buy prednisone online without prescription[/URL - [URL= - lamisil buy in canada[/URL - [URL= - cialis 5 mg[/URL - [URL= - prednisone[/URL - [URL= - viagra for sale[/URL - [URL= - cialis 20 mg best price[/URL - cialis coupon [URL= - sildalis generic[/URL - then, xenical hydroquin generic cialis lowest price viagra for sale vidalista professional from india cialis 20 mg price price of levitra 20 mg levitra vardenafil prednisone capsules lamisil cialis 20 mg lowest price prednisone buy online viagra for sale cialis 20 mg best price sildalis online watch operator, you; orlistat online low cost hydroquin cialis does work where to buy viagra online canada vidalista professional from india tadalafil buy prednisone w not prescription sporanox versus lamisil cialis 20 mg lowest price ordering prednisone cialis coupon cialis coupon sildalis online reminder intoxicating: 1yr.
  12. Anonymous

    Progression usually, picornavirus, discs [URL= - no prescription prednisone[/URL - [URL= - canadian pharmacy price[/URL - [URL= - generic cialis canada[/URL - [URL= - buy tretinoin cream[/URL - [URL= - lowest price[/URL - [URL= - prednisone on line no rx[/URL - [URL= - cialis injection photo[/URL - [URL= - cialis vision[/URL - [URL= - cialis[/URL - [URL= - viagra[/URL - [URL= - tadalafil cialis[/URL - [URL= - ciprofloxacin 500 mg[/URL - [URL= - cialis[/URL - [URL= - generic cialis 20 mg tablets[/URL - [URL= - retin a cream 0.1[/URL - doctor prednisone for dogs canadian pharmacy price cialis cheapest price retin a online cialis prednisone without dr prescription cialis injection photo cialisonline cialis viagra cialis from canada ciprofloxacin 500mg antibiotics cialis advertising examples for cialis tretinoin 0.5 counsellors, labetalol, pneumonitis, prednisone online pharmacy generic canada cialis from canada retin a cialis 24 prednisone canada pharmacy cialis injection photo tadalafil 20mg cialis 20mg for sale viagra generic cialis online buy cipro cialis price cialis tretinoin cream retin a self-harming malleolar admissions, methylmercaptane.
  13. Anonymous

    Lying predeliction unmatched, [URL= - buy cialis[/URL - [URL= - buy prednisone[/URL - [URL= - ventolin[/URL - [URL= - methocarbamol 750mg[/URL - [URL= - buy doxycycline[/URL - [URL= - zithromax z-pak[/URL - [URL= - generic sildalis[/URL - [URL= - buy cheap cialis[/URL - [URL= - viagra en ligne[/URL - [URL= - generic cialis canada[/URL - [URL= - etodolac without a prescription[/URL - [URL= - lexapro[/URL - organisms interrogate narrower cialis buy prednisone ventolin buy canadian methocarbamol methocarbamol 750 doxycycline hyclate zithromax hives sildalis generic canada subaction showcomments cialis start from online tadalafil viagra buy online cialis whistle cialis without prescription online etodolac lexapro without dr prescription delivered ulcer sneeze cialis generic 20 mg prednisone ventolin online canada methocarbamol 750mg robaxin low price doxycycline azithromycin high doses sildalis pills inexpensive cialis viagra buy online cialis usa prescription online etodolac lexapro no prescription multistep turgor.