src/lib/protocols/security/CHIPSecurity.h

   1 /*
   2  *
   3  *    Copyright (c) 2020 Project CHIP Authors
   4  *    Copyright (c) 2019-2020 Google LLC.
   5  *    Copyright (c) 2013-2017 Nest Labs, Inc.
   6  *    All rights reserved.
   7  *
   8  *    Licensed under the Apache License, Version 2.0 (the "License");
   9  *    you may not use this file except in compliance with the License.
  10  *    You may obtain a copy of the License at
  11  *
  12  *        http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  *    Unless required by applicable law or agreed to in writing, software
  15  *    distributed under the License is distributed on an "AS IS" BASIS,
  16  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  *    See the License for the specific language governing permissions and
  18  *    limitations under the License.
  19  */
  20
  21 /**
  22  *    @file
  23  *      This file defines base and common data types and interfaces
  24  *      for the CHIP Security profile.
  25  *
  26  */
  27
  28 #ifndef CHIPSECURITY_H_
  29 #define CHIPSECURITY_H_
  30
  31 #include <core/CHIPVendorIdentifiers.hpp>
  32
  33 /**
  34  *   @namespace chip::Protocols::Security
  35  *
  36  *   @brief
  37  *     This namespace includes all interfaces within CHIP for the
  38  *     CHIP Security profile.
  39  */
  40
  41 namespace chip {
  42 namespace Protocols {
  43 namespace Security {
  44
  45 // Message Types for CHIP Security Protocol
  46 //
  47 enum
  48 {
  49     // ---- Certificate Provisioning Protocol ----
  50     kMsgType_GetCertificateRequest  = 40,
  51     kMsgType_GetCertificateResponse = 41,
  52
  53     // ---- General Messages ----
  54     kMsgType_EndSession         = 100,
  55     kMsgType_KeyError           = 101,
  56     kMsgType_MsgCounterSyncResp = 102,
  57 };
  58
  59 // CHIP Security Status Codes
  60 //
  61 enum
  62 {
  63     kStatusCode_SessionAborted                 = 1,  // The sender has aborted the session establishment process.
  64     kStatusCode_PASESupportsOnlyConfig1        = 2,  // PASE supports only Config1.
  65     kStatusCode_UnsupportedEncryptionType      = 3,  // The requested encryption type is not supported.
  66     kStatusCode_InvalidKeyId                   = 4,  // An invalid key id was requested.
  67     kStatusCode_DuplicateKeyId                 = 5,  // The specified key id is already in use.
  68     kStatusCode_KeyConfirmationFailed          = 6,  // The derived session keys do not agree.
  69     kStatusCode_InternalError                  = 7,  // The sender encountered an internal error (e.g. no memory, etc...).
  70     kStatusCode_AuthenticationFailed           = 8,  // The sender rejected the authentication attempt.
  71     kStatusCode_UnsupportedCASEConfiguration   = 9,  // No common CASE configuration supported.
  72     kStatusCode_UnsupportedCertificate         = 10, // An unsupported certificate was offered.
  73     kStatusCode_NoCommonPASEConfigurations     = 11, // No common PASE configuration supported.
  74     kStatusCode_KeyNotFound                    = 12, // The specified key is not found.
  75     kStatusCode_WrongEncryptionType            = 13, // The specified encryption type is invalid.
  76     kStatusCode_UnknownKeyType                 = 14, // The specified key has unknown key type.
  77     kStatusCode_InvalidUseOfSessionKey         = 15, // The specified key is used incorrectly.
  78     kStatusCode_InternalKeyError               = 16, // The receiver of the CHIP message encountered key error.
  79     kStatusCode_NoCommonKeyExportConfiguration = 17, // No common key export protocol configuration supported.
  80     kStatusCode_UnauthorizedKeyExportRequest   = 18, // An unauthorized key export request.
  81     kStatusCode_NoNewOperationalCertRequired   = 19, // No new operational certificate required.
  82     kStatusCode_OperationalNodeIdInUse =
  83         20, // The specified operational node Id is already used by another CHIP node (indication of node id collision).
  84     kStatusCode_InvalidOperationalNodeId      = 21, // The specified operational node Id is invalid.
  85     kStatusCode_InvalidOperationalCertificate = 22, // The specified operational certificate is invalid.
  86 };
  87
  88 // CHIP Key Error Message Size
  89 //
  90 enum
  91 {
  92     kChipKeyErrorMessageSize = 9, // The size of the key error message.
  93 };
  94
  95 // CHIP Message Counter Synchronization Response Message Size.
  96 //
  97 enum
  98 {
  99     kChipMsgCounterSyncRespMsgSize = 4, // The size of the message counter synchronization response message.
 100 };
 101
 102 // Data Element Tags for the CHIP Security Protocol
 103 //
 104 enum
 105 {
 106     // ---- Top-level Protocol-Specific Tags ----
 107     kTag_ChipCertificate                = 1, // [ structure ] A CHIP certificate.
 108     kTag_EllipticCurvePrivateKey        = 2, // [ structure ] An elliptic curve private key.
 109     kTag_RSAPrivateKey                  = 3, // [ structure ] An RSA private key.
 110     kTag_ChipCertificateList            = 4, // [ array ] An array of CHIP certificates.
 111     kTag_ChipSignature                  = 5, // [ structure ] A CHIP signature object.
 112     kTag_ChipCertificateReference       = 6, // [ structure ] A CHIP certificate reference object.
 113     kTag_ChipCASECertificateInformation = 7, // [ structure ] A CHIP CASE certificate information object.
 114     kTag_ChipCASESignature              = 8, // [ structure ] An CHIP CASE signature object.
 115                                              //    Presently this has the same internal structure as an ECDSASignature.
 116     kTag_ChipAccessToken   = 9,              // [ structure ] A CHIP Access Token object
 117     kTag_GroupKeySignature = 10,             // [ structure ] A CHIP group Key signature object
 118     kTag_SerializedSession = 11,             // [ structure ] A serialized representation of CHIP session
 119                                              //    suitable for persisting.
 120
 121     // ---- Context-specific Tags for ChipCertificate Structure ----
 122     kTag_SerialNumber            = 1,  // [ byte string ] Certificate serial number, in BER integer encoding.
 123     kTag_SignatureAlgorithm      = 2,  // [ unsigned int ] Enumerated value identifying the certificate signature algorithm.
 124     kTag_Issuer                  = 3,  // [ path ] The issuer distinguished name of the certificate.
 125     kTag_NotBefore               = 4,  // [ unsigned int ] Certificate validity period start (certificate date format).
 126     kTag_NotAfter                = 5,  // [ unsigned int ] Certificate validity period end (certificate date format).
 127     kTag_Subject                 = 6,  // [ path ] The subject distinguished name of the certificate.
 128     kTag_PublicKeyAlgorithm      = 7,  // [ unsigned int ] Identifies the algorithm with which the public key can be used.
 129     kTag_EllipticCurveIdentifier = 8,  // [ unsigned int ] For EC certs, identifies the elliptic curve used.
 130     kTag_RSAPublicKey            = 9,  // [ structure ] The RSA public key.
 131     kTag_EllipticCurvePublicKey  = 10, // [ byte string ] The elliptic curve public key, in X9.62 encoded format.
 132     kTag_RSASignature            = 11, // [ byte string ] The RSA signature for the certificate.
 133     kTag_ECDSASignature          = 12, // [ structure ] The ECDSA signature for the certificate.
 134                                        // Tags identifying certificate extensions (tag numbers 128 - 255)
 135     kCertificateExtensionTagsStart = 128,
 136     kTag_AuthorityKeyIdentifier    = 128, // [ structure ] Information about the public key used to sign the certificate.
 137     kTag_SubjectKeyIdentifier      = 129, // [ structure ] Information about the certificate's public key.
 138     kTag_KeyUsage                  = 130, // [ structure ] TODO: document me
 139     kTag_BasicConstraints          = 131, // [ structure ] TODO: document me
 140     kTag_ExtendedKeyUsage          = 132, // [ structure ] TODO: document me
 141     kCertificateExtensionTagsEnd   = 255,
 142
 143     // ---- Context-specific Tags for RSAPublicKey Structure ----
 144     kTag_RSAPublicKey_Modulus        = 1, // [ byte string ] RSA public key modulus, in ASN.1 integer encoding.
 145     kTag_RSAPublicKey_PublicExponent = 2, // [ unsigned int ] RSA public key exponent.
 146
 147     // ---- Context-specific Tags for ECDSASignature Structure ----
 148     kTag_ECDSASignature_r = 1, // [ byte string ] ECDSA r value, in ASN.1 integer encoding.
 149     kTag_ECDSASignature_s = 2, // [ byte string ] ECDSA s value, in ASN.1 integer encoding.
 150
 151     // ---- Context-specific Tags for AuthorityKeyIdentifier Structure ----
 152     kTag_AuthorityKeyIdentifier_Critical =
 153         1, // [ boolean ] True if the AuthorityKeyIdentifier extension is critical. Otherwise absent.
 154     kTag_AuthorityKeyIdentifier_KeyIdentifier = 2, // [ byte string ] TODO: document me
 155     kTag_AuthorityKeyIdentifier_Issuer        = 3, // [ path ] TODO: document me
 156     kTag_AuthorityKeyIdentifier_SerialNumber  = 4, // [ byte string ] TODO: document me
 157
 158     // ---- Context-specific Tags for SubjectKeyIdentifier Structure ----
 159     kTag_SubjectKeyIdentifier_Critical = 1, // [ boolean ] True if the SubjectKeyIdentifier extension is critical. Otherwise absent.
 160     kTag_SubjectKeyIdentifier_KeyIdentifier = 2, // [ byte string ] Unique identifier for certificate's public key, per RFC5280.
 161
 162     // ---- Context-specific Tags for KeyUsage Structure ----
 163     kTag_KeyUsage_Critical = 1, // [ boolean ] True if the KeyUsage extension is critical. Otherwise absent.
 164     kTag_KeyUsage_KeyUsage = 2, // [ unsigned int ] Integer containing key usage bits, per to RFC5280.
 165
 166     // ---- Context-specific Tags for BasicConstraints Structure ----
 167     kTag_BasicConstraints_Critical = 1, // [ boolean ] True if the BasicConstraints extension is critical. Otherwise absent.
 168     kTag_BasicConstraints_IsCA     = 2, // [ boolean ] True if the certificate can be used to verify certificate signatures.
 169     kTag_BasicConstraints_PathLenConstraint = 3, // [ unsigned int ] Maximum number of subordinate intermediate certificates.
 170
 171     // ---- Context-specific Tags for ExtendedKeyUsage Structure ----
 172     kTag_ExtendedKeyUsage_Critical = 1, // [ boolean ] True if the ExtendedKeyUsage extension is critical. Otherwise absent.
 173     kTag_ExtendedKeyUsage_KeyPurposes =
 174         2, // [ array ] Array of enumerated values giving the purposes for which the public key can be used.
 175
 176     // ---- Context-specific Tags for EllipticCurvePrivateKey Structure ----
 177     kTag_EllipticCurvePrivateKey_CurveIdentifier = 1, // [ unsigned int ] ChipCurveId identifying the elliptic curve.
 178     kTag_EllipticCurvePrivateKey_PrivateKey =
 179         2,                                      // [ byte string ] Private key encoded using the I2OSP algorithm defined in RFC3447.
 180     kTag_EllipticCurvePrivateKey_PublicKey = 3, // [ byte string ] The elliptic curve public key, in X9.62 encoded format.
 181
 182     // ---- Context-specific Tags for RSAPrivateKey Structure ----
 183     // ... TBD ...
 184
 185     // ---- Context-specific Tags for ChipSignature Structure ----
 186     kTag_ChipSignature_ECDSASignatureData = 1, // [ structure ] ECDSA signature data for the signed message.
 187     kTag_ChipSignature_RSASignatureData   = 2, // [ byte string ] RSA signature for the signed message.
 188                                                //   Per the schema, exactly one of ECDSASignature or RSASignature must be present.
 189     kTag_ChipSignature_SigningCertificateRef =
 190         3, // [ structure ] A CHIP certificate reference structure identifying the certificate
 191            //   used to generate the signature. If absent, the signature was generated by the
 192            //   first certificate in the RelatedCertificates list.
 193     kTag_ChipSignature_RelatedCertificates =
 194         4, // [ array ] Array of certificates needed to validate the signature.  May be omitted if
 195            //   validators are expected to have the necessary certificates for validation.
 196            //   At least one of SigningCertificateRef or RelatedCertificates must be present.
 197     kTag_ChipSignature_SignatureAlgorithm =
 198         5, // [ unsigned int ] Enumerated value identifying the signature algorithm.
 199            //   Legal values per the schema are: kOID_SigAlgo_ECDSAWithSHA1, kOID_SigAlgo_ECDSAWithSHA256,
 200            //     kOID_SigAlgo_SHA1WithRSAEncryption and kOID_SigAlgo_SHA256WithRSAEncryption.
 201            //   For backwards compatibility, this field should be omitted when the signature
 202            //     algorithm is ECDSAWithSHA1.
 203            //   When this field is included it must appear first within the ChipSignature structure.
 204            //   kOID_SigAlgo_SHA1WithRSAEncryption and kOID_SigAlgo_SHA256WithRSAEncryption are
 205            //     not presently supported in the code.
 206
 207     // ---- Context-specific Tags for CHIP Certificate Reference Structure ----
 208     kTag_ChipCertificateRef_Subject = 1, // [ path ] The subject DN of the referenced certificate.
 209     kTag_ChipCertificateRef_PublicKeyId =
 210         2, // [ byte string ] Unique identifier for referenced certificate's public key, per RFC5280.
 211
 212     // ---- Context-specific Tags for CHIP CASE Certificate Information Structure ----
 213     kTag_CASECertificateInfo_EntityCertificate =
 214         1, // [ structure ] A CHIP certificate object representing the authenticating entity.
 215     kTag_CASECertificateInfo_EntityCertificateRef =
 216         2, // [ structure ] A CHIP certificate reference object identifying the authenticating entity.
 217     kTag_CASECertificateInfo_RelatedCertificates = 3, // [ path ] A collection of certificates related to the authenticating entity.
 218     kTag_CASECertificateInfo_TrustAnchors =
 219         4, // [ path ] A collection of CHIP certificate reference identifying certificates trusted
 220            //   by the authenticating entity.
 221
 222     // ---- Context-specific Tags for CHIP Access Token Structure ----
 223     kTag_AccessToken_Certificate = 1, // [ structure ] A CHIP certificate object representing the entity that is trusted to
 224                                       //   access a device or fabric.
 225     kTag_AccessToken_PrivateKey = 2,  // [ structure ] An EllipticCurvePrivateKey object containing the private key associated
 226                                       //   with the access token certificate.
 227     kTag_AccessToken_RelatedCertificates = 3, // [ array, optional ] An optional array of certificates related to the access token
 228                                               //   certificate that may be needed to validate it.
 229
 230     kTag_GroupKeySignature_SignatureAlgorithm = 1, //  [ unsigned int ] Enumerated value identifying the certificate signature
 231                                                    //  algorithm.  Legal values are taken from the kOID_SigAlgo_* constant
 232                                                    //  namespace.  The only value currently supported is
 233                                                    //  kOID_SigAlgo_HMACWithSHA256.  When the tag is ommitted the signature
 234                                                    //  algorithm defaults to HMACWithSHA256
 235     kTag_GroupKeySignature_KeyId     = 2,          //  [ unsigned int ] CHIP KeyId to be used to generate and verify the signature
 236     kTag_GroupKeySignature_Signature = 3,          //  [ byte string ] Signature bytes themselves.
 237
 238     // ---- Context-specific Tags for GetCertificateRequest Message Structure ----
 239     kTag_GetCertReqMsg_ReqType = 1, // [ unsigned int ] Identifies the certificate request type.
 240     kTag_GetCertReqMsg_Authorize_PairingToken =
 241         2, // [ byte string, optional ] Pairing token from the service. This token is used to authorize
 242            //   GetCertificateRequest message to the CA service.
 243     kTag_GetCertReqMsg_Authorize_PairingInitData =
 244         3, // [ byte string, optional ] Pairing initialization data from the service. This data is used
 245            //   to authorize GetCertificateRequest message to the CA service.
 246     kTag_GetCertReqMsg_OpDeviceCert = 4, // [ structure ] CHIP operational device certificate.
 247                                          //   This has the same internal structure as an kTag_ChipCertificate.
 248     kTag_GetCertReqMsg_OpRelatedCerts =
 249         5, // [ array, optional ] An optional array of CHIP operational intermediate CA certificates,
 250            //   which are needed to validate CHIP operational device certificate. May be omitted if
 251            //   validators are expected to have the necessary certificates for validation.
 252            //   Each element of this array has the same internal structure as an kTag_ChipCertificate.
 253     kTag_GetCertReqMsg_MfrAttest_ChipCert =
 254         6, // [ structure ] CHIP device certificate provisioned at the factory at manufacturing time.
 255            //   This has the same internal structure as an kTag_ChipCertificate.
 256     kTag_GetCertReqMsg_MfrAttest_ChipRelCerts =
 257         7, // [ array, optional ] An optional array of CHIP intermediate CA certificates, which are needed
 258            //   to validate included manufacturer-assigned CHIP device certificate. May be omitted if
 259            //   validators are expected to have the necessary certificates for validation.
 260            //   Each element of this array has the same internal structure as an kTag_ChipCertificate.
 261     kTag_GetCertReqMsg_MfrAttest_X509Cert =
 262         8, // [ byte string ] X509 device certificate provisioned at the factory at manufacturing time.
 263            //   This is an ASN1 encoded ECDSA or RSA certificate TLV-encoded as a data blob.
 264     kTag_GetCertReqMsg_MfrAttest_X509RelCerts =
 265         9, // [ array, optional ] An optional array of X509 intermediate CA certificates,
 266            //   which are needed to validate included manufacturer-assigned X509 device certificate.
 267            //   May be omitted if validators are expected to have the necessary certificates for validation.
 268            //   Each element of this array is a byte string, and each X509 certificate is TLV-encoded as a data blob.
 269     kTag_GetCertReqMsg_MfrAttest_HMACKeyId =
 270         10, // [ unsigned int ] Identifies the secret key that is used for the HMAC manufacturer attestation.
 271     kTag_GetCertReqMsg_MfrAttest_HMACMetaData =
 272         11, // [ byte string, optional ] Meta data associated with the HMAC manufacturer attestation.
 273     kTag_GetCertReqMsg_OpDeviceSigAlgo = 12,   // [ unsigned int ] Enumerated value identifying the operational signature algorithm.
 274                                                //   Legal values are taken from the kOID_SigAlgo_* constant namespace.
 275     kTag_GetCertReqMsg_OpDeviceSig_ECDSA = 13, // [ structure ] Operational device EC signature.
 276                                                //   This has the same internal structure as an kTag_ECDSASignature.
 277     kTag_GetCertReqMsg_MfrAttestSigAlgo =
 278         14, // [ unsigned int ] Enumerated value identifying the manufacturer attestation signature algorithm.
 279             //   Legal values are taken from the kOID_SigAlgo_* constant namespace.
 280     kTag_GetCertReqMsg_MfrAttestSig_ECDSA = 15, // [ structure ] Manufacturer attestation device EC signature.
 281                                                 //   This has the same internal structure as an kTag_ECDSASignature.
 282     kTag_GetCertReqMsg_MfrAttestSig_RSA  = 16,  // [ byte string ] Manufacturer attestation device RSA signature.
 283     kTag_GetCertReqMsg_MfrAttestSig_HMAC = 17,  // [ byte string ] Manufacturer attestation device HMAC signature.
 284
 285     // ---- Context-specific Tags for GetCertificateResponse Message Structure ----
 286     kTag_GetCertRespMsg_OpDeviceCert = 1, // [ structure ] Service assigned CHIP operational device certificate.
 287                                           //   This has the same internal structure as an kTag_ChipCertificate.
 288     kTag_GetCertRespMsg_OpRelatedCerts =
 289         2, // [ array, optional ] An optional array of CHIP certificates related to the
 290            //   operational device certificate, which are needed to validate certificate.
 291            //   Each element of this array has the same internal structure as an kTag_ChipCertificate.
 292
 293     // ---- Context-specific Tags for CHIP representation of X.509 Distinguished Name Attributes ----
 294     //
 295     // The value used here must match *exactly* the OID enum values assigned to the corresponding object ids in the gen-oid-table.py
 296     // script.
 297     //
 298     // WARNING! Assign no values higher than 127.
 299     //
 300     kTag_DNAttrType_CommonName              = 1,  // [ UTF8 string ]
 301     kTag_DNAttrType_Surname                 = 2,  // [ UTF8 string ]
 302     kTag_DNAttrType_SerialNumber            = 3,  // [ UTF8 string ]
 303     kTag_DNAttrType_CountryName             = 4,  // [ UTF8 string ]
 304     kTag_DNAttrType_LocalityName            = 5,  // [ UTF8 string ]
 305     kTag_DNAttrType_StateOrProvinceName     = 6,  // [ UTF8 string ]
 306     kTag_DNAttrType_OrganizationName        = 7,  // [ UTF8 string ]
 307     kTag_DNAttrType_OrganizationalUnitName  = 8,  // [ UTF8 string ]
 308     kTag_DNAttrType_Title                   = 9,  // [ UTF8 string ]
 309     kTag_DNAttrType_Name                    = 10, // [ UTF8 string ]
 310     kTag_DNAttrType_GivenName               = 11, // [ UTF8 string ]
 311     kTag_DNAttrType_Initials                = 12, // [ UTF8 string ]
 312     kTag_DNAttrType_GenerationQualifier     = 13, // [ UTF8 string ]
 313     kTag_DNAttrType_DNQualifier             = 14, // [ UTF8 string ]
 314     kTag_DNAttrType_Pseudonym               = 15, // [ UTF8 string ]
 315     kTag_DNAttrType_DomainComponent         = 16, // [ UTF8 string ]
 316     kTag_DNAttrType_ChipDeviceId            = 17, // [ unsigned int ]
 317     kTag_DNAttrType_ChipServiceEndpointId   = 18, // [ unsigned int ]
 318     kTag_DNAttrType_ChipCAId                = 19, // [ unsigned int ]
 319     kTag_DNAttrType_ChipSoftwarePublisherId = 20, // [ unsigned int ]
 320
 321     // ---- Context-specific Tags for Serialized Session structure ----
 322     kTag_SerializedSession_KeyId                   = 1,     // [ UNSIGNED INT, range 16bits ] Assigned session key id
 323     kTag_SerializedSession_PeerNodeId              = 2,     // [ UNSIGNED INT, range 64bits ] Node id of session peer
 324     kTag_SerializedSession_NextMessageId           = 3,     // [ UNSIGNED INT, range 32bits ] Next message id
 325     kTag_SerializedSession_MaxRcvdMessageId        = 4,     // [ UNSIGNED INT, range 32bits ] Max received message id
 326     kTag_SerializedSession_MessageRcvdFlags        = 5,     // [ UNSIGNED INT, range 64bits ] Message received flags
 327     kTag_SerializedSession_IsLocallyInitiated      = 6,     // [ BOOLEAN ] Is session locally initiated
 328     kTag_SerializedSession_IsShared                = 7,     // [ BOOLEAN ] Is session shared
 329     kTag_SerializedSession_SharedSessionAltNodeIds = 8,     // [ ARRAY OF UNSIGNED INT, range 64bits ] For a shared session,
 330                                                             //    list of alternate peer node ids.
 331     kTag_SerializedSession_CASE_PeerCertType = 9,           // [ UNSIGNED INT, range 8bits ] For CASE sessions, the type
 332                                                             //    of certificate presented by the peer.
 333     kTag_SerializedSession_EncryptionType        = 10,      // [ UNSIGNED INT, range 8bits ] Message encryption type
 334     kTag_SerializedSession_AES128CTRSHA1_DataKey = 11,      // [ BYTE STRING, len 16 ] For sessions supporting AES128CTRSHA1
 335                                                             //    message encryption, the data encryption key.
 336     kTag_SerializedSession_AES128CTRSHA1_IntegrityKey = 12, // [ BYTE STRING, len 20 ] For sessions supporting AES128CTRSHA1
 337                                                             //    message encryption, the data integrity key.
 338 };
 339
 340 } // namespace Security
 341 } // namespace Protocols
 342 } // namespace chip
 343
 344 #endif /* CHIPSECURITY_H_ */