md.h

00001 /**
00002  * \file md.h
00003  *
00004  * \brief Generic message digest wrapper
00005  *
00006  * \author Adriaan de Jong <dejong@fox-it.com>
00007  *
00008  *  Copyright (C) 2006-2014, Brainspark B.V.
00009  *
00010  *  This file is part of PolarSSL (http://www.polarssl.org)
00011  *  Lead Maintainer: Paul Bakker <polarssl_maintainer at polarssl.org>
00012  *
00013  *  All rights reserved.
00014  *
00015  *  This program is free software; you can redistribute it and/or modify
00016  *  it under the terms of the GNU General Public License as published by
00017  *  the Free Software Foundation; either version 2 of the License, or
00018  *  (at your option) any later version.
00019  *
00020  *  This program is distributed in the hope that it will be useful,
00021  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
00022  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00023  *  GNU General Public License for more details.
00024  *
00025  *  You should have received a copy of the GNU General Public License along
00026  *  with this program; if not, write to the Free Software Foundation, Inc.,
00027  *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
00028  */
00029 #ifndef POLARSSL_MD_H
00030 #define POLARSSL_MD_H
00031 
00032 #include <string.h>
00033 
00034 #if defined(_MSC_VER) && !defined(inline)
00035 #define inline _inline
00036 #else
00037 #if defined(__ARMCC_VERSION) && !defined(inline)
00038 #define inline __inline
00039 #endif /* __ARMCC_VERSION */
00040 #endif /*_MSC_VER */
00041 
00042 #define POLARSSL_ERR_MD_FEATURE_UNAVAILABLE                -0x5080  /**< The selected feature is not available. */
00043 #define POLARSSL_ERR_MD_BAD_INPUT_DATA                     -0x5100  /**< Bad input parameters to function. */
00044 #define POLARSSL_ERR_MD_ALLOC_FAILED                       -0x5180  /**< Failed to allocate memory. */
00045 #define POLARSSL_ERR_MD_FILE_IO_ERROR                      -0x5200  /**< Opening or reading of file failed. */
00046 
00047 #ifdef __cplusplus
00048 extern "C" {
00049 #endif
00050 
00051 typedef enum {
00052     POLARSSL_MD_NONE=0,
00053     POLARSSL_MD_MD2,
00054     POLARSSL_MD_MD4,
00055     POLARSSL_MD_MD5,
00056     POLARSSL_MD_SHA1,
00057     POLARSSL_MD_SHA224,
00058     POLARSSL_MD_SHA256,
00059     POLARSSL_MD_SHA384,
00060     POLARSSL_MD_SHA512,
00061     POLARSSL_MD_RIPEMD160,
00062 } md_type_t;
00063 
00064 #if defined(POLARSSL_SHA512_C)
00065 #define POLARSSL_MD_MAX_SIZE         64  /* longest known is SHA512 */
00066 #else
00067 #define POLARSSL_MD_MAX_SIZE         32  /* longest known is SHA256 or less */
00068 #endif
00069 
00070 /**
00071  * Message digest information. Allows message digest functions to be called
00072  * in a generic way.
00073  */
00074 typedef struct {
00075     /** Digest identifier */
00076     md_type_t type;
00077 
00078     /** Name of the message digest */
00079     const char * name;
00080 
00081     /** Output length of the digest function */
00082     int size;
00083 
00084     /** Digest initialisation function */
00085     void (*starts_func)( void *ctx );
00086 
00087     /** Digest update function */
00088     void (*update_func)( void *ctx, const unsigned char *input, size_t ilen );
00089 
00090     /** Digest finalisation function */
00091     void (*finish_func)( void *ctx, unsigned char *output );
00092 
00093     /** Generic digest function */
00094     void (*digest_func)( const unsigned char *input, size_t ilen,
00095                          unsigned char *output );
00096 
00097     /** Generic file digest function */
00098     int (*file_func)( const char *path, unsigned char *output );
00099 
00100     /** HMAC Initialisation function */
00101     void (*hmac_starts_func)( void *ctx, const unsigned char *key,
00102                               size_t keylen );
00103 
00104     /** HMAC update function */
00105     void (*hmac_update_func)( void *ctx, const unsigned char *input,
00106                               size_t ilen );
00107 
00108     /** HMAC finalisation function */
00109     void (*hmac_finish_func)( void *ctx, unsigned char *output);
00110 
00111     /** HMAC context reset function */
00112     void (*hmac_reset_func)( void *ctx );
00113 
00114     /** Generic HMAC function */
00115     void (*hmac_func)( const unsigned char *key, size_t keylen,
00116                        const unsigned char *input, size_t ilen,
00117                        unsigned char *output );
00118 
00119     /** Allocate a new context */
00120     void * (*ctx_alloc_func)( void );
00121 
00122     /** Free the given context */
00123     void (*ctx_free_func)( void *ctx );
00124 
00125     /** Internal use only */
00126     void (*process_func)( void *ctx, const unsigned char *input );
00127 } md_info_t;
00128 
00129 /**
00130  * Generic message digest context.
00131  */
00132 typedef struct {
00133     /** Information about the associated message digest */
00134     const md_info_t *md_info;
00135 
00136     /** Digest-specific context */
00137     void *md_ctx;
00138 } md_context_t;
00139 
00140 #define MD_CONTEXT_T_INIT { \
00141     NULL, /* md_info */ \
00142     NULL, /* md_ctx */ \
00143 }
00144 
00145 /**
00146  * \brief Returns the list of digests supported by the generic digest module.
00147  *
00148  * \return          a statically allocated array of digests, the last entry
00149  *                  is 0.
00150  */
00151 const int *md_list( void );
00152 
00153 /**
00154  * \brief           Returns the message digest information associated with the
00155  *                  given digest name.
00156  *
00157  * \param md_name   Name of the digest to search for.
00158  *
00159  * \return          The message digest information associated with md_name or
00160  *                  NULL if not found.
00161  */
00162 const md_info_t *md_info_from_string( const char *md_name );
00163 
00164 /**
00165  * \brief           Returns the message digest information associated with the
00166  *                  given digest type.
00167  *
00168  * \param md_type   type of digest to search for.
00169  *
00170  * \return          The message digest information associated with md_type or
00171  *                  NULL if not found.
00172  */
00173 const md_info_t *md_info_from_type( md_type_t md_type );
00174 
00175 /**
00176  * \brief          Initialises and fills the message digest context structure
00177  *                 with the appropriate values.
00178  *
00179  * \param ctx      context to initialise. May not be NULL. The
00180  *                 digest-specific context (ctx->md_ctx) must be NULL. It will
00181  *                 be allocated, and must be freed using md_free_ctx() later.
00182  * \param md_info  message digest to use.
00183  *
00184  * \returns        \c 0 on success, \c POLARSSL_ERR_MD_BAD_INPUT_DATA on
00185  *                 parameter failure, \c POLARSSL_ERR_MD_ALLOC_FAILED if
00186  *                 allocation of the digest-specific context failed.
00187  */
00188 int md_init_ctx( md_context_t *ctx, const md_info_t *md_info );
00189 
00190 /**
00191  * \brief          Free the message-specific context of ctx. Freeing ctx itself
00192  *                 remains the responsibility of the caller.
00193  *
00194  * \param ctx      Free the message-specific context
00195  *
00196  * \returns        0 on success, POLARSSL_ERR_MD_BAD_INPUT_DATA if parameter
00197  *                 verification fails.
00198  */
00199 int md_free_ctx( md_context_t *ctx );
00200 
00201 /**
00202  * \brief           Returns the size of the message digest output.
00203  *
00204  * \param md_info   message digest info
00205  *
00206  * \return          size of the message digest output.
00207  */
00208 static inline unsigned char md_get_size( const md_info_t *md_info )
00209 {
00210     if( md_info == NULL )
00211         return( 0 );
00212 
00213     return md_info->size;
00214 }
00215 
00216 /**
00217  * \brief           Returns the type of the message digest output.
00218  *
00219  * \param md_info   message digest info
00220  *
00221  * \return          type of the message digest output.
00222  */
00223 static inline md_type_t md_get_type( const md_info_t *md_info )
00224 {
00225     if( md_info == NULL )
00226         return( POLARSSL_MD_NONE );
00227 
00228     return md_info->type;
00229 }
00230 
00231 /**
00232  * \brief           Returns the name of the message digest output.
00233  *
00234  * \param md_info   message digest info
00235  *
00236  * \return          name of the message digest output.
00237  */
00238 static inline const char *md_get_name( const md_info_t *md_info )
00239 {
00240     if( md_info == NULL )
00241         return( NULL );
00242 
00243     return md_info->name;
00244 }
00245 
00246 /**
00247  * \brief          Set-up the given context for a new message digest
00248  *
00249  * \param ctx      generic message digest context.
00250  *
00251  * \returns        0 on success, POLARSSL_ERR_MD_BAD_INPUT_DATA if parameter
00252  *                 verification fails.
00253  */
00254 int md_starts( md_context_t *ctx );
00255 
00256 /**
00257  * \brief          Generic message digest process buffer
00258  *
00259  * \param ctx      Generic message digest context
00260  * \param input    buffer holding the  datal
00261  * \param ilen     length of the input data
00262  *
00263  * \returns        0 on success, POLARSSL_ERR_MD_BAD_INPUT_DATA if parameter
00264  *                 verification fails.
00265  */
00266 int md_update( md_context_t *ctx, const unsigned char *input, size_t ilen );
00267 
00268 /**
00269  * \brief          Generic message digest final digest
00270  *
00271  * \param ctx      Generic message digest context
00272  * \param output   Generic message digest checksum result
00273  *
00274  * \returns        0 on success, POLARSSL_ERR_MD_BAD_INPUT_DATA if parameter
00275  *                 verification fails.
00276  */
00277 int md_finish( md_context_t *ctx, unsigned char *output );
00278 
00279 /**
00280  * \brief          Output = message_digest( input buffer )
00281  *
00282  * \param md_info  message digest info
00283  * \param input    buffer holding the  data
00284  * \param ilen     length of the input data
00285  * \param output   Generic message digest checksum result
00286  *
00287  * \returns        0 on success, POLARSSL_ERR_MD_BAD_INPUT_DATA if parameter
00288  *                 verification fails.
00289  */
00290 int md( const md_info_t *md_info, const unsigned char *input, size_t ilen,
00291         unsigned char *output );
00292 
00293 /**
00294  * \brief          Output = message_digest( file contents )
00295  *
00296  * \param md_info  message digest info
00297  * \param path     input file name
00298  * \param output   generic message digest checksum result
00299  *
00300  * \return         0 if successful, POLARSSL_ERR_MD_FILE_OPEN_FAILED if fopen
00301  *                 failed, POLARSSL_ERR_MD_FILE_READ_FAILED if fread failed,
00302  *                 POLARSSL_ERR_MD_BAD_INPUT_DATA if md_info was NULL.
00303  */
00304 int md_file( const md_info_t *md_info, const char *path,
00305              unsigned char *output );
00306 
00307 /**
00308  * \brief          Generic HMAC context setup
00309  *
00310  * \param ctx      HMAC context to be initialized
00311  * \param key      HMAC secret key
00312  * \param keylen   length of the HMAC key
00313  *
00314  * \returns        0 on success, POLARSSL_ERR_MD_BAD_INPUT_DATA if parameter
00315  *                 verification fails.
00316  */
00317 int md_hmac_starts( md_context_t *ctx, const unsigned char *key,
00318                     size_t keylen );
00319 
00320 /**
00321  * \brief          Generic HMAC process buffer
00322  *
00323  * \param ctx      HMAC context
00324  * \param input    buffer holding the  data
00325  * \param ilen     length of the input data
00326  *
00327  * \returns        0 on success, POLARSSL_ERR_MD_BAD_INPUT_DATA if parameter
00328  *                 verification fails.
00329  */
00330 int md_hmac_update( md_context_t *ctx, const unsigned char *input,
00331                     size_t ilen );
00332 
00333 /**
00334  * \brief          Generic HMAC final digest
00335  *
00336  * \param ctx      HMAC context
00337  * \param output   Generic HMAC checksum result
00338  *
00339  * \returns        0 on success, POLARSSL_ERR_MD_BAD_INPUT_DATA if parameter
00340  *                 verification fails.
00341  */
00342 int md_hmac_finish( md_context_t *ctx, unsigned char *output);
00343 
00344 /**
00345  * \brief          Generic HMAC context reset
00346  *
00347  * \param ctx      HMAC context to be reset
00348  *
00349  * \returns        0 on success, POLARSSL_ERR_MD_BAD_INPUT_DATA if parameter
00350  *                 verification fails.
00351  */
00352 int md_hmac_reset( md_context_t *ctx );
00353 
00354 /**
00355  * \brief          Output = Generic_HMAC( hmac key, input buffer )
00356  *
00357  * \param md_info  message digest info
00358  * \param key      HMAC secret key
00359  * \param keylen   length of the HMAC key
00360  * \param input    buffer holding the  data
00361  * \param ilen     length of the input data
00362  * \param output   Generic HMAC-result
00363  *
00364  * \returns        0 on success, POLARSSL_ERR_MD_BAD_INPUT_DATA if parameter
00365  *                 verification fails.
00366  */
00367 int md_hmac( const md_info_t *md_info, const unsigned char *key, size_t keylen,
00368                 const unsigned char *input, size_t ilen,
00369                 unsigned char *output );
00370 
00371 /* Internal use */
00372 int md_process( md_context_t *ctx, const unsigned char *data );
00373 
00374 #ifdef __cplusplus
00375 }
00376 #endif
00377 
00378 #endif /* POLARSSL_MD_H */
00379 
00380