Package com.chilkatsoft.chilkat2

Class Cert

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

Load, inspect, validate, and use X.509 certificates throughout Chilkat.

Chilkat.Cert is the central certificate object used throughout Chilkat for TLS, S/MIME, PKCS7/CMS, PDF signing, XML signing, code signing, decryption, certificate stores, smart cards, HSMs, PKCS#11, and cloud-based signing. It provides a broad set of features for loading certificates, inspecting certificate fields, checking validity, accessing private keys, building chains, checking revocation status, exporting certificate data, and diagnosing certificate-related problems.

Load certificates

Load public certificates from PEM, DER, Base64, files, strings, binary data, certificate stores, PFX/P12 files, smart cards, and other sources.

Inspect certificate details

Read subject and issuer fields, serial numbers, fingerprints, validity dates, key usage, extensions, SAN values, and other X.509 information.

Private key access

Work with certificates backed by private keys from PFX/P12 files, OS certificate stores, smart cards, HSMs, PKCS#11 modules, or cloud signing providers.

Trust and validation

Build and inspect certificate chains, verify signatures, check expiration, examine trust-related information, and work with revocation data.

Use across Chilkat

Pass Cert objects to other Chilkat classes for TLS client authentication, S/MIME, signing, encryption, decryption, and verification.

Export and diagnostics

Export certificate data in common formats and use detailed diagnostic output to troubleshoot loading, validation, private-key, chain, or store problems.

Common pattern: Use certificate-only formats such as PEM or DER when only the public certificate is needed. Use PFX/P12, an OS certificate store, smart-card loading, PKCS#11 linking, HSM integration, or cloud-signing configuration when a private key operation is required.

For an extended overview, see Cert Class Overview.

</section>

Event-capable: long-running methods report progress through a ProgressListener installed with setProgressListener(ProgressListener), onAbortCheck(BooleanSupplier), onPercentDone(IntPredicate) or onProgressInfo(BiConsumer).

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

    • Cert

      public Cert()
      Creates a new Cert object.

  • Method Details

    • getAuthorityKeyId

      public String getAuthorityKeyId()
      The authority key identifier of the certificate in base64 string format. This is only present if the certificate contains the extension OID 2.5.29.35.
      Returns:
      the value of the AuthorityKeyId property (read-only)

    • getAvoidWindowsPkAccess

      public boolean getAvoidWindowsPkAccess()
      Applies only when running on a Microsoft Windows operating system. If true, then any method that returns a certificate will not try to also access the associated private key, assuming one exists. This is useful if the certificate was installed with high-security such that a private key access would trigger the Windows OS to display a security warning dialog. The default value of this property is false.
      Returns:
      the value of the AvoidWindowsPkAccess property

    • setAvoidWindowsPkAccess

      public void setAvoidWindowsPkAccess​(boolean value)
      Sets the AvoidWindowsPkAccess property; see getAvoidWindowsPkAccess().
      Parameters:
      value - the new value

    • getCertVersion

      public int getCertVersion()
      The version of the certificate (1, 2, or 3). A value of 0 indicates an error -- the most likely cause being that the certificate object is empty (i.e. was never loaded with a certificate). Note: This is not the version of the software, it is the version of the X.509 certificate object. The version of the Chilkat certificate software is indicated by the Version property.
      Returns:
      the value of the CertVersion property (read-only)

    • getExpired

      public boolean getExpired()
      Has a value of true if the certificate or any certificate in the chain of authority has expired. (This information is not available when running on Windows 95/98 computers.)
      Returns:
      the value of the Expired property (read-only)

    • getExtendedKeyUsage

      public String getExtendedKeyUsage()
      Returns a string containing a comma separated list of keywords with the extended key usages of the certificate. The list of possible extended key usages are:
      • serverAuth - TLS WWW server authentication
      • clientAuth - TLS WWW client authentication
      • codeSigning - Signing of downloadable executable code
      • emailProtection - Email protection
      • timeStamping - Binding the hash of an object to a time
      • OCSPSigning - Signing OCSP responses

      Returns:
      the value of the ExtendedKeyUsage property (read-only)

    • getForClientAuthentication

      public boolean getForClientAuthentication()
      true if this certificate can be used for client authentication, otherwise false.
      Returns:
      the value of the ForClientAuthentication property (read-only)

    • getForCodeSigning

      public boolean getForCodeSigning()
      true if this certificate can be used for code signing, otherwise false.
      Returns:
      the value of the ForCodeSigning property (read-only)

    • getForSecureEmail

      public boolean getForSecureEmail()
      true if this certificate can be used for sending secure email, otherwise false.
      Returns:
      the value of the ForSecureEmail property (read-only)

    • getForServerAuthentication

      public boolean getForServerAuthentication()
      true if this certificate can be used for server authentication, otherwise false.
      Returns:
      the value of the ForServerAuthentication property (read-only)

    • getForTimeStamping

      public boolean getForTimeStamping()
      true if this certificate can be used for time stamping, otherwise false.
      Returns:
      the value of the ForTimeStamping property (read-only)

    • getIntendedKeyUsage

      public long getIntendedKeyUsage()
      Bitflags indicating the intended usages of the certificate. The flags are:
      Digital Signature: 0x80
      Non-Repudiation: 0x40
      Key Encipherment: 0x20
      Data Encipherment: 0x10
      Key Agreement: 0x08
      Certificate Signing: 0x04
      CRL Signing: 0x02
      Encipher-Only: 0x01
      Returns:
      the value of the IntendedKeyUsage property (read-only)

    • getIsRoot

      public boolean getIsRoot()
      true if this is the root certificate, otherwise false.
      Returns:
      the value of the IsRoot property (read-only)

    • getIssuerC

      public String getIssuerC()
      The certificate issuer's country.
      Returns:
      the value of the IssuerC property (read-only)

    • getIssuerCN

      public String getIssuerCN()
      The certificate issuer's common name.
      Returns:
      the value of the IssuerCN property (read-only)

    • getIssuerDN

      public String getIssuerDN()
      The issuer's full distinguished name.
      Returns:
      the value of the IssuerDN property (read-only)

    • getIssuerE

      public String getIssuerE()
      The certificate issuer's email address.
      Returns:
      the value of the IssuerE property (read-only)

    • getIssuerL

      public String getIssuerL()
      The certificate issuer's locality, which could be a city, count, township, or other geographic region.
      Returns:
      the value of the IssuerL property (read-only)

    • getIssuerO

      public String getIssuerO()
      The certificate issuer's organization, which is typically the company name.
      Returns:
      the value of the IssuerO property (read-only)

    • getIssuerOU

      public String getIssuerOU()
      The certificate issuer's organizational unit, which is the unit within the organization.
      Returns:
      the value of the IssuerOU property (read-only)

    • getIssuerS

      public String getIssuerS()
      The certificate issuer's state or province.
      Returns:
      the value of the IssuerS property (read-only)

    • getOcspUrl

      public String getOcspUrl()
      If present in the certificate's extensions, returns the OCSP URL of the certificate. (The Online Certificate Status Protocol (OCSP) is an Internet protocol used for obtaining the revocation status of an X.509 digital certificate.)
      Returns:
      the value of the OcspUrl property (read-only)

    • getPrivateKeyExportable

      public boolean getPrivateKeyExportable()
      (Relevant only when running on a Microsoft Windows operating system.) Indicates whether the private key was installed with security settings that allow it to be re-exported.
      Returns:
      the value of the PrivateKeyExportable property (read-only)

    • getRevoked

      public boolean getRevoked()
      Deprecated: This property does not check the revocation status of the certificate, and always returns false. Do not use it to decide whether a certificate is revoked.

      To check whether a certificate has been revoked, call checkRevoked() (Windows only), which returns 1 (revoked), 0 (not revoked), or -1 (unable to check). Applications on any operating system can also send an OCSP request to the certificate's getOcspUrl(), if the certificate has one.

      (A property cannot do this work because checking revocation can require contacting a CRL distribution point or an OCSP responder over the network, which can take a long time. In some programming languages, properties are evaluated at design time in the IDE.)

      Note: Chilkat does not check certificate revocation status during the TLS handshake. Settings such as RequireSslCertVerify verify signatures, expiration, and the chain to a trusted root, but not revocation. To reject a revoked server certificate, the application must check it after connecting.

      Returns:
      the value of the Revoked property (read-only)

    • getRfc822Name

      public String getRfc822Name()
      The RFC822 name of the certificate. (The RFC822 name is one part of the Subject Alternative Name extension of a certificate, if it exists. It is often the only part of the SAN.)

      If the certificate contains a list of RFC822 names then this property will return the comma separated list of names.

      Starting in Chilkat v9.5.0.85, to get the complete Subject Alternative Name extension as XML, use the SubjectAlternativeName property.

      Returns:
      the value of the Rfc822Name property (read-only)

    • getSelfSigned

      public boolean getSelfSigned()
      true if this is a self-signed certificate, otherwise false.
      Returns:
      the value of the SelfSigned property (read-only)

    • getSerialDecimal

      public String getSerialDecimal()
      The certificate's serial number as a decimal string.
      Returns:
      the value of the SerialDecimal property (read-only)

    • getSerialNumber

      public String getSerialNumber()
      The certificate's serial number as a hexidecimal string.
      Returns:
      the value of the SerialNumber property (read-only)

    • getSha1Thumbprint

      public String getSha1Thumbprint()
      Hexidecimal string of the SHA-1 thumbprint for the certificate. (This is the SHA1 hash of the binary DER representation of the entire X.509 certificate.)
      Returns:
      the value of the Sha1Thumbprint property (read-only)

    • getSignatureVerified

      public boolean getSignatureVerified()
      Returns true if the certificate and all certificates in the chain of authority have valid signatures, otherwise returns false.
      Returns:
      the value of the SignatureVerified property (read-only)

    • getSmartCardFailReason

      public int getSmartCardFailReason()
      Set after calling LoadFromSmartcard. Possible values are:
      • 0 - No failure. The call to LoadFromSmartcard was successful.
      • 1 - No smartcard or USB token was detected.
      • 2 - The SmartCardPin was provided and the PIN login failed. (Note: Chilkat only PIN authenticates if PKCS11 was the chosen means for communicating with the smartcard.)
      • 3 - The certificate matching the specified criteria was not found.
      • 99 - Some other undefined failure. Consult the LastErrorText for more information.

      Returns:
      the value of the SmartCardFailReason property (read-only)

    • getSmartCardNoDialog

      public boolean getSmartCardNoDialog()
      If set to true, then no dialog will automatically popup if the SmartCardPin is incorrect. Instead, the method requiring the private key on the smart card will fail. The default value of this property is false, which means that if the SmartCardPin property is incorrect, a dialog with prompt will be displayed.
      Returns:
      the value of the SmartCardNoDialog property

    • setSmartCardNoDialog

      public void setSmartCardNoDialog​(boolean value)
      Sets the SmartCardNoDialog property; see getSmartCardNoDialog().
      Parameters:
      value - the new value

    • getSmartCardPin

      public String getSmartCardPin()
      Can be set to the PIN value for a certificate / private key stored on a smart card.
      Returns:
      the value of the SmartCardPin property

    • setSmartCardPin

      public void setSmartCardPin​(String value)
      Sets the SmartCardPin property; see getSmartCardPin().
      Parameters:
      value - the new value (not null)

    • getSubjectAlternativeName

      public String getSubjectAlternativeName()
      The subject alternative name (SAN) name of the certificate returned as XML. See the examples linked below.
      Returns:
      the value of the SubjectAlternativeName property (read-only)

    • getSubjectC

      public String getSubjectC()
      The certificate subject's country.
      Returns:
      the value of the SubjectC property (read-only)

    • getSubjectCN

      public String getSubjectCN()
      The certificate subject's common name.
      Returns:
      the value of the SubjectCN property (read-only)

    • getSubjectDN

      public String getSubjectDN()
      The certificate subject's full distinguished name.
      Returns:
      the value of the SubjectDN property (read-only)

    • getSubjectE

      public String getSubjectE()
      The certificate subject's email address.
      Returns:
      the value of the SubjectE property (read-only)

    • getSubjectKeyId

      public String getSubjectKeyId()
      The subject key identifier of the certificate in base64 string format. This is only present if the certificate contains the extension OID 2.5.29.14.
      Returns:
      the value of the SubjectKeyId property (read-only)

    • getSubjectL

      public String getSubjectL()
      The certificate subject's locality, which could be a city, count, township, or other geographic region.
      Returns:
      the value of the SubjectL property (read-only)

    • getSubjectO

      public String getSubjectO()
      The certificate subject's organization, which is typically the company name.
      Returns:
      the value of the SubjectO property (read-only)

    • getSubjectOU

      public String getSubjectOU()
      The certificate subject's organizational unit, which is the unit within the organization.
      Returns:
      the value of the SubjectOU property (read-only)

    • getSubjectS

      public String getSubjectS()
      The certificate subject's state or province.
      Returns:
      the value of the SubjectS property (read-only)

    • getTrustedRoot

      public boolean getTrustedRoot()
      Returns true if the certificate has a trusted root authority, otherwise returns false.

      Note: As of version 9.5.0.41, the notion of what your application deems as trusted becomes more specific. The TrustedRoots class/object was added in v9.5.0.0. Prior to this, a certificate was considered to be anchored by a trusted root if the certificate chain could be established to a root (self-signed) certificate, AND if the root certificate was located somewhere in the Windows registry-based certificate stores. There are two problems with this: (1) it's a Windows-only solution. This property would always return false on non-Windows systems, and (2) it might be considered not a strong enough set of conditions for trusting a root certificate.

      As of version 9.5.0.41, this property pays attention to the new TrustedRoots class/object, which allows for an application to specificallly indicate which root certificates are to be trusted. Certificates may be added to the TrustedRoots object via the LoadCaCertsPem or AddCert methods, and then activated by calling the TrustedRoots.Activate method. The activated trusted roots are deemed to be trusted in any Chilkat API method/property that needs to make this determination. In addition, the TrustedRoots object has a property named TrustSystemCaRoots, which defaults to true, which allows for backward compatibility. It will trust CA certificates stored in the Windows registry-based certificate stores, or if on Linux, will trust certificates found in /etc/ssl/certs/ca-certificates.crt.

      Returns:
      the value of the TrustedRoot property (read-only)

    • getUncommonOptions

      public String getUncommonOptions()
      This is a catch-all property to be used for uncommon needs. This property defaults to the empty string, and should typically remain empty. Possible comma separated keywords can include:
      • CheckRevokedCacheOnly: Added in v11.2.0. In the CheckRevoked method, prevents network access and only checks the cached revocation information on the local computer.

      Returns:
      the value of the UncommonOptions property

    • setUncommonOptions

      public void setUncommonOptions​(String value)
      Sets the UncommonOptions property; see getUncommonOptions().
      Parameters:
      value - the new value (not null)

    • getValidFromStr

      public String getValidFromStr()
      The date (in RFC822 string format) that this certificate becomes (or became) valid. It is a GMT/UTC date that is returned.
      Returns:
      the value of the ValidFromStr property (read-only)

    • getValidToStr

      public String getValidToStr()
      The date (in RFC822 string format) that this certificate expires. It is a GMT/UTC date that is returned.
      Returns:
      the value of the ValidToStr property (read-only)

    • buildCertChain

      public void buildCertChain​(CertChain certChain)
      Builds the certificate chain in certChain containing all the certificates (including this one), in the chain of authentication to the trusted root (if possible). If this certificate object was loaded from a PFX, then the certiicates contained in the PFX are automatically available for building the certificate chain. The UseCertVault method can be called to provide additional certificates that might be required to build the cert chain. Finally, the TrustedRoots object can be used to provide a way of making trusted root certificates available.

      Note: Returns true even if certificate chain is not completed to the root. The certificate chain's ReachesRoot property can be examined to see if the chain was completed to the root.

      On Windows systems, the registry-based certificate stores are automatically consulted if needed to locate intermediate or root certificates in the chain. Chilkat searches certificate stores in the following order. See System Store Locations for more information.

      1. Current-User CA Certificate Store
      2. Local-Machine CA Certificate Store
      3. Current-User Root Certificate Store
      4. Local-Machine Root Certificate Store
      5. Current-User MY Certificate Store
      6. Local-Machine MY Certificate Store
      7. Current-User ADDRESSBOOK Certificate Store (if it exists)
      8. Local-Machine ADDRESSBOOK Certificate Store (if it exists)

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

    • checkRevoked

      public int checkRevoked()
      Returns 1 if the certificate has been revoked, 0 if not revoked, and -1 if unable to check the revocation status.

      Note: This method is only implemented on Windows systems. It uses the underlying Microsoft CertVerifyRevocation Platform SDK function to check the revocation status of a certificate. (Search CertVerifyRevocation to get information about it.) Starting in v11.2.0, the keyword "CheckRevokedCacheOnly" can be included in the UncommonOptions to prevent the Microsoft revocation handler from accessing any network based resources for revocation checking. In other words, just check the cached revocation information on the local computer.

      CertVerifyRevocation can use the certificate's CRL distribution points as well as OCSP. If it returns -1, see the LastErrorText. One cause is that the issuing intermediate CA certificate is not present in the Windows certificate store.

      Non-Windows (and Windows) applications can send an OCSP request as shown in the example below. Note that some CAs publish revocation status only through CRLs, not OCSP. For example, Let's Encrypt removed the OCSP URL from its certificates in May 2025 and shut down its OCSP responders in August 2025, so an OCSP request is not possible for current Let's Encrypt certificates.

      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • checkSmartCardPin

      public int checkSmartCardPin()
      Verifies that the SmartCardPin property setting is correct. Returns 1 if correct, 0 if incorrect, and -1 if unable to check because the underlying CSP does not support the functionality.
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • exportCertDerBd

      public void exportCertDerBd​(BinData cerData)
      Exports the digital certificate in ASN.1 DER format to a BinData object.
      Parameters:
      cerData - the cerData argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • exportCertDerFile

      public void exportCertDerFile​(String path)
      Exports the digital certificate to ASN.1 DER format binary file.
      Parameters:
      path - the path argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • exportCertPem

      public String exportCertPem()
      Exports the digital certificate to an unencrypted PEM formatted string.
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • exportCertPemFile

      public void exportCertPemFile​(String path)
      Exports the digital certificate to an unencrypted PEM formatted file.
      Parameters:
      path - the path argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • exportCertXml

      public String exportCertXml()
      Exports a certificate to an XML format where the XML tags are the names of the ASN.1 objects that compose the X.509 certificate. Binary data is either hex or base64 encoded. (The binary data for a bits ASN.1 tag is hex encoded, whereas for all other ASN.1 tags, such as octets, it is base64.)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • exportToPfxBd

      public void exportToPfxBd​(String password, boolean includeCertChain, BinData pfxData)
      Exports the certificate and private key (if available) to pfxData. The password is what will be required to access the PFX contents at a later time. If includeCertChain is true, then the certificates in the chain of authority are also included in the PFX.
      Parameters:
      password - the password argument (not null)
      includeCertChain - the includeCertChain argument
      pfxData - the pfxData argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • exportToPfxFile

      public void exportToPfxFile​(String pfxFilename, String pfxPassword, boolean bIncludeCertChain)
      Exports the certificate and private key (if available) to a PFX (.pfx or .p12) file. The output PFX is secured using the pfxPassword. If bIncludeCertChain is true, then the certificates in the chain of authority are also included in the PFX output file.
      Parameters:
      pfxFilename - the pfxFilename argument (not null)
      pfxPassword - the pfxPassword argument (not null)
      bIncludeCertChain - the bIncludeCertChain argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • findIssuer

      public Cert findIssuer()
      Finds and returns the issuer certificate. If the certificate is a root or self-issued, then the certificate returned is a copy of the caller certificate. (The IsRoot property can be check to see if the certificate is a root (or self-issued) certificate.)
      Returns:
      a new Cert owned by the caller, or null if not found (no exception is thrown in that case); close it when done

    • getEncoded

      public String getEncoded()
      Returns a base64 encoded string representation of the certificate's binary DER format, which can be passed to SetFromEncoded to recreate the certificate object.
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getExtensionAsText

      public String getExtensionAsText​(String oid)
      Returns the certificate extension data as a string. This method should only be called for those extensions with text values NOT stored as binary ASN.1. In most cases, applications should call GetExtensionAsXml because most extensions contain ASN.1 values that need to be decoded..
      Parameters:
      oid - the oid argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getExtensionAsXml

      public String getExtensionAsXml​(String oid)
      Returns the certificate extension data in XML format (converted from ASN.1). The oid is an OID, such as the ones listed here: http://www.alvestrand.no/objectid/2.5.29.html

      Note: In many cases, the data within the XML is returned base64 encoded. An application may need to take one further step to base64 decode the information contained within the XML.

      Parameters:
      oid - the oid argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getExtensionBd

      public void getExtensionBd​(String oid, BinData bd)
      Returns the certificate extension data specified by oid in bd.
      Parameters:
      oid - the oid argument (not null)
      bd - the bd argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getIssuer

      public void getIssuer​(Cert issuer)
      Finds and returns the issuer certificate in issuer. If the certificate is a root or self-issued, then the certificate returned is a copy of the caller certificate. (The IsRoot property can be check to see if the certificate is a root (or self-issued) certificate.)
      Parameters:
      issuer - the issuer argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getPrivateKey

      public void getPrivateKey​(PrivateKey privKey)
      Loads the privKey with the certificate's private key, if it exists. Returns false if the certificate has no associated private key.
      Parameters:
      privKey - the privKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getPrivateKeyPem

      public String getPrivateKeyPem()
      Exports the certificate's private key to a PEM string (if the private key is available).
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getPubKeyDer

      public void getPubKeyDer​(boolean preferPkcs1, BinData bd)
      Loads the bd with the certificate's public key in ASN.1 DER format. If the key type (such as RSA) supports both PKCS1 and PKCS8 formats, then preferPkcs1 selects which format to return.
      Parameters:
      preferPkcs1 - the preferPkcs1 argument
      bd - the bd argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getPublicKey

      public void getPublicKey​(PublicKey pubKey)
      Loads the pubKey with the certificate's public key.
      Parameters:
      pubKey - the pubKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getSignature

      public void getSignature​(BinData bd)
      Loads the bd with the certificate's signature.
      Parameters:
      bd - the bd argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getSpkiFingerprint

      public String getSpkiFingerprint​(String hashAlg, String encoding)
      Returns the SPKI Fingerprint suitable for use in pinning. (See RFC 7469.) An SPKI Fingerprint is defined as the output of a known cryptographic hash algorithm whose input is the DER-encoded ASN.1 representation of the Subject Public Key Info (SPKI) of an X.509 certificate. The hashAlg specifies the hash algorithm and may be sha256, sha384, sha512, sha1, md2, md5, haval, ripemd128, ripemd160,ripemd256, or ripemd320. The encoding specifies the encoding, and may be base64, hex, or any of the encoding modes specified in the article at the link below.
      Parameters:
      hashAlg - the hashAlg argument (not null)
      encoding - the encoding argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getSubjectPart

      public String getSubjectPart​(String partNameOrOid)
      Returns a part of the certificate's subject by name or OID. The partNameOrOid can be a part name, such as CN, O, OU, E, S, L, C, or SERIALNUMBER, or it can be an OID such as 2.5.4.3.
      Parameters:
      partNameOrOid - the partNameOrOid argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • hasPrivateKey

      public boolean hasPrivateKey()
      Returns true if a private key associated with the certificate is available.
      Returns:
      the result; this method never throws ChilkatException

    • hashOf

      public String hashOf​(String part, String hashAlg, String encoding)
      Returns an encoded hash of a particular part of the certificate. The part may be one of the following:
      • IssuerDN
      • IssuerPublicKey
      • SubjectDN
      • SubjectPublicKey

      The hashAlg is the name of the hash algorithm, such as sha1, sha256, sha384, sha512, md5, etc. The encoding is the format to return, such as hex, base64, etc.

      Parameters:
      part - the part argument (not null)
      hashAlg - the hashAlg argument (not null)
      encoding - the encoding argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • isEcdsa

      public boolean isEcdsa()
      Returns true if certificate is ECDSA-based (i.e. has an ECDSA key).
      Returns:
      the result; this method never throws ChilkatException

    • isRsa

      public boolean isRsa()
      Returns true if certificate is RSA-based (i.e. has an RSA key).
      Returns:
      the result; this method never throws ChilkatException

    • linkPkcs11

      public void linkPkcs11​(Pkcs11 session)
      Links to the certificate's private key located on an HSM (smart card, token, or cloud HSM). Once linked, the certificate can be used for signing where the signing occurs on the HSM. See the example below for more detailed information.
      Parameters:
      session - the session argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadByCommonName

      public void loadByCommonName​(String cn)
      This method searches for a certificate with the specified common name (CN) on different operating systems.

      - On Windows, it searches the Local Machine and Current User certificate stores. - On macOS and iOS, it searches the Default and System Keychains.

      If the certificate is found, it is loaded and ready for use.

      Note: Chilkat v10.0.0 or later is needed for Apple Keychain.

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

    • loadByEmailAddress

      public void loadByEmailAddress​(String emailAddress)
      This method searches for a certificate with the specified email address on different operating systems.

      - On Windows, it searches the Local Machine and Current User certificate stores. - On macOS and iOS, it searches the Default and System Keychains.

      If the certificate is found, it is loaded and ready for use.

      Note: Chilkat v10.0.0 or later is needed for Apple Keychain.

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

    • loadByIssuerAndSerialNumber

      public void loadByIssuerAndSerialNumber​(String issuerCN, String serialNumber)
      This method searches for a certificate with the specified issuer common name (issuerCN) and serial number (serialNumber) on different operating systems.

      - On Windows, it searches the Local Machine and Current User certificate stores. - On macOS and iOS, it searches the Default and System Keychains.

      If the certificate is found, it is loaded and ready for use.

      Note: Chilkat v10.0.0 or later is needed for Apple Keychain.

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

    • loadBySubjectOid

      public void loadBySubjectOid​(String oid, String value)
      This method searches for a certificate containing a subject part matching the oid and value.

      On Windows, it searches the Local Machine and Current User certificate stores. - On macOS and iOS, it searches the Default and System Keychains.

      If the certificate is found, it is loaded and ready for use.

      Note: Chilkat v10.0.0 or later is needed for Apple Keychain.

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

    • loadByThumbprint

      public void loadByThumbprint​(String thumbprint, String encoding)
      This method searches for a certificate with the specified thumbprint. The thumbprint is passed as a string using the encoding specified by encoding (such as base64, hex, etc.).

      On Windows, it searches the Local Machine and Current User certificate stores. - On macOS and iOS, it searches the Default and System Keychains.

      If the certificate is found, it is loaded and ready for use.

      Note: Chilkat v10.0.0 or later is needed for Apple Keychain.

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

    • loadFromBase64

      public void loadFromBase64​(String encodedCert)
      Loads an ASN.1 or DER encoded certificate represented in a Base64 string.
      Parameters:
      encodedCert - the encodedCert argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadFromBd

      public void loadFromBd​(BinData certBytes)
      Loads an X.509 certificate from data contained in certBytes.

      Note: The certBytes may contain the certificate in any format. It can be binary DER (ASN.1), PEM, Base64, etc. Chilkat will automatically detect the format.

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

    • loadFromFile

      public void loadFromFile​(String path)
      Loads a certificate from a .cer, .crt, .p7b, or .pem file. This method accepts certificates from files in any of the following formats:
      1. DER encoded binary X.509 (.CER)
      2. Base-64 encoded X.509 (.CER)
      3. Cryptographic Message Syntax Standard - PKCS #7 Certificates (.P7B)
      4. PEM format
      This method decodes the certificate based on the contents if finds within the file, and not based on the file extension. If your certificate is in a file having a different extension, try loading it using this method before assuming it won't work. This method does not load .p12 or .pfx (PKCS #12) files.
      Parameters:
      path - the path argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadFromSmartcard

      public void loadFromSmartcard​(String certSpec)
      Important: It's important to set the SmartCardPin property before calling this method.

      Loads a certificate and its associated private key (if available) from a connected USB token or smart card. This function works on Windows, Linux, MacOS, iOS, and Alpine Linux. If multiple USB tokens and/or smartcards are connected to the system, then each will be searched and the first matching certificate will be loaded.

      The certSpec can have the following formats and values:

      • Empty String: Passing the empty string is the most common way to call this function. Pass the empty string when only one HSM (USB token or smart card) is connected to the system, and it contains only one certificate with a private key. The HSM can contain other certificates, but Chilkat will automatically choose and load the certificate that has the associated private key also located on the HSM.
      • cn=<cert subject common name>: Finds and loads the certificate having the specified subject common name (CN).
      • subjectdn_withtags=<distinguished name with tags>: Finds and loads the certificate having the specified DN with tags. For example, subjectdn_withtags=C=US, O=Example Corporation, OU=IT Department, CN=www.example.com
      • subjectdn=<distinguished name without tags>: Finds and loads the certificate having the specified DN without tags. For example, subjectdn=US, California, San Francisco, Example Corp, Engineering, www.example.com, support@example.com
      • issuercn=<subject hex serial:issuer common name>: Finds and loads the certificate having the specified hex serial number and an issuer with the specified common name. For example, 01020304: Let's Encrypt Authority X1
      • serial=<hex serial number>: Finds and loads the certificate having the specified hexidecimal serial number.
      • thumbprint=<hex SHA1 thumbprint>: Finds and loads the certificate having the specified hexidecimal SHA1 thumbprint.
      • policyoid=<certificate policy OID>: Finds and loads the certificate having a policy OID equal to the specified value, such as 2.16.840.1.101.2.1.11.39.
      • o=<subject organization>: Finds and loads the certificate having the O subject part equal to the specified value.
      • c=<subject country>: Finds and loads the certificate having the C subject part equal to the specified value.
      • l=<subject locality>: Finds and loads the certificate having the L subject part equal to the specified value.
      • ou=<subject organizational unit>: Finds and loads the certificate having the OU subject part equal to the specified value.
      • st=<subject state>: Finds and loads the certificate having the ST subject part equal to the specified value.
      • e=<subject email>: Finds and loads the certificate having the E subject part equal to the specified value.

      On Windows systems, certSpec can specify a CSP (Cryptographic Service Provider) name, such as YubiHSM Key Storage Provider. This option is retained for legacy support, as Chilkat initially handled USB tokens and smartcards only on Windows via CSPs. Chilkat now supports HSMs across multiple platforms (Windows, Linux, macOS, iOS, Alpine Linux) and uses various methods to communicate with HSMs, including PKCS11, macOS Keychain services, Windows ScMinidriver, MsCNG, and legacy Windows CryptoAPI. Chilkat automatically detects the HSM make/model and selects the optimal communication method.

      Some possible CSP values are:

      • Microsoft Smart Card Key Storage Provider
      • Microsoft Base Smart Card Crypto Provider
      • Bit4id Universal Middleware Provider
      • YubiHSM Key Storage Provider (starting in v9.5.0.83)
      • SafeSign Standard Cryptographic Service Provider
      • SafeSign Standard RSA and AES Cryptographic Service Provider
      • eToken Base Cryptographic Provider
      • cryptoCertum3 CSP
      • FTSafe ePass1000 RSA Cryptographic Service Provider
      • SecureStoreCSP
      • EnterSafe ePass2003 CSP v2.0
      • Gemalto Classic Card CSP
      • PROXKey CSP India V1.0
      • PROXKey CSP India V2.0
      • TRUST KEY CSP V1.0
      • Watchdata Brazil CSP V1.0
      • Luna Cryptographic Services for Microsoft Windows
      • Luna SChannel Cryptographic Services for Microsoft Windows
      • Safenet RSA Full Cryptographic Provider
      • nCipher Enhanced Cryptographic Provider
      • MySmartLogon NFC CSP
      • NFC Connector Enterprise
      • ActivClient Cryptographic Service Provider
      • EnterSafe ePass2003 CSP v1.0
      • Oberthur Card Systems Cryptographic Provider
      • Athena ASECard Crypto CSP
      • many others...

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

    • loadPem

      public void loadPem​(String strPem)
      Loads the certificate from a PEM string.
      Parameters:
      strPem - the strPem argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadPfxBd

      public void loadPfxBd​(BinData pfxData, String password)
      Loads the certificate from the PFX contained in pfxData. Note: If the PFX contains multiple certificates, the 1st certificate in the PFX is loaded.
      Parameters:
      pfxData - the pfxData argument (not null)
      password - the password argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadPfxFile

      public void loadPfxFile​(String pfxPath, String password)
      Loads a PFX file. Note: If the PFX contains multiple certificates, the 1st certificate in the PFX is loaded.
      Parameters:
      pfxPath - the pfxPath argument (not null)
      password - the password argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • pemFileToDerFile

      public void pemFileToDerFile​(String fromPath, String toPath)
      Converts a PEM file to a DER file.
      Parameters:
      fromPath - the fromPath argument (not null)
      toPath - the toPath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • saveToFile

      public void saveToFile​(String path)
      Saves a certificate object to a .cer file.
      Parameters:
      path - the path argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setCloudSigner

      public void setCloudSigner​(JsonObject json)
      Provides information for a cloud signing service to do the signing via a remote signing server. Current supported services are AWS KMS, Azure Key Vault, and ARSS (Aruba Remote Signing Service). See the examples below.
      Parameters:
      json - the json argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setFromEncoded

      public void setFromEncoded​(String encodedCert)
      Initializes the certificate object from a base64 encoded string representation of the certificate's binary DER format.
      Parameters:
      encodedCert - the encodedCert argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setPrivateKey

      public void setPrivateKey​(PrivateKey privKey)
      Used to associate a private key with the certificate for subsequent (PKCS7) signature creation or decryption.
      Parameters:
      privKey - the privKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setPrivateKeyPem

      public void setPrivateKeyPem​(String privKeyPem)
      Same as SetPrivateKey, but the key is provided in unencrypted PEM format. (Note: The privKeyPem is not a file path, it is the actual PEM text.)
      Parameters:
      privKeyPem - the privKeyPem argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • unload

      public void unload()
      Unload the certificate, which could mean closing a PKCS11 session if the certificate was loaded from a smart card.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • uploadToCloud

      public void uploadToCloud​(JsonObject jsonIn, JsonObject jsonOut)
      This is an open-ended method to accomodate uploading the private key to a cloud service, such as AWS KMS, or Azure Key Vault. For details, see the examples below.
      Parameters:
      jsonIn - the jsonIn argument (not null)
      jsonOut - the jsonOut argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • useCertVault

      public void useCertVault​(XmlCertVault vault)
      Adds an XML certificate vault to the object's internal list of sources to be searched for certificates for help in building certificate chains and verifying the certificate signature to the trusted root.
      Parameters:
      vault - the vault argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • verifySignature

      public boolean verifySignature()
      Verifies the certificate signature, as well as the signatures of all certificates in the chain of authentication to the trusted root. Returns true if all signatures are verified to the trusted root. Otherwise returns false.
      Returns:
      the result; this method never throws ChilkatException

    • x509PKIPathv1

      public String x509PKIPathv1()
      Returns the base64 representation of an X509PKIPathv1 containing just the calling certificate. This is typically used in an X.509 Binary Security Token. It is a PKIPath that contains an ordered list of X.509 public certificates packaged in a PKIPath. The X509PKIPathv1 token type may be used to represent a certificate path. (This is sometimes used in XAdES signatures.)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setProgressListener

      public void setProgressListener​(ProgressListener listener)
      Installs the listener that receives this object's progress events (abortCheck, percentDone, progressInfo) during its long-running methods; replaces any listener or lambda installed before; null removes it.
      Parameters:
      listener - the listener, or null
      Throws:
      IllegalStateException - if called from inside one of this object's own callbacks

    • getProgressListener

      public ProgressListener getProgressListener()
      Returns the installed listener, or null.
      Returns:
      the listener installed with setProgressListener(ProgressListener) or one of the on... methods

    • onAbortCheck

      public void onAbortCheck​(BooleanSupplier callback)
      Installs a listener whose only callback is abortCheck: called every HeartbeatMs milliseconds during a long-running method; return true to abort it. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener

    • onPercentDone

      public void onPercentDone​(IntPredicate callback)
      Installs a listener whose only callback is percentDone: called with the completion percentage (0..100) as a long-running method progresses; return true to abort it. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener

    • onProgressInfo

      public void onProgressInfo​(BiConsumer<String,​String> callback)
      Installs a listener whose only callback is progressInfo: called with a name/value pair of progress information as a long-running method proceeds. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener