Package com.chilkatsoft.chilkat2

Class Pem

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.Pem
All Implemented Interfaces:
AutoCloseable
public class Pem extends ChilkatObject
<section class="pem-summary">

Load, inspect, assemble, export, and convert PEM certificate and key material.

Chilkat.Pem is the Chilkat class for handling PEM-formatted certificate and key material. It can load PEM and PKCS#7 data, add certificates, private keys, public keys, CSRs, and certificate chains, retrieve individual items, remove content, control PKCS#1 vs. PKCS#8 private key output, export PEM with optional encryption and extended attributes, and convert PEM material to PFX or Java KeyStore objects.

Load PEM and PKCS#7

Load PEM-encoded certificates, keys, CSRs, and PKCS#7 certificate data from files, strings, or memory.

Collect certs and keys

Add certificates, private keys, public keys, CSRs, and certificate chains into a single PEM container.

Retrieve individual items

Extract selected certificates, keys, CSRs, or chains for use with Cert, PrivateKey, PublicKey, or related Chilkat classes.

Private-key format control

Choose PKCS#1 or PKCS#8 private-key output depending on the format required by the target system.

Encrypted PEM output

Export private-key material with password-based encryption when PEM data must be stored or transferred securely.

Convert to PFX or JKS

Convert PEM certificates and keys into PFX/P12 or Java KeyStore objects when another platform or API requires those container formats.

Common pattern: Use Pem when certificate and key material is packaged as one or more PEM blocks. Load the PEM, inspect or retrieve the needed items, add or remove entries as needed, then export the result as PEM, PFX/P12, or Java KeyStore data. Use Chilkat.Cert, PrivateKey, and PublicKey when working directly with individual objects.

For an extended overview, see Pem Class Overview.

</section>

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Details

    • Pem

      public Pem()
      Creates a new Pem object.

  • Method Details

    • getAppendMode

      public boolean getAppendMode()
      When set to true, each of the Load* methods appends to the current contents of this PEM object. When set to false, a Load* method replaces the contents of this PEM object. The default is false.
      Returns:
      the value of the AppendMode property

    • setAppendMode

      public void setAppendMode​(boolean value)
      Sets the AppendMode property; see getAppendMode().
      Parameters:
      value - the new value

    • getHeartbeatMs

      public int getHeartbeatMs()
      The interval in milliseconds between each AbortCheck event callback, which enables an application to abort certain method calls before they complete. By default, HeartbeatMs is set to 0, meaning no AbortCheck event callbacks will trigger.
      Returns:
      the value of the HeartbeatMs property

    • setHeartbeatMs

      public void setHeartbeatMs​(int value)
      Sets the HeartbeatMs property; see getHeartbeatMs().
      Parameters:
      value - the new value

    • getNumCerts

      public int getNumCerts()
      The number of certificates in the loaded PEM. To get the 1st certificate, call GetCert(0).
      Returns:
      the value of the NumCerts property (read-only)

    • getNumCrls

      public int getNumCrls()
      The number of certificate revocation lists (CRLs) in the loaded PEM.
      Returns:
      the value of the NumCrls property (read-only)

    • getNumCsrs

      public int getNumCsrs()
      The number of certificate signing requests (CSRs) in the loaded PEM.
      Returns:
      the value of the NumCsrs property (read-only)

    • getNumPrivateKeys

      public int getNumPrivateKeys()
      The number of private keys in the loaded PEM. To get the 1st private key, call GetPrivateKey(0).
      Returns:
      the value of the NumPrivateKeys property (read-only)

    • getNumPublicKeys

      public int getNumPublicKeys()
      The number of public keys in the loaded PEM. To get the 1st public key, call GetPublicKey(0).
      Returns:
      the value of the NumPublicKeys property (read-only)

    • getPrivateKeyFormat

      public String getPrivateKeyFormat()
      Controls the format to be used for unencrypted private keys when writing a PEM. Possible values are pkcs1 and pkcs8. (OpenSSL typically uses the pkcs8 format.) When writing encrypted private keys to PEM, the format is always PKCS8, and the PEM header is BEGIN ENCRYPTED PRIVATE KEY. The default is pkcs8.

      The PKCS1 format uses the PEM header: BEGIN RSA PRIVATE KEY.
      The PKCS8 format uses the PEM header: BEGIN PRIVATE KEY.

      Returns:
      the value of the PrivateKeyFormat property

    • setPrivateKeyFormat

      public void setPrivateKeyFormat​(String value)
      Sets the PrivateKeyFormat property; see getPrivateKeyFormat().
      Parameters:
      value - the new value (not null)

    • getPublicKeyFormat

      public String getPublicKeyFormat()
      Controls the format to be used for public keys when writing a PEM. Possible values are pkcs1 and pkcs8. (OpenSSL typically uses the pkcs8 format.) The default is pkcs8.

      The PKCS1 format uses the PEM header: BEGIN RSA PUBLIC KEY.
      The PKCS8 format uses the PEM header: BEGIN PUBLIC KEY.

      Returns:
      the value of the PublicKeyFormat property

    • setPublicKeyFormat

      public void setPublicKeyFormat​(String value)
      Sets the PublicKeyFormat property; see getPublicKeyFormat().
      Parameters:
      value - the new value (not null)

    • addCert

      public void addCert​(Cert cert, boolean includeChain)
      Adds a certificate, and potentially the certs in its chain of authentication to the PEM. If includeChain is true, then certificates in the cert's chain of authentication up to and including the root are automatically added.
      Parameters:
      cert - the cert argument (not null)
      includeChain - the includeChain argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addItem

      public void addItem​(String itemType, String encoding, String itemData)
      Adds a certificate, private key, public key, or csr to the PEM. The possible values for itemType are certificate (or cert), privateKey, publicKey, or csr. The encoding can be Base64, modBase64, Base32, QP (for quoted-printable), URL (for url-encoding), Hex, url_oauth, url_rfc1738, url_rfc2396, and url_rfc3986. The itemData contains the ASN.1 data in string format according to the encoding specified in encoding.
      Parameters:
      itemType - the itemType argument (not null)
      encoding - the encoding argument (not null)
      itemData - the itemData argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addP7b

      public void addP7b​(BinData bd)
      Loads the PEM from the contents of an PKCS7 container (.p7b) contained in bd.

      A .p7b (or .p7c) file contains a PKCS#7 container, which may include:

      • One or more X.509 certificates (a certificate chain)

      • Optionally, CRLs (Certificate Revocation Lists)

      • No private key

      Common Use: Used to bundle intermediate and root certificates for things like SSL certificate chains.

      Parameters:
      bd - the bd argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addPrivateKey

      public void addPrivateKey​(PrivateKey privateKey)
      Adds a private key to the PEM object.
      Parameters:
      privateKey - the privateKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addPrivateKey2

      public void addPrivateKey2​(PrivateKey privKey, CertChain certChain)
      Adds a private key and it's associated certificate chain to the PEM object.
      Parameters:
      privKey - the privKey argument (not null)
      certChain - the certChain argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addPublicKey

      public void addPublicKey​(PublicKey pubkey)
      Adds a public key to the PEM object.
      Parameters:
      pubkey - the pubkey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • certAt

      public void certAt​(int index, Cert cert)
      Returns in cert the Nth certificate from the PEM. The first certificate is at index 0.
      Parameters:
      index - the index argument
      cert - the cert argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • clear

      public void clear()
      Removes all content from this PEM object.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getEncodedItem

      public String getEncodedItem​(String itemType, String itemSubType, String encoding, int index)
      Returns the encoded contents of the Nth item of a particular type (0-based index). The possible values for itemType are certificate (or cert), privateKey, publicKey, or csr. Input string args are case-insensitive. If the itemType is privateKey, the itemSubType may be der or pkcs8. If the itemType is publicKey, the itemSubType may be der or pkcs1. The itemSubType is ignored for other values of itemType. The valid encoding modes are Base64, modBase64, Base32, Base58, QP (for quoted-printable), URL (for url-encoding), Hex, url_oauth, url_rfc1738, url_rfc2396, and url_rfc3986.
      Parameters:
      itemType - the itemType argument (not null)
      itemSubType - the itemSubType argument (not null)
      encoding - the encoding argument (not null)
      index - the index argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadP7bFile

      public void loadP7bFile​(String path)
      Loads the contents of a PKCS7 container (.p7b file).
      Parameters:
      path - the path argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadPem

      public void loadPem​(String pemContent, String password)
      Loads the PEM from a PEM string. If encrypted, then the password is required for decryption. Otherwise, an empty string (or any string) may be passed for the password.
      Parameters:
      pemContent - the pemContent argument (not null)
      password - the password argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadPemFile

      public void loadPemFile​(String path, String password)
      Loads the PEM from a PEM file. If encrypted, then the password is required for decryption. Otherwise, an empty string (or any string) may be passed for the password.
      Parameters:
      path - the path argument (not null)
      password - the password argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • privateKeyAt

      public void privateKeyAt​(int index, PrivateKey privKey)
      Returns in privKey the Nth private key from the PEM. The first private key is at index 0.
      Parameters:
      index - the index argument
      privKey - the privKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • publicKeyAt

      public void publicKeyAt​(int index, PublicKey pubKey)
      Returns in pubKey the Nth public key from the PEM. The first public key is at index 0.
      Parameters:
      index - the index argument
      pubKey - the pubKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • removeCert

      public void removeCert​(int index)
      Removes the Nth certificate from the PEM. The first certificate is at index 0.
      Parameters:
      index - the index argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • removePrivateKey

      public void removePrivateKey​(int index)
      Removes the Nth private key from the PEM. The first private key is at index 0.
      Parameters:
      index - the index argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • toJksObj

      public void toJksObj​(String aliasName, String password, JavaKeyStore jksObj)
      This function converts this PEM to a Java KeyStore (JKS) object and stores it in jksObj. If aliasName is provided, it will be used as the alias for the first object in the PEM (either a private key or certificate), while subsequent objects will receive autogenerated aliases. The resulting JKS will be encrypted with password, unless the PEM contains only certificates, in which case password is not used.
      Parameters:
      aliasName - the aliasName argument (not null)
      password - the password argument (not null)
      jksObj - the jksObj argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • toPem

      public String toPem()
      Write the PFX to a PEM formatted string. The resultant PEM will contain the private key, as well as the certs in the chain of authentication (or whatever certs are available in the PFX). For example: 
       -----BEGIN RSA PRIVATE KEY-----
 ...
 ... the private key associated with the main certificate.
 ...
 -----END RSA PRIVATE KEY-----
 -----BEGIN CERTIFICATE-----
 ...
 ... the main certificate
 ...
 -----END CERTIFICATE-----
 -----BEGIN CERTIFICATE-----
 ...
 ... an intermediate CA certificate (if present)
 ...
 -----END CERTIFICATE-----
 -----BEGIN CERTIFICATE-----
 ...
 ... the root CA certificate
 ...
 -----END CERTIFICATE-----
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • toPemEx

      public String toPemEx​(boolean extendedAttrs, boolean noKeys, boolean noCerts, boolean noCaCerts, String encryptAlg, String password)
      Write the PFX to a PEM formatted string. If extendedAttrs is true, then extended properties (Bag Attributes and Key Attributes) are output. If noKeys is true, then no private keys are output. If noCerts is true, then no certificates are output. If noCaCerts is true, then no CA certs or intermediate CA certs are output. If encryptAlg is not empty, it indicates the encryption algorithm to be used for encrypting the private keys (otherwise the private keys are output unencrypted). The possible choices for the encryptAlg are des3, aes128, aes192, and aes256. (All encryption algorithm choices use CBC mode.) If the private keys are to be encrypted, then password is the password to be used. Otherwise, password may be left empty.

      For example: 

      Bag Attributes
     Microsoft Local Key set: <No Values>
     localKeyID: 01 00 00 00 
     friendlyName: le-2b09a3d2-9037-4a05-95cc-4d44518e8607
     Microsoft CSP Name: Microsoft RSA SChannel Cryptographic Provider
 Key Attributes
     X509v3 Key Usage: 10 
  -----BEGIN RSA PRIVATE KEY-----
 ...
 ... the private key associated with the main certificate.
 ...
 -----END RSA PRIVATE KEY-----
 Bag Attributes
     localKeyID: 01 00 00 00 
     1.3.6.1.4.1.311.17.3.92: 00 08 00 00 
     1.3.6.1.4.1.311.17.3.20: C2 53 54 F3 ...
     1.3.6.1.4.1.311.17.3.71: 49 00 43 00 ...
     1.3.6.1.4.1.311.17.3.75: 31 00 42 00 ...
 subject=/OU=Domain Control Validated/OU=PositiveSSL/CN=something.com
 issuer=/C=GB/ST=Greater Manchester/L=Salford/O=COMODO CA Limited/CN=COMODO RSA Domain Validation Secure Server CA
 -----BEGIN CERTIFICATE-----
 ...
 ... the main certificate
 ...
 -----END CERTIFICATE-----
 ...
 -----BEGIN CERTIFICATE-----
 ...
 ... an intermediate CA certificate (if present)
 ...
 -----END CERTIFICATE-----
 ...
 -----BEGIN CERTIFICATE-----
 ...
 ... the root CA certificate
 ...
 -----END CERTIFICATE-----
      Parameters:
      extendedAttrs - the extendedAttrs argument
      noKeys - the noKeys argument
      noCerts - the noCerts argument
      noCaCerts - the noCaCerts argument
      encryptAlg - the encryptAlg argument (not null)
      password - the password argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • toPfxObj

      public void toPfxObj​(Pfx pfxObj)
      Converts this PEM object, which must contain at least one private key, to PKCS12 and returns the PFX in pfxObj. Typically, a PKCS12 file includes one private key, its associated certificate, and the certificate chain.
      Parameters:
      pfxObj - the pfxObj argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why