com.prosysopc.ua

Class ApplicationIdentity

java.lang.Object

com.prosysopc.ua.SecureIdentity

com.prosysopc.ua.ApplicationIdentity

public class ApplicationIdentity
extends SecureIdentity

ApplicationIdentity defines the security settings for the OPC UA application. These are used when a new Session is created. Use Mode to define the selected security level to use. SecurityKeys define the application instance certificate generated for the installed application.

See Also:

UserIdentity

Field Summary

Fields

Modifier and Type	Field and Description
static String	CERT_FILE_EXTENSIONS

Fields inherited from class com.prosysopc.ua.SecureIdentity

certificate, privateKey

Constructor Summary

Constructors

Constructor and Description
ApplicationIdentity() Create a new empty identity.
ApplicationIdentity(Cert certificate, PrivKey privateKey) Create a new identity
ApplicationIdentity(File certificateFile, File privateKeyFile, String privateKeyPassword) Create an identity with an application certificate.
ApplicationIdentity(File storeLocation, String alias, String privateKeyPassword, String keyStorePassword, String keyStoreType) Create an identity with an application certificate.
ApplicationIdentity(KeyPair... keyPairs) Create an identity with one or more application certificate.
ApplicationIdentity(URL certificateFile, URL privateKeyFile, String privateKeyPassword) Create an identity with an application certificate.

Method Summary

Modifier and Type	Method and Description
void	addSoftwareCertificates(SignedSoftwareCertificate[] softwareCertificates) Deprecated. this method does nothing as the serverSoftwareCertificates parameter of CreateSessionResponse is deprecated in UA 1.04
static ApplicationIdentity	createCertificate(ApplicationDescription applicationDescription, String organisation, int keySize, String... hostNames) Create a new self-signed Application Identity certificate.
static ApplicationIdentity	createCertificate(ApplicationDescription applicationDescription, String organisation, KeyPair issuerKeys, int keySize, String... hostNames) Create a new Application Identity certificate.
static ApplicationIdentity	createCertificate(ApplicationDescription applicationDescription, String organisation, KeyPair issuerKeys, String... hostNames) Deprecated. this method depend on static state. Call createCertificate(ApplicationDescription, String, KeyPair, int, String...) instead.
static ApplicationIdentity	createCertificate(ApplicationDescription applicationDescription, String organisation, String... hostNames) Deprecated. this method depends on static state. Call createCertificate(ApplicationDescription, String, int, String...) instead.
static ApplicationIdentity	createCertificate(String applicationName, String organisation, KeyPair issuerKeys, String applicationUri, int keySize, String... hostNames) Create the Application Identity certificate.
static ApplicationIdentity	createCertificate(String applicationName, String organisation, KeyPair issuerKeys, String applicationUri, String... hostNames) Deprecated. this method depends on static state. Call createCertificate(String, String, KeyPair, String, int, String...) instead.
static KeyPair	createHttpsCertificate(ApplicationDescription applicationDecription, String hostName, KeyPair issuerKeys) Deprecated. this method depends on static state. Call createHttpsCertificate(ApplicationDescription, String, KeyPair, int) instead.
static KeyPair	createHttpsCertificate(ApplicationDescription applicationDecription, String hostName, KeyPair issuerKeys, int keySize) /** Create certificate and private key to be used for HTTPS
static KeyPair	createKeyPair(String commonName, String organisation, int certificateDays, KeyPair issuerKeys, String applicationUri, int keySize, String... hostNames) Create a new Certificate.
static KeyPair	createKeyPair(String commonName, String organisation, int certificateDays, KeyPair issuerKeys, String applicationUri, String... hostNames) Deprecated. this method depends on static state. Call createKeyPair(String, String, int, KeyPair, String, int, String...) instead.
boolean	equals(Object obj)
static String	getActualHostName() Returns the hostname with domain (if available).
static String	getActualHostNameWithoutDomain() Returns the hostname without the domain part.
ApplicationDescription	getApplicationDescription() The application description defines information about the running application instance.
static Set<String>	getBannedHostnames() The set of hostnames that we don't want to return from getActualHostName().
protected static File	getBestFile(File path, String baseName, String... extension)
KeyPair[]	getCertificates() The OPC UA Application Instance Certificates of the application.
static int	getDefaultCertificateDays() The number of days new certificates are valid.
KeyPair	getHttpsCertificate() The HTTPS Certificate (and private key).
String	getOrganisation() The organization name used for the application certificates.
SignedSoftwareCertificate[]	getSoftwareCertificates() Deprecated. this method returns empty array always as the serverSoftwareCertificates parameter of CreateSessionResponse is deprecated in UA 1.04
int	hashCode()
static boolean	isCacheLocalHostname()
protected static KeyPair	loadCertificate(String certType, String privateKeyPassword, boolean enableRenew, File certFile, File privFile, boolean usePfx)
static ApplicationIdentity	loadOrCreateCertificate(ApplicationDescription applicationDescription, String organisation, String privateKeyPassword, File path, boolean enableRenew, String... hostNames) Load the Application Identity certificate, or create a new one and save it.
static ApplicationIdentity	loadOrCreateCertificate(ApplicationDescription applicationDescription, String organisation, String privateKeyPassword, File path, KeyPair issuerKeys, int[] keySizes, boolean enableRenew, String... hostNames) Load the Application Identity certificate, or create a new one and save it.
static ApplicationIdentity	loadOrCreateCertificate(String applicationName, String organisation, File certFile, File privFile, String privateKeyPassword, KeyPair issuerKeys, boolean enableRenew, String applicationUri, int keySize, String... hostNames) Load the Application Identity certificate, or create a new one and save it.
static ApplicationIdentity	loadOrCreateCertificate(String applicationName, String organisation, File certFile, File privFile, String privateKeyPassword, KeyPair issuerKeys, boolean enableRenew, String applicationUri, String... hostNames) Deprecated. this method depends on static state. Call loadOrCreateCertificate(String, String, File, File, String, KeyPair, boolean, String, int, String...) instead.
static ApplicationIdentity	loadOrCreateCertificate(String applicationName, String organisation, String privateKeyPassword, File path, KeyPair issuerKeys, int[] keySizes, boolean enableRenew, String applicationUri, String... hostNames) Load the Application Identity certificate, or create a new one and save it.
protected static ApplicationIdentity	loadOrCreateFromProtectedStore(ApplicationDescription applicationDescription, String organisation, String privateKeyPassword, String keystoreLocation, String keyStorePassword, KeyPair issuerKeys, int keySize, String... hostNames) Load the Application Identity certificate from a protected key store, or create a new one and save it to the store.
protected static ApplicationIdentity	loadOrCreateFromProtectedStore(ApplicationDescription applicationDescription, String organisation, String privateKeyPassword, String keystoreLocation, String keyStorePassword, KeyPair issuerKeys, String... hostNames) Load the Application Identity certificate from a protected key store, or create a new one and save it to the store.
static KeyPair	loadOrCreateHttpsCertificate(ApplicationDescription applicationDecription, String hostName, String privateKeyPassword, KeyPair issuerKeys, File path, boolean enableRenew) Deprecated. this method depends on static state. Call loadOrCreateHttpsCertificate(ApplicationDescription, String, String, KeyPair, File, boolean, int) instead.
static KeyPair	loadOrCreateHttpsCertificate(ApplicationDescription applicationDecription, String hostName, String privateKeyPassword, KeyPair issuerKeys, File path, boolean enableRenew, int keySize) Load certificate and private key from applicationName_https.der & .pem - or create ones if they do not exist
static KeyPair	loadOrCreateIssuerCertificate(String issuerName, File path, String privateKeyPassword, int days, boolean enableRenew) Load CA certificate and private key from .der & .pem - or create ones if they do not exist
static KeyPair	loadOrCreateIssuerCertificate(String issuerName, File path, String privateKeyPassword, int days, boolean enableRenew, int keySize) Load CA certificate and private key from .der & .pem - or create ones if they do not exist
static KeyPair	loadOrCreateKeyPair(String applicationName, String organisation, File certFile, File privFile, String privateKeyPassword, KeyPair caKeys, boolean enableRenew, String applicationUri, int keySize, String... hostNames)
static KeyPair	loadOrCreateKeyPair(String applicationName, String organisation, File certFile, File privFile, String privateKeyPassword, KeyPair caKeys, boolean enableRenew, String applicationUri, String... hostNames) Deprecated. this method depends on static state. Call loadOrCreateKeyPair(String, String, File, File, String, KeyPair, boolean, String, int, String...). instead.
static String	replaceHostNameTagWithActualHostName(String string) Replaces all occurrences of "localhost", "domainname" and "hostname" with the actual hostname of the computer.
protected static void	saveCertificate(String certType, KeyPair keys, File certFile, File privFile, String privateKeyPassword, boolean usePfx)
static void	setActualHostName(String hostnameWithDomain) Calling this method will override the normal hostname resolution used in getActualHostName().
void	setApplicationDescription(ApplicationDescription applicationDescription) Define the application description information.
void	setApplicationDescription(ApplicationDescription applicationDescription, boolean enableValidation) Define the application description information.
static void	setCacheLocalHostname(boolean cacheLocalHostname) Set to true to cache the values of getActualHostName() and getActualHostNameWithoutDomain() for subsequent calls.
static void	setDefaultCertificateDays(int days) Define the number of days new certificates are valid.
void	setHttpsCertificate(KeyPair httpsCertificate) The HTTPS Certificate (and private key).
void	setOrganisation(String organisation) Define the organisation name used for the application

Methods inherited from class com.prosysopc.ua.SecureIdentity

decrypt, decrypt, encrypt, getCertificate, getKeys, getPrivateKey

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

CERT_FILE_EXTENSIONS

public static final String CERT_FILE_EXTENSIONS

See Also:

Constant Field Values

Constructor Detail

ApplicationIdentity

public ApplicationIdentity()

Create a new empty identity.

ApplicationIdentity

public ApplicationIdentity(Cert certificate,
                           PrivKey privateKey)

Create a new identity

Parameters:

certificate - The application certificate

privateKey - The private key

ApplicationIdentity

public ApplicationIdentity(File certificateFile,
                           File privateKeyFile,
                           String privateKeyPassword)
                    throws IOException,
                           SecureIdentityException

Create an identity with an application certificate. The certificate and private key are loaded from the files.

Parameters:

certificateFile - the file containing the user certificate

privateKeyFile - the file containing the user private key

privateKeyPassword - password used to secure the private key

Throws:

IOException - if the files cannot be read

SecureIdentityException - if the certificate or private key file is not valid

ApplicationIdentity

public ApplicationIdentity(File storeLocation,
                           String alias,
                           String privateKeyPassword,
                           String keyStorePassword,
                           String keyStoreType)
                    throws IOException,
                           SecureIdentityException

Create an identity with an application certificate. The certificate and private key are loaded from a pfx-keystore file.

Parameters:

storeLocation - the pfx-file containing the key store

alias - string alias of the key pair

privateKeyPassword - password used to secure the private key

keyStorePassword - password used to secure the key store

keyStoreType - type of the key store, "JKS" and "PKCS12" are supported types

Throws:

IOException - if the files cannot be read

SecureIdentityException - if the certificate or private key file is not valid

ApplicationIdentity

public ApplicationIdentity(KeyPair... keyPairs)

Create an identity with one or more application certificate. The certificate and private key are given as KeyPairs.

Parameters:

keyPairs - array of key pairs.

ApplicationIdentity

public ApplicationIdentity(URL certificateFile,
                           URL privateKeyFile,
                           String privateKeyPassword)
                    throws IOException,
                           SecureIdentityException

Create an identity with an application certificate. The certificate and private key are loaded from the files.

Parameters:

certificateFile - the file containing the user certificate

privateKeyFile - the file containing the user private key

privateKeyPassword - password used to secure the private key

Throws:

IOException - if the files cannot be read

SecureIdentityException - if the certificate or private key file is not valid

Method Detail

createCertificate

public static ApplicationIdentity createCertificate(ApplicationDescription applicationDescription,
                                                    String organisation,
                                                    int keySize,
                                                    String... hostNames)
                                             throws SecureIdentityException

Create a new self-signed Application Identity certificate.

Generates a new public&private key pair and creates a new ApplicationIdentity using it.

Parameters:

applicationDescription - Application name to use in the certificate and also as the file name base. If the ApplicationUri contains 'localhost' or 'domainname', it will be converted to the actual host name ( getActualHostName()). If it contains 'hostname', it will be converted to the hostname without domain ( getActualHostNameWithoutDomain())

organisation - Organization name to use in the certificate.

keySize - the key size

hostNames - alternate host names or IP addresses to add to SubjectAlternativeName

Returns:

Identity to use as an application identity.

Throws:

SecureIdentityException - if the certificate could not be generated. Read the cause for the original exception.

createCertificate

public static ApplicationIdentity createCertificate(ApplicationDescription applicationDescription,
                                                    String organisation,
                                                    KeyPair issuerKeys,
                                                    int keySize,
                                                    String... hostNames)
                                             throws SecureIdentityException

Create a new Application Identity certificate.

Generates a new public&private key pair and creates a new ApplicationIdentity using it.

The certificate is signed with the issuerKeys.

Parameters:

applicationDescription - Application name to use in the certificate and also as the file name base. If the ApplicationUri contains 'localhost' or 'domainname', it will be converted to the actual host name ( getActualHostName()). If it contains 'hostname', it will be converted to the hostname without domain ( getActualHostNameWithoutDomain())

organisation - Organization name to use in the certificate.

issuerKeys - the certificate and private key of the issuer, to be used for signing the new certificate

keySize - the key size

hostNames - alternate host names or IP addresses to add to SubjectAlternativeName

Returns:

Identity to use as an application identity.

Throws:

SecureIdentityException - if the certificate could not be generated. Read the cause for the original exception.

createCertificate

@Deprecated
public static ApplicationIdentity createCertificate(ApplicationDescription applicationDescription,
                                                                 String organisation,
                                                                 KeyPair issuerKeys,
                                                                 String... hostNames)
                                                          throws SecureIdentityException

Deprecated. this method depend on static state. Call createCertificate(ApplicationDescription, String, KeyPair, int, String...) instead.

Create a new Application Identity certificate.

Generates a new public&private key pair and creates a new ApplicationIdentity using it.

The certificate is signed with the issuerKeys.

Parameters:

applicationDescription - Application name to use in the certificate and also as the file name base. If the ApplicationUri contains 'localhost' or 'domainname', it will be converted to the actual host name ( getActualHostName()). If it contains 'hostname', it will be converted to the hostname without domain ( getActualHostNameWithoutDomain())

organisation - Organization name to use in the certificate.

issuerKeys - the certificate and private key of the issuer, to be used for signing the new certificate

hostNames - alternate host names or IP addresses to add to SubjectAlternativeName

Returns:

Identity to use as an application identity.

Throws:

SecureIdentityException - if the certificate could not be generated. Read the cause for the original exception.

createCertificate

@Deprecated
public static ApplicationIdentity createCertificate(ApplicationDescription applicationDescription,
                                                                 String organisation,
                                                                 String... hostNames)
                                                          throws SecureIdentityException

Deprecated. this method depends on static state. Call createCertificate(ApplicationDescription, String, int, String...) instead.

Create a new self-signed Application Identity certificate.

Generates a new public&private key pair and creates a new ApplicationIdentity using it.

Parameters:

applicationDescription - Application name to use in the certificate and also as the file name base. If the ApplicationUri contains 'localhost' or 'domainname', it will be converted to the actual host name ( getActualHostName()). If it contains 'hostname', it will be converted to the hostname without domain ( getActualHostNameWithoutDomain())

organisation - Organization name to use in the certificate.

hostNames - alternate host names or IP addresses to add to SubjectAlternativeName

Returns:

Identity to use as an application identity.

Throws:

SecureIdentityException - if the certificate could not be generated. Read the cause for the original exception.

createCertificate

public static ApplicationIdentity createCertificate(String applicationName,
                                                    String organisation,
                                                    KeyPair issuerKeys,
                                                    String applicationUri,
                                                    int keySize,
                                                    String... hostNames)
                                             throws SecureIdentityException

Create the Application Identity certificate.

Generates a new public&private key pair and creates a new ApplicationIdentity using it.

Parameters:

applicationName - Application name to use in the certificate and also as the file name base. If the ApplicationUri contains 'localhost' or 'domainname', it will be converted to the actual host name ( getActualHostName()). If it contains 'hostname', it will be converted to the hostname without domain ( getActualHostNameWithoutDomain())

organisation - Organization name to use in the certificate.

issuerKeys - the certificate and private key of the issuer, to be used for signing the new certificate

applicationUri - The application URI to use for SubjectAlternativeName

keySize - the key size

hostNames - alternate host names or IP addresses to add to SubjectAlternativeName

Returns:

Identity to use as an application identity.

Throws:

SecureIdentityException - if the certificate could not be generated. Read the cause for the original exception.

createCertificate

@Deprecated
public static ApplicationIdentity createCertificate(String applicationName,
                                                                 String organisation,
                                                                 KeyPair issuerKeys,
                                                                 String applicationUri,
                                                                 String... hostNames)
                                                          throws SecureIdentityException

Deprecated. this method depends on static state. Call createCertificate(String, String, KeyPair, String, int, String...) instead.

Create the Application Identity certificate.

Generates a new public&private key pair and creates a new ApplicationIdentity using it.

Parameters:

applicationName - Application name to use in the certificate and also as the file name base. If the ApplicationUri contains 'localhost' or 'domainname', it will be converted to the actual host name ( getActualHostName()). If it contains 'hostname', it will be converted to the hostname without domain ( getActualHostNameWithoutDomain())

organisation - Organization name to use in the certificate.

issuerKeys - the certificate and private key of the issuer, to be used for signing the new certificate

applicationUri - The application URI to use for SubjectAlternativeName

hostNames - alternate host names or IP addresses to add to SubjectAlternativeName

Returns:

Identity to use as an application identity.

Throws:

SecureIdentityException - if the certificate could not be generated. Read the cause for the original exception.

createHttpsCertificate

@Deprecated
public static KeyPair createHttpsCertificate(ApplicationDescription applicationDecription,
                                                          String hostName,
                                                          KeyPair issuerKeys)
                                                   throws GeneralSecurityException,
                                                          IOException

Deprecated. this method depends on static state. Call createHttpsCertificate(ApplicationDescription, String, KeyPair, int) instead.

/** Create certificate and private key to be used for HTTPS

Parameters:

applicationDescription - Application name to use in the certificate and also as the file name base.

hostName - The hostname to use for the certificate subject. The clients may verify the hostname that it matches the URL of the server.

issuerKeys - The certificate and private key of the issuer, to be used for signing the new certificate

Returns:

Throws:

GeneralSecurityException

IOException

createHttpsCertificate

public static KeyPair createHttpsCertificate(ApplicationDescription applicationDecription,
                                             String hostName,
                                             KeyPair issuerKeys,
                                             int keySize)
                                      throws GeneralSecurityException,
                                             IOException

/** Create certificate and private key to be used for HTTPS

Parameters:

applicationDescription - Application name to use in the certificate and also as the file name base.

hostName - The hostname to use for the certificate subject. The clients may verify the hostname that it matches the URL of the server.

issuerKeys - The certificate and private key of the issuer, to be used for signing the new certificate

Returns:

Throws:

GeneralSecurityException

IOException

createKeyPair

public static KeyPair createKeyPair(String commonName,
                                    String organisation,
                                    int certificateDays,
                                    KeyPair issuerKeys,
                                    String applicationUri,
                                    int keySize,
                                    String... hostNames)
                             throws SecureIdentityException

Create a new Certificate.

Parameters:

commonName - The value for the Common Name field of the certificate

organisation - The value for the Common Name field of the certificate

certificateDays - Number of days that the certificate is to be valid

issuerKeys - the keys of the optional Certificate Authority to use for signing the certificate

applicationUri - The application URI to use for SubjectAlternativeName

keySize - the key size

hostNames - alternate host names or IP addresses to add to SubjectAlternativeName

Returns:

The certificate and private key in a KeyPair

Throws:

SecureIdentityException - if the certificate could not be created

createKeyPair

@Deprecated
public static KeyPair createKeyPair(String commonName,
                                                 String organisation,
                                                 int certificateDays,
                                                 KeyPair issuerKeys,
                                                 String applicationUri,
                                                 String... hostNames)
                                          throws SecureIdentityException

Deprecated. this method depends on static state. Call createKeyPair(String, String, int, KeyPair, String, int, String...) instead.

Create a new Certificate.

Parameters:

commonName - The value for the Common Name field of the certificate

organisation - The value for the Common Name field of the certificate

certificateDays - Number of days that the certificate is to be valid

issuerKeys - the keys of the optional Certificate Authority to use for signing the certificate

applicationUri - The application URI to use for SubjectAlternativeName

hostNames - alternate host names or IP addresses to add to SubjectAlternativeName

Returns:

The certificate and private key in a KeyPair

Throws:

SecureIdentityException - if the certificate could not be created

getActualHostName

public static String getActualHostName()

Returns the hostname with domain (if available). Calling this method the first time may be slow, subsequent calls use cached value, if setCacheLocalHostname(boolean) is true, which by default is.

The hostnames that are included in getBannedHostnames() are ignored if they would be returned. Instead the result of OSUtil.getHostNameWithDomain() is used. This is done basically to work around the 'host.docker.internal' hostname alias appearing in Windows with Docker installation, which overrides the real hostname of the computer.

Returns:

the actual host name of the computer as defined by InetAddress.getLocalHost().getHostName() or .getCanonicalHostName(). If the host name cannot be determined, will return 'localhost'.

getActualHostNameWithoutDomain

public static String getActualHostNameWithoutDomain()

Returns the hostname without the domain part. Convenience method for calling getActualHostName() and removing everything after the first dot. If there is no domain part, just returns the whole hostname. Calling this method the first time may be slow, subsequent calls use cached value, if setCacheLocalHostname(boolean) is true, which by default is.

getBannedHostnames

public static Set<String> getBannedHostnames()

The set of hostnames that we don't want to return from getActualHostName().

This set is used to work around the 'host.docker.internal' hostname alias appearing in Windows with Docker installation, which overrides the real hostname of the computer. Therefore the list includes just 'host.docker.internal' by default, but if you need to ban other names, you can add them to the set. Or if you still wish to see this hostname, you can remove it from the set.

Returns:

the set of banned hostnames.

getDefaultCertificateDays

public static int getDefaultCertificateDays()

The number of days new certificates are valid.

Returns:

number of days

isCacheLocalHostname

public static boolean isCacheLocalHostname()

Returns:

the current setting of Hostname caching

See Also:

setCacheLocalHostname(boolean), setActualHostName(String)

loadOrCreateCertificate

public static ApplicationIdentity loadOrCreateCertificate(ApplicationDescription applicationDescription,
                                                          String organisation,
                                                          String privateKeyPassword,
                                                          File path,
                                                          boolean enableRenew,
                                                          String... hostNames)
                                                   throws SecureIdentityException,
                                                          IOException

Load the Application Identity certificate, or create a new one and save it.

In the first run this method creates public&private key pair and saves them to files. In other runs the key pairs are loaded from files.

• The public key is saved (or read) in applicationName.der
• The private key is saved (or read) in applicationName.pem. If it does not exist, applicationName.pfx, or applicationName.key (raw binary) is also looked for.

If the certificate expires, it is automatically renewed, if enableRenew is true.

Parameters:

applicationDescription - Application name to use in the certificate and also as the file name base.

organisation - Organization name to use in the certificate.

privateKeyPassword - The password for private key

path - Optional path to the files

enableRenew - Enable renewing the certificate if it has expired.

hostNames - alternate host names or IP addresses to add to SubjectAlternativeName

Returns:

Identity to use as an application identity.

Throws:

SecureIdentityException - if the certificate could not be loaded or generated. Read the cause for the original exception.

IOException - if the certificate files cannot be read or created.

loadOrCreateCertificate

public static ApplicationIdentity loadOrCreateCertificate(ApplicationDescription applicationDescription,
                                                          String organisation,
                                                          String privateKeyPassword,
                                                          File path,
                                                          KeyPair issuerKeys,
                                                          int[] keySizes,
                                                          boolean enableRenew,
                                                          String... hostNames)
                                                   throws SecureIdentityException,
                                                          IOException

Load the Application Identity certificate, or create a new one and save it.

In the first run this method creates public&private key pair and saves them to files. In other runs the key pairs are loaded from files.

• The public key is saved (or read) in applicationName.der
• The private key is saved (or read) in applicationName.pem. If it does not exist, applicationName.pfx, or applicationName.key (raw binary) is also looked for.

If the certificate expires, it is automatically renewed, if enableRenew is true.

Parameters:

applicationDescription - Application name to use in the certificate and also as the file name base.

organisation - Organization name to use in the certificate.

privateKeyPassword - The password for private key

path - Optional path to the files

issuerKeys - the certificate and private key of the issuer, to be used for signing the new certificate

keySizes - an array of key sizes to use for the identity. A separate certificate will be created with each size. The various key sizes may be necessary, depending on which SecurityPolicy alternatives are enabled by the application.

enableRenew - Enable renewing the certificate if it has expired.

hostNames - alternate host names or IP addresses to add to SubjectAlternativeName

Returns:

Identity to use as an application identity.

Throws:

SecureIdentityException - if the certificate could not be loaded or generated. Read the cause for the original exception.

IOException - if the certificate files cannot be read or created.

loadOrCreateCertificate

public static ApplicationIdentity loadOrCreateCertificate(String applicationName,
                                                          String organisation,
                                                          File certFile,
                                                          File privFile,
                                                          String privateKeyPassword,
                                                          KeyPair issuerKeys,
                                                          boolean enableRenew,
                                                          String applicationUri,
                                                          int keySize,
                                                          String... hostNames)
                                                   throws SecureIdentityException,
                                                          IOException

Load the Application Identity certificate, or create a new one and save it.

In the first run this method creates public&private key pair and saves them to files. In other runs the key pairs are loaded from files.

If the certificate expires, it is automatically renewed, if enableRenew is true.

The key size will be the default, as defined by CertificateUtils.getKeySize().

Parameters:

applicationName - Application name to use in the certificate and also as the file name base.

organisation - Organization name to use in the certificate.

certFile - The file used to store the certificate. The certificate is saved in binary DER format

privFile - The file used to store the private key. The key is saved in PEM format, but can be read in PFX or raw binary as well, depending on the actual format of the file.

privateKeyPassword - The password for private key

issuerKeys - The certificate and private key of the issuer, to be used for signing the new certificate. If null, a self-signed certificate is created.

enableRenew - Enable renewing the certificate if it has expired.

applicationUri - The application URI to use for SubjectAlternativeName

keySize - the key size

hostNames - Alternate host names or IP addresses to add to SubjectAlternativeName

Returns:

Identity to use as an application identity

Throws:

SecureIdentityException - if the certificate could not be loaded or generated. Read the cause for the original exception.

IOException - if the certificate files cannot be loaded or created.

loadOrCreateCertificate

@Deprecated
public static ApplicationIdentity loadOrCreateCertificate(String applicationName,
                                                                       String organisation,
                                                                       File certFile,
                                                                       File privFile,
                                                                       String privateKeyPassword,
                                                                       KeyPair issuerKeys,
                                                                       boolean enableRenew,
                                                                       String applicationUri,
                                                                       String... hostNames)
                                                                throws SecureIdentityException,
                                                                       IOException

Deprecated. this method depends on static state. Call loadOrCreateCertificate(String, String, File, File, String, KeyPair, boolean, String, int, String...) instead.

Load the Application Identity certificate, or create a new one and save it.

In the first run this method creates public&private key pair and saves them to files. In other runs the key pairs are loaded from files.

If the certificate expires, it is automatically renewed, if enableRenew is true.

The key size will be the default, as defined by CertificateUtils.getKeySize().

Parameters:

applicationName - Application name to use in the certificate and also as the file name base.

organisation - Organization name to use in the certificate.

certFile - The file used to store the certificate. The certificate is saved in binary DER format

privFile - The file used to store the private key. The key is saved in PEM format, but can be read in PFX or raw binary as well, depending on the actual format of the file.

privateKeyPassword - The password for private key

issuerKeys - The certificate and private key of the issuer, to be used for signing the new certificate. If null, a self-signed certificate is created.

enableRenew - Enable renewing the certificate if it has expired.

applicationUri - The application URI to use for SubjectAlternativeName

hostNames - Alternate host names or IP addresses to add to SubjectAlternativeName

Returns:

Identity to use as an application identity

Throws:

SecureIdentityException - if the certificate could not be loaded or generated. Read the cause for the original exception.

IOException - if the certificate files cannot be loaded or created.

loadOrCreateCertificate

public static ApplicationIdentity loadOrCreateCertificate(String applicationName,
                                                          String organisation,
                                                          String privateKeyPassword,
                                                          File path,
                                                          KeyPair issuerKeys,
                                                          int[] keySizes,
                                                          boolean enableRenew,
                                                          String applicationUri,
                                                          String... hostNames)
                                                   throws SecureIdentityException,
                                                          IOException

Load the Application Identity certificate, or create a new one and save it.

In the first run this method creates public&private key pair and saves them to files. In other runs the key pairs are loaded from files.

• The public key is saved (or read) in applicationName.crt
• The private key is saved (or read) in applicationName.pem. If the key is in applicationName.pfx, it is preferred, when loading, as it also enables usage of a password. Note: The .pfx file is expected to use a password: if the password is not defined, the file is not read. If the password is an empty string use "", instead of null.
  If the certificate expires, it is automatically renewed, if enableRenew is true.

Parameters:

applicationName - Application name to use in the certificate and also as the file name base.

organisation - Organization name to use in the certificate.

privateKeyPassword - The password for private key

path - Optional path to the files

issuerKeys - The certificate and private key of the issuer, to be used for signing the new certificate. If null, a self-signed certificate is created.

keySizes - An array of key sizes to use for the identity. A separate certificate will be created with each size. The various key sizes may be necessary, depending on which SecurityPolicy alternatives are enabled by the application. Entry may be 0, in which case the default KeySize is used - and the fileName to look for is not appended with the keySize. If the keySizes is omitted (null or empty), the default key size, as defined by CertificateUtils.DEFAULT_KEY_SIZE, is used.

enableRenew - Enable renewing the certificate if it has expired.

applicationUri - The application URI to use for SubjectAlternativeName

hostNames - Alternate host names or IP addresses to add to SubjectAlternativeName

Returns:

Identity to use as an application identity

Throws:

SecureIdentityException - if the certificate could not be loaded or generated. Read the cause for the original exception.

IOException - if the certificate files cannot be loaded or created.

loadOrCreateHttpsCertificate

@Deprecated
public static KeyPair loadOrCreateHttpsCertificate(ApplicationDescription applicationDecription,
                                                                String hostName,
                                                                String privateKeyPassword,
                                                                KeyPair issuerKeys,
                                                                File path,
                                                                boolean enableRenew)
                                                         throws IOException,
                                                                SecureIdentityException

Deprecated. this method depends on static state. Call loadOrCreateHttpsCertificate(ApplicationDescription, String, String, KeyPair, File, boolean, int) instead.

Load certificate and private key from applicationName_https.der & .pem - or create ones if they do not exist

Parameters:

applicationDescription - Application name to use in the certificate and also as the file name base.

hostName - The hostname to use for the certificate subject. The clients may verify the hostname that it matches the URL of the server.

path - Optional path to the files

issuerKeys - The certificate and private key of the issuer, to be used for signing the new certificate

enableRenew - Enable renewing the certificate if it has expired.

Returns:

the KeyPair composed of the certificate and private key

Throws:

IOException - if the certificate or private key cannot be stored in the defined path.

SecureIdentityException - if the certificate creation fails.

loadOrCreateHttpsCertificate

public static KeyPair loadOrCreateHttpsCertificate(ApplicationDescription applicationDecription,
                                                   String hostName,
                                                   String privateKeyPassword,
                                                   KeyPair issuerKeys,
                                                   File path,
                                                   boolean enableRenew,
                                                   int keySize)
                                            throws IOException,
                                                   SecureIdentityException

Load certificate and private key from applicationName_https.der & .pem - or create ones if they do not exist

Parameters:

applicationDescription - Application name to use in the certificate and also as the file name base.

hostName - The hostname to use for the certificate subject. The clients may verify the hostname that it matches the URL of the server.

path - Optional path to the files

issuerKeys - The certificate and private key of the issuer, to be used for signing the new certificate

enableRenew - Enable renewing the certificate if it has expired.

keySize - The key size

Returns:

the KeyPair composed of the certificate and private key

Throws:

IOException - if the certificate or private key cannot be stored in the defined path.

SecureIdentityException - if the certificate creation fails.

loadOrCreateIssuerCertificate

public static KeyPair loadOrCreateIssuerCertificate(String issuerName,
                                                    File path,
                                                    String privateKeyPassword,
                                                    int days,
                                                    boolean enableRenew)
                                             throws IOException,
                                                    SecureIdentityException

Load CA certificate and private key from .der & .pem - or create ones if they do not exist

Parameters:

issuerName - The name of the issuer to use as the Subject for the certificate and file names.

path - optional path to the files

privateKeyPassword - the password used to protect the private key file

days - number of days the certificate will be valid

enableRenew -

Returns:

the KeyPair composed of the certificate and private key

Throws:

IOException

SecureIdentityException

loadOrCreateIssuerCertificate

public static KeyPair loadOrCreateIssuerCertificate(String issuerName,
                                                    File path,
                                                    String privateKeyPassword,
                                                    int days,
                                                    boolean enableRenew,
                                                    int keySize)
                                             throws IOException,
                                                    SecureIdentityException

Load CA certificate and private key from .der & .pem - or create ones if they do not exist

Parameters:

issuerName - The name of the issuer to use as the Subject for the certificate and file names.

path - optional path to the files

privateKeyPassword - the password used to protect the private key file

days - number of days the certificate will be valid

enableRenew -

keySize -

Returns:

the KeyPair composed of the certificate and private key

Throws:

IOException

SecureIdentityException

loadOrCreateKeyPair

public static KeyPair loadOrCreateKeyPair(String applicationName,
                                          String organisation,
                                          File certFile,
                                          File privFile,
                                          String privateKeyPassword,
                                          KeyPair caKeys,
                                          boolean enableRenew,
                                          String applicationUri,
                                          int keySize,
                                          String... hostNames)
                                   throws IOException,
                                          SecureIdentityException

Throws:

IOException

SecureIdentityException

loadOrCreateKeyPair

@Deprecated
public static KeyPair loadOrCreateKeyPair(String applicationName,
                                                       String organisation,
                                                       File certFile,
                                                       File privFile,
                                                       String privateKeyPassword,
                                                       KeyPair caKeys,
                                                       boolean enableRenew,
                                                       String applicationUri,
                                                       String... hostNames)
                                                throws IOException,
                                                       SecureIdentityException

Deprecated. this method depends on static state. Call loadOrCreateKeyPair(String, String, File, File, String, KeyPair, boolean, String, int, String...). instead.

Throws:

IOException

SecureIdentityException

replaceHostNameTagWithActualHostName

public static String replaceHostNameTagWithActualHostName(String string)

Replaces all occurrences of "localhost", "domainname" and "hostname" with the actual hostname of the computer. getActualHostName() is used to replace "localhost" and "domainname". "hostname" is replaced with getActualHostNameWithoutDomain().

Parameters:

string - the string value to modify

Returns:

string where the hostname is replaced with the actual hostname of the computer as defined above.

setActualHostName

public static void setActualHostName(String hostnameWithDomain)

Calling this method will override the normal hostname resolution used in getActualHostName(). The value will be stored regardless of setCacheLocalHostname(boolean). The hostname should be the fully qualified domain name, if that is available. This method should be called before calling any other method of the SDK that might use the hostname.

See Also:

setActualHostName(String)

setCacheLocalHostname

public static void setCacheLocalHostname(boolean cacheLocalHostname)

Set to true to cache the values of getActualHostName() and getActualHostNameWithoutDomain() for subsequent calls. Default value is true.

setDefaultCertificateDays

public static void setDefaultCertificateDays(int days)

Define the number of days new certificates are valid.

getBestFile

protected static File getBestFile(File path,
                                  String baseName,
                                  String... extension)

loadCertificate

protected static KeyPair loadCertificate(String certType,
                                         String privateKeyPassword,
                                         boolean enableRenew,
                                         File certFile,
                                         File privFile,
                                         boolean usePfx)
                                  throws SecureIdentityException

Throws:

SecureIdentityException

loadOrCreateFromProtectedStore

protected static ApplicationIdentity loadOrCreateFromProtectedStore(ApplicationDescription applicationDescription,
                                                                    String organisation,
                                                                    String privateKeyPassword,
                                                                    String keystoreLocation,
                                                                    String keyStorePassword,
                                                                    KeyPair issuerKeys,
                                                                    int keySize,
                                                                    String... hostNames)
                                                             throws IOException,
                                                                    SecureIdentityException

Load the Application Identity certificate from a protected key store, or create a new one and save it to the store. In the first run this method creates public&private key pair and saves them to the Java KeyStore. In other runs the key pairs are loaded from the KeyStore.

Parameters:

applicationDescription - Application description to use in the certificate and also as the file name base. Must not be null

organisation - Organization name to use in the certificate.

privateKeyPassword -

keystoreLocation -

keyStorePassword -

issuerKeys -

keySize -

hostNames -

Returns:

Identity to use as an application identity.

Throws:

IOException - if the key store cannot be opened

SecureIdentityException - if the certificate could not be generated. Read the cause for the original exception.

loadOrCreateFromProtectedStore

protected static ApplicationIdentity loadOrCreateFromProtectedStore(ApplicationDescription applicationDescription,
                                                                    String organisation,
                                                                    String privateKeyPassword,
                                                                    String keystoreLocation,
                                                                    String keyStorePassword,
                                                                    KeyPair issuerKeys,
                                                                    String... hostNames)
                                                             throws IOException,
                                                                    SecureIdentityException

Load the Application Identity certificate from a protected key store, or create a new one and save it to the store. In the first run this method creates public&private key pair and saves them to the Java KeyStore. In other runs the key pairs are loaded from the KeyStore.

Parameters:

applicationDescription - Application description to use in the certificate and also as the file name base. Must not be null

organisation - Organization name to use in the certificate.

privateKeyPassword -

keystoreLocation -

keyStorePassword -

Returns:

Identity to use as an application identity.

Throws:

IOException - if the key store cannot be opened

SecureIdentityException - if the certificate could not be generated. Read the cause for the original exception.

saveCertificate

protected static void saveCertificate(String certType,
                                      KeyPair keys,
                                      File certFile,
                                      File privFile,
                                      String privateKeyPassword,
                                      boolean usePfx)
                               throws IOException,
                                      GeneralSecurityException

Throws:

IOException

GeneralSecurityException

addSoftwareCertificates

@Deprecated
public void addSoftwareCertificates(SignedSoftwareCertificate[] softwareCertificates)

Deprecated. this method does nothing as the serverSoftwareCertificates parameter of CreateSessionResponse is deprecated in UA 1.04

Add software certificates to the application. The software certificates are used to define the profiles supported by the application. The certificates are provided by the OPC Foundation, when the application has been certified for the profiles.

Parameters:

softwareCertificates -

equals

public boolean equals(Object obj)

Overrides:

equals in class SecureIdentity

getApplicationDescription

public ApplicationDescription getApplicationDescription()

The application description defines information about the running application instance. It is provided to the other applications that we connect to as an identification.

Returns:

the current application description information.

getCertificates

public KeyPair[] getCertificates()

The OPC UA Application Instance Certificates of the application. Depending on the enabled security modes, the application may need one or two certificates of different size.

Returns:

the array of certificates defined for the application in the constructor.

getHttpsCertificate

public KeyPair getHttpsCertificate()

The HTTPS Certificate (and private key). If the application enables HTTPS, then it must also define an HTTPS certificate. You can create one with loadOrCreateHttpsCertificate(ApplicationDescription, String, String, KeyPair, File, boolean) .

Returns:

the HTTPS certificate, if defined.

getOrganisation

public String getOrganisation()

The organization name used for the application certificates.

Returns:

the defined organisation name

getSoftwareCertificates

@Deprecated
public SignedSoftwareCertificate[] getSoftwareCertificates()

Deprecated. this method returns empty array always as the serverSoftwareCertificates parameter of CreateSessionResponse is deprecated in UA 1.04

Get the software certificates to the application. The software certificates are used to define the profiles supported by the application. The certificates are provided by the OPC Foundation, when the application has been certified for the profiles.

Returns:

the list of software certificates for the application

hashCode

public int hashCode()

Overrides:

hashCode in class SecureIdentity

setApplicationDescription

public void setApplicationDescription(ApplicationDescription applicationDescription)

Define the application description information. If the ApplicationUri contains 'localhost', it will be converted to the actual host name (if possible).

Parameters:

applicationDescription - the application description information.

setApplicationDescription

public void setApplicationDescription(ApplicationDescription applicationDescription,
                                      boolean enableValidation)

Define the application description information. If enableValidation is set and the ApplicationUri contains 'localhost', 'domainname' or 'hostname', it will be converted to the actual host name (if possible).

Parameters:

applicationDescription - the application description information.

enableValidation - if set, 'localhost', 'domainname' or 'hostname' may be replaced with the actual hostname. 'hostname' will be replaced without the domain part of the hostname. The other ones, will use the fully qualified hostname.

setHttpsCertificate

public void setHttpsCertificate(KeyPair httpsCertificate)

The HTTPS Certificate (and private key). If the application enables HTTPS, then it must also define an HTTPS certificate. You can create one with loadOrCreateHttpsCertificate(ApplicationDescription, String, String, KeyPair, File, boolean) .

Parameters:

httpsCertificate -

setOrganisation

public void setOrganisation(String organisation)

Define the organisation name used for the application

Parameters:

organisation -