com.prosysopc.ua.stack.utils

Class CryptoUtil

java.lang.Object

com.prosysopc.ua.stack.utils.CryptoUtil

public class CryptoUtil
extends Object

This class contains Cryptographic utilities used by the OPC UA SDK.

NOTE: By default, getRandom() is initialized with SecureRandom.getInstance(..). On Windows 'Windows-PRNG' is used and 'NativePRNGNonBlocking' elsewhere. In case it is not found, 'SHA1PRNG' is used as a fallback. The 'SHA1PRNG' is seeded with System.currentTimeMillis() and System.nanoTime(), to avoid blocking at the application startup. For the others SecureRandom.nextBytes(byte[]) is used ('Windows-PRNG' and 'NativePRNGNonBlocking' should not block here).

IF you require real entropy, and your target systems will be able to provide that without blocking the application for long periods, you can use setRandom(SecureRandom) override the default. Please do seed it first though. Some SecureRandom implementations to use might be SecureRandom.getInstance("DBRG") or SecureRandom.getInstanceStrong(), however please note that they might block (for some time!) in some environments.

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	sendNullInsteadOfEmptyNonce Setting this to true will cause null ByteStrings to be sent as nonces instead of empty ByteStrings.

Constructor Summary

Constructors

Constructor and Description
CryptoUtil()

Method Summary

Modifier and Type	Method and Description
static byte[]	asymmEncrypt(byte[] input, Key key, SecurityAlgorithm algorithm) Deprecated. use encryptAsymm(byte[], PublicKey, SecurityAlgorithm) instead.
static byte[]	base64Decode(String string) Decodes a String having Base64 encoding to an array of bytes.
static String	base64Encode(byte[] bytes) Base64 encodes a byte array to string.
static Mac	createMac(SecurityAlgorithm algorithm, byte[] secret) Create Message Authentication Code (MAC).
static ByteString	createNonce(int bytes) Create a non-repeatable set of bytes.
static ByteString	createNonce(SecurityAlgorithm algorithm) Deprecated. use createNonce(int) and get the size from SecurityPolicy.getSecureChannelNonceLength() directly
static void	decryptAsymm(PrivateKey decryptingKey, SecurityConfiguration profile, byte[] dataToDecrypt, byte[] output, int outputOffset) Convenience method for CryptoProvider.decryptAsymm(PrivateKey, SecurityAlgorithm, byte[], byte[], int) Possible to use only SecurityConfiguration instead of specifying SecurityAlgorithm explicitly.
static byte[]	encryptAsymm(byte[] input, PublicKey key, SecurityAlgorithm algorithm) Convenience method for CryptoProvider.encryptAsymm(java.security.PublicKey, com.prosysopc.ua.stack.transport.security.SecurityAlgorithm, byte[], byte[], int).
static void	encryptAsymm(Certificate encryptingCertificate, SecurityConfiguration profile, byte[] dataToEncrypt, byte[] output, int outputOffset) Convenience method for CryptoProvider.encryptAsymm(PublicKey, SecurityAlgorithm, byte[], byte[], int) Possible to use only Certificate and SecurityConfiguration instead of specifying PublicKey and SecurityAlgorithm explicitly.
static String[]	filterCipherSuiteList(String[] cipherSuiteSet, String[] cipherSuitePatterns) filterCipherSuiteList.
static Cipher	getAsymmetricCipher(SecurityAlgorithm algorithm) Create signer instance using an algorithm uri.
static int	getAsymmInputBlockSize(SecurityAlgorithm algorithm) getAsymmInputBlockSize.
static int	getCipherBlockSize(SecurityAlgorithm algorithm, Key key) Get cipher block (=output) size in bytes.
static String[]	getCipherSuiteIntersection(String[] cipherSuiteSet1, String[] cipherSuiteSet2, boolean omitProtocol) Create an intersection of two lists of cipher suite lists.
static CryptoProvider	getCryptoProvider() Returns CryptoProvider previously set with setCryptoProvider(CryptoProvider).
static int	getNonceLength(SecurityAlgorithm algorithm) Deprecated. use SecurityPolicy.getSecureChannelNonceLength() directly instead
static int	getPlainTextBlockSize(SecurityAlgorithm securityAlgorithm, Key key) Get plain text block (=input) size in bytes.
static SecureRandom	getRandom() The SecureRandom instance used in crypto operations of the SDK.
static int	getRandomReseedCount() The ReseedCount defines how often the getRandom() will reseed the instance.
static Provider	getSecurityProvider() Returns a Provider that can be used for crypto operations.
static String	getSecurityProviderName() Deprecated. use getSecurityProvider() instead
static String	getSecurityProviderName(Class<?> clazz) Deprecated. use getSecurityProvider() instead
static int	getSignatureSize(SecurityAlgorithm signatureAlgorithm, Key key) Get signature size in bytes.
static byte[]	hexToBytes(String string) Converts a hexadecimal string to an array of bytes.
static Integer	hexToInt(String string) Converts a hexadecimal string to Integer.
static Long	hexToLong(String string) Converts a hexadecimal string to Long.
static Long	hexToLong(String string, int firstIndex, int maxLen) Converts a hexadecimal string to Long.
static void	setCryptoProvider(CryptoProvider cryptoProvider) Define the preferred CryptoProvider.
static void	setRandom(SecureRandom secureRandom) Replaces the default SecureRandom instance used in crypto operations of the SDK.
static void	setRandomReseedCount(int reseedCount) Define how often getRandom() should be reseeded automatically.
static void	setSecurityProviderName(String securityProviderName) Define the preferred SecurityProvider.
static SignatureData	signAsymm(PrivateKey signerKey, SecurityAlgorithm algorithm, byte[] dataToSign) signAsymm.
static String	toHex(byte[] bytes) Convenience method for "displaying" a hex-string of a given byte array.
static String	toHex(byte[] bytes, int bytesPerRow) Convenience method for "displaying" a hex-string of a given byte array.
static String	toHex(byte[] bytes, int bytesPerRow, boolean includeLengthPrefix) Convenience method for "displaying" a hex-string of a given byte array.
static String	toHex(int value) Convenience method for "displaying" an int value as a hex-string, interpreting it as an unsigned value.
static String	toHex(long value) Convenience method for "displaying" an Long value as a hex-string.
static boolean	verifyAsymm(X509Certificate certificate, SecurityAlgorithm algorithm, byte[] data, byte[] signature) Verify a signature.

Methods inherited from class java.lang.Object

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

Field Detail

sendNullInsteadOfEmptyNonce

public static boolean sendNullInsteadOfEmptyNonce

Setting this to true will cause null ByteStrings to be sent as nonces instead of empty ByteStrings. By default false (some future version may change the default). Only affects "empty" nonce generation.

Constructor Detail

CryptoUtil

public CryptoUtil()

Method Detail

asymmEncrypt

@Deprecated
public static byte[] asymmEncrypt(byte[] input,
                                               Key key,
                                               SecurityAlgorithm algorithm)
                                        throws InvalidKeyException,
                                               IllegalBlockSizeException,
                                               BadPaddingException,
                                               ServiceResultException,
                                               NoSuchAlgorithmException,
                                               NoSuchPaddingException

Deprecated. use encryptAsymm(byte[], PublicKey, SecurityAlgorithm) instead.

Convenience method for CryptoProvider.encryptAsymm(java.security.PublicKey, com.prosysopc.ua.stack.transport.security.SecurityAlgorithm, byte[], byte[], int). Deprecated: Use encryptAsymm(byte[], java.security.PublicKey, com.prosysopc.ua.stack.transport.security.SecurityAlgorithm) instead.

Parameters:

input - an array of byte.

key - a Key object.

algorithm - a SecurityAlgorithm object.

Returns:

an array of byte.

Throws:

InvalidKeyException - if any.

IllegalBlockSizeException - if any.

BadPaddingException - if any.

ServiceResultException - if any.

NoSuchAlgorithmException - if any.

NoSuchPaddingException - if any.

base64Decode

public static byte[] base64Decode(String string)

Decodes a String having Base64 encoding to an array of bytes.

base64Encode

public static String base64Encode(byte[] bytes)

Base64 encodes a byte array to string.

createMac

public static Mac createMac(SecurityAlgorithm algorithm,
                            byte[] secret)
                     throws ServiceResultException

Create Message Authentication Code (MAC).

Parameters:

algorithm - encryption algorithm

secret - an array of byte.

Returns:

MAC

Throws:

ServiceResultException - Bad_SecurityPolicyRejected algorithm not supported

createNonce

public static ByteString createNonce(int bytes)

Create a non-repeatable set of bytes.

Parameters:

bytes - number of byte

Returns:

nonce

createNonce

@Deprecated
public static ByteString createNonce(SecurityAlgorithm algorithm)
                                           throws ServiceResultException

Deprecated. use createNonce(int) and get the size from SecurityPolicy.getSecureChannelNonceLength() directly

createNonce.

Parameters:

algorithm - a SecurityAlgorithm object.

Returns:

an array of byte.

Throws:

ServiceResultException - if any.

decryptAsymm

public static void decryptAsymm(PrivateKey decryptingKey,
                                SecurityConfiguration profile,
                                byte[] dataToDecrypt,
                                byte[] output,
                                int outputOffset)
                         throws ServiceResultException

Convenience method for CryptoProvider.decryptAsymm(PrivateKey, SecurityAlgorithm, byte[], byte[], int) Possible to use only SecurityConfiguration instead of specifying SecurityAlgorithm explicitly.

Parameters:

decryptingKey - a PrivateKey object.

profile - a SecurityConfiguration object.

dataToDecrypt - an array of byte.

output - output

outputOffset - output offset

Throws:

ServiceResultException - if any.

encryptAsymm

public static byte[] encryptAsymm(byte[] input,
                                  PublicKey key,
                                  SecurityAlgorithm algorithm)
                           throws InvalidKeyException,
                                  IllegalBlockSizeException,
                                  BadPaddingException,
                                  ServiceResultException,
                                  NoSuchAlgorithmException,
                                  NoSuchPaddingException

Convenience method for CryptoProvider.encryptAsymm(java.security.PublicKey, com.prosysopc.ua.stack.transport.security.SecurityAlgorithm, byte[], byte[], int).

Parameters:

input - an array of byte.

key - a PublicKey object.

algorithm - a SecurityAlgorithm object.

Returns:

an array of byte.

Throws:

InvalidKeyException - if any.

IllegalBlockSizeException - if any.

BadPaddingException - if any.

ServiceResultException - if any.

NoSuchAlgorithmException - if any.

NoSuchPaddingException - if any.

encryptAsymm

public static void encryptAsymm(Certificate encryptingCertificate,
                                SecurityConfiguration profile,
                                byte[] dataToEncrypt,
                                byte[] output,
                                int outputOffset)
                         throws ServiceResultException

Convenience method for CryptoProvider.encryptAsymm(PublicKey, SecurityAlgorithm, byte[], byte[], int) Possible to use only Certificate and SecurityConfiguration instead of specifying PublicKey and SecurityAlgorithm explicitly.

Parameters:

encryptingCertificate - Certificate which public key will be used during encryption.

profile - Asymmetric encryption algorithm will be taken from this SecurityConfiguration

dataToEncrypt - Data to encrypt

output - output

outputOffset - output offset

Throws:

ServiceResultException - if any.

filterCipherSuiteList

public static String[] filterCipherSuiteList(String[] cipherSuiteSet,
                                             String[] cipherSuitePatterns)

filterCipherSuiteList.

Parameters:

cipherSuiteSet - an array of String objects.

cipherSuitePatterns - an array of String objects.

Returns:

an array of String objects.

getAsymmetricCipher

public static Cipher getAsymmetricCipher(SecurityAlgorithm algorithm)
                                  throws ServiceResultException

Create signer instance using an algorithm uri. http://www.ietf.org/rfc/rfc2437.txt Ciphers are defined in PKCS #1: RSA Cryptography Specifications

Parameters:

algorithm - UA Specified algorithm

Returns:

Cipher

Throws:

ServiceResultException - if algorithm is not supported by the stack

getAsymmInputBlockSize

public static int getAsymmInputBlockSize(SecurityAlgorithm algorithm)
                                  throws ServiceResultException

getAsymmInputBlockSize.

Parameters:

algorithm - a SecurityAlgorithm object.

Returns:

a int.

Throws:

ServiceResultException - if any.

getCipherBlockSize

public static int getCipherBlockSize(SecurityAlgorithm algorithm,
                                     Key key)
                              throws ServiceResultException

Get cipher block (=output) size in bytes.

Parameters:

algorithm - algorithm

key - Optional, required for asymmetric encryption algorithms

Returns:

cipher block size

Throws:

ServiceResultException - Bad_SecurityPolicyRejected algorithm not supported

getCipherSuiteIntersection

public static String[] getCipherSuiteIntersection(String[] cipherSuiteSet1,
                                                  String[] cipherSuiteSet2,
                                                  boolean omitProtocol)

Create an intersection of two lists of cipher suite lists.

Parameters:

cipherSuiteSet1 - enabled cipher suites

cipherSuiteSet2 - filter list

omitProtocol - if true the first 3 characters are ignored in compare

Returns:

an intersection of suites

getCryptoProvider

public static CryptoProvider getCryptoProvider()

Returns CryptoProvider previously set with setCryptoProvider(CryptoProvider). If it is not set, tries to load BouncyCastle based on the return value of getSecurityProviderName(). Throws RuntimeException if cannot be loaded.

getNonceLength

@Deprecated
public static int getNonceLength(SecurityAlgorithm algorithm)
                                       throws ServiceResultException

Deprecated. use SecurityPolicy.getSecureChannelNonceLength() directly instead

Returns the length of the nonce to be used with an asymmetric or symmetric encryption algorithm.

For symmetric algorithms, returns the algorithm key size (in bytes). For asymmetric algorithms, returns 32.

Parameters:

algorithm - encryption algorithm or null (=no encryption)

Returns:

the length of the nonce in bytes

Throws:

ServiceResultException - Bad_SecurityPolicyRejected, if the algorithm is not supported

getPlainTextBlockSize

public static int getPlainTextBlockSize(SecurityAlgorithm securityAlgorithm,
                                        Key key)
                                 throws ServiceResultException

Get plain text block (=input) size in bytes.

Parameters:

securityAlgorithm - algorithm

key - Optional, required for asymmetric encryption algorithms

Returns:

cipher block size

Throws:

ServiceResultException - Bad_SecurityPolicyRejected algorithm not supported

getRandom

public static SecureRandom getRandom()

The SecureRandom instance used in crypto operations of the SDK. *

By default, this is SecureRandom.getInstance("SHA1PRNG"), which is available in all Java systems, but may not provide the best entropy for all crypto operations. By default it is also seeded with System.currentTimeMillis() and System.nanoTime(), to avoid blocking at the application startup.

If setRandomReseedCount(int) is defined, the instance will also be automatically reseeded every now and then to add more entropy to the default instance.

Use #setEnableBlockingRandomInit() to enable default initialization with system specific (possibly blocking) algorithm, instead.

Or use setRandom(SecureRandom) to use a better entropy source than the default implementation.

getRandomReseedCount

public static int getRandomReseedCount()

The ReseedCount defines how often the getRandom() will reseed the instance.

getSecurityProvider

public static Provider getSecurityProvider()

Returns a Provider that can be used for crypto operations.

getSecurityProviderName

@Deprecated
public static String getSecurityProviderName()

Deprecated. use getSecurityProvider() instead

The Preferred Security Provider name. If not set via setSecurityProviderName(String), will return "BC". Otherwise returns the set String.

getSecurityProviderName

@Deprecated
public static String getSecurityProviderName(Class<?> clazz)

Deprecated. use getSecurityProvider() instead

Gets a suitable jce provider name for the given situation.

getSignatureSize

public static int getSignatureSize(SecurityAlgorithm signatureAlgorithm,
                                   Key key)
                            throws ServiceResultException

Get signature size in bytes.

Parameters:

signatureAlgorithm - a SecurityAlgorithm object.

key - a Key object.

Returns:

signature size in bytes

Throws:

ServiceResultException - Bad_SecurityPolicyRejected algorithm not supported

hexToBytes

public static byte[] hexToBytes(String string)

Converts a hexadecimal string to an array of bytes.

Parameters:

string - the string to convert

Returns:

null if string is null, otherwise the bytes, if parsing succeeds.

Throws:

NumberFormatException - if the string is not a hexadecimal string

hexToInt

public static Integer hexToInt(String string)
                        throws NumberFormatException

Converts a hexadecimal string to Integer.

Parameters:

string - the string to convert

Returns:

null if string is null, otherwise the Integer value, if parsing succeeds.

Throws:

NumberFormatException - if the string is not a hexadecimal string

hexToLong

public static Long hexToLong(String string)

Converts a hexadecimal string to Long.

Parameters:

string - the string to convert

Returns:

null if string is null, otherwise the Long value, if parsing succeeds.

Throws:

NumberFormatException - if the string is not a hexadecimal string

hexToLong

public static Long hexToLong(String string,
                             int firstIndex,
                             int maxLen)
                      throws NumberFormatException

Converts a hexadecimal string to Long.

Parameters:

string - the string to convert

firstIndex - the first character to start parsing from

maxLen - max number of characters to parse

Returns:

null if string is null, otherwise the Long value, if parsing succeeds.

Throws:

NumberFormatException - if the string is not a hexadecimal string

setCryptoProvider

public static void setCryptoProvider(CryptoProvider cryptoProvider)

Define the preferred CryptoProvider. Usually this is determined automatically, but you may define the provider that you wish to use yourself. NOTE! This method will set the setSecurityProviderName(String) from the given provider.

Parameters:

cryptoProvider - the cryptoProvider to set, if null will clear the previous one.

setRandom

public static void setRandom(SecureRandom secureRandom)

Replaces the default SecureRandom instance used in crypto operations of the SDK.

By default, getRandom() is initialized with SecureRandom.getInstance(..). On Windows 'Windows-PRNG' is used and 'NativePRNGNonBlocking' elsewhere. In case it is not found, 'SHA1PRNG' is used as a fallback. The 'SHA1PRNG' is seeded with System.currentTimeMillis() and System.nanoTime(), to avoid blocking at the application startup. For the others SecureRandom.nextBytes(byte[]) is used ('Windows-PRNG' and 'NativePRNGNonBlocking' should not block here).

This should be called at the start of the application before any other interactions with the SDK. Note that this method does call SecureRandom.setSeed(long) with System.currentTimeMillis() and System.nanoTime(). for the given SecureRandom. Depending on the SecureRandom you chose, you might wish to call SecureRandom.nextBytes(byte[]) before calling this to ensure the initial seed is obtained internally (note that this operation might block, which is why it is not done by this method).

Throws:

IllegalArgumentException - if called with null

setRandomReseedCount

public static void setRandomReseedCount(int reseedCount)

Define how often getRandom() should be reseeded automatically.

Reseeding is not a blocking operation, since it uses the system clock with nanosecond accuracy, but still need not be done too often. Good values might still be between 10 and 100.

If the value is 0, automatic reseeding will not happen.

If you wish to use the system reseeding capabilities, you should provide your own SecureRandom instance and call reseed (Java 9+) for it every now and then.

See Also:

#setRandomBlockingInitEnabled(boolean), setRandom(SecureRandom)

setSecurityProviderName

public static void setSecurityProviderName(String securityProviderName)

Define the preferred SecurityProvider. Usually this is determined automatically if BouncyCastle is found, but you may define the provider name that you wish to use yourself.

NOTE! Calling this with a different provider name than previously set will reset possible calls made to setCryptoProvider(CryptoProvider).

Parameters:

securityProviderName - the securityProviderName to set, e.g. "BC" for BouncyCastleProvider

signAsymm

public static SignatureData signAsymm(PrivateKey signerKey,
                                      SecurityAlgorithm algorithm,
                                      byte[] dataToSign)
                               throws ServiceResultException

signAsymm.

Parameters:

signerKey - the private key used to sign the data

algorithm - asymmetric signer algorithm, See SecurityAlgorithm

dataToSign - the data to sign

Returns:

SignatureData

Throws:

ServiceResultException - if the signing fails. Read the StatusCode and cause for more details

toHex

public static String toHex(byte[] bytes)

Convenience method for "displaying" a hex-string of a given byte array. Calls toHex(byte[], int) with bytesPerRow=0 (no line breaks)

Parameters:

bytes - the byte array to "display"

Returns:

a String object.

toHex

public static String toHex(byte[] bytes,
                           int bytesPerRow)

Convenience method for "displaying" a hex-string of a given byte array. Breaks the string to lines, if bytesPerRow > 0.

Parameters:

bytes - the byte array to "display"

bytesPerRow - number of bytes to include on a text row. If it is 0, no line breaks are added.

Returns:

a String object.

toHex

public static String toHex(byte[] bytes,
                           int bytesPerRow,
                           boolean includeLengthPrefix)

Convenience method for "displaying" a hex-string of a given byte array. Breaks the string to lines, if bytesPerRow > 0. Optionally displays the number of bytes in the array.

The value is always prefixed with "0x" to distinguish it from any 10-base number.

For example, if bytes = {15, 16} the string will be "0x0F10"

Parameters:

bytes - the byte array to "display"

bytesPerRow - number of bytes to include on a text row. If it is 0, no line breaks are added.

includeLengthPrefix - if true, prefix the string with the number of bytes e.g. "[2] 0x4d6d"

Returns:

a String object.

toHex

public static String toHex(int value)

Convenience method for "displaying" an int value as a hex-string, interpreting it as an unsigned value.

The value is always prefixed with "0x" to distinguish it from a 10-base number and it will always be of full Integer length, e.g. 8 bytes and uses lower case letters ("abcdef").

For example, value = 258 will be converted to "0x00000102", Integer.MIN_VALUE to "0x8000000" and -1 to "0xffffffff".

Returns:

a String object.

toHex

public static String toHex(long value)

Convenience method for "displaying" an Long value as a hex-string.

The value is always prefixed with "0x" to distinguish it from a 10-base number and it will always be of full Integer length, e.g. 16 bytes and uses lower case letters ("abcdef").

For example, value = 258 will be converted to "0x0000000000000102", Long.MIN_VALUE to "0x8000000000000000" and -1 to "0xffffffffffffffff".

Returns:

a String object.

verifyAsymm

public static boolean verifyAsymm(X509Certificate certificate,
                                  SecurityAlgorithm algorithm,
                                  byte[] data,
                                  byte[] signature)
                           throws ServiceResultException

Verify a signature.

Parameters:

certificate - the certificate used to verify the signature

algorithm - the signature algorithm

data - data to verify

signature - the signature to verify

Returns:

true if the signature is valid

Throws:

ServiceResultException - if the verification fails