org.opensaml.xml.security
Class SecurityHelper

java.lang.Object
  org.opensaml.xml.security.SecurityHelper

public final class SecurityHelper
extends Object

Helper methods for security-related requirements.

Method Summary

static KeyInfoCredentialResolver	buildBasicInlineKeyInfoResolver() Get a basic KeyInfo credential resolver which can process standard inline data - RSAKeyValue, DSAKeyValue, X509Data.
static EncryptionParameters	buildDataEncryptionParams(Credential encryptionCredential, SecurityConfiguration config, String keyInfoGenName) Build an instance of EncryptionParameters suitable for passing to an Encrypter.
static DSAPrivateKey	buildJavaDSAPrivateKey(String base64EncodedKey) Build Java DSA private key from base64 encoding.
static DSAPublicKey	buildJavaDSAPublicKey(String base64EncodedKey) Build Java DSA public key from base64 encoding.
static ECPublicKey	buildJavaECPublicKey(String base64EncodedKey) Build Java EC public key from base64 encoding.
static PrivateKey	buildJavaPrivateKey(String base64EncodedKey) Build Java private key from base64 encoding.
static RSAPrivateKey	buildJavaRSAPrivateKey(String base64EncodedKey) Build Java RSA private key from base64 encoding.
static RSAPublicKey	buildJavaRSAPublicKey(String base64EncodedKey) Build Java RSA public key from base64 encoding.
static X509Certificate	buildJavaX509Cert(String base64Cert) Build Java certificate from base64 encoding.
static X509CRL	buildJavaX509CRL(String base64CRL) Build Java CRL from base64 encoding.
static PublicKey	buildKey(KeySpec keySpec, String keyAlgorithm) Generates a public key from the given key spec.
static KeyEncryptionParameters	buildKeyEncryptionParams(Credential encryptionCredential, String wrappedKeyAlgorithm, SecurityConfiguration config, String keyInfoGenName, String recipient) Build an instance of KeyEncryptionParameters suitable for passing to an Encrypter.
static PrivateKey	decodePrivateKey(byte[] key, char[] password) Decodes RSA/DSA private keys in DER, PEM, or PKCS#8 (encrypted or unencrypted) formats.
static PrivateKey	decodePrivateKey(File key, char[] password) Decodes RSA/DSA private keys in DER, PEM, or PKCS#8 (encrypted or unencrypted) formats.
static PublicKey	decodePublicKey(byte[] key, char[] password) Decodes RSA/DSA public keys in DER-encoded "SubjectPublicKeyInfo" format.
static SecretKey	decodeSecretKey(byte[] key, char[] password) Decodes secret keys in DER and PEM format.
static PublicKey	derivePublicKey(PrivateKey key) Derives the public key from either a DSA or RSA private key.
static Key	extractDecryptionKey(Credential credential) Extract the decryption key from the credential.
static Key	extractEncryptionKey(Credential credential) Extract the encryption key from the credential.
static Key	extractSigningKey(Credential credential) Extract the signing key from the credential.
static Key	extractVerificationKey(Credential credential) Extract the verification key from the credential.
static SecretKey	generateKey(String algo, int keyLength, String provider) Generate a random symmetric key.
static Credential	generateKeyAndCredential(String algorithmURI) Generate a random symmetric key and return in a BasicCredential.
static SecretKey	generateKeyFromURI(String algoURI) Randomly generates a Java JCE symmetric Key object from the specified XML Encryption algorithm URI.
static KeyPair	generateKeyPair(String algo, int keyLength, String provider) Generate a random asymmetric key pair.
static Credential	generateKeyPairAndCredential(String algorithmURI, int keyLength, boolean includePrivate) Generate a random asymmetric key pair and return in a BasicCredential.
static KeyPair	generateKeyPairFromURI(String algoURI, int keyLength) Randomly generates a Java JCE KeyPair object from the specified XML Encryption algorithm URI.
static SecretKey	generateSymmetricKey(String algoURI) Generates a random Java JCE symmetric Key object from the specified XML Encryption algorithm URI.
static String	getAlgorithmIDFromURI(String algorithmURI) Get the Java security JCA/JCE algorithm identifier associated with an algorithm URI.
static String	getKeyAlgorithmFromURI(String algorithmURI) Get the Java security JCA/JCE key algorithm specifier associated with an algorithm URI.
static KeyInfoGenerator	getKeyInfoGenerator(Credential credential, SecurityConfiguration config, String keyInfoGenName) Obtains a KeyInfoGenerator for the specified Credential.
static Integer	getKeyLength(Key key) Get the key length in bits of the specified key.
static Integer	getKeyLengthFromURI(String algorithmURI) Get the length of the key indicated by the algorithm URI, if applicable and available.
static BasicCredential	getSimpleCredential(PublicKey publicKey, PrivateKey privateKey) Get a simple, minimal credential containing a public key, and optionally a private key.
static BasicCredential	getSimpleCredential(SecretKey secretKey) Get a simple, minimal credential containing a secret (symmetric) key.
static BasicX509Credential	getSimpleCredential(X509Certificate cert, PrivateKey privateKey) Get a simple, minimal credential containing an end-entity X.509 certificate, and optionally a private key.
static boolean	isHMAC(String signatureAlgorithm) Check whether the signature method algorithm URI indicates HMAC.
static boolean	matchKeyPair(PublicKey pubKey, PrivateKey privKey) Compare the supplied public and private keys, and determine if they correspond to the same key pair.
static void	prepareSignatureParams(Signature signature, Credential signingCredential, SecurityConfiguration config, String keyInfoGenName) Prepare a Signature with necessary additional information prior to signing.

Methods inherited from class java.lang.Object

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

Method Detail

getAlgorithmIDFromURI

public static String getAlgorithmIDFromURI(String algorithmURI)

Get the Java security JCA/JCE algorithm identifier associated with an algorithm URI.

Parameters:

algorithmURI - the algorithm URI to evaluate

Returns:

the Java algorithm identifier, or null if the mapping is unavailable or indeterminable from the URI

isHMAC

public static boolean isHMAC(String signatureAlgorithm)

Check whether the signature method algorithm URI indicates HMAC.

Parameters:

signatureAlgorithm - the signature method algorithm URI

Returns:

true if URI indicates HMAC, false otherwise

getKeyAlgorithmFromURI

public static String getKeyAlgorithmFromURI(String algorithmURI)

Get the Java security JCA/JCE key algorithm specifier associated with an algorithm URI.

Parameters:

algorithmURI - the algorithm URI to evaluate

Returns:

the Java key algorithm specifier, or null if the mapping is unavailable or indeterminable from the URI

getKeyLengthFromURI

public static Integer getKeyLengthFromURI(String algorithmURI)

Get the length of the key indicated by the algorithm URI, if applicable and available.

Parameters:

algorithmURI - the algorithm URI to evaluate

Returns:

the length of the key indicated by the algorithm URI, or null if the length is either unavailable or indeterminable from the URI

generateSymmetricKey

public static SecretKey generateSymmetricKey(String algoURI)
                                      throws NoSuchAlgorithmException,
                                             KeyException

Generates a random Java JCE symmetric Key object from the specified XML Encryption algorithm URI.

Parameters:

algoURI - The XML Encryption algorithm URI

Returns:

a randomly-generated symmetric Key

Throws:

NoSuchAlgorithmException - thrown if the specified algorithm is invalid

KeyException - thrown if the length of the key to generate could not be determined

extractEncryptionKey

public static Key extractEncryptionKey(Credential credential)

Extract the encryption key from the credential.

Parameters:

credential - the credential containing the encryption key

Returns:

the encryption key (either a public key or a secret (symmetric) key

extractDecryptionKey

public static Key extractDecryptionKey(Credential credential)

Extract the decryption key from the credential.

Parameters:

credential - the credential containing the decryption key

Returns:

the decryption key (either a private key or a secret (symmetric) key

extractSigningKey

public static Key extractSigningKey(Credential credential)

Extract the signing key from the credential.

Parameters:

credential - the credential containing the signing key

Returns:

the signing key (either a private key or a secret (symmetric) key

extractVerificationKey

public static Key extractVerificationKey(Credential credential)

Extract the verification key from the credential.

Parameters:

credential - the credential containing the verification key

Returns:

the verification key (either a public key or a secret (symmetric) key

getKeyLength

public static Integer getKeyLength(Key key)

Get the key length in bits of the specified key.

Parameters:

key - the key to evaluate

Returns:

length of the key in bits, or null if the length can not be determined

getSimpleCredential

public static BasicCredential getSimpleCredential(SecretKey secretKey)

Get a simple, minimal credential containing a secret (symmetric) key.

Parameters:

secretKey - the symmetric key to wrap

Returns:

a credential containing the secret key specified

getSimpleCredential

public static BasicCredential getSimpleCredential(PublicKey publicKey,
                                                  PrivateKey privateKey)

Get a simple, minimal credential containing a public key, and optionally a private key.

Parameters:

publicKey - the public key to wrap

privateKey - the private key to wrap, which may be null

Returns:

a credential containing the key(s) specified

getSimpleCredential

public static BasicX509Credential getSimpleCredential(X509Certificate cert,
                                                      PrivateKey privateKey)

Get a simple, minimal credential containing an end-entity X.509 certificate, and optionally a private key.

Parameters:

cert - the end-entity certificate to wrap

privateKey - the private key to wrap, which may be null

Returns:

a credential containing the certificate and key specified

decodeSecretKey

public static SecretKey decodeSecretKey(byte[] key,
                                        char[] password)
                                 throws KeyException

Decodes secret keys in DER and PEM format. This method is not yet implemented.

Parameters:

key - secret key

password - password if the key is encrypted or null if not

Returns:

the decoded key

Throws:

KeyException - thrown if the key can not be decoded

decodePublicKey

public static PublicKey decodePublicKey(byte[] key,
                                        char[] password)
                                 throws KeyException

Decodes RSA/DSA public keys in DER-encoded "SubjectPublicKeyInfo" format.

Parameters:

key - encoded key

password - password if the key is encrypted or null if not

Returns:

decoded key

Throws:

KeyException - thrown if the key can not be decoded

derivePublicKey

public static PublicKey derivePublicKey(PrivateKey key)
                                 throws KeyException

Derives the public key from either a DSA or RSA private key.

Parameters:

key - the private key to derive the public key from

Returns:

the derived public key

Throws:

KeyException - thrown if the given private key is not a DSA or RSA key or there is a problem generating the public key

decodePrivateKey

public static PrivateKey decodePrivateKey(File key,
                                          char[] password)
                                   throws KeyException

Decodes RSA/DSA private keys in DER, PEM, or PKCS#8 (encrypted or unencrypted) formats.

Parameters:

key - encoded key

password - decryption password or null if the key is not encrypted

Returns:

deocded private key

Throws:

KeyException - thrown if the key can not be decoded

decodePrivateKey

public static PrivateKey decodePrivateKey(byte[] key,
                                          char[] password)
                                   throws KeyException

Decodes RSA/DSA private keys in DER, PEM, or PKCS#8 (encrypted or unencrypted) formats.

Parameters:

key - encoded key

password - decryption password or null if the key is not encrypted

Returns:

deocded private key

Throws:

KeyException - thrown if the key can not be decoded

buildJavaX509Cert

public static X509Certificate buildJavaX509Cert(String base64Cert)
                                         throws CertificateException

Build Java certificate from base64 encoding.

Parameters:

base64Cert - base64-encoded certificate

Returns:

a native Java X509 certificate

Throws:

CertificateException - thrown if there is an error constructing certificate

buildJavaX509CRL

public static X509CRL buildJavaX509CRL(String base64CRL)
                                throws CertificateException,
                                       CRLException

Build Java CRL from base64 encoding.

Parameters:

base64CRL - base64-encoded CRL

Returns:

a native Java X509 CRL

Throws:

CertificateException - thrown if there is an error constructing certificate

CRLException - thrown if there is an error constructing CRL

buildJavaDSAPublicKey

public static DSAPublicKey buildJavaDSAPublicKey(String base64EncodedKey)
                                          throws KeyException

Build Java DSA public key from base64 encoding.

Parameters:

base64EncodedKey - base64-encoded DSA public key

Returns:

a native Java DSAPublicKey

Throws:

KeyException - thrown if there is an error constructing key

buildJavaRSAPublicKey

public static RSAPublicKey buildJavaRSAPublicKey(String base64EncodedKey)
                                          throws KeyException

Build Java RSA public key from base64 encoding.

Parameters:

base64EncodedKey - base64-encoded RSA public key

Returns:

a native Java RSAPublicKey

Throws:

KeyException - thrown if there is an error constructing key

buildJavaECPublicKey

public static ECPublicKey buildJavaECPublicKey(String base64EncodedKey)
                                        throws KeyException

Build Java EC public key from base64 encoding.

Parameters:

base64EncodedKey - base64-encoded EC public key

Returns:

a native Java ECPublicKey

Throws:

KeyException - thrown if there is an error constructing key

buildJavaRSAPrivateKey

public static RSAPrivateKey buildJavaRSAPrivateKey(String base64EncodedKey)
                                            throws KeyException

Build Java RSA private key from base64 encoding.

Parameters:

base64EncodedKey - base64-encoded RSA private key

Returns:

a native Java RSAPrivateKey

Throws:

KeyException - thrown if there is an error constructing key

buildJavaDSAPrivateKey

public static DSAPrivateKey buildJavaDSAPrivateKey(String base64EncodedKey)
                                            throws KeyException

Build Java DSA private key from base64 encoding.

Parameters:

base64EncodedKey - base64-encoded DSA private key

Returns:

a native Java DSAPrivateKey

Throws:

KeyException - thrown if there is an error constructing key

buildJavaPrivateKey

public static PrivateKey buildJavaPrivateKey(String base64EncodedKey)
                                      throws KeyException

Build Java private key from base64 encoding. The key should have no password.

Parameters:

base64EncodedKey - base64-encoded private key

Returns:

a native Java PrivateKey

Throws:

KeyException - thrown if there is an error constructing key

buildKey

public static PublicKey buildKey(KeySpec keySpec,
                                 String keyAlgorithm)
                          throws KeyException

Generates a public key from the given key spec.

Parameters:

keySpec - KeySpec specification for the key

keyAlgorithm - key generation algorithm, only DSA and RSA supported

Returns:

the generated PublicKey

Throws:

KeyException - thrown if the key algorithm is not supported by the JCE or the key spec does not contain valid information

generateKeyFromURI

public static SecretKey generateKeyFromURI(String algoURI)
                                    throws NoSuchAlgorithmException,
                                           NoSuchProviderException

Randomly generates a Java JCE symmetric Key object from the specified XML Encryption algorithm URI.

Parameters:

algoURI - The XML Encryption algorithm URI

Returns:

a randomly-generated symmteric key

Throws:

NoSuchProviderException - provider not found

NoSuchAlgorithmException - algorithm not found

generateKeyPairFromURI

public static KeyPair generateKeyPairFromURI(String algoURI,
                                             int keyLength)
                                      throws NoSuchAlgorithmException,
                                             NoSuchProviderException

Randomly generates a Java JCE KeyPair object from the specified XML Encryption algorithm URI.

Parameters:

algoURI - The XML Encryption algorithm URI

keyLength - the length of key to generate

Returns:

a randomly-generated KeyPair

Throws:

NoSuchProviderException - provider not found

NoSuchAlgorithmException - algorithm not found

generateKey

public static SecretKey generateKey(String algo,
                                    int keyLength,
                                    String provider)
                             throws NoSuchAlgorithmException,
                                    NoSuchProviderException

Generate a random symmetric key.

Parameters:

algo - key algorithm

keyLength - key length

provider - JCA provider

Returns:

randomly generated symmetric key

Throws:

NoSuchAlgorithmException - algorithm not found

NoSuchProviderException - provider not found

generateKeyPair

public static KeyPair generateKeyPair(String algo,
                                      int keyLength,
                                      String provider)
                               throws NoSuchAlgorithmException,
                                      NoSuchProviderException

Generate a random asymmetric key pair.

Parameters:

algo - key algorithm

keyLength - key length

provider - JCA provider

Returns:

randomly generated key

Throws:

NoSuchAlgorithmException - algorithm not found

NoSuchProviderException - provider not found

generateKeyAndCredential

public static Credential generateKeyAndCredential(String algorithmURI)
                                           throws NoSuchAlgorithmException,
                                                  NoSuchProviderException

Generate a random symmetric key and return in a BasicCredential.

Parameters:

algorithmURI - The XML Encryption algorithm URI

Returns:

a basic credential containing a randomly generated symmetric key

Throws:

NoSuchAlgorithmException - algorithm not found

NoSuchProviderException - provider not found

generateKeyPairAndCredential

public static Credential generateKeyPairAndCredential(String algorithmURI,
                                                      int keyLength,
                                                      boolean includePrivate)
                                               throws NoSuchAlgorithmException,
                                                      NoSuchProviderException

Generate a random asymmetric key pair and return in a BasicCredential.

Parameters:

algorithmURI - The XML Encryption algorithm URI

keyLength - key length

includePrivate - if true, the private key will be included as well

Returns:

a basic credential containing a randomly generated asymmetric key pair

Throws:

NoSuchAlgorithmException - algorithm not found

NoSuchProviderException - provider not found

buildBasicInlineKeyInfoResolver

public static KeyInfoCredentialResolver buildBasicInlineKeyInfoResolver()

Get a basic KeyInfo credential resolver which can process standard inline data - RSAKeyValue, DSAKeyValue, X509Data.

Returns:

a new KeyInfoCredentialResolver instance

matchKeyPair

public static boolean matchKeyPair(PublicKey pubKey,
                                   PrivateKey privKey)
                            throws SecurityException

Compare the supplied public and private keys, and determine if they correspond to the same key pair.

Parameters:

pubKey - the public key

privKey - the private key

Returns:

true if the public and private are from the same key pair, false if not

Throws:

SecurityException - if the keys can not be evaluated, or if the key algorithm is unsupported or unknown

prepareSignatureParams

public static void prepareSignatureParams(Signature signature,
                                          Credential signingCredential,
                                          SecurityConfiguration config,
                                          String keyInfoGenName)
                                   throws SecurityException

Prepare a Signature with necessary additional information prior to signing.

NOTE:Since this operation modifies the specified Signature object, it should be called prior to marshalling the Signature object.

The following Signature values will be added:

• signature algorithm URI
• canonicalization algorithm URI
• HMAC output length (if applicable and a value is configured)
• a KeyInfo element representing the signing credential

Existing (non-null) values of these parameters on the specified signature will NOT be overwritten, however.

All values are determined by the specified SecurityConfiguration. If a security configuration is not supplied, the global security configuration (Configuration.getGlobalSecurityConfiguration()) will be used.

The signature algorithm URI and optional HMAC output length are derived from the signing credential.

The KeyInfo to be generated is based on the NamedKeyInfoGeneratorManager defined in the security configuration, and is determined by the type of the signing credential and an optional KeyInfo generator manager name. If the latter is ommited, the default manager (NamedKeyInfoGeneratorManager.getDefaultManager()) of the security configuration's named generator manager will be used.

Parameters:

signature - the Signature to be updated

signingCredential - the credential with which the Signature will be computed

config - the SecurityConfiguration to use (may be null)

keyInfoGenName - the named KeyInfoGeneratorManager configuration to use (may be null)

Throws:

SecurityException - thrown if there is an error generating the KeyInfo from the signing credential

buildDataEncryptionParams

public static EncryptionParameters buildDataEncryptionParams(Credential encryptionCredential,
                                                             SecurityConfiguration config,
                                                             String keyInfoGenName)

Build an instance of EncryptionParameters suitable for passing to an Encrypter.

The following parameter values will be added:

• the encryption credential (optional)
• encryption algorithm URI
• an appropriate KeyInfoGenerator instance which will be used to generate a KeyInfo element from the encryption credential

All values are determined by the specified SecurityConfiguration. If a security configuration is not supplied, the global security configuration (Configuration.getGlobalSecurityConfiguration()) will be used.

The encryption algorithm URI is derived from the optional supplied encryption credential. If omitted, the value of SecurityConfiguration.getAutoGeneratedDataEncryptionKeyAlgorithmURI() will be used.

The KeyInfoGenerator to be used is based on the NamedKeyInfoGeneratorManager defined in the security configuration, and is determined by the type of the signing credential and an optional KeyInfo generator manager name. If the latter is ommited, the default manager (NamedKeyInfoGeneratorManager.getDefaultManager()) of the security configuration's named generator manager will be used.

Parameters:

encryptionCredential - the credential with which the data will be encrypted (may be null)

config - the SecurityConfiguration to use (may be null)

keyInfoGenName - the named KeyInfoGeneratorManager configuration to use (may be null)

Returns:

a new instance of EncryptionParameters

buildKeyEncryptionParams

public static KeyEncryptionParameters buildKeyEncryptionParams(Credential encryptionCredential,
                                                               String wrappedKeyAlgorithm,
                                                               SecurityConfiguration config,
                                                               String keyInfoGenName,
                                                               String recipient)
                                                        throws SecurityException

Build an instance of KeyEncryptionParameters suitable for passing to an Encrypter.

The following parameter values will be added:

• the key encryption credential
• key transport encryption algorithm URI
• an appropriate KeyInfoGenerator instance which will be used to generate a KeyInfo element from the key encryption credential
• intended recipient of the resultant encrypted key (optional)

All values are determined by the specified SecurityConfiguration. If a security configuration is not supplied, the global security configuration (Configuration.getGlobalSecurityConfiguration()) will be used.

The encryption algorithm URI is derived from the optional supplied encryption credential. If omitted, the value of SecurityConfiguration.getAutoGeneratedDataEncryptionKeyAlgorithmURI() will be used.

The KeyInfoGenerator to be used is based on the NamedKeyInfoGeneratorManager defined in the security configuration, and is determined by the type of the signing credential and an optional KeyInfo generator manager name. If the latter is ommited, the default manager (NamedKeyInfoGeneratorManager.getDefaultManager()) of the security configuration's named generator manager will be used.

Parameters:

encryptionCredential - the credential with which the key will be encrypted

wrappedKeyAlgorithm - the JCA key algorithm name of the key to be encrypted (may be null)

config - the SecurityConfiguration to use (may be null)

keyInfoGenName - the named KeyInfoGeneratorManager configuration to use (may be null)

recipient - the intended recipient of the resultant encrypted key, typically the owner of the key encryption key (may be null)

Returns:

a new instance of KeyEncryptionParameters

Throws:

SecurityException - if encryption credential is not supplied

getKeyInfoGenerator

public static KeyInfoGenerator getKeyInfoGenerator(Credential credential,
                                                   SecurityConfiguration config,
                                                   String keyInfoGenName)

Obtains a KeyInfoGenerator for the specified Credential.

The KeyInfoGenerator returned is based on the NamedKeyInfoGeneratorManager defined by the specified security configuration via SecurityConfiguration.getKeyInfoGeneratorManager(), and is determined by the type of the signing credential and an optional KeyInfo generator manager name. If the latter is ommited, the default manager (NamedKeyInfoGeneratorManager.getDefaultManager()) of the security configuration's named generator manager will be used.

The generator is determined by the specified SecurityConfiguration. If a security configuration is not supplied, the global security configuration (Configuration.getGlobalSecurityConfiguration()) will be used.

Parameters:

credential - the credential for which a generator is desired

config - the SecurityConfiguration to use (may be null)

keyInfoGenName - the named KeyInfoGeneratorManager configuration to use (may be null)

Returns:

a KeyInfoGenerator appropriate for the specified credential