com.unboundid.util.ssl.cert.PKCS8EncryptionProperties Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of unboundid-ldapsdk Show documentation
The UnboundID LDAP SDK for Java is a fast, comprehensive, and easy-to-use Java API for communicating with LDAP directory servers and performing related tasks like reading and writing LDIF, encoding and decoding data using base64 and ASN.1 BER, and performing secure communication. This package contains the Standard Edition of the LDAP SDK, which is a complete, general-purpose library for communicating with LDAPv3 directory servers.
There is a newer version: 7.0.2
Show newest version
/*
 * Copyright 2022-2023 Ping Identity Corporation
 * All Rights Reserved.
 */
/*
 * Copyright 2022-2023 Ping Identity Corporation
 *
 * 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.
 */
/*
 * Copyright (C) 2022-2023 Ping Identity Corporation
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License (GPLv2 only)
 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
 * as published by the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, see .
 */
package com.unboundid.util.ssl.cert;



import java.io.Serializable;

import com.unboundid.util.Mutable;
import com.unboundid.util.NotNull;
import com.unboundid.util.ThreadSafety;
import com.unboundid.util.ThreadSafetyLevel;
import com.unboundid.util.Validator;

import static com.unboundid.util.ssl.cert.CertMessages.*;



/**
 * This class defines a set of properties that may be used when encrypting a
 * PKCS #8 private key.
 */
@Mutable()
@ThreadSafety(level=ThreadSafetyLevel.NOT_THREADSAFE)
public final class PKCS8EncryptionProperties
       implements Serializable
{
  /**
   * The default value that will be used for the key factory iteration count.
   */
  private static final int DEFAULT_KEY_FACTORY_ITERATION_COUNT = 2048;



  /**
   * The default value that will be used for the key factory salt length.
   */
  private static final int DEFAULT_KEY_FACTORY_SALT_LENGTH_BYTES = 8;



  /**
   * The default value that will be used for the encryption cipher
   * transformation.
   */
  @NotNull()
  private static final PKCS5AlgorithmIdentifier DEFAULT_CIPHER_TRANSFORMATION =
       PKCS5AlgorithmIdentifier.AES_128_CBC_PAD;



  /**
   * The default value that will be used for the pseudorandom function for the
   * key factory algorithm.
   */
  @NotNull()
  private static final PKCS5AlgorithmIdentifier DEFAULT_KEY_FACTORY_PRF =
       PKCS5AlgorithmIdentifier.HMAC_SHA_256;



  /**
   * The serial version UID for this serializable class.
   */
  private static final long serialVersionUID = 9162621645150582722L;



  // The iteration count to use when generating the encryption key from the
  // encryption password.
  private int keyFactoryIterationCount;

  // The length of the key factory salt to create, in bytes.
  private int keyFactorySaltLengthBytes;

  // The cipher transformation to use to encrypt the private key.
  @NotNull private PKCS5AlgorithmIdentifier cipherTransformationAlgorithm;

  // The algorithm to use to generate the encryption key from the encryption
  // password.
  @NotNull private PKCS5AlgorithmIdentifier keyFactoryPRFAlgorithm;



  /**
   * Creates a set of PKCS #8 encryption properties with the default settings.
   */
  public PKCS8EncryptionProperties()
  {
    keyFactoryIterationCount = DEFAULT_KEY_FACTORY_ITERATION_COUNT;
    keyFactorySaltLengthBytes = DEFAULT_KEY_FACTORY_SALT_LENGTH_BYTES;
    cipherTransformationAlgorithm = DEFAULT_CIPHER_TRANSFORMATION;
    keyFactoryPRFAlgorithm = DEFAULT_KEY_FACTORY_PRF;
  }



  /**
   * Retrieves the algorithm identifier for the pseudorandom function to use for
   * the key factory when generating the encryption key from the provided
   * password.
   *
   * @return  The algorithm identifier for the pseudorandom function to use for
   *          the key factory when generating the encryption key from the
   *          provided password.
   */
  @NotNull()
  public PKCS5AlgorithmIdentifier getKeyFactoryPRFAlgorithm()
  {
    return keyFactoryPRFAlgorithm;
  }



  /**
   * Specifies the algorithm identifier for the pseudorandom function to use
   * when generating the encryption key from the provided password.
   *
   * @param  keyFactoryPRFAlgorithm  The algorithm identifier for the
   *                                 pseudorandom function to use when
   *                                 generating the encryption key from the
   *                                 provided password.  It must not be
   *                                 {@code null}, and it must represent a valid
   *                                 pseudorandom function.
   *
   * @throws  CertException  If the provided algorithm identifier does not
   *                         represent a valid pseudorandom function.
   */
  public void setKeyFactoryPRFAlgorithm(
       @NotNull final PKCS5AlgorithmIdentifier keyFactoryPRFAlgorithm)
       throws CertException
  {
    if (! PKCS5AlgorithmIdentifier.getPseudorandomFunctions().contains(
         keyFactoryPRFAlgorithm))
    {
      throw new CertException(
           ERR_PKCS8_ENC_PROPS_INVALID_KEY_FACTORY_PRF_ALG.get(
                keyFactoryPRFAlgorithm.getName(),
                keyFactoryPRFAlgorithm.getDescription()));
    }

    this.keyFactoryPRFAlgorithm = keyFactoryPRFAlgorithm;
  }



  /**
   * Retrieves the iteration count to use when generating the encryption key
   * from the provided password.
   *
   * @return  The iteration count to use when generating the encryption key from
   *          the provided password.
   */
  public int getKeyFactoryIterationCount()
  {
    return keyFactoryIterationCount;
  }



  /**
   * Specifies the iteration count to use when generating the encryption key
   * from the provided password.
   *
   * @param  keyFactoryIterationCount  The iteration count to use when
   *                                   generating the encryption key from the
   *                                   provided password.  It must be greater
   *                                   than zero.
   */
  public void setKeyFactoryIterationCount(final int keyFactoryIterationCount)
  {
    Validator.ensureTrue((keyFactoryIterationCount > 0),
         "The key factory iteration count must be greater than zero.");
    this.keyFactoryIterationCount = keyFactoryIterationCount;
  }



  /**
   * Retrieves the length in bytes to use for the key factory salt when
   * generating the encryption key from the provided password.
   *
   * @return  The length in bytes to use for the key factory salt when
   *          generating the encryption key from the provided password.
   */
  public int getKeyFactorySaltLengthBytes()
  {
    return keyFactorySaltLengthBytes;
  }



  /**
   * Specifies the length in bytes to use for the key factory salt when
   * generating the encryption key from the provided password.
   *
   * @param  keyFactorySaltLengthBytes  The length in bytes to use for the key
   *                                    factory salt when generating the
   *                                    encryption key from the provided
   *                                    password.  It must be greater than zero.
   */
  public void setKeyFactorySaltLengthBytes(final int keyFactorySaltLengthBytes)
  {
    Validator.ensureTrue((keyFactorySaltLengthBytes > 0),
         "The key factory salt length must be greater than zero bytes.");
    this.keyFactorySaltLengthBytes = keyFactorySaltLengthBytes;
  }



  /**
   * Retrieves the algorithm identifier for the cipher transformation to use
   * when encrypting a PKCS #8 private key.
   *
   * @return  The algorithm identifier for the cipher transformation to use when
   *          encrypting a PKCS #8 private key.
   */
  @NotNull()
  public PKCS5AlgorithmIdentifier getCipherTransformationAlgorithm()
  {
    return cipherTransformationAlgorithm;
  }



  /**
   * Specifies  the algorithm identifier for the cipher transformation to use
   * when encrypting a PKCS #8 private key.
   *
   * @param  cipherTransformationAlgorithm  The algorithm identifier for the
   *                                        cipher transformation to use when
   *                                        encrypting a PKCS #8 private key.
   *                                        It must not be {@code null}, and it
   *                                        must represent a valid cipher
   *                                        transformation.
   *
   * @throws  CertException  If the provided algorithm identifier does not
   *                         represent a valid cipher transformation.
   */
  public void setCipherTransformationAlgorithm(
       @NotNull final PKCS5AlgorithmIdentifier cipherTransformationAlgorithm)
       throws CertException
  {
    if (! PKCS5AlgorithmIdentifier.getCipherTransformations().contains(
         cipherTransformationAlgorithm))
    {
      throw new CertException(
           ERR_PKCS8_ENC_PROPS_INVALID_CIPHER_TRANSFORMATION_ALG.get(
                cipherTransformationAlgorithm.getName(),
                cipherTransformationAlgorithm.getDescription()));
    }

    this.cipherTransformationAlgorithm = cipherTransformationAlgorithm;
  }



  /**
   * Retrieves a string representation of the PKCS #8 encryption properties.
   *
   * @return  A string representation of the PKCS #8 encryption properties.
   */
  @NotNull()
  public String toString()
  {
    final StringBuilder buffer = new StringBuilder();
    toString(buffer);
    return buffer.toString();
  }



  /**
   * Appends a string representation of the PKCS #8 encryption properties to the
   * provided buffer.
   *
   * @param  buffer  The buffer to which the information should be appended.  It
   *                 must not be {@code null}.
   */
  public void toString(@NotNull final StringBuilder buffer)
  {
    buffer.append("PKCS8EncryptionProperties(keyFactoryPRFAlgorithm='");
    buffer.append(keyFactoryPRFAlgorithm.getName());
    buffer.append("', keyFactoryIterationCount=");
    buffer.append(keyFactoryIterationCount);
    buffer.append(", keyFactorySaltLengthBytes=");
    buffer.append(keyFactorySaltLengthBytes);
    buffer.append(", cipherTransformation='");
    buffer.append(cipherTransformationAlgorithm.getName());
    buffer.append("')");
  }
}