Package org.metricshub.ipmi.core.coding.security

Class CipherSuite

java.lang.Object
org.metricshub.ipmi.core.coding.security.CipherSuite
public class CipherSuite extends Object
Provides cipher suite (authentication, confidentiality and integrity algorithms used during the session).

  • Field Details

    • NOT_YET_IMPLEMENTED_MESSAGE

      @Deprecated public static final String NOT_YET_IMPLEMENTED_MESSAGE
      Deprecated.
      unused since 2.0.00; this constant will be removed in 3.0.
      A message no exception carries: the exceptions about the algorithms this library does not implement name the algorithm, such as Confidentiality algorithm XRC4-40 is not implemented.
      See Also:

  • Constructor Details

    • CipherSuite

      public CipherSuite(byte id, byte authenticationAlgorithm, byte confidentialityAlgorithm, byte integrityAlgorithm)
      Creates a cipher suite.
      Parameters:
      id - the ID of the cipher suite
      authenticationAlgorithm - the code of the authentication algorithm (SecurityConstants)
      confidentialityAlgorithm - the code of the confidentiality algorithm
      integrityAlgorithm - the code of the integrity algorithm

  • Method Details

    • getId

      public byte getId()
      Returns:
      the ID of the cipher suite (IPMI 2.0 table 22-20)

    • getAuthenticationAlgorithmCode

      public byte getAuthenticationAlgorithmCode()
      Returns:
      the code of the authentication algorithm (IPMI 2.0 table 13-17: SecurityConstants.AA_*), whether the library implements it or not

    • getIntegrityAlgorithmCode

      public byte getIntegrityAlgorithmCode()
      Returns:
      the code of the integrity algorithm (IPMI 2.0 table 13-18: SecurityConstants.IA_*), whether the library implements it or not

    • getConfidentialityAlgorithmCode

      public byte getConfidentialityAlgorithmCode()
      Returns:
      the code of the confidentiality algorithm (IPMI 2.0 table 13-19: SecurityConstants.CA_*), whether the library implements it or not

    • copy

      public CipherSuite copy()
      Returns a new instance of this suite, with uninitialized algorithms: opening a session keys the algorithms of its suite, so two sessions must never share an instance.
      Returns:
      a cipher suite with the same ID and algorithms

    • initializeAlgorithms

      public void initializeAlgorithms(byte[] sik) throws InvalidKeyException, NoSuchAlgorithmException, NoSuchPaddingException
      Initializes algorithms contained in this CipherSuite. A suite with MD5-128 integrity (11 to 14) is keyed with the password, which this method does not have: use initializeAlgorithms(byte[], byte[]) for it.
      Parameters:
      sik - - Session Integrity Key calculated during the opening of the session or user password if 'one-key' logins are enabled.
      Throws:
      IllegalArgumentException - - when an algorithm of the suite is not implemented, or when the suite uses MD5-128 integrity
      InvalidKeyException - - when initiation of the algorithm fails
      NoSuchAlgorithmException - - when initiation of the algorithm fails
      NoSuchPaddingException - - when initiation of the algorithm fails

    • initializeAlgorithms

      public void initializeAlgorithms(byte[] sik, byte[] password) throws InvalidKeyException, NoSuchAlgorithmException, NoSuchPaddingException
      Initializes algorithms contained in this CipherSuite: the HMAC integrity algorithms and the confidentiality algorithm are keyed with the Session Integrity Key, MD5-128 integrity (suites 11 to 14) with the user's password (IPMI 2.0 section 13.28.4).
      Parameters:
      sik - the Session Integrity Key calculated during the opening of the session
      password - the password of the user, as sent to the BMC; null for an empty password
      Throws:
      IllegalArgumentException - - when an algorithm of the suite is not implemented
      InvalidKeyException - - when initiation of the algorithm fails
      NoSuchAlgorithmException - - when initiation of the algorithm fails
      NoSuchPaddingException - - when initiation of the algorithm fails

    • getAuthenticationAlgorithm

      public AuthenticationAlgorithm getAuthenticationAlgorithm()
      Returns instance of AuthenticationAlgorithm class.
      Returns:
      the authentication algorithm of the suite
      Throws:
      IllegalArgumentException - when authentication algorithm code is incorrect.

    • getIntegrityAlgorithm

      public IntegrityAlgorithm getIntegrityAlgorithm()
      Returns instance of IntegrityAlgorithm class.
      Returns:
      the integrity algorithm of the suite
      Throws:
      IllegalArgumentException - when integrity algorithm code is incorrect.

    • getConfidentialityAlgorithm

      public ConfidentialityAlgorithm getConfidentialityAlgorithm()
      Returns instance of ConfidentialityAlgorithm class.
      Returns:
      the confidentiality algorithm of the suite
      Throws:
      IllegalArgumentException - when confidentiality algorithm code is incorrect.

    • getCipherSuites

      public static List<CipherSuite> getCipherSuites(byte[] bytes)
      Builds Cipher Suites collection from raw data received by GetChannelCipherSuites commands. Cannot be executed in GetChannelCipherSuitesResponseData since data comes in 16-byte packets and is fragmented.

      A standard record (IPMI 2.0 table 22-19) is C0h, the suite ID, then the algorithm tags. The algorithms of the standard suites 0 to 19 are those of IPMI 2.0 table 22-20, whatever the tags say, as in ipmitool and FreeIPMI: the records come unauthenticated, and a suite 17 whose tags were stripped must not become a suite without integrity. OEM records (C1h, the OEM suite ID, a 3-byte IANA, then the tags), whose suite IDs are vendor-specific, records with a reserved suite ID, and malformed or truncated records are skipped.

      Parameters:
      bytes - - concatenated Cipher Suite Records received by GetChannelCipherSuites commands.
      Returns:
      list of the standard Cipher Suites offered by BMC, in the BMC's order (including suites whose algorithms this library does not implement, see isSupported())

    • isSupported

      public boolean isSupported()
      Tells whether this library implements the algorithms of this suite. The suites listed by getCipherSuites(byte[]) include the ones it does not implement (xRC4 confidentiality: suites 4, 5, 9, 10, 13, 14, 18 and 19), which fail when the session is opened.
      Returns:
      true when the authentication, integrity and confidentiality algorithms are all implemented

    • getEmpty

      public static CipherSuite getEmpty()
      Returns:
      CipherSuite with algorithms set to AuthenticationRakpNone, ConfidentialityNone and IntegrityNone.

    • forId

      public static CipherSuite forId(int id)
      Creates one of the standard cipher suites (IPMI 2.0 table 22-20) from its ID, with the algorithms the specification assigns to it: the suite to use with a BMC whose offer is not read.
      Parameters:
      id - the ID of the suite, 0 to 19
      Returns:
      the suite, with uninitialized algorithms
      Throws:
      IllegalArgumentException - when the ID is not a standard suite

    • listIds

      public static String listIds(List<CipherSuite> suites)
      Lists the IDs of the given suites, for messages.
      Parameters:
      suites - the suites, or null
      Returns:
      the comma-separated IDs, or "none" when there is no suite

    • wipeKeys

      public void wipeKeys()
      Wipes the key of the integrity algorithm of the suite, if it was keyed (the password for MD5-128 integrity), once the session is over.

    • newMacInstance

      public static Mac newMacInstance(String algorithmName)
      Constructs a Mac object that implements the given MAC algorithm.
      Parameters:
      algorithmName - the name of the algorithm to use
      Returns:
      The Mac object that implements the specified MAC algorithm.