snmp_usm.h

00001 /**
00002  * @file snmp_usm.h
00003  * @brief User-based Security Model (USM) for SNMPv3
00004  *
00005  * @section License
00006  *
00007  * Copyright (C) 2010-2017 Oryx Embedded SARL. All rights reserved.
00008  *
00009  * This file is part of CycloneTCP Open.
00010  *
00011  * This program is free software; you can redistribute it and/or
00012  * modify it under the terms of the GNU General Public License
00013  * as published by the Free Software Foundation; either version 2
00014  * of the License, or (at your option) any later version.
00015  *
00016  * This program is distributed in the hope that it will be useful,
00017  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00018  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00019  * GNU General Public License for more details.
00020  *
00021  * You should have received a copy of the GNU General Public License
00022  * along with this program; if not, write to the Free Software Foundation,
00023  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
00024  *
00025  * @author Oryx Embedded SARL (www.oryx-embedded.com)
00026  * @version 1.7.6
00027  **/
00028 
00029 #ifndef _SNMP_USM_H
00030 #define _SNMP_USM_H
00031 
00032 //Dependencies
00033 #include "core/net.h"
00034 #include "snmp/snmp_common.h"
00035 #include "crypto.h"
00036 
00037 //Time window for replay protection
00038 #ifndef SNMP_TIME_WINDOW
00039    #define SNMP_TIME_WINDOW 150
00040 #elif (SNMP_TIME_WINDOW < 1)
00041    #error SNMP_TIME_WINDOW parameter is not valid
00042 #endif
00043 
00044 //MD5 authentication support
00045 #ifndef SNMP_MD5_SUPPORT
00046    #define SNMP_MD5_SUPPORT ENABLED
00047 #elif (SNMP_MD5_SUPPORT != ENABLED && SNMP_MD5_SUPPORT != DISABLED)
00048    #error SNMP_MD5_SUPPORT parameter is not valid
00049 #endif
00050 
00051 //SHA-1 authentication support
00052 #ifndef SNMP_SHA1_SUPPORT
00053    #define SNMP_SHA1_SUPPORT ENABLED
00054 #elif (SNMP_SHA1_SUPPORT != ENABLED && SNMP_SHA1_SUPPORT != DISABLED)
00055    #error SNMP_SHA1_SUPPORT parameter is not valid
00056 #endif
00057 
00058 //SHA-224 authentication support
00059 #ifndef SNMP_SHA224_SUPPORT
00060    #define SNMP_SHA224_SUPPORT DISABLED
00061 #elif (SNMP_SHA224_SUPPORT != ENABLED && SNMP_SHA224_SUPPORT != DISABLED)
00062    #error SNMP_SHA224_SUPPORT parameter is not valid
00063 #endif
00064 
00065 //SHA-256 authentication support
00066 #ifndef SNMP_SHA256_SUPPORT
00067    #define SNMP_SHA256_SUPPORT DISABLED
00068 #elif (SNMP_SHA256_SUPPORT != ENABLED && SNMP_SHA256_SUPPORT != DISABLED)
00069    #error SNMP_SHA256_SUPPORT parameter is not valid
00070 #endif
00071 
00072 //SHA-384 authentication support
00073 #ifndef SNMP_SHA384_SUPPORT
00074    #define SNMP_SHA384_SUPPORT DISABLED
00075 #elif (SNMP_SHA384_SUPPORT != ENABLED && SNMP_SHA384_SUPPORT != DISABLED)
00076    #error SNMP_SHA384_SUPPORT parameter is not valid
00077 #endif
00078 
00079 //SHA-512 authentication support
00080 #ifndef SNMP_SHA512_SUPPORT
00081    #define SNMP_SHA512_SUPPORT DISABLED
00082 #elif (SNMP_SHA512_SUPPORT != ENABLED && SNMP_SHA512_SUPPORT != DISABLED)
00083    #error SNMP_SHA512_SUPPORT parameter is not valid
00084 #endif
00085 
00086 //DES encryption support
00087 #ifndef SNMP_DES_SUPPORT
00088    #define SNMP_DES_SUPPORT ENABLED
00089 #elif (SNMP_DES_SUPPORT != ENABLED && SNMP_DES_SUPPORT != DISABLED)
00090    #error SNMP_DES_SUPPORT parameter is not valid
00091 #endif
00092 
00093 //AES encryption support
00094 #ifndef SNMP_AES_SUPPORT
00095    #define SNMP_AES_SUPPORT ENABLED
00096 #elif (SNMP_AES_SUPPORT != ENABLED && SNMP_AES_SUPPORT != DISABLED)
00097    #error SNMP_AES_SUPPORT parameter is not valid
00098 #endif
00099 
00100 //Support for MD5 authentication?
00101 #if (SNMP_MD5_SUPPORT == ENABLED)
00102    #include "md5.h"
00103 #endif
00104 
00105 //Support for SHA-1 authentication?
00106 #if (SNMP_SHA1_SUPPORT == ENABLED)
00107    #include "sha1.h"
00108 #endif
00109 
00110 //Support for SHA-224 authentication?
00111 #if (SNMP_SHA224_SUPPORT == ENABLED)
00112    #include "sha224.h"
00113 #endif
00114 
00115 //Support for SHA-256 authentication?
00116 #if (SNMP_SHA256_SUPPORT == ENABLED)
00117    #include "sha256.h"
00118 #endif
00119 
00120 //Support for SHA-384 authentication?
00121 #if (SNMP_SHA384_SUPPORT == ENABLED)
00122    #include "sha384.h"
00123 #endif
00124 
00125 //Support for SHA-512 authentication?
00126 #if (SNMP_SHA512_SUPPORT == ENABLED)
00127    #include "sha512.h"
00128 #endif
00129 
00130 //Support for DES encryption?
00131 #if (SNMP_DES_SUPPORT == ENABLED)
00132    #include "des.h"
00133    #include "cipher_mode_cbc.h"
00134 #endif
00135 
00136 //Support for AES encryption ?
00137 #if (SNMP_AES_SUPPORT == ENABLED)
00138    #include "aes.h"
00139    #include "cipher_mode_cfb.h"
00140 #endif
00141 
00142 //Maximum size for authentication and privacy keys
00143 #if (SNMP_SHA512_SUPPORT == ENABLED)
00144    #define SNMP_MAX_KEY_SIZE 64
00145 #elif (SNMP_SHA384_SUPPORT == ENABLED)
00146    #define SNMP_MAX_KEY_SIZE 48
00147 #elif (SNMP_SHA256_SUPPORT == ENABLED)
00148    #define SNMP_MAX_KEY_SIZE 32
00149 #elif (SNMP_SHA224_SUPPORT == ENABLED)
00150    #define SNMP_MAX_KEY_SIZE 28
00151 #elif (SNMP_SHA1_SUPPORT == ENABLED)
00152    #define SNMP_MAX_KEY_SIZE 20
00153 #else
00154    #define SNMP_MAX_KEY_SIZE 16
00155 #endif
00156 
00157 //Maximum size for HMAC digests
00158 #if (SNMP_SHA512_SUPPORT == ENABLED)
00159    #define SNMP_MAX_HMAC_DIGEST_SIZE 48
00160 #elif (SNMP_SHA384_SUPPORT == ENABLED)
00161    #define SNMP_MAX_HMAC_DIGEST_SIZE 32
00162 #elif (SNMP_SHA256_SUPPORT == ENABLED)
00163    #define SNMP_MAX_HMAC_DIGEST_SIZE 24
00164 #elif (SNMP_SHA224_SUPPORT == ENABLED)
00165    #define SNMP_MAX_HMAC_DIGEST_SIZE 16
00166 #elif (SNMP_SHA1_SUPPORT == ENABLED)
00167    #define SNMP_MAX_HMAC_DIGEST_SIZE 12
00168 #else
00169    #define SNMP_MAX_HMAC_DIGEST_SIZE 12
00170 #endif
00171 
00172 //SNMP message encryption overhead
00173 #if (SNMP_DES_SUPPORT == ENABLED)
00174    #define SNMP_MSG_ENCRYPTION_OVERHEAD 8
00175 #else
00176    #define SNMP_MSG_ENCRYPTION_OVERHEAD 0
00177 #endif
00178 
00179 
00180 /**
00181  * SNMP message flags
00182  **/
00183 
00184 typedef enum
00185 {
00186    SNMP_MSG_FLAG_AUTH   = 1,
00187    SNMP_MSG_FLAG_PRIV   = 2,
00188    SNMP_MSG_FLAG_REPORT = 4
00189 } SnmpMessageFlags;
00190 
00191 
00192 /**
00193  * SNMP security models
00194  **/
00195 
00196 typedef enum
00197 {
00198    SNMP_SECURITY_MODEL_USM = 3, ///<User-based security model
00199    SNMP_SECURITY_MODEL_TSM = 4  ///<Transport security model
00200 } SnmpSecurityModel;
00201 
00202 
00203 /**
00204  * @brief Access modes
00205  **/
00206 
00207 typedef enum
00208 {
00209    SNMP_ACCESS_NONE       = 0,
00210    SNMP_ACCESS_READ_ONLY  = 1,
00211    SNMP_ACCESS_WRITE_ONLY = 2,
00212    SNMP_ACCESS_READ_WRITE = 3
00213 } SnmpAccess;
00214 
00215 
00216 /**
00217  * SNMP authentication protocols
00218  **/
00219 
00220 typedef enum
00221 {
00222    SNMP_AUTH_PROTOCOL_NONE   = 0, ///<No authentication
00223    SNMP_AUTH_PROTOCOL_MD5    = 1, ///<HMAC-MD5-96
00224    SNMP_AUTH_PROTOCOL_SHA1   = 2, ///<HMAC-SHA-1-96
00225    SNMP_AUTH_PROTOCOL_SHA224 = 3, ///<HMAC-SHA-224-128
00226    SNMP_AUTH_PROTOCOL_SHA256 = 4, ///<HMAC-SHA-256-192
00227    SNMP_AUTH_PROTOCOL_SHA384 = 5, ///<HMAC-SHA-384-256
00228    SNMP_AUTH_PROTOCOL_SHA512 = 6  ///<HMAC-SHA-512-384
00229 } SnmpAuthProtocol;
00230 
00231 
00232 /**
00233  * SNMP privacy protocols
00234  **/
00235 
00236 typedef enum
00237 {
00238    SNMP_PRIV_PROTOCOL_NONE = 0, ///<No privacy
00239    SNMP_PRIV_PROTOCOL_DES  = 1, ///<DES-CBC
00240    SNMP_PRIV_PROTOCOL_AES  = 2  ///<AES-128-CFB
00241 } SnmpPrivProtocol;
00242 
00243 
00244 /**
00245  * @brief SNMP key format
00246  **/
00247 
00248 typedef enum
00249 {
00250    SNMP_KEY_FORMAT_NONE = 0, ///<Unspecified key format
00251    SNMP_KEY_FORMAT_TEXT = 1, ///<ASCII password
00252    SNMP_KEY_FORMAT_RAW  = 2  ///<Raw key
00253 } SnmpKeyFormat;
00254 
00255 
00256 /**
00257  * @brief SNMP secret key
00258  **/
00259 
00260 typedef struct
00261 {
00262    uint8_t b[SNMP_MAX_KEY_SIZE];
00263 } SnmpKey;
00264 
00265 
00266 /**
00267  * @brief SNMP user information
00268  **/
00269 
00270 typedef struct
00271 {
00272    char_t name[SNMP_MAX_USER_NAME_LEN + 1]; ///<User name
00273    SnmpAccess mode;                         ///<Access mode
00274 #if (SNMP_V3_SUPPORT == ENABLED)
00275    SnmpAuthProtocol authProtocol;           ///<Authentication protocol
00276    SnmpKey authKey;                         ///<Authentication key
00277    SnmpPrivProtocol privProtocol;           ///<Privacy protocol
00278    SnmpKey privKey;                         ///<Privacy key
00279 #endif
00280 } SnmpUserInfo;
00281 
00282 
00283 //USM related constants
00284 extern const uint8_t usmStatsUnsupportedSecLevelsObject[10];
00285 extern const uint8_t usmStatsNotInTimeWindowsObject[10];
00286 extern const uint8_t usmStatsUnknownUserNamesObject[10];
00287 extern const uint8_t usmStatsUnknownEngineIdsObject[10];
00288 extern const uint8_t usmStatsWrongDigestsObject[10];
00289 extern const uint8_t usmStatsDecryptionErrorsObject[10];
00290 
00291 //USM related functions
00292 error_t snmpGenerateKey(SnmpAuthProtocol authProtocol, const char_t *password,
00293    const uint8_t *engineId, size_t engineIdLen, SnmpKey *key);
00294 
00295 error_t snmpCheckSecurityParameters(const SnmpUserInfo *user,
00296    SnmpMessage *message, const uint8_t *engineId, size_t engineIdLen);
00297 
00298 error_t snmpAuthOutgoingMessage(const SnmpUserInfo *user, SnmpMessage *message);
00299 error_t snmpAuthIncomingMessage(const SnmpUserInfo *user, SnmpMessage *message);
00300 
00301 error_t snmpEncryptData(const SnmpUserInfo *user, SnmpMessage *message, uint64_t *salt);
00302 error_t snmpDecryptData(const SnmpUserInfo *user, SnmpMessage *message);
00303 
00304 #endif
00305