org.xwiki.crypto.passwd
Interface PasswordCryptoService

@Role
public interface PasswordCryptoService

Service allowing users to encrypt and decrypt text using a password.

Since:

2.5M1

Version:

$Id: 8aabd010edd5ce3ae92c9d9ffd24360d2a7b8232 $

Method Summary

byte[]	decryptBytes(byte[] rawCiphertext, String password) Decrypt raw ciphertext created with encryptBytes(byte[], String).
String	decryptText(String base64Ciphertext, String password) Decrypt a piece of text encrypted with encryptText.
byte[]	encryptBytes(byte[] message, String password) Encipher the given byte array with the password.
String	encryptText(String plaintext, String password) Encipher the given text with the password.
boolean	isPasswordCorrect(String password, String protectedPassword) Check the validity of a password.
String	protectPassword(String password) Hash a password with a hash function specifically designed to make password guessing attacks difficult.

Method Detail

encryptText

String encryptText(String plaintext,
                   String password)
                   throws GeneralSecurityException

Encipher the given text with the password. The same password will be able to decipher it.

Parameters:

plaintext - the text to encrypt.

password - which will be needed to decrypt the text.

Returns:

Base64 encoded ciphertext which can be decrypted back to plaintext only with the decryptText function.

Throws:

GeneralSecurityException - if something goes wrong.

decryptText

String decryptText(String base64Ciphertext,
                   String password)
                   throws GeneralSecurityException

Decrypt a piece of text encrypted with encryptText.

Parameters:

base64Ciphertext - Base64 encoded ciphertext to decrypt.

password - which was used to encrypt the text.

Returns:

the decrypted text or null if the provided password was wrong.

Throws:

GeneralSecurityException - if something goes wrong.

encryptBytes

byte[] encryptBytes(byte[] message,
                    String password)
                    throws GeneralSecurityException

Encipher the given byte array with the password. The same password will be able to decipher it.

Parameters:

message - the message to encrypt.

password - which will be needed to decrypt the text.

Returns:

raw ciphertext which can be decrypted back to data using decryptBytes(byte[], String)

Throws:

GeneralSecurityException - if something goes wrong.

decryptBytes

byte[] decryptBytes(byte[] rawCiphertext,
                    String password)
                    throws GeneralSecurityException

Decrypt raw ciphertext created with encryptBytes(byte[], String). Most of the time the response is null if the password is incorrect, 1 out of 250 times the output is unintelligable garbage.

Parameters:

rawCiphertext - the ciphertext to decrypt.

password - which was used to encrypt the text.

Returns:

the decrypted message or null if the provided password was wrong.

Throws:

GeneralSecurityException - if something goes wrong.

protectPassword

String protectPassword(String password)
                       throws GeneralSecurityException

Hash a password with a hash function specifically designed to make password guessing attacks difficult. This hash does salting and multiple iterations which incure not only CPU but memory expense.

Parameters:

password - the plain text user supplied password.

Returns:

a String of base-64 formatted bytes which can be used to verify the password later using isPasswordCorrect. It is generally considered impossible to derive a password from this data however for particularly easy to guess passwords, an attacker may guess the password using isPasswordCorrect although the underlying function is designed to make that resource intensive.

Throws:

GeneralSecurityException - on errors

isPasswordCorrect

boolean isPasswordCorrect(String password,
                          String protectedPassword)
                          throws GeneralSecurityException

Check the validity of a password.

Parameters:

password - the plain text user supplied password.

protectedPassword - the result from calling protectPassword.

Returns:

true if after running the user supplied password through the same underlying function, the output matches the protectedPassword.

Throws:

GeneralSecurityException - on errors