src/include/k5-spake.h

   1 /* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */
   2 /* include/k5-spake.h - SPAKE preauth mech declarations */
   3 /*
   4  * Copyright (C) 2015 by the Massachusetts Institute of Technology.
   5  * All rights reserved.
   6  *
   7  * Redistribution and use in source and binary forms, with or without
   8  * modification, are permitted provided that the following conditions
   9  * are met:
  10  *
  11  * * Redistributions of source code must retain the above copyright
  12  *   notice, this list of conditions and the following disclaimer.
  13  *
  14  * * Redistributions in binary form must reproduce the above copyright
  15  *   notice, this list of conditions and the following disclaimer in
  16  *   the documentation and/or other materials provided with the
  17  *   distribution.
  18  *
  19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  22  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  23  * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  24  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  25  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  26  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  28  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  29  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  30  * OF THE POSSIBILITY OF SUCH DAMAGE.
  31  */
  32
  33 /*
  34  * The SPAKE preauth mechanism allows long-term client keys to be used for
  35  * preauthentication without exposing them to offline dictionary attacks.  The
  36  * negotiated key can also be used for second-factor authentication.  This
  37  * header file declares structures and encoder/decoder functions for the
  38  * mechanism's padata messages.
  39  */
  40
  41 #ifndef K5_SPAKE_H
  42 #define K5_SPAKE_H
  43
  44 #include "k5-int.h"
  45
  46 /* SPAKESecondFactor is contained within a SPAKEChallenge, SPAKEResponse, or
  47  * EncryptedData message and contains a second-factor challenge or response. */
  48 typedef struct krb5_spake_factor_st {
  49     int32_t type;
  50     krb5_data *data;
  51 } krb5_spake_factor;
  52
  53 /* SPAKESupport is sent from the client to the KDC to indicate which group the
  54  * client supports. */
  55 typedef struct krb5_spake_support_st {
  56     int32_t ngroups;
  57     int32_t *groups;
  58 } krb5_spake_support;
  59
  60 /* SPAKEChallenge is sent from the KDC to the client to communicate its group
  61  * selection, public value, and second-factor challenge options. */
  62 typedef struct krb5_spake_challenge_st {
  63     int32_t group;
  64     krb5_data pubkey;
  65     krb5_spake_factor **factors;
  66 } krb5_spake_challenge;
  67
  68 /* SPAKEResponse is sent from the client to the KDC to communicate its public
  69  * value and encrypted second-factor response. */
  70 typedef struct krb5_spake_response_st {
  71     krb5_data pubkey;
  72     krb5_enc_data factor;
  73 } krb5_spake_response;
  74
  75 enum krb5_spake_msgtype {
  76     SPAKE_MSGTYPE_UNKNOWN = -1,
  77     SPAKE_MSGTYPE_SUPPORT = 0,
  78     SPAKE_MSGTYPE_CHALLENGE = 1,
  79     SPAKE_MSGTYPE_RESPONSE = 2,
  80     SPAKE_MSGTYPE_ENCDATA = 3
  81 };
  82
  83 /* PA-SPAKE is a choice among the message types which can appear in a PA-SPAKE
  84  * padata element. */
  85 typedef struct krb5_pa_spake_st {
  86     enum krb5_spake_msgtype choice;
  87     union krb5_spake_message_choices {
  88         krb5_spake_support support;
  89         krb5_spake_challenge challenge;
  90         krb5_spake_response response;
  91         krb5_enc_data encdata;
  92     } u;
  93 } krb5_pa_spake;
  94
  95 krb5_error_code encode_krb5_spake_factor(const krb5_spake_factor *val,
  96                                          krb5_data **code_out);
  97 krb5_error_code decode_krb5_spake_factor(const krb5_data *code,
  98                                          krb5_spake_factor **val_out);
  99 void k5_free_spake_factor(krb5_context context, krb5_spake_factor *val);
 100
 101 krb5_error_code encode_krb5_pa_spake(const krb5_pa_spake *val,
 102                                      krb5_data **code_out);
 103 krb5_error_code decode_krb5_pa_spake(const krb5_data *code,
 104                                      krb5_pa_spake **val_out);
 105 void k5_free_pa_spake(krb5_context context, krb5_pa_spake *val);
 106
 107 #endif /* K5_SPAKE_H */