org.bouncycastle.tls.crypto.TlsSecret Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of bctls-jdk14 Show documentation
The Bouncy Castle Java APIs for TLS and DTLS.
There is a newer version: 1.78.1
package org.bouncycastle.tls.crypto;

import java.io.IOException;

/**
 * Interface supporting the generation of key material and other SSL/TLS secret values from PRFs.
 */
public interface TlsSecret
{
    /**
     * Calculate an HMAC with this secret's data as the key.
     * 
     * @param cryptoHashAlgorithm
     *            the hash algorithm to instantiate HMAC with. See {@link CryptoHashAlgorithm} for values.
     * @param buf array containing the input data.
     * @param off offset into the input array the input starts at.
     * @param len the length of the input data.
     * @return
     */
    byte[] calculateHMAC(int cryptoHashAlgorithm, byte[] buf, int off, int len);

    /**
     * Return a new secret based on applying a PRF to this one.
     *
     * @param prfAlgorithm PRF algorithm to use.
     * @param label the label details.
     * @param seed the seed details.
     * @param length the size (in bytes) of the secret to generate.
     * @return the new secret.
     */
    TlsSecret deriveUsingPRF(int prfAlgorithm, String label, byte[] seed, int length);

    /**
     * Destroy the internal state of the secret. After this call, any attempt to use the
     * {@link TlsSecret} will result in an {@link IllegalStateException} being thrown.
     */
    void destroy();

    /**
     * Return an encrypted copy of the data this secret is based on.
     *
     * @param encryptor the encryptor to use for protecting the internal data.
     * @return an encrypted copy of this secret's internal data.
     */
    byte[] encrypt(TlsEncryptor encryptor) throws IOException;

    /**
     * Return the internal data from this secret. The {@link TlsSecret} does not keep a copy of the
     * data. After this call, any attempt to use the {@link TlsSecret} will result in an
     * {@link IllegalStateException} being thrown.
     *
     * @return the secret's internal data.
     */
    byte[] extract();

    /**
     * RFC 5869 HKDF-Expand function, with this secret's data as the pseudo-random key ('prk').
     * 
     * @param cryptoHashAlgorithm
     *            the hash algorithm to instantiate HMAC with. See {@link CryptoHashAlgorithm} for values.
     * @param info
     *            optional context and application specific information (can be zero-length).
     * @param length
     *            length of output keying material in octets.
     * @return output keying material (of 'length' octets).
     */
    TlsSecret hkdfExpand(int cryptoHashAlgorithm, byte[] info, int length);

    /**
     * RFC 5869 HKDF-Extract function, with this secret's data as the 'salt'. The {@link TlsSecret}
     * does not keep a copy of the data. After this call, any attempt to use the {@link TlsSecret}
     * will result in an {@link IllegalStateException} being thrown.
     * 
     * @param cryptoHashAlgorithm
     *            the hash algorithm to instantiate HMAC with. See {@link CryptoHashAlgorithm} for values.
     * @param ikm
     *            input keying material.
     * @return a pseudo-random key (of HashLen octets).
     */
    TlsSecret hkdfExtract(int cryptoHashAlgorithm, TlsSecret ikm);

    boolean isAlive();
}