1 /*
   2  * Copyright (c) 2002, 2003, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 package com.sun.jmx.snmp;
  26 
  27 /**
  28  * This interface allows you to compute key localization and delta generation. It is useful when adding user in USM MIB. An instance of <CODE> SnmpUsmKeyHandler </CODE> is associated to each <CODE> SnmpEngine </CODE> object.
  29  * When computing key, an authentication algorithm is needed. The supported ones are : usmHMACMD5AuthProtocol and usmHMACSHAAuthProtocol.
  30  * <p><b>This API is a Sun Microsystems internal API  and is subject
  31  * to change without notice.</b></p>
  32  * @since 1.5
  33  */
  34 public interface SnmpUsmKeyHandler {
  35 
  36     /**
  37      * DES privacy algorithm key size. To be used when localizing privacy key
  38      */
  39     public static int DES_KEY_SIZE = 16;
  40 
  41     /**
  42      * DES privacy algorithm delta size. To be used when calculing privacy key delta.
  43      */
  44     public static int DES_DELTA_SIZE = 16;
  45 
  46     /**
  47      * Translate a password to a key. It MUST be compliant to RFC 2574 description.
  48      * @param algoName The authentication algorithm to use.
  49      * @param password Password to convert.
  50      * @return The key.
  51      * @exception IllegalArgumentException If the algorithm is unknown.
  52      */
  53     public byte[] password_to_key(String algoName, String password) throws IllegalArgumentException;
  54     /**
  55      * Localize the passed key using the passed <CODE>SnmpEngineId</CODE>. It MUST be compliant to RFC 2574 description.
  56      * @param algoName The authentication algorithm to use.
  57      * @param key The key to localize;
  58      * @param engineId The Id used to localize the key.
  59      * @return The localized key.
  60      * @exception IllegalArgumentException If the algorithm is unknown.
  61      */
  62     public byte[] localizeAuthKey(String algoName, byte[] key, SnmpEngineId engineId) throws IllegalArgumentException;
  63 
  64     /**
  65      * Localize the passed privacy key using the passed <CODE>SnmpEngineId</CODE>. It MUST be compliant to RFC 2574 description.
  66      * @param algoName The authentication algorithm to use.
  67      * @param key The key to localize;
  68      * @param engineId The Id used to localize the key.
  69      * @param keysize The privacy algorithm key size.
  70      * @return The localized key.
  71      * @exception IllegalArgumentException If the algorithm is unknown.
  72      */
  73     public byte[] localizePrivKey(String algoName, byte[] key, SnmpEngineId engineId,int keysize) throws IllegalArgumentException;
  74 
  75     /**
  76      * Calculate the delta parameter needed when processing key change. This computation is done by the key change initiator. It MUST be compliant to RFC 2574 description.
  77      * @param algoName The authentication algorithm to use.
  78      * @param oldKey The old key.
  79      * @param newKey The new key.
  80      * @param random The random value.
  81      * @return The delta.
  82      * @exception IllegalArgumentException If the algorithm is unknown.
  83      */
  84     public byte[] calculateAuthDelta(String algoName, byte[] oldKey, byte[] newKey, byte[] random) throws IllegalArgumentException;
  85 
  86     /**
  87      * Calculate the delta parameter needed when processing key change for a privacy algorithm. This computation is done by the key change initiator. It MUST be compliant to RFC 2574 description.
  88      * @param algoName The authentication algorithm to use.
  89      * @param oldKey The old key.
  90      * @param newKey The new key.
  91      * @param random The random value.
  92      * @param deltaSize The algo delta size.
  93      * @return The delta.
  94      * @exception IllegalArgumentException If the algorithm is unknown.
  95      */
  96     public byte[] calculatePrivDelta(String algoName, byte[] oldKey, byte[] newKey, byte[] random, int deltaSize) throws IllegalArgumentException;
  97 
  98 }