net.corda.core.crypto

## Class X509Utilities

- net.corda.core.crypto.X509Utilities

-     public class X509Utilities

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `X509Utilities.CACertAndKey` Helper data class to pass around public certificate and KeyPair entities when using CA certs.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static X509Utilities` | `INSTANCE`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addOrReplaceCertificate(java.security.KeyStore $receiver, java.lang.String alias, java.security.cert.Certificate cert)` Helper extension method to add, or overwrite any public certificate data in store
    `void` | `addOrReplaceKey(java.security.KeyStore $receiver, java.lang.String alias, java.security.Key key, char[] password, java.security.cert.Certificate[] chain)` Helper extension method to add, or overwrite any key data in store
    `java.security.KeyStore` | `createCAKeyStoreAndTrustStore(java.nio.file.Path keyStoreFilePath, java.lang.String storePassword, java.lang.String keyPassword, java.nio.file.Path trustStoreFilePath, java.lang.String trustStorePassword)` All in one wrapper to manufacture a root CA cert and an Intermediate CA cert. Normally this would be run once and then the outputs would be re-used repeatedly to manufacture the server certs
    `org.bouncycastle.pkcs.PKCS10CertificationRequest` | `createCertificateSigningRequest(java.lang.String myLegalName, java.lang.String nearestCity, java.lang.String email, java.security.KeyPair keyPair)` Create certificate signing request using provided information.
    `X509Utilities.CACertAndKey` | `createIntermediateCert(java.lang.String domain, X509Utilities.CACertAndKey certificateAuthority)` Create a de novo root intermediate X509 v3 CA cert and KeyPair.
    `java.security.KeyStore` | `createKeystoreForSSL(java.nio.file.Path keyStoreFilePath, java.lang.String storePassword, java.lang.String keyPassword, java.security.KeyStore caKeyStore, java.lang.String caKeyPassword, java.lang.String commonName)` An all in wrapper to manufacture a server certificate and keys all stored in a KeyStore suitable for running TLS on the local machine
    `X509Utilities.CACertAndKey` | `createSelfSignedCACert(java.lang.String myLegalName)` Create a de novo root self-signed X509 v3 CA cert and KeyPair.
    `java.security.cert.X509Certificate` | `createServerCert(org.bouncycastle.asn1.x500.X500Name subject, java.security.PublicKey publicKey, X509Utilities.CACertAndKey certificateAuthority, java.util.List<java.lang.String> subjectAlternativeNameDomains, java.util.List<java.lang.String> subjectAlternativeNameIps)` Create an X509v3 certificate suitable for use in TLS roles.
    `java.security.KeyPair` | `generateECDSAKeyPairForSSL()` Generate a standard curve ECDSA KeyPair suitable for TLS, although the rest of Corda uses newer curves.
    `java.lang.String` | `getCORDA_CLIENT_CA()`
    `java.lang.String` | `getCORDA_CLIENT_CA_PRIVATE_KEY()`
    `java.lang.String` | `getCORDA_INTERMEDIATE_CA()`
    `java.lang.String` | `getCORDA_INTERMEDIATE_CA_PRIVATE_KEY()`
    `java.lang.String` | `getCORDA_ROOT_CA()`
    `java.lang.String` | `getCORDA_ROOT_CA_PRIVATE_KEY()`
    `org.bouncycastle.asn1.x500.X500Name` | `getDevX509Name(java.lang.String commonName)` Return a bogus X509 for dev purposes. Use getX509Name for something more real.
    `java.lang.String` | `getECDSA_CURVE()`
    `java.lang.String` | `getKEYSTORE_TYPE()`
    `java.lang.String` | `getKEY_GENERATION_ALGORITHM()`
    `java.lang.String` | `getSIGNATURE_ALGORITHM()`
    `org.bouncycastle.asn1.x500.X500Name` | `getX509Name(java.lang.String myLegalName, java.lang.String nearestCity, java.lang.String email)`
    `X509Utilities.CACertAndKey` | `loadCertificateAndKey(java.security.KeyStore keyStore, java.lang.String keyPassword, java.lang.String alias)` Helper method to load a Certificate and KeyPair from their KeyStore. The access details should match those of the createCAKeyStoreAndTrustStore call used to manufacture the keys.
    `java.security.cert.X509Certificate` | `loadCertificateFromKeyStore(java.nio.file.Path keyStoreFilePath, java.lang.String storePassword, java.lang.String alias)` Extract public X509 certificate from a KeyStore file assuming storage alias is know
    `java.security.cert.X509Certificate` | `loadCertificateFromPEMFile(java.nio.file.Path filename)` Helper method to load back a .pem/.cer format file copy of a certificate
    `java.security.KeyPair` | `loadKeyPairFromKeyStore(java.nio.file.Path keyStoreFilePath, java.lang.String storePassword, java.lang.String keyPassword, java.lang.String alias)` Extract public and private keys from a KeyStore file assuming storage alias is known.
    `java.security.KeyStore` | `loadKeyStore(java.nio.file.Path keyStoreFilePath, java.lang.String storePassword)` Helper method to open an existing keystore for modification/read
    `java.security.KeyStore` | `loadKeyStore(java.io.InputStream input, java.lang.String storePassword)` Helper method to open an existing keystore for modification/read
    `java.security.KeyPair` | `loadOrCreateKeyPairFromKeyStore(java.nio.file.Path keyStoreFilePath, java.lang.String storePassword, java.lang.String keyPassword, java.lang.String alias, kotlin.jvm.functions.Function0<net.corda.core.crypto.X509Utilities.CACertAndKey> keyGenerator)` Extract public and private keys from a KeyStore file assuming storage alias is known, or create a new pair of keys using the provided function if the keys not exist.
    `java.security.KeyStore` | `loadOrCreateKeyStore(java.nio.file.Path keyStoreFilePath, java.lang.String storePassword)` Helper method to either open an existing keystore for modification, or create a new blank keystore.
    `void` | `saveCertificateAsPEMFile(java.security.cert.X509Certificate x509Certificate, java.nio.file.Path filename)` Helper method to store a .pem/.cer format file copy of a certificate if required for import into a PC/Mac, or for inspection
    `void` | `saveKeyStore(java.security.KeyStore keyStore, java.nio.file.Path keyStoreFilePath, java.lang.String storePassword)` Helper method save KeyStore to storage

- - ### Field Detail

    - #### INSTANCE

          public static X509Utilities INSTANCE

  - ### Method Detail

    - #### getSIGNATURE_ALGORITHM

          public java.lang.String getSIGNATURE_ALGORITHM()

    - #### getKEY_GENERATION_ALGORITHM

          public java.lang.String getKEY_GENERATION_ALGORITHM()

    - #### getECDSA_CURVE

          public java.lang.String getECDSA_CURVE()

    - #### getKEYSTORE_TYPE

          public java.lang.String getKEYSTORE_TYPE()

    - #### getCORDA_ROOT_CA_PRIVATE_KEY

          public java.lang.String getCORDA_ROOT_CA_PRIVATE_KEY()

    - #### getCORDA_ROOT_CA

          public java.lang.String getCORDA_ROOT_CA()

    - #### getCORDA_INTERMEDIATE_CA_PRIVATE_KEY

          public java.lang.String getCORDA_INTERMEDIATE_CA_PRIVATE_KEY()

    - #### getCORDA_INTERMEDIATE_CA

          public java.lang.String getCORDA_INTERMEDIATE_CA()

    - #### getCORDA_CLIENT_CA_PRIVATE_KEY

          public java.lang.String getCORDA_CLIENT_CA_PRIVATE_KEY()

    - #### getCORDA_CLIENT_CA

          public java.lang.String getCORDA_CLIENT_CA()

    - #### getDevX509Name

          public org.bouncycastle.asn1.x500.X500Name getDevX509Name(java.lang.String commonName)

      Return a bogus X509 for dev purposes. Use getX509Name for something more real.

    - #### getX509Name

          public org.bouncycastle.asn1.x500.X500Name getX509Name(java.lang.String myLegalName,
                                                                 java.lang.String nearestCity,
                                                                 java.lang.String email)

    - #### loadOrCreateKeyStore

          public java.security.KeyStore loadOrCreateKeyStore(java.nio.file.Path keyStoreFilePath,
                                                             java.lang.String storePassword)

      Helper method to either open an existing keystore for modification, or create a new blank keystore.

      Parameters:
        `keyStoreFilePath` - location of KeyStore file
        `storePassword` - password to open the store. This does not have to be the same password as any keys stored, but for SSL purposes this is recommended.
      Returns:
        returns the KeyStore opened/created

    - #### loadKeyStore

          public java.security.KeyStore loadKeyStore(java.nio.file.Path keyStoreFilePath,
                                                     java.lang.String storePassword)

      Helper method to open an existing keystore for modification/read

      Parameters:
        `keyStoreFilePath` - location of KeyStore file which must exist, or this will throw FileNotFoundException
        `storePassword` - password to open the store. This does not have to be the same password as any keys stored, but for SSL purposes this is recommended.
      Returns:
        returns the KeyStore opened

    - #### loadKeyStore

          public java.security.KeyStore loadKeyStore(java.io.InputStream input,
                                                     java.lang.String storePassword)

      Helper method to open an existing keystore for modification/read

      Parameters:
        `input` - stream containing a KeyStore e.g. loaded from a resource file
        `storePassword` - password to open the store. This does not have to be the same password as any keys stored, but for SSL purposes this is recommended.
      Returns:
        returns the KeyStore opened

    - #### saveKeyStore

          public void saveKeyStore(java.security.KeyStore keyStore,
                                   java.nio.file.Path keyStoreFilePath,
                                   java.lang.String storePassword)

      Helper method save KeyStore to storage

      Parameters:
        `keyStore` - the KeyStore to persist
        `keyStoreFilePath` - the file location to save to
        `storePassword` - password to access the store in future. This does not have to be the same password as any keys stored, but for SSL purposes this is recommended.

    - #### addOrReplaceKey

          public void addOrReplaceKey(java.security.KeyStore $receiver,
                                      java.lang.String alias,
                                      java.security.Key key,
                                      char[] password,
                                      java.security.cert.Certificate[] chain)

      Helper extension method to add, or overwrite any key data in store

      Parameters:
        `alias` - name to record the private key and certificate chain under
        `key` - cryptographic key to store
        `password` - password for unlocking the key entry in the future. This does not have to be the same password as any keys stored, but for SSL purposes this is recommended.
        `chain` - the sequence of certificates starting with the public key certificate for this key and extending to the root CA cert

    - #### addOrReplaceCertificate

          public void addOrReplaceCertificate(java.security.KeyStore $receiver,
                                              java.lang.String alias,
                                              java.security.cert.Certificate cert)

      Helper extension method to add, or overwrite any public certificate data in store

      Parameters:
        `alias` - name to record the public certificate under
        `cert` - certificate to store

    - #### generateECDSAKeyPairForSSL

          public java.security.KeyPair generateECDSAKeyPairForSSL()

      Generate a standard curve ECDSA KeyPair suitable for TLS, although the rest of Corda uses newer curves.

      Returns:
        The generated Public/Private KeyPair

    - #### createCertificateSigningRequest

          public org.bouncycastle.pkcs.PKCS10CertificationRequest createCertificateSigningRequest(java.lang.String myLegalName,
                                                                                                  java.lang.String nearestCity,
                                                                                                  java.lang.String email,
                                                                                                  java.security.KeyPair keyPair)

      Create certificate signing request using provided information.

      Parameters:
        `myLegalName` - The legal name of your organization. This should not be abbreviated and should include suffixes such as Inc, Corp, or LLC.
        `nearestCity` - The city where your organization is located.
        `email` - An email address used to contact your organization.
        `keyPair` - Standard curve ECDSA KeyPair generated for TLS.
      Returns:
        The generated Certificate signing request.

    - #### createSelfSignedCACert

          public X509Utilities.CACertAndKey createSelfSignedCACert(java.lang.String myLegalName)

      Create a de novo root self-signed X509 v3 CA cert and KeyPair.

      Returns:
        A data class is returned containing the new root CA Cert and its KeyPair for signing downstream certificates. Note the generated certificate tree is capped at max depth of 2 to be in line with commercially available certificates
      See Also:
        KeyPair

    - #### createIntermediateCert

          public X509Utilities.CACertAndKey createIntermediateCert(java.lang.String domain,
                                                                   X509Utilities.CACertAndKey certificateAuthority)

      Create a de novo root intermediate X509 v3 CA cert and KeyPair.

      Parameters:
        `domain` - The Common (CN) field of the cert Subject will be populated with the domain string
        `certificateAuthority` - The Public certificate and KeyPair of the root CA certificate above this used to sign it
      Returns:
        A data class is returned containing the new intermediate CA Cert and its KeyPair for signing downstream certificates. Note the generated certificate tree is capped at max depth of 1 below this to be in line with commercially available certificates

    - #### createServerCert

          public java.security.cert.X509Certificate createServerCert(org.bouncycastle.asn1.x500.X500Name subject,
                                                                     java.security.PublicKey publicKey,
                                                                     X509Utilities.CACertAndKey certificateAuthority,
                                                                     java.util.List<java.lang.String> subjectAlternativeNameDomains,
                                                                     java.util.List<java.lang.String> subjectAlternativeNameIps)

      Create an X509v3 certificate suitable for use in TLS roles.

      Parameters:
        `subject` - The contents to put in the subject field of the certificate
        `publicKey` - The PublicKey to be wrapped in the certificate
        `certificateAuthority` - The Public certificate and KeyPair of the parent CA that will sign this certificate
        `subjectAlternativeNameDomains` - A set of alternate DNS names to be supported by the certificate during validation of the TLS handshakes
        `subjectAlternativeNameIps` - A set of alternate IP addresses to be supported by the certificate during validation of the TLS handshakes
      Returns:
        The generated X509Certificate suitable for use as a Server/Client certificate in TLS. This certificate is not marked as a CA cert to be similar in nature to commercial certificates.

    - #### saveCertificateAsPEMFile

          public void saveCertificateAsPEMFile(java.security.cert.X509Certificate x509Certificate,
                                               java.nio.file.Path filename)

      Helper method to store a .pem/.cer format file copy of a certificate if required for import into a PC/Mac, or for inspection

      Parameters:
        `x509Certificate` - certificate to save
        `filename` - Target filename

    - #### loadCertificateFromPEMFile

          public java.security.cert.X509Certificate loadCertificateFromPEMFile(java.nio.file.Path filename)

      Helper method to load back a .pem/.cer format file copy of a certificate

      Parameters:
        `filename` - Source filename
      Returns:
        The X509Certificate that was encoded in the file

    - #### loadKeyPairFromKeyStore

          public java.security.KeyPair loadKeyPairFromKeyStore(java.nio.file.Path keyStoreFilePath,
                                                               java.lang.String storePassword,
                                                               java.lang.String keyPassword,
                                                               java.lang.String alias)

      Extract public and private keys from a KeyStore file assuming storage alias is known.

      Parameters:
        `keyStoreFilePath` - Path to load KeyStore from
        `storePassword` - Password to unlock the KeyStore
        `keyPassword` - Password to unlock the private key entries
        `alias` - The name to lookup the Key and Certificate chain from
      Returns:
        The KeyPair found in the KeyStore under the specified alias

    - #### loadOrCreateKeyPairFromKeyStore

          public java.security.KeyPair loadOrCreateKeyPairFromKeyStore(java.nio.file.Path keyStoreFilePath,
                                                                       java.lang.String storePassword,
                                                                       java.lang.String keyPassword,
                                                                       java.lang.String alias,
                                                                       kotlin.jvm.functions.Function0<net.corda.core.crypto.X509Utilities.CACertAndKey> keyGenerator)

      Extract public and private keys from a KeyStore file assuming storage alias is known, or create a new pair of keys using the provided function if the keys not exist.

      Parameters:
        `keyStoreFilePath` - Path to load KeyStore from
        `storePassword` - Password to unlock the KeyStore
        `keyPassword` - Password to unlock the private key entries
        `alias` - The name to lookup the Key and Certificate chain from
        `keyGenerator` - Function for generating new keys
      Returns:
        The KeyPair found in the KeyStore under the specified alias

    - #### loadCertificateFromKeyStore

          public java.security.cert.X509Certificate loadCertificateFromKeyStore(java.nio.file.Path keyStoreFilePath,
                                                                                java.lang.String storePassword,
                                                                                java.lang.String alias)

      Extract public X509 certificate from a KeyStore file assuming storage alias is know

      Parameters:
        `keyStoreFilePath` - Path to load KeyStore from
        `storePassword` - Password to unlock the KeyStore
        `alias` - The name to lookup the Key and Certificate chain from
      Returns:
        The X509Certificate found in the KeyStore under the specified alias

    - #### createCAKeyStoreAndTrustStore

          public java.security.KeyStore createCAKeyStoreAndTrustStore(java.nio.file.Path keyStoreFilePath,
                                                                      java.lang.String storePassword,
                                                                      java.lang.String keyPassword,
                                                                      java.nio.file.Path trustStoreFilePath,
                                                                      java.lang.String trustStorePassword)

      All in one wrapper to manufacture a root CA cert and an Intermediate CA cert. Normally this would be run once and then the outputs would be re-used repeatedly to manufacture the server certs

      Parameters:
        `keyStoreFilePath` - The output KeyStore path to publish the private keys of the CA root and intermediate certs into.
        `storePassword` - The storage password to protect access to the generated KeyStore and public certificates
        `keyPassword` - The password that protects the CA private keys. Unlike the SSL libraries that tend to assume the password is the same as the keystore password. These CA private keys should be protected more effectively with a distinct password.
        `trustStoreFilePath` - The output KeyStore to place the Root CA public certificate, which can be used as an SSL truststore
        `trustStorePassword` - The password to protect the truststore
      Returns:
        The KeyStore object that was saved to file

    - #### loadCertificateAndKey

          public X509Utilities.CACertAndKey loadCertificateAndKey(java.security.KeyStore keyStore,
                                                                  java.lang.String keyPassword,
                                                                  java.lang.String alias)

      Helper method to load a Certificate and KeyPair from their KeyStore. The access details should match those of the createCAKeyStoreAndTrustStore call used to manufacture the keys.

      Parameters:
        `keyStore` - Source KeyStore to look in for the data
        `keyPassword` - The password for the PrivateKey (not the store access password)
        `alias` - The name to search for the data. Typically if generated with the methods here this will be one of CERT_PRIVATE_KEY_ALIAS, ROOT_CA_CERT_PRIVATE_KEY_ALIAS, INTERMEDIATE_CA_PRIVATE_KEY_ALIAS defined above

    - #### createKeystoreForSSL

          public java.security.KeyStore createKeystoreForSSL(java.nio.file.Path keyStoreFilePath,
                                                             java.lang.String storePassword,
                                                             java.lang.String keyPassword,
                                                             java.security.KeyStore caKeyStore,
                                                             java.lang.String caKeyPassword,
                                                             java.lang.String commonName)

      An all in wrapper to manufacture a server certificate and keys all stored in a KeyStore suitable for running TLS on the local machine

      Parameters:
        `keyStoreFilePath` - KeyStore path to save output to
        `storePassword` - access password for KeyStore
        `keyPassword` - PrivateKey access password for the generated keys. It is recommended that this is the same as the storePassword as most TLS libraries assume they are the same.
        `caKeyStore` - KeyStore containing CA keys generated by createCAKeyStoreAndTrustStore
        `caKeyPassword` - password to unlock private keys in the CA KeyStore
      Returns:
        The KeyStore created containing a private key, certificate chain and root CA public cert for use in TLS applications