org.jasypt.digest.config.DigesterConfig Maven / Gradle / Ivy
/*
* =============================================================================
*
* Copyright (c) 2007-2010, The JASYPT team (http://www.jasypt.org)
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
* =============================================================================
*/
package org.jasypt.digest.config;
import java.security.Provider;
import org.jasypt.salt.SaltGenerator;
/**
*
* Common interface for config classes applicable to
* {@link org.jasypt.digest.StandardByteDigester},
* {@link org.jasypt.digest.StandardStringDigester},
* {@link org.jasypt.digest.PooledByteDigester} or
* {@link org.jasypt.digest.PooledStringDigester}
* objects.
*
*
* This interface lets the user create new DigesterConfig
* classes which retrieve values for this parameters from different
* (and maybe more secure) sources (remote servers, LDAP, other databases...),
* and do this transparently for the digester object.
*
*
* The config objects passed to a digester will only be queried once
* for each configuration parameter, and this will happen
* during the initialization of the digester object.
*
*
* For a default implementation, see {@link SimpleDigesterConfig}.
*
*
* @since 1.0
*
* @author Daniel Fernández
*
*/
public interface DigesterConfig {
/**
*
* Returns the name of an algorithm to be used for hashing, like "MD5" or
* "SHA-1".
*
*
* This algorithm has to be supported by your Java Virtual Machine, and
* it should be allowed as an algorithm for creating
* java.security.MessageDigest instances.
*
*
* If this method returns null, the digester will ignore the config object
* when deciding the algorithm to be used.
*
*
* @return the name of the algorithm to be used, or null if this object
* will not want to set an algorithm. See Appendix A
* in the Java
* Cryptography Architecture API Specification &
* Reference
* for information about standard algorithm names.
*/
public String getAlgorithm();
/**
*
* Returns the size of the salt to be used to compute the digest.
* This mechanism is explained in
* PKCS #5: Password-Based Cryptography Standard.
*
*
* If salt size is set to zero, then no salt will be used.
*
*
* If this method returns null, the digester will ignore the config object
* when deciding the size of the salt to be used.
*
*
* @return the size of the salt to be used, in bytes, or null if
* this object will not want to set a size for salt.
*/
public Integer getSaltSizeBytes();
/**
*
* Returns the number of times the hash function will be applied recursively.
*
* The hash function will be applied to its own results as many times as
* specified: h(h(...h(x)...))
*
*
* This mechanism is explained in
* PKCS #5: Password-Based Cryptography Standard.
*
*
* If this method returns null, the digester will ignore the config object
* when deciding the number of hashing iterations.
*
*
* @return the number of iterations, or null if this object will not want
* to set the number of iterations.
*/
public Integer getIterations();
/**
*
* Returns a {@link SaltGenerator} implementation to be used by the digester.
*
*
* If this method returns null, the digester will ignore the config object
* when deciding the salt generator to be used.
*
*
* @since 1.2
*
* @return the salt generator, or null if this object will not want to set
* a specific SaltGenerator implementation.
*/
public SaltGenerator getSaltGenerator();
/**
*
* Returns the name of the java.security.Provider implementation
* to be used by the digester for obtaining the digest algorithm. This
* provider must have been registered beforehand.
*
*
* If this method returns null, the digester will ignore this parameter
* when deciding the name of the security provider to be used.
*
*
* If this method does not return null, and neither does {@link #getProvider()},
* providerName will be ignored, and the provider object returned
* by getProvider() will be used.
*
*
* @since 1.3
*
* @return the name of the security provider to be used.
*/
public String getProviderName();
/**
*
* Returns the java.security.Provider implementation object
* to be used by the digester for obtaining the digest algorithm.
*
*
* If this method returns null, the digester will ignore this parameter
* when deciding the security provider object to be used.
*
*
* If this method does not return null, and neither does {@link #getProviderName()},
* providerName will be ignored, and the provider object returned
* by getProvider() will be used.
*
*
* The provider returned by this method does not need to be
* registered beforehand, and its use will not result in its
* being registered.
*
*
* @since 1.3
*
* @return the security provider object to be asked for the digest
* algorithm.
*/
public Provider getProvider();
/**
*
* Returns Boolean.TRUE if the salt bytes are to be appended after the
* message ones before performing the digest operation on the whole. The
* default behaviour is to insert those bytes before the message bytes, but
* setting this configuration item to true allows compatibility
* with some external systems and specifications (e.g. LDAP {SSHA}).
*
*
* @since 1.7
*
* @return whether salt will be appended after the message before applying
* the digest operation on the whole, instead of inserted before it
* (which is the default). If null is returned, the default
* behaviour will be applied.
*/
public Boolean getInvertPositionOfSaltInMessageBeforeDigesting();
/**
*
* Returns Boolean.TRUE if the plain (not hashed) salt bytes are to
* be appended after the digest operation result bytes. The default behaviour is
* to insert them before the digest result, but setting this configuration
* item to true allows compatibility with some external systems
* and specifications (e.g. LDAP {SSHA}).
*
*
* @since 1.7
*
* @return whether plain salt will be appended after the digest operation
* result instead of inserted before it (which is the
* default). If null is returned, the default behaviour will be
* applied.
*/
public Boolean getInvertPositionOfPlainSaltInEncryptionResults();
/**
*
* Returns Boolean.TRUE if digest matching operations will allow matching
* digests with a salt size different to the one configured in the "saltSizeBytes"
* property. This is possible because digest algorithms will produce a fixed-size
* result, so the remaining bytes from the hashed input will be considered salt.
*
*
* This will allow the digester to match digests produced in environments which do not
* establish a fixed salt size as standard (for example, SSHA password encryption
* in LDAP systems).
*
*
* The value of this property will not affect the creation of digests,
* which will always have a salt of the size established by the "saltSizeBytes"
* property. It will only affect digest matching.
*
*
* Setting this property to true is not compatible with {@link SaltGenerator}
* implementations which return false for their
* {@link SaltGenerator#includePlainSaltInEncryptionResults()} property.
*
*
* Also, be aware that some algorithms or algorithm providers might not support
* knowing the size of the digests beforehand, which is also incompatible with
* a lenient behaviour.
*
*
* Default is FALSE.
*
*
* @since 1.7
*
* @return whether the digester will allow matching of digests with different
* salt sizes than established or not (default is false).
*/
public Boolean getUseLenientSaltSizeCheck();
/**
*
* Get the size of the pool of digesters to be created.
*
*
* This parameter will be ignored if used with a non-pooled digester.
*
*
* @since 1.7
*
* @return the size of the pool to be used if this configuration is used with a
* pooled digester
*/
public Integer getPoolSize();
}