Package com.chilkatsoft.chilkat2

Class Csr

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

Create, load, inspect, and verify Certificate Signing Requests.

Chilkat.Csr is the Chilkat class for working with Certificate Signing Requests. It can create CSRs from RSA or ECDSA private keys, set common certificate subject fields, add custom subject fields by OID, include Subject Alternative Names, request certificate extensions, export CSRs in PEM or DER format, load existing CSRs, extract the public key, inspect SAN values, and verify the CSR signature.

Create CSRs

Generate certificate signing requests using RSA or ECDSA private keys and the subject fields required by the certificate authority.

Subject fields

Set common X.509 subject fields such as common name, organization, organizational unit, locality, state, country, and email address.

Custom OID fields

Add custom subject attributes by object identifier when a certificate authority or application profile requires nonstandard fields.

Subject Alternative Names

Include DNS names, IP addresses, email addresses, URIs, or other SAN entries needed for modern TLS and identity certificates.

Extension requests

Request certificate extensions that the issuing CA may include in the final certificate.

Inspect and verify

Load an existing CSR, extract its public key, inspect requested names and fields, and verify that the CSR signature is valid.

Common pattern: Create or load a private key, populate the subject and SAN values required by the certificate authority, generate the CSR in PEM or DER format, submit it to the CA, and keep the private key secure because it will be needed when using the issued certificate.

For an extended overview, see Csr 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

    • Csr

      public Csr()
      Creates a new Csr object.

  • Method Details

    • getCommonName

      public String getCommonName()
      Gets or sets the subject common name (CN), OID 2.5.4.3, for the CSR. For a TLS server request this has traditionally been a DNS hostname; for other certificate profiles it may identify a person, device, service, or organization.

      Chilkat requires this property when generating a CSR. The exact value and validation rules are determined by the certificate authority and certificate profile.

      Do not use CN as a substitute for SAN: For modern TLS certificates, add every DNS hostname or IP address through addSan(String, String). Current TLS identity verification uses Subject Alternative Name entries, and the common name is retained primarily for compatibility and display.

      Returns:
      the value of the CommonName property

    • setCommonName

      public void setCommonName​(String value)
      Sets the CommonName property; see getCommonName().
      Parameters:
      value - the new value (not null)

    • getCompany

      public String getCompany()
      Gets or sets the subject organization name (O), OID 2.5.4.10. For organization-validated certificate profiles, this is typically the legal or verified organization name.

      This property is optional at the PKCS #10 level, but a certificate authority may require it or replace it with a value established during identity validation.

      Returns:
      the value of the Company property

    • setCompany

      public void setCompany​(String value)
      Sets the Company property; see getCompany().
      Parameters:
      value - the new value (not null)

    • getCompanyDivision

      public String getCompanyDivision()
      Gets or sets the subject organizational unit name (OU), OID 2.5.4.11. It may identify a department, division, team, or other unit within the organization.

      This property is optional. Some public certificate profiles restrict or omit organizational-unit values, so follow the requirements of the receiving CA.

      Returns:
      the value of the CompanyDivision property

    • setCompanyDivision

      public void setCompanyDivision​(String value)
      Sets the CompanyDivision property; see getCompanyDivision().
      Parameters:
      value - the new value (not null)

    • getCountry

      public String getCountry()
      Gets or sets the subject country name (C), OID 2.5.4.6. The value is normally a two-letter uppercase ISO 3166-1 country code, such as US, CA, or DE.

      This property is optional unless required by the certificate authority's enrollment profile.

      X.520 encoding: The country-name attribute is defined as a two-character PrintableString. Do not place a full country name such as United States in this field.

      Returns:
      the value of the Country property

    • setCountry

      public void setCountry​(String value)
      Sets the Country property; see getCountry().
      Parameters:
      value - the new value (not null)

    • getEmailAddress

      public String getEmailAddress()
      Gets or sets the legacy PKCS #9 emailAddress subject attribute, OID 1.2.840.113549.1.9.1. This property is optional.

      Prefer an email SAN for email identity: The subject-DN emailAddress attribute is permitted for legacy compatibility but is deprecated in the Internet X.509 profile. When the certificate must identify an email address, also use addSan(String, String) with rfc822Name, as required by the target certificate profile.

      Returns:
      the value of the EmailAddress property

    • setEmailAddress

      public void setEmailAddress​(String value)
      Sets the EmailAddress property; see getEmailAddress().
      Parameters:
      value - the new value (not null)

    • getHashAlgorithm

      public String getHashAlgorithm()
      Gets or sets the message-digest algorithm used when signing a generated CSR. Supported values are sha1, sha256, sha384, and sha512. The default is sha256.

      This property selects the digest for the CSR's proof-of-possession signature. It does not select the signature algorithm that the certificate authority will use on the issued certificate.

      Avoid SHA-1 for new requests: Use sha256 or stronger unless a legacy enrollment system explicitly requires SHA-1. The digest must also be compatible with the supplied key type and the receiving CA.

      Returns:
      the value of the HashAlgorithm property

    • setHashAlgorithm

      public void setHashAlgorithm​(String value)
      Sets the HashAlgorithm property; see getHashAlgorithm().
      Parameters:
      value - the new value (not null)

    • getLocality

      public String getLocality()
      Gets or sets the subject locality name (L), OID 2.5.4.7. This usually identifies a city, town, or other local jurisdiction.

      This property is optional unless required by the certificate authority's enrollment profile.

      Returns:
      the value of the Locality property

    • setLocality

      public void setLocality​(String value)
      Sets the Locality property; see getLocality().
      Parameters:
      value - the new value (not null)

    • getMgfHashAlg

      public String getMgfHashAlg()
      Gets or sets the hash algorithm used by MGF1 in an RSASSA-PSS CSR signature. This property applies only when the private key is RSA and getPssPadding() is true.

      Supported values are sha256, sha384, and sha512. The default is sha256.

      Common choice: For straightforward interoperability, set this to the same digest selected by getHashAlgorithm() unless the receiving profile explicitly specifies different RSASSA-PSS parameters.

      Returns:
      the value of the MgfHashAlg property

    • setMgfHashAlg

      public void setMgfHashAlg​(String value)
      Sets the MgfHashAlg property; see getMgfHashAlg().
      Parameters:
      value - the new value (not null)

    • getPssPadding

      public boolean getPssPadding()
      Controls the RSA signature scheme used when generating a CSR with an RSA private key. When true, Chilkat signs using RSASSA-PSS. When false, the RSA signature uses the traditional RSASSA-PKCS1-v1_5 scheme. This property has no effect for elliptic-curve keys.

      Related settings: getHashAlgorithm() selects the digest of the certification-request information. When PSS is enabled, getMgfHashAlg() selects the digest used by MGF1. Interoperability: RSASSA-PSS is a modern RSA signature scheme, but the receiving CA or enrollment protocol must support PSS algorithm parameters in PKCS #10 requests.

      Returns:
      the value of the PssPadding property

    • setPssPadding

      public void setPssPadding​(boolean value)
      Sets the PssPadding property; see getPssPadding().
      Parameters:
      value - the new value

    • getState

      public String getState()
      Gets or sets the subject state or province name (ST, sometimes displayed as S), OID 2.5.4.8.

      This property is optional unless required by the certificate authority. Use the full jurisdiction name expected by the CA, such as Illinois, rather than assuming an abbreviation is accepted.

      Returns:
      the value of the State property

    • setState

      public void setState​(String value)
      Sets the State property; see getState().
      Parameters:
      value - the new value (not null)

    • addSan

      public void addSan​(String sanType, String sanValue)
      Adds one Subject Alternative Name to the CSR that will be generated. Call this method once for each name to request. The SAN values are carried as requested certificate extensions; the issuing certificate authority decides whether to validate and include them in the final certificate.

      sanType Meaning and example

      dnsName A DNS hostname, such as www.example.com or an allowed wildcard such as *.example.com.

      IPAddress An IPv4 or IPv6 address, such as 192.0.2.10 or 2001:db8::10.

      rfc822Name An Internet email address, such as user@example.com.

      uniformResourceIndicator A URI. This is Chilkat's accepted keyword; the X.509 GeneralName field is formally named uniformResourceIdentifier.

      directoryName An X.500 distinguished name.

      registeredID A registered object identifier.

      otherName, x400Address, ediPartyName Less common X.509 GeneralName forms used by specialized profiles.

      TLS server certificates: Put every DNS name and IP address that clients must validate in the SAN extension. Modern TLS identity checking uses dNSName and iPAddress SAN entries rather than relying on the subject common name.

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

    • genCsrBd

      public void genCsrBd​(PrivateKey privKey, BinData csrData)
      Generates a PKCS #10 Certificate Signing Request using the supplied RSA or elliptic-curve private key and writes the binary DER representation to csrData.

      The generated request uses the subject fields, Subject Alternative Names, extension request, and signature settings currently configured on this object. The DER bytes are the same request data that would appear as the Base64 body returned by genCsrPem(PrivateKey).

      DER versus PEM: DER is the binary ASN.1 encoding of the CSR. PEM is that DER data encoded as Base64 with certificate-request header and footer lines. Use DER for binary protocols such as EST when required by the receiving system.

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

    • genCsrPem

      public String genCsrPem​(PrivateKey privKey)
      Generates a PKCS #10 Certificate Signing Request using the supplied PrivateKey and the subject fields, Subject Alternative Names, extension request, and signature settings currently configured on this object. The private key may be RSA or elliptic-curve (ECDSA).

      On success, returns the CSR in PEM form, normally enclosed by -----BEGIN CERTIFICATE REQUEST----- and -----END CERTIFICATE REQUEST----- lines. The Base64 body is the DER-encoded PKCS #10 request.

      What a CSR contains: A CSR contains the subject name, the public key derived from privKey, optional attributes such as requested extensions, and a signature made with the corresponding private key. The private key itself is never included. Signature settings: getHashAlgorithm() selects the digest. For RSA keys, getPssPadding() and getMgfHashAlg() control whether RSASSA-PSS is used and which MGF1 digest is encoded in its parameters.

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

    • getExtensionRequest

      public void getExtensionRequest​(Xml extensionReqXml)
      Retrieves the PKCS #9 extensionRequest attribute, OID 1.2.840.113549.1.9.14, from the currently loaded CSR. When present, the requested extensions are loaded into extensionReqXml as Chilkat ASN.1 XML.

      CSR contents only: The returned XML describes extensions requested by the applicant. It does not show which extensions a certificate authority ultimately accepted or placed in an issued certificate.

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

    • getPublicKey

      public void getPublicKey​(PublicKey pubkey)
      Copies the public key contained in the currently loaded CSR into pubkey. The resulting PublicKey object is independent of the CSR and contains no private-key material.

      Proof of possession: A PKCS #10 request is signed with the private key corresponding to this public key. Use verifyCsr() to check that relationship; merely extracting the public key does not verify the CSR signature.

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

    • getSans

      public void getSans​(StringTable sans)
      Retrieves the Subject Alternative Names requested by the currently loaded CSR and writes them to the supplied StringTable.

      Requested, not issued: These values are taken from the CSR's extension-request data. They describe what the applicant asked the CA to place in the certificate, not what a CA has validated or will necessarily issue.

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

    • getSubjectField

      public String getSubjectField​(String oid)
      Returns the value of a subject distinguished-name attribute from the currently loaded or configured CSR, identified by its object identifier. For example, OID 2.5.4.9 identifies streetAddress.

      OID-based lookup: The short names commonly displayed in certificate tools, such as CN, O, OU, and C, are labels for specific OIDs. This method uses the numeric OID so uncommon or application-specific attributes can also be retrieved.

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

    • loadCsrPem

      public void loadCsrPem​(String csrPemStr)
      Loads a PEM-encoded PKCS #10 Certificate Signing Request. On success, the subject properties and retrieval methods on this object reflect the values contained in the loaded request, including its public key, Subject Alternative Names, and extension-request attribute when present.

      Loading is not verification: Parsing a CSR does not prove that its signature is valid. Call verifyCsr() to verify that the request was signed by the private key corresponding to the public key carried in the CSR. No private key is loaded: A PKCS #10 request contains only the public key and signature. The applicant must retain the original private key separately for use with the certificate issued by the CA.

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

    • setExtensionRequest

      public void setExtensionRequest​(Xml extensionReqXml)
      Sets the PKCS #9 extensionRequest attribute, OID 1.2.840.113549.1.9.14, for the CSR to be generated. extensionReqXml supplies the requested X.509 extensions as ASN.1 represented in Chilkat XML form.

      Purpose of extensionRequest: PKCS #10 has no certificate-extension field of its own. Requested X.509 extensions, such as Subject Alternative Name, key usage, or extended key usage, are commonly carried in this signed attribute. A request is not a command: The certificate authority may ignore, modify, reject, or independently validate any requested extension according to its enrollment profile and security policy.

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

    • setSubjectField

      public void setSubjectField​(String oid, String value, String asnType)
      Sets a subject distinguished-name attribute identified by oid. For example, OID 2.5.4.9 identifies streetAddress. Use the dedicated properties such as getCommonName(), getCompany(), and getCountry() for the commonly used subject attributes.

      asnType specifies the ASN.1 string type used to encode the value and may be UTF8String, IA5String, or PrintableString. Use UTF8String unless the attribute definition or certificate-authority profile requires another type.

      ASN.1 type Typical use

      UTF8String General Unicode text and the preferred default for most modern directory attributes.

      IA5String ASCII-based attributes whose schema specifically requires IA5String, such as the legacy PKCS #9 emailAddress attribute.

      PrintableString Attributes constrained to the limited PrintableString character set, such as the X.520 country name.

      Schema matters: The OID determines the attribute's meaning and permitted syntax. A value can be valid text yet still be rejected by a CA if the selected ASN.1 type, length, or format does not match that attribute's schema or the CA's enrollment policy.

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

    • verifyCsr

      public void verifyCsr()
      Verifies the digital signature on the currently loaded CSR using the public key embedded in that request. Returns true when the signature is cryptographically valid; otherwise returns false.

      What this proves: Successful verification shows that the request was signed using the private key corresponding to the included public key and that the signed request data has not been altered. What this does not prove: Signature verification does not validate the applicant's identity, confirm control of a DNS name or email address, approve requested extensions, establish trust, or issue a certificate. Those checks and policy decisions belong to the certificate authority.

      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why