org.opensaml.xml.security
Class SecurityHelper

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

public final class SecurityHelper
extends java.lang.Object

Helper methods for security-related requirements.


Method Summary
static EncryptionParameters buildDataEncryptionParams(Credential encryptionCredential, SecurityConfiguration config, java.lang.String keyInfoGenName)
          Build an instance of EncryptionParameters suitable for passing to an Encrypter.
static KeyEncryptionParameters buildKeyEncryptionParams(Credential encryptionCredential, java.lang.String wrappedKeyAlgorithm, SecurityConfiguration config, java.lang.String keyInfoGenName, java.lang.String recipient)
          Build an instance of KeyEncryptionParameters suitable for passing to an Encrypter.
static java.security.PrivateKey decodePrivateKey(byte[] key, char[] password)
          Decodes RSA/DSA private keys in DER, PEM, or PKCS#8 (encrypted or unencrypted) formats.
static java.security.PrivateKey decodePrivateKey(java.io.File key, char[] password)
          Decodes RSA/DSA private keys in DER, PEM, or PKCS#8 (encrypted or unencrypted) formats.
static java.security.PublicKey decodePublicKey(byte[] key, char[] password)
          Decodes RSA/DSA public keys in DER or PEM formats.
static javax.crypto.SecretKey decodeSecretKey(byte[] key, char[] password)
          Decodes secret keys in DER and PEM format.
static java.security.PublicKey derivePublicKey(java.security.PrivateKey key)
          Derives the public key from either a DSA or RSA private key.
static java.security.Key extractDecryptionKey(Credential credential)
          Extract the decryption key from the credential.
static java.security.Key extractEncryptionKey(Credential credential)
          Extract the encryption key from the credential.
static java.security.Key extractSigningKey(Credential credential)
          Extract the signing key from the credential.
static java.security.Key extractVerificationKey(Credential credential)
          Extract the verification key from the credential.
static javax.crypto.SecretKey generateSymmetricKey(java.lang.String algoURI)
          Generates a random Java JCE symmetric Key object from the specified XML Encryption algorithm URI.
static java.lang.String getAlgorithmIDFromURI(java.lang.String algorithmURI)
          Get the Java security JCA/JCE algorithm identifier associated with an algorithm URI.
static java.lang.String getKeyAlgorithmFromURI(java.lang.String algorithmURI)
          Get the Java security JCA/JCE key algorithm specifier associated with an algorithm URI.
static KeyInfoGenerator getKeyInfoGenerator(Credential credential, SecurityConfiguration config, java.lang.String keyInfoGenName)
          Obtains a KeyInfoGenerator for the specified Credential.
static java.lang.Integer getKeyLength(java.security.Key key)
          Get the key length in bits of the specified key.
static java.lang.Integer getKeyLengthFromURI(java.lang.String algorithmURI)
          Get the length of the key indicated by the algorithm URI, if applicable and available.
static BasicCredential getSimpleCredential(java.security.PublicKey publicKey, java.security.PrivateKey privateKey)
          Get a simple, minimal credential containing a public key, and optionally a private key.
static BasicCredential getSimpleCredential(javax.crypto.SecretKey secretKey)
          Get a simple, minimal credential containing a secret (symmetric) key.
static BasicX509Credential getSimpleCredential(java.security.cert.X509Certificate cert, java.security.PrivateKey privateKey)
          Get a simple, minimal credential containing an end-entity X.509 certificate, and optionally a private key.
static boolean isHMAC(java.lang.String signatureAlgorithm)
          Check whether the signature method algorithm URI indicates HMAC.
static boolean matchKeyPair(java.security.PublicKey pubKey, java.security.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, java.lang.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 java.lang.String getAlgorithmIDFromURI(java.lang.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(java.lang.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 java.lang.String getKeyAlgorithmFromURI(java.lang.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 java.lang.Integer getKeyLengthFromURI(java.lang.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 javax.crypto.SecretKey generateSymmetricKey(java.lang.String algoURI)
                                                   throws java.security.NoSuchAlgorithmException,
                                                          java.security.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:
java.security.NoSuchAlgorithmException - thrown if the specified algorithm is invalid
java.security.KeyException - thrown if the length of the key to generate could not be determined

extractEncryptionKey

public static java.security.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 java.security.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 java.security.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 java.security.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 java.lang.Integer getKeyLength(java.security.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(javax.crypto.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(java.security.PublicKey publicKey,
                                                  java.security.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(java.security.cert.X509Certificate cert,
                                                      java.security.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 javax.crypto.SecretKey decodeSecretKey(byte[] key,
                                                     char[] password)
                                              throws java.security.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:
java.security.KeyException - thrown if the key can not be decoded

decodePublicKey

public static java.security.PublicKey decodePublicKey(byte[] key,
                                                      char[] password)
                                               throws java.security.KeyException
Decodes RSA/DSA public keys in DER or PEM formats.

Parameters:
key - encoded key
password - password if the key is encrypted or null if not
Returns:
deocded key
Throws:
java.security.KeyException - thrown if the key can not be decoded

derivePublicKey

public static java.security.PublicKey derivePublicKey(java.security.PrivateKey key)
                                               throws java.security.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:
java.security.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 java.security.PrivateKey decodePrivateKey(java.io.File key,
                                                        char[] password)
                                                 throws java.security.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:
java.security.KeyException - thrown if the key can not be decoded

decodePrivateKey

public static java.security.PrivateKey decodePrivateKey(byte[] key,
                                                        char[] password)
                                                 throws java.security.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:
java.security.KeyException - thrown if the key can not be decoded

matchKeyPair

public static boolean matchKeyPair(java.security.PublicKey pubKey,
                                   java.security.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,
                                          java.lang.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:

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,
                                                             java.lang.String keyInfoGenName)
Build an instance of EncryptionParameters suitable for passing to an Encrypter.

The following parameter values will be added:

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,
                                                               java.lang.String wrappedKeyAlgorithm,
                                                               SecurityConfiguration config,
                                                               java.lang.String keyInfoGenName,
                                                               java.lang.String recipient)
                                                        throws SecurityException
Build an instance of KeyEncryptionParameters suitable for passing to an Encrypter.

The following parameter values will be added:

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,
                                                   java.lang.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


Copyright © 2006-2011 Internet2. All Rights Reserved.