001/*
002 * jPOS Project [http://jpos.org]
003 * Copyright (C) 2000-2026 jPOS Software SRL
004 *
005 * This program is free software: you can redistribute it and/or modify
006 * it under the terms of the GNU Affero General Public License as
007 * published by the Free Software Foundation, either version 3 of the
008 * License, or (at your option) any later version.
009 *
010 * This program is distributed in the hope that it will be useful,
011 * but WITHOUT ANY WARRANTY; without even the implied warranty of
012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
013 * GNU Affero General Public License for more details.
014 *
015 * You should have received a copy of the GNU Affero General Public License
016 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
017 */
018
019package  org.jpos.security;
020
021import org.jpos.util.Loggeable;
022
023import java.io.Serializable;
024
025
026/**
027 * Represents a key that cannot be used except by your security module and for
028 * performing the operations allowed by the security module for this type 
029 * of keys.
030 *
031 * So, a SecureKey can be safely stored in a clear file or database.
032 *
033 * <p>
034 * A SecureKey is typically a key encrypted under one of the secret keys that are
035 * protected by the security module itself (Local Master Keys --LMK for short).<br>
036 * </p>
037 * <p>
038 * SecureKey just holds:<br>
039 * 1- Secure Key: a byte[] holding the key in the secure proprietary format
040 *    of your security module. This is typically the clear key encrypted under LMK.<br>
041 * 2- Key Type: identifies what this key can be used for (e.g. TYPE_ZPK
042 *    (Zone PIN Key), TYPE_ZMK (Zone Master Key)...<BR>
043 * 3- Key Length (in bits): also called key size. e.g. LENGTH_DES, LENGTH_DES3_2KEY,...etc.
044 *    This is not necessarily deducible from the length of the byte[] holding
045 *    the secure key bytes, since encryption under LMK is proprietary to the
046 *    security module.
047 * </p>
048 * <p>
049 * NOTE: The security of SecureKey is totally dependent on the security of
050 * the used security module.
051 * </p>
052 * @author Hani S. Kirollos
053 * @version $Revision$ $Date$
054 * @see SMAdapter SMAdapter
055 *
056 */
057public abstract class SecureKey
058        implements Serializable, Loggeable {
059    /** Default constructor; no instance state to initialise. */
060    protected SecureKey() {}
061    /**
062     * Secure Key Bytes
063     */
064    protected byte[] keyBytes = null;
065
066    /**
067     * The keyCheckValue allows identifying which clear key does this
068     * secure key represent.
069     */
070    protected byte[] keyCheckValue;
071
072    /**
073     * This is the bit length of the key
074     * This can be: LENGTH_DES, LENGTH_DES3_2KEY, ...
075     */
076    protected short keyLength;
077    /**
078     * Key Type is useful for stating what this key can be used for.
079     * The value of Key Type specifies whether this encryped key is a
080     * TYPE_TMK (Terminal Master Key), TYPE_ZPK (Zone PIN Key)....<BR>
081     */
082    protected String keyType;
083
084    /**
085     * Key scheme indicates protection metchod appiled to this key by
086     * a security module.
087     */
088    protected KeyScheme scheme;
089
090    /**
091     * Optional key name
092     */
093    protected String keyName;
094
095    /**
096     * Sets the secure key bytes
097     * @param keyBytes byte[] representing the secured key bytes
098     */
099    public void setKeyBytes (byte[] keyBytes) {
100        this.keyBytes = keyBytes;
101    }
102
103    /**
104     * Returns the secure (LMK-protected) key bytes.
105     *
106     * @return The byte[] holding the secure key Bytes
107     */
108    public byte[] getKeyBytes () {
109        return  keyBytes;
110    }
111
112    /**
113     * The Key Check Value is typically a 24-bits (3 bytes) formed by encrypting a
114     * block of zeros under the secure key when the secure key is clear
115     * (not in this class, but inside the security module).
116     * This check value allows identifying if two secure keys map to the
117     * same clear key.
118     * @param keyCheckValue 3-byte (or longer) key check value
119     */
120    public void setKeyCheckValue (byte[] keyCheckValue) {
121        this.keyCheckValue = keyCheckValue;
122    }
123
124    /**
125     * The Key Check Value is typically a 24-bits (3 bytes) formed by encrypting a
126     * block of zeros under the secure key when the secure key is clear
127     * (not in this class, but inside the security module).
128     * @return the keyCheckValue that was set before by setKeyCheckValue()
129     */
130    public byte[] getKeyCheckValue () {
131        return  keyCheckValue;
132    }
133
134    /**
135     * Sets the length of the key (in bits) (when it was still clear).
136     * This might be different than the bit length of the secureKeyBytes.
137     * @param keyLength clear key length in bits
138     */
139    public void setKeyLength (short keyLength) {
140        this.keyLength = keyLength;
141    }
142
143    /**
144     * Returns the clear-key length in bits.
145     *
146     * @return The Length of the secure key (when it was still clear)
147     */
148    public short getKeyLength () {
149        return  keyLength;
150    }
151
152    /**
153     * Key Type is useful for stating what this key can be used for.
154     * The value of Key Type specifies whether this secure key is a
155     * TYPE_TMK (Terminal Master Key), TYPE_ZPK (Zone PIN Key)....<BR>
156     * @param keyType key-type label (e.g. {@code TYPE_ZPK}, {@code TYPE_TMK})
157     */
158    public void setKeyType (String keyType) {
159        this.keyType = keyType;
160    }
161
162    /**
163     * Key Type is useful for stating what this key can be used for.
164     * The value of Key Type specifies whether this secure key is a
165     * TYPE_TMK (Terminal Master Key), TYPE_ZPK (Zone PIN Key)....<BR>
166     * @return keyType
167     */
168    public String getKeyType () {
169        return  this.keyType;
170    }
171
172    /**
173     * Key scheme indicates protection metchod appiled to this key by
174     * the security module.
175     *
176     * @param scheme key scheme used to protect this key.
177     */
178    public void setScheme(KeyScheme scheme) {
179        this.scheme = scheme;
180    }
181
182    /**
183     * Gets the key scheme used to protect this key.
184     *
185     * @return key scheme used to protect this key.
186     */
187    public abstract KeyScheme getScheme();
188
189    /**
190     * Returns the optional key name.
191     *
192     * @return the configured key name, or {@code null} if none was set
193     */
194    public String getKeyName() {
195        return this.keyName;
196    }
197    /**
198     * Sets the optional key name.
199     *
200     * @param keyName string
201     */
202    public void setKeyName (String keyName) {
203        this.keyName = keyName;
204    }
205}
206