Open Software Foundation A. Anderson (HP) Request For Comments: 68.3 S. Cuti (HP) January 1997 DCE 1.2.2 PUBLIC KEY LOGIN -- FUNCTIONAL SPECIFICATION 1. INTRODUCTION This document specifies the functionality required to integrate public key mechanisms into DCE login, that is, into the initial DCE Kerberos Ticket-Granting Ticket protocol. This specification obsoletes [RFC 68.2]. The goal of this effort is to allow users to use a private key rather than a shared-secret password to prove their identity to the DCE Key Distribution Center (KDC) (a.k.a. Key Distribution Server, KDS). The immediate benefit is that, in the event of a compromise of the KDC, public key users do not have any identifying information exposed to the intruder. If the KDC is compromised, all user secret keys will be revealed to the intruder. This means they become worthless as a proof of identity, and therefore the cell administrator must re-issue passwords to all such users before they can be allowed to log-in to the cell. Under the design described in this RFC, public key users prove their identity by knowledge of a private key that is never known to the KDC, and therefore a compromise of the KDC cannot reveal these keys. The authentication information and protocol are based on the PK-INIT Kerberos protocol [DRAFT-PKINIT] where the user's private key is stored locally. A DCE Personal Security Module Interface is provided to abstract and hide underlying details of public key algorithm implementations, interfaces, and information storage mechanisms. A DCE Public Key Module API is provided to abstract and hide the underlying details of KDC and client public key acquisition for use in the Public Key Login protocol. A DCE Private Key Module Interface is provided to abstract and hide the underlying details of the private key storage mechanism. There are no changes to existing login APIs (`sec_login') other than for the addition of some new error status values, and no need for changes to existing login utilities or user interfaces. Anderson, Cuti Page 1 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 1.1. Changes Since Last Publication Changes since [RFC 68.2]: (a) The public key login protocol was previously based on [ITU X.509] as described in [RFC 85.0]. The protocol is now one of the protocols specified in [DRAFT-PKINIT]. (b) Support for public key generation has been added. (c) `dcecp' support for creating or modifying accounts to use the public key login protocol has been added. (d) Two new interfaces, `sec_pubkey' and `sec_pvtkey', have been specified. (e) The `DCEPKModulusLength' ERA has been removed. The modulus length for key-pair generation is now specified as part of the `dcecp' command. (f) The `DCEPKPrivateKeyStorage' ERA has been added. This ERA is used to identify the private key storage mechanism used by each principal. (g) The format of public keys as stored in the `DCEPKKeyEncipherment' and `DCEPKAuthentication' ERAs has changed. The keys are now stored as IDL-encoded structures of type `sec_passwd_rec_t', with `key' of type `sec_passwd_pubkey'. This allows a version number to be associated with each public key. 2. TARGET This technology is provided for customers who require less reliance on the physical security of DCE Security servers. It may also be of interest to customers moving toward public key based security mechanisms such as smart cards, or public key based "Single Sign On" facilities, although this technology is only a starting point for such enhancements, which are not part of this deliverable. 3. GOALS AND NON-GOALS 3.1. Goals (a) Allow users to use a private key rather than a password to prove their identity to the DCE Key Distribution Center. (b) Provide a standards-based mutual authentication protocol between the user and the DCE Key Distribution Center. Anderson, Cuti Page 2 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 (c) The protocol must not require private keys to be stored in the DCE Registry or to be transmitted across the wire protected by a password-derived key. (d) Ease recovery from a compromise of the DCE Key Distribution Center. (e) Allow for use of public key algorithms that need not be RSA (although the reference implementation uses the RSA BSAFE library). (f) Allow for integration with public key formats that need not be RSA-format keys (although the reference implementation uses the RSA BSAFE library). 3.2. Non-Goals (a) It is not a goal to support public key certificates in the reference implementation, or to provide integration with the DCE Certification API [RFC 80.0], or to assume the existence of a Certification Authority. The wire protocol is designed to allow integration of such support in the future.[1] In the reference implementation, public keys are obtained by the KDC from the DCE Registry. If a client provides a certificate as part of the authentication protocol, the KDC ignores the certificate gracefully. (b) Server principals that use public key authentication to the KDC must use the OSF DCE 1.2.2 User-to-User Protocol for authenticated communication with DCE clients. This is because non-User-to-User Kerberos Service Tickets continue to be DES- encrypted under the DES key of the server. Extending public key technology into this context is beyond the scope of this project. (c) It is not a goal of this project to integrate or test the DCE Private Key Storage Server (see [RFC 94.0]) with the functionality provided by this project. Such integration and testing is expected to be done by the provider of the DCE Private Key Storage Server. (d) There is no specified or supported policy control for public keys (such as control of lifetime, expiration, or length) other __________ 1. Although it is expected that DCE will support public key certificates eventually, the format of those certificates is still undetermined. Anderson, Cuti Page 3 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 than as specified in "Public Key Policy Control" under "FUNCTIONAL DEFINITION". 4. TERMINOLOGY The same terminology and notation used in [RFC 85.0] is carried over here, with a few additions: (a) *PSM* -- Personal Security Module; a layer defined to abstract knowledge of public and private key storage mechanisms and public key cryptosystem operations and data types. (b) *ERA* -- OSF DCE 1.1 Extended Registry Attribute. See [RFC 6.0]. (c) *ASN.1* -- Abstract Syntax Notation 1. A notation defined in [ITU X.208] for describing abstract types and values. (d) *BER* -- Basic Encoding Rules. A set of rules defined in [ITU X.209] and used to encode ASN.1 values as strings of octets. A single value can have multiple valid BER encodings. (e) *DER* -- Distinguished Encoding Rules. A restricted form of BER defined in [ITU X.509] to eliminate most of the ambiguities in BER. (f) *Smart Card* -- A multi-purpose, tamper-resistant, portable personal security device, utilizing VLSI chip technology for information storage and processing. (g) *User* -- The human user (and any associated private key storage). (h) *Client* -- An application running on the user's workstation. The login process is an example of a client. (i) `Cx' -- Certificate of X. (j) `K' -- Symmetric (session) key. (k) `Ktgt' -- The session key to be used with a TGT. (l) `{M}Px' -- Message M encrypted with X's public key. (m) `{M}Sx' -- Message M signed by X. (n) `Nx' -- A nonce (e.g., random number) generated by X. (o) `Tx' -- A time stamp generated by X. Anderson, Cuti Page 4 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 (p) *KDC* -- The Kerberos Key Distribution Center.[2] (q) *TGT* -- A Kerberos Ticket Granting Ticket. 5. REQUIREMENTS The technology must support an increase to the overall security of a DCE cell. It must also represent a genuine integration of public key technology with the DCE login process. 6. FUNCTIONAL DEFINITION 6.1. TGT Acquisition Protocol The DCE Public Key TGT acquisition protocol is a subset of the protocol described in [DRAFT-PKINIT], using the option for user's private key being stored locally. NOTE: The protocol defined by [DRAFT-PKINIT] is very new, and is a candidate for entry onto the IETF standards track. Before it becomes standardized, it may change in an incompatible and non-interoperable way. It is the intent of the authors that the DCE implementation track this protocol as it evolves; however, resource and schedule constraints have prevented us from implementing the full protocol in DCE 1.2.2. Future versions of DCE are expected to change to follow the successors to [DRAFT-PKINIT] as well as maintain interoperability with DCE 1.2.2; however, in the interests of greater interoperability, compliance with [DRAFT-PKINIT] will have priority. The DCE login APIs (`sec_login_validate_identity()', `sec_login_valid_and_cert_ident()', and `sec_login_validate_first()') attempt to use this protocol initially by default as long as Public Key authentication information can be constructed. If Public Key authentication information can not be constructed, then the default for the initial attempt is the OSF DCE Third Party protocol. If OSF DCE Third Party authentication information can not be constructed, then the default for the initial attempt is the Timestamps protocol (for which information can always be constructed). __________ 2. No distinction is made here between the Authentication Service and the Ticket Granting Service (subservices of the KDC), for reasons of clarity. Anderson, Cuti Page 5 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 NOTE: In the reference implementation, for backwards compatibility with pre-1.2.2 servers, both the `KRB5_PADATA_ENC_UNIX_TIME' and `KRB5_PADATA_ENC_TIMESTAMP' PADATA are constructed. If the KDC is unable to authenticate the user with the supplied public key pre-authentication data, the KDC returns error information. If the initial public key login attempt fails, then the `sec_login' code falls back to the existing symmetric key password-based authentication, unless the KDC error information indicates that the principal is required to use public key pre-authentication. Sites that do not wish to allow any fall-back must attach an instance of the `pre_auth_req' ERA, with a value of `3' (`PADATA-ENC-PUBLIC- KEY'), to each principal that is required to use public key login. With this ERA attached, the KDC will not accept anything except a public key login for the principal, even if attempted. A two-message protocol is used to acquire a TGT. This protocol relies, in part, on time stamps to guarantee the freshness of messages. There is no reason to adopt a challenge-response mechanism since the subsequent Kerberos protocols rely on time stamps. Since the TGT session key is encrypted with a random key that is encrypted with the public key of the client, successful use of the TGT implies the ability to decrypt this session key, and therefore possession of the user's private key. The authentication information is transmitted in the pre- authentication data fields of the standard Kerberos V5 `KRB_AS_REQ' and `KRB_AS_REP' messages [IETF 1510] as new `KRB5_PADATA_ROOT_CERT' and `KRB5_PADATA_PUBLIC_REP' pre-authentication data types. NOTE: As an implementation optimization and for backwards compatibility with pre-1.2.2 servers, the client sends both Third-Party (PADATA-ENC-OSF-DCE) and Public Key (PADATA-ENC- ROOT-CERT) PADATA in the initial TGT request. The Third-Party PADATA is the first PADATA stored in the request. Pre-1.2.2 servers examine and verify the first PADATA, and ignore any remaining PADATA. DCE 1.2.2 servers examine and verify each PADATA type. If the Third-Party PADATA can not be verified, but the Public Key PADATA can, then the KDC returns a TGT to the client using the Public Key reply protocol. The protocol usage criteria can be diagrammed as follows. The "TP can be built" column indicates whether a Third-Party PADATA structure can be built by the `sec_login' client code. The "PK can be built" column indicates whether Public Key Protocol information can be built by the `sec_login' client code. This can be Anderson, Cuti Page 6 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 built only if the client has a `PSM' and if the supplied passphrase is valid for gaining access to that `PSM'. The "PADATA sent" column indicates which PADATA types are sent in the `KRB_AS_REQ', and in what order. The "PADATA verified" column indicates which PADATA type must pass verification in order for a TGT to be returned and which protocol will be used for the PADATA in the `KRB_AS_REP'. If there is no possibility of a TGT to be returned, the column indicates "none". TABLE 1: PROTOCOL USAGE CRITERIA PROTOCOLS VERSIONS CASES USED --------------- -------------------------- -------------- client server TP can PK can password PADATA PADATA version version be built be built valid sent+ verified+ ------- ------- -------- -------- -------- ------ --------- 1.2.2 1.2.2 yes yes yes TP,PK PK 1.2.2 1.2.2 yes yes no TP,PK PK 1.2.2 1.2.2 yes no yes TP TP* 1.2.2 1.2.2 yes no no TP none 1.2.2 1.2.2 no yes yes TS,PK PK 1.2.2 1.2.2 no yes no TS,PK PK 1.2.2 1.2.2 no no yes TS TS* 1.2.2 1.2.2 no no no TS none 1.2.2 <1.2.2 yes yes yes TP,PK TP 1.2.2 <1.2.2 yes yes no TP,PK none 1.2.2 <1.2.2 yes no yes TP TP 1.2.2 <1.2.2 yes no no TP none 1.2.2 <1.2.2 no yes yes TS,PK TS* 1.2.2 <1.2.2 no yes no TS,PK none 1.2.2 <1.2.2 no no yes TS TS* 1.2.2 <1.2.2 no no no TS none <1.2.2 1.2.2 yes N/A yes TP TP* <1.2.2 1.2.2 yes N/A no TP none <1.2.2 1.2.2 no N/A yes TS TS* <1.2.2 1.2.2 no N/A no TS none Anderson, Cuti Page 7 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * PADATA passes verification only if the client's effective pre_auth_req value allows the client to use this PADATA type. + TS: Timestamps PADATA (KRB5_PADATA_ENC_UNIX_TIME from pre-1.2.2 clients, KRB5_PADATA_ENC_UNIX_TIME followed by KRB5_PADATA_ENC_TIMESTAMP from 1.2.2 clients) TP: Third-Party PADATA (KRB5_PADATA_ENC_OSF_DCE) PK: Public Key PADATA (KRB5_PADATA_ENC_ROOT_CERT, KRB5_PADATA_ENC_PUBLIC_REP) 6.1.1. Client-to-KDC Message NOTE: The following protocol description is necessarily a high-level simplification of the actual protocol used. For full details, see [DRAFT-PKINIT]. C-->KDC: {Rc,Cksum,Tc,Nc,KDC}Sc The client process signs a message including an optional list of root certifiers trusted by the client, a checksum, a time stamp, a nonce and the identity of the KDC. The signature is done with the client's private digital signature key. This signed message is sent to the KDC along with the client's (optional) certificate as the contents of the PADATA field of a standard `KRB_AS_REQ' message. The client's identity is part of the existing `KRB_AS_REQ' message. NOTE: In the reference implementation, client processes do not send a certificate, and the list of root certifiers trusted by the client is NULL. If the client supplies a certificate, the KDC may choose to ignore the certificate and retrieve public keys directly from the DCE Registry. Alternatively, the KDC may check revocation lists to establish the validity of the certificate. NOTE: In the reference implementation, the KDC ignores any certificates sent by client processes and obtains public keys directly from the DCE Registry. 6.1.2. KDC-to-Client Message NOTE: The following protocol description is necessarily a high-level simplification of the actual protocol used. For full details, see [DRAFT-PKINIT]. KDC-->C: Ckdc,{{Kreply,Nc}Skdc}EncReplytmpKey, {EncReplytmpKey}Pc Anderson, Cuti Page 8 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 The KDC checks the time stamp and signature of the client's message. If the time stamp is sufficiently current and the signature can be verified using the client's public key, the KDC responds with a standard `KRB_AS_REP' reply message in which the PADATA field contains a random symmetric reply key (`Kreply') and the client's nonce. The reply key and client nonce are first signed using the KDC's private digital signature key, then encrypted using a temporary random symmetric key (`EncReplytmpKey'). This temporary random symmetric key is encrypted with the client's public key-encipherment key [the combination of symmetrically encrypted signed data and asymmetrically encrypted key is called _digital enveloping_]. The reply key is used to encrypt the encrypted portion of the standard `KRB_AS_REP', which includes the symmetric session key associated with the TGT. The KDC optionally includes its certificate in the PADATA field of the response. This certificate, if included, must be signed by one of the root certifiers trusted by the client. The TGT is passed in the standard `KRB_AS_REP' ticket field. The TGT is returned without additional encryption (portions of it were encrypted by the KDC) since it is subsequently used in the clear by the client. The symmetric session key used in association with the TGT is returned in the standard `EncKDCRepPart' field of the `KRB_AS_REP' message. This `EncKDCRepPart' field is encrypted using the reply key (`Kreply') returned in the signed and encrypted authentication data from the KDC. NOTE: In the reference implementation, the KDC does not send its certificate in the response. The public key of the KDC is cached locally on the client node by the `dced' daemon, and can be read from the cache by the client. Vendors implementing smart cards may wish to store the public key of the KDC on each user's smart card, and have the client obtain the KDC public key from the smart card. By checking the signature on this response, the client can be assured that the reply is from the KDC. The session key can only be decrypted by the legitimate client who possesses the private key needed to decrypt the key encryption key. The TGT and associated session key are then used as normal. 6.1.3. Changes to existing TGT acquisition protocols When any TGT acquisition request is received, the DCE KDC checks for an instance of the `pre_auth_req' ERA attached to the user principal. If found, the authentication attempt is rejected with the `KDC_PREAUTH_FAILED' error if the value of the ERA is less than the value associated with the protocol used by the TGT acquisition request. The public key login protocol has a higher associated value than any previously specified preauthentication protocol, including the various forms of encrypted timestamps and the DCE 1.1 third-party Anderson, Cuti Page 9 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 protocol. 6.2. Public Key Interfaces 6.2.1. Overview Public Key Login provides a number of layers and APIs. Some of these are provided to help satisfy export requirements. Some are provided to allow easy extension or enhancement by vendors. Only one API -- `sec_pubkey' -- is provided for user application use. The Public Key Login layers and APIs may be diagrammed as follows as they are used internally by the DCE Security client library. TABLE 2: PUBLIC KEY LOGIN LAYERS ___________________________________________________ | | | sec_login | |___________________________________________________| | | | sec_psm | |___________________________________________________| | | | | | sec_pubkey | sec_pvtkey | crypto library | |_________________|______________|__________________| | | | | | rsec_pk_cache | PKSS | file | |_________________|______|_______| Descriptions of the individual interfaces follow. 6.2.2. DCE Personal Security Module Interface A `sec_psm' layer is defined to abstract knowledge of public and private storage mechanisms and public key cryptosystem functions and data types. This interface is not specified as an application program interface, but rather as a way to allow replacement with a standard personal security module interface as one emerges. This layer provides access to high-level security operations such as `sign()', `verify()', `encrypt()', and `decrypt()', hiding the actual implementations in lower layers. The existing `sec_login' API has been made a consumer of this interface. Only the user principal has the permissions needed to obtain information from this layer, as access to the user's private key requires knowledge of the user's password. Anderson, Cuti Page 10 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 6.2.3. Public Key Module API A DCE Public Key Module API -- `sec_pubkey' -- is provided to abstract and hide the details of public key storage and acquisition for use in the Public Key Login protocol. This mechanism is extensible to other storage and acquisition mechanisms and for use by other protocols. This API may be used directly by DCE Applications. It is also used internal to the DCE Public Key protocol implementation. The mechanisms provided with the reference implementation are: (a) `sec_pk_domain_dce_general': retrieval of a principal's public keys from ERAs attached to the principal in the DCE Registry. This mechanism may be used for retrieval by any client for any principal. This mechanism may also be used for public key storage by a cell administrator, or other authorized client. (b) `sec_pk_domain_kdc_cache': retrieval of a principal's public keys from a local cache file, backed up by retrieval via request to `dced'. This mechanism may be used only for retrieval of a krbtgt principal's key. It is intended for use by unauthenticated clients as part of the Public Key Login protocol. (c) `sec_pk_domain_kdc_refresh_refresh': retrieval of a principal's public keys via request to `dced'. This mechanism may be used only for retrieval of a krbtgt principal's key. This mechanism causes the `dced' daemon to refresh the associated krbtgt principal's local public key cache file. (d) `sec_pk_domain_kdc_pk_init': retrieval of a principal's keys directly from the DCE Registry. This mechanism is available only internal to the DCE Security Server. 6.2.4. Private Key Module Interface A DCE Private Key Module Interface is provided to abstract and hide the underlying details of the private key storage mechanism. This interface is extensible to other acquisition mechanisms and for use by other protocols. The DCE Private Key Module Interface is not provided as an application API, but rather as a means for DCE vendors to supply alternative key storage mechanisms. The storage mechanisms provided with the reference implementation are: (a) `sec_psm_pkss_mechanism': storage using the Public Key Storage Server [RFC 94.0]. Anderson, Cuti Page 11 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 (b) `sec_psm_file_mechanism': storage using a local file. (c) `sec_psm_kdc_pk_init_mechanism': storage in the DCE Registry. This mechanism is available only internal to the DCE Security Server. 6.3. KDC Key Management The KDC requires a public key pair in order to support the OSF DCE Public Key Login protocol. While the KDC uses the `sec_psm' layer for accessing public key functions, it uses a `sec_pvtkey' mechanism that accesses the DCE Registry directly, both for security and for performance. This mechanism is only available within the `secd' binary image. 6.3.1. KDC Private and Public Key The KDC private key used for authentication (generating signatures) is stored in the DCE Registry. It is stored, protected, and propagated exactly as the DES symmetric KDC key is now stored, protected, and propagated, by the implementation of a new password type: `sec_passwd_pubkey', and by the extension of internal mechanisms for storage of keys. This new type is used within the DCE Registry, for propagation to DCE Registry replicas, and for the encoding of public key values inside ERAs. This new type may not be specified by Registry clients. The KDC public key used for authentication is stored in the `DCEPKAuthentication' ERA attached to the `krbtgt' principal for the cell. The DCE Registry sets or updates the KDC authentication public key key-pair when the password of the krbtgt principal is set to a keytype of `sec_passwd_genprivkey'. It uses the `modulus_size' parameter in the keytype to determine what modulus size to use. The `dcecp> account modify krbtgt/ -pkgenprivkey ' user interface can be used by a cell administrator to set the KDC's key to a keytype of `sec_passwd_genprivkey'. 6.3.2. KDC Public Key Caching During login, a principal needs an authenticated copy of the public key of the local KDC in order to verify that the TGT it obtains is from the correct KDC. However, the principal is not yet authenticated, and so is unable to obtain an authenticated copy of an ERA. Since the `dced' daemon is authenticated (as the client host principal), we make use of this to obtain an authenticated copy of the KDC public key. Anderson, Cuti Page 12 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 The daemon, via the `rsec_pk_cache_kdc_key' remote interface, supports client requests for updates or additions to a local cache of KDC public authentication keys. It retrieves the authentication public key of a cell's KDC from the `DCEPKAuthentication' ERA attached to the `krbtgt' principal for the cell, and writes it to the file `/etc/opt/dce/security/kdc_pk_auth//.key' in ASN.1 DER encoding. The `sec_login' APIs retrieve required public keys of local or foreign KDCs from the cache file for the cell. If a required KDC key file is not found, or if a KDC key fails to decrypt the reply from the KDC successfully, `sec_login' asks the local `dced' daemon to obtain or refresh the required key. 6.4. Public Key Policy Control The modulus length of the KDC authentication public key is determined by the value of the `-pkgenprivkey' parameter to the `dcecp> account modify krbtgt/' command. By default, only the cell administrator is authorized to modify this account. Public keys may be revoked by removing the `DCEPKKeyEncipherment' and `DCEPKAuthentication' ERA instances from the principal. Usage of the public key login protocol can be mandated by attaching a `pre_auth_req' ERA with a value of `PADATA_ENC_PUBLIC_KEY' to a principal. See "Changes to existing TGT acquisition protocols" under the "TGT Acquisition Protocol" sub-section under "FUNCTIONAL DEFINITION", and "Configuring Public Key Login Users" under "MANAGEMENT INTERFACES". Except as stated above, there is no specified or supported policy control for public keys (such as control of lifetime, expiration, or modulus length) included as part of this project. 6.5. Passwords During login operations, including `dce_login' and `dcecp> login', the string entered as the `password' value is used first as a `passphrase' in an attempt to access the `PSM'. If this fails, and the user is not identified as requiring use of the public key authentication protocol, then the string is used as a DCE shared- secret `password'. Except for login operations, the `dcecp -password' option always refers to a user's DCE shared-secret `password', while the `oldpassphrase' and `newpassphrase' options always refer to a user's `PSM' `passphrase'. A user's `PSM' `passphrase' values may or may not match the DCE shared-secret `password' value. Anderson, Cuti Page 13 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 7. DATA STRUCTURES 7.1. Public Key Login Base Types The common base definitions for the DCE Public Key Login APIs are defined in three new files `security/idl/sec_pk_base.idl', `security/h/sec_pk.h', and `security/h/sec_psm_base.h', listed here: 7.1.1. `security/idl/sec_pk_base.idl' /* * @OSF_COPYRIGHT@ * COPYRIGHT NOTICE * Copyright (c) 1990, 1991, 1992, 1993, 1996 Open Software * Foundation, Inc. * ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE * in the src directory for the full copyright text. */ /* ** Copyright (c) Hewlett-Packard Company 1996 ** Unpublished work. All Rights Reserved. ** ** Public Key Base Definitions */ interface sec_pk_base { /* s e c _ p k _ d o m a i n _ t * * A UUID associated with the application domain * in which a public or private key is used. */ typedef uuid_t sec_pk_domain_t; /* s e c _ p k _ u s a g e _ f l a g s _ t * * A set of key usage flags indicating the uses for * a key or key-pair. * * These correspond to KeyUsage types defined in * DAM 1 (Dec 1995) to X.509 (1993) */ typedef unsigned32 sec_pk_usage_flags_t; const unsigned32 sec_pk_usage_digitalSignature = 0x1; const unsigned32 sec_pk_usage_nonRepudiation = 0x2; const unsigned32 sec_pk_usage_keyEncipherment = 0x4; const unsigned32 sec_pk_usage_dataEncipherment = 0x8; const unsigned32 sec_pk_usage_keyAgreement = 0x10; const unsigned32 sec_pk_usage_keyCertSign = 0x20; const unsigned32 sec_pk_usage_offLineCRLSign = 0x40; Anderson, Cuti Page 14 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 const unsigned32 MAX_USAGES = 7; /* s e c _ p k _ d a t a _ t * * A structure pointing to an X.509 or X.511 * ASN.1 DER-encoded value. * * Rather than using this structure directly, users * should use one of the types that follow, which * indicate the type of information contained in the * particular structure instance. */ typedef struct{ unsigned32 len; [ptr, size_is(len)] byte *data; } sec_pk_data_t; /* s e c _ p k _ d a t a _ p _ t * * A pointer to a sec_pk_data_t * structure */ typedef [ptr] sec_pk_data_t *sec_pk_data_p_t; /* s e c _ p k _ g e n _ d a t a _ t * * A sec_pk_data_t structure containing len and data which are * parallel to sec_pk_data_t structure to hold * non-ASN.1 DER-encoded data, such as plaintext or ciphertext. */ typedef sec_pk_data_t sec_pk_gen_data_t; /* s e c _ p k _ p u b k e y _ t * * A sec_pk_data_t structure containing an X.509 * ASN.1 DER-encoded value of type * SubjectPublicKeyInfo * * The vendor's public key infrastructure is assumed * to provide functions for generating a public key * in this format. * * In the reference implementation, the BSAFE library * provides such a function. */ typedef sec_pk_data_t sec_pk_pubkey_t; /* s e c _ p k _ p u b k e y _ p _ t Anderson, Cuti Page 15 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * * A pointer to a sec_pk_pubkey_t structure */ typedef [ptr] sec_pk_pubkey_t *sec_pk_pubkey_p_t; /* s e c _ p k _ p v t k e y _ t * * A sec_pk_data_t structure containing an ASN.1 * DER-encoded private key value. The * format will depend on the public key infrastructure. * * In the reference implementation, the structure will * contain a PKCS#8 private key of type PrivateKeyInfo. * * The vendor's public key infrastructure is assumed * to provide functions for generating a private key * in this format. */ typedef sec_pk_data_t sec_pk_pvtkey_t; /* s e c _ p k _ p v t k e y _ p _ t * * A pointer to a sec_pk_pvtkey_t structure */ typedef [ptr] sec_pk_pvtkey_t *sec_pk_pvtkey_p_t; /* s e c _ p k _ s i g n e d _ t * * A sec_pk_data_t structure containing an X.509 * ASN.1 DER-encoded value of type * SIGNED. * * The vendor's public key infrastructure is assumed * to provide functions for generating signed data * in this format. * * In the reference implementation, the BSAFE library * provides such a function. */ typedef sec_pk_data_t sec_pk_signed_t; /* s e c _ p k _ s i g n e d _ p _ t * * A pointer to a sec_pk_signed_t structure */ typedef [ptr] sec_pk_signed_t *sec_pk_signed_p_t; /* s e c _ p k _ e n c r y p t e d _ t Anderson, Cuti Page 16 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * * A sec_pk_data_t structure containing an X.509 * ASN.1 DER-encoded value of type * ENCRYPTED. * * The vendor's public key infrastructure is assumed * to provide functions for generating encrypted data * in this format. * * In the reference implementation, the BSAFE library * provides such a function. */ typedef sec_pk_data_t sec_pk_encrypted_t; /* s e c _ p k _ e n c r y p t e d _ p _ t * * A pointer to a sec_pk_encrypted_t structure */ typedef [ptr] sec_pk_encrypted_t *sec_pk_encrypted_p_t; /* s e c _ p k _ a l g o r i t h m _ i d _ t * * A sec_pk_data_t structure containing an X.509 * ASN.1 DER-encoded value of type * AlgorithmIdentifier. * * The vendor's public key infrastructure is assumed * to provide functions for providing * this format. * * In the reference implementation, the BSAFE library * provides such a function. */ typedef sec_pk_data_t sec_pk_algorithm_id_t; /* s e c _ p k _ a l g o r i t h m _ i d _ p _ t * * A pointer to a sec_pk_algorithm_id_t structure */ typedef [ptr] sec_pk_algorithm_id_t *sec_pk_algorithm_id_p_t; } 7.1.2. `security/h/sec_pk.h' /* * @OSF_COPYRIGHT@ * COPYRIGHT NOTICE * Copyright (c) 1996 Open Software Foundation, Inc. * ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE * in the src directory for the full copyright text. */ Anderson, Cuti Page 17 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 /* * Copyright (c) Hewlett-Packard Company 1996 * Unpublished work. All Rights Reserved. */ #ifndef _SEC_PK_H_ #define _SEC_PK_H_ #include #include #include #include /* The following sec_pk_domain_t UUIDs are * architectural. They cannot be changed without * destroying interoperability. */ /* sec_pk_domain_dce_general: for use by * authenticated clients in retrieving and storing * public and private keys */ extern uuid_t sec_pk_domain_dce_general; /* ae991638-5cbe-11cf-a22d-08000919ebb5 */ /* sec_pk_domain_kdc_cache: for use by * unauthenticated clients in retrieving the * public key of a krbtgt principal from the * dced-maintained krbtgt key cache. */ extern uuid_t sec_pk_domain_kdc_cache; /* e925f8b4-0a3a-11d0-94f1-08000919ebb5 */ /* sec_pk_domain_pk_kdc_cache_refresh: for use by * unauthenticated clients in retrieving a * refreshed cache copy of the public key of a * krbtgt principal. */ extern uuid_t sec_pk_domain_kdc_cache_refresh; /* f087b8e0-0a3a-11d0-9113-08000919ebb5 */ /* sec_pk_domain_kdc_pk_init: for use by the KDC * in performing sec_psm operations using its own * private key. */ extern uuid_t sec_pk_domain_kdc_pk_init; /* 7d2d9810-e721-11cf-9021-08000919ebb5 */ /* UUIDs of DCE public key-related ERAs * */ Anderson, Cuti Page 18 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 /* DCEPKAuthentication_id: UUID of the * DCEPKAuthentication ERA, used to hold a * principal's sec_pk_usage_digitalSignature * Public Key for use in the DCE Public Key Login * protocol */ extern uuid_t DCEPKAuthentication_id; /* d44dc60e-6230-11cf-98ed-08000919ebb5 */ /* DCEPKKeyEncipherment_id: UUID of the * DCEPKKeyEncipherment ERA, used to hold a * principal's sec_pk_usage_keyEncipherment Public * Key for use in the DCE Public Key Login * protocol */ extern uuid_t DCEPKKeyEncipherment_id; /* 76251f8c-6230-11cf-af89-08000919ebb5 */ /* DCEPKPrivateKeyStorage_id: UUID of the * DCEPKPrivateKeyStorage ERA, used to associate * a principal with a private key storage mechanism. * The UUIDs of the mechanisms themselves are contained in * file sec_psm_base.h */ extern uuid_t DCEPKPrivateKeyStorage_id; /* 1f79c78e-b026-11cf-b7c8-0800090a5254 */ /* Following format is used in the header of a public * or private key keyfile. A PK keyfile is used both * by the dced in caching the public keys of krbtgt * principals, and also by dcecp in reading public * or private key values from a file supplied by * the user. * * The values used in the header are defined in * sec_pk.c */ typedef struct { char keyfile_id[4]; unsigned32 keyfile_fmt_ver; } sec_pk_keyfile_hdr_t; extern const sec_pk_keyfile_hdr_t sec_pk_keyfile_hdr; #define DCEPKKEYFILE_ID sec_pk_keyfile_hdr.keyfile_id; #define DCEPKKEYFILE_VER sec_pk_keyfile_hdr.keyfile_fmt_ver; /* s e c _ p k _ d a t a _ i n i t * * Initializes sec_pk_data_t or its type-specific variants. * * In Parameters: Anderson, Cuti Page 19 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * data_p - pointer to a sec_pk_data_t * that is to be initialized. * data_p is returned * with data_p->len set to 0 and * data_p->data set to NULL. * * Errors: none. */ #define sec_pk_data_init(data_p) \ do { sec_pk_data_t *__d = \ (data_p); __d->data = NULL; __d->len = 0; } \ while (0) /* s e c _ p k _ d a t a _ c r e a t e * * Copies data to a sec_pk_data_t or its type-specific variants. * * In Parameters: * data, len * pointer to, and length of, memory to be copied * Out Parameters: * data_out_p - pointer to a sec_pk_data_t * that receives a pointer to the copied data. * * Errors: * error_status_ok - success * sec_pk_e_no_memory - malloc failed */ error_status_t sec_pk_data_create ( unsigned8 *data, /* [in] */ size_t len, /* [in] */ sec_pk_data_t *data_out_p /* [out] */ ); /* s e c _ p k _ d a t a _ c o p y * * Copies a sec_pk_data_t or its type-specific variants. * * In Parameters: * data_in_p - pointer to a sec_pk_data_t * that points to the memory to be copied * Out Parameters: * data_out_p - pointer to a sec_pk_data_t * which receives a pointer to the copied data. * * Errors: * error_status_ok - success * sec_pk_e_no_memory - malloc failed */ error_status_t sec_pk_data_copy ( Anderson, Cuti Page 20 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 sec_pk_data_t *data_in_p, /* [in] */ sec_pk_data_t *data_out_p /* [out] */ ); /* s e c _ p k _ d a t a _ f r e e * * Frees memory associated with data of type * sec_pk_data_t or its type-specific variants. * * In Parameters: * data_p - pointer to a sec_pk_data_t * that points to the memory * to be reclaimed. * data_p is returned * with data_p->data set to NULL and * data_p->len set to 0. * * Errors: None */ void sec_pk_data_free ( sec_pk_data_t *data_p /* [in,out] */ ); /* s e c _ p k _ d a t a _ z e r o _ a n d _ f r e e * * Zeroes out, then frees memory associated with data * of type sec_pk_data_t or its type-specific variants. * * This function, rather than sec_pk_data_free, should * be called for structures containing private or * secret keys. * * In Parameters: * data_p - pointer to a sec_pk_data_t * that points to the memory * to be reclaimed. * data_p is returned with * data_p->data set to NULL, * and data_p->len set to 0. * * Errors: none */ void sec_pk_data_zero_and_free ( sec_pk_data_t *data_p /* [in,out] */ ); /* sec_pk_get_key_usage_count * * In Parameters: Anderson, Cuti Page 21 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * key_usages - a value of type sec_pk_usage_flags_t * containing key usage flag settings * Return value: * integer count of the number of key usage * flags set in key_usages * * Errors: none * extern int sec_pk_get_key_usage_count( sec_pk_usage_flags_t key_usages ); /* s e c _ p k _ a t t r _ w r i t e _ s e t u p * * Function: * Set up an attribute value with public key data * for call to rs_attr_update() * -sets attr->attr_id to id * -IDL-encodes the public key data as a * sec_passwd_rec_t of type sec_passwd_pubkey * -allocates attr->attr_value.tagged_union.bytes * -copies IDL-encoded public key data to * tagged_union.bytes->data * * In Parameters: * alloc - allocator (e.g. malloc or rpc_ss_allocate) * dealloc - deallocator (e.g. free or rpc_ss_free) * attr - pointer to an attribute to be set up * id - UUID of attribute to be written * kvno - pointer to key version number to be * written; must not be 0! * pk_data_p - pointer to a sec_pk_data_t * containing the key value to * be written as an attribute * Errors: * error_status_ok * sec_pk_e_no_memory - malloc failed * sec_pk_e_no_key_value - input pk_data is empty * sec_pk_e_key_vers_unsupported - input kvno is * NULL, < 0, or > 255 * Errors passed through from: * sec_pwd_encode() */ error_status_t sec_pk_attr_write_setup( idl_void_p_t (*alloc)(idl_size_t size), void (*dealloc)(idl_void_p_t ptr), sec_attr_t *attr, uuid_t id, unsigned32 *kvno, sec_pk_data_t *pk_data_p Anderson, Cuti Page 22 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 ); #endif 7.1.3. `security/h/sec_psm_base.h' /* * @OSF_COPYRIGHT@ * COPYRIGHT NOTICE * Copyright (c) 1996 Open Software Foundation, Inc. * ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE * in the src directory for the full copyright text. */ /* * Copyright (c) Hewlett-Packard Company 1996 * Unpublished work. All Rights Reserved. */ #ifndef _SEC_PSM_BASE_H_ #define _SEC_PSM_BASE_H_ /* The following private key storage mechanism are * architectural. They cannot be changed without * destroying interoperability. * * The UUIDs are defined in sec_psm.c */ extern uuid_t sec_psm_pkss_mechanism; /* 72053e72-b01a-11cf-8bf5-0800090a5254 */ extern uuid_t sec_psm_file_mechanism; /* 8687c5b8-b01a-11cf-b137-0800090a5254 */ extern uuid_t sec_psm_kdc_pk_init_mechanism; /* adb48ed4-e94d-11cf-ab4b-08000919ebb5 */ extern sec_pk_algorithm_id_t rsa_pkcs; extern sec_pk_algorithm_id_t md5_rsa; extern sec_pk_algorithm_id_t rsa_enc; #define RSA_PKCS &rsa_pkcs #define MD5RSA &md5_rsa #define RSAENC &rsa_enc #endif Anderson, Cuti Page 23 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 7.2. Password types In order to allow a cell administrator to request the KDC to update its authentication public key key-pair, two new password types are added to the existing `sec_passwd_type_t' `enum', and definitions are added to the existing `sec_passwd_rec_t' structure. These modified types are specified in the file `security/idl/passwd.idl', listed here: /* * @OSF_COPYRIGHT@ * COPYRIGHT NOTICE * Copyright (c) 1990, 1991, 1992, 1993, 1996 Open Software * Foundation, Inc. * ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE * in the src directory for the full copyright text. */ /* ** Copyright (c) Hewlett-Packard Company 1991, 1993, 1996 ** Unpublished work. All Rights Reserved. ** */ /* * User Registry - Base password datatypes */ interface passwd { import "dce/sec_base.idl"; import "dce/sec_pk_base.idl"; const unsigned32 sec_passwd_c_des_key_size = 8; typedef byte sec_passwd_des_key_t[sec_passwd_c_des_key_size]; const unsigned32 sec_passwd_str_max_len = 512; const unsigned32 sec_passwd_str_t_size = 513; typedef [string] char sec_passwd_str_t[sec_passwd_str_t_size]; /* BSAFE1.2.1 limits modulus to 1024 bits, but we will support * up to 4096 bits. Public key is stored with private key. The * extra 384 bytes of structure is accurate for BSAFE1.2.1, but * may not be sufficient for revisions supporting larger moduli. * This value should be checked if new BSAFE (or other RSA * encryption implementation) is used. */ const unsigned32 sec_passwd_c_max_pk_modulus = 4096; /*bits*/ Anderson, Cuti Page 24 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 const unsigned32 sec_passwd_c_max_pk_overhead = 384; /*bytes*/ const unsigned32 sec_passwd_c_max_pk_key_size = \ (2*sec_passwd_c_max_pk_modulus/8) \ + sec_passwd_c_max_pk_overhead; /* currently supported key types */ typedef enum { sec_passwd_none, sec_passwd_plain, sec_passwd_des, sec_passwd_pubkey, sec_passwd_genprivkey } sec_passwd_type_t; typedef struct { sec_passwd_version_t version_number; [string, ptr] char *pepper; union switch (sec_passwd_type_t key_type) { case sec_passwd_plain: [string, ptr] char *plain; case sec_passwd_des: sec_passwd_des_key_t des_key; case sec_passwd_pubkey: sec_pk_data_t pub_key; case sec_passwd_genprivkey: unsigned32 modulus_size; } key; } sec_passwd_rec_t; } 7.3. pre_auth_req ERA The existing `pre_auth_req' ERA is extended by the addition of one more value. The semantics remain consistent: pre-authentication protocols associated with values lower than the value of the `pre_auth_req' ERA are rejected by the KDC. Attribute Name: pre_auth_req Attribute UUID: 6c9d0ec8-dd2d-11cc-abdd-080009353559 Attribute Encoding: sec_attr_enc_integer ACL Manager Type: 06ab9320-0191-11ca-a9e8-08001e039d7d Query Permissions Set: sec_acl_perm_mgmt_info, Update Permissions Set: sec_acl_perm_mgmt_info Anderson, Cuti Page 25 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 Test Permissions Set: sec_acl_perm_mgmt_info Delete Permissions Set: sec_acl_perm_mgmt_info Unique: TRUE Reserved: TRUE Intercell Action: REJECT Trigger Type: NONE Trigger Binding: NULL Scope: "" Multi-valued: FALSE Comment: "values: {0=NONE, 1=PADATA_ENC_TIMESTAMPS, 2=PADATA_ENC_THIRD_PARTY, 3=PADATA_ENC_PUBLIC_KEY}" 7.4. DCEPKKeyEncipherment ERA The `DCEPKKeyEncipherment' ERA is a reserved ERA that may be attached to any principal object to hold the public key used in the DCE authentication protocol to encrypt DCE session (conversation) keys for that principal. The format of the `DCEPKKeyEncipherment' ERA is an IDL-encoded byte- string of type `sec_passwd_rec_t' with key type `sec_passwd_pubkey'. Attribute Name: DCEPKKeyEncipherment Attribute UUID: 76251f8c-6230-11cf-af89-08000919ebb5 Attribute Encoding: sec_attr_enc_bytes ACL Manager Type: 06ab9320-0191-11ca-a9e8-08001e039d7d Query Permissions Set: sec_acl_perm_read Update Permissions Set: sec_acl_perm_mgmt_info Test Permissions Set: sec_acl_perm_read Delete Permissions Set: sec_acl_perm_mgmt_info Unique: TRUE Reserved: TRUE Intercell Action: ACCEPT Trigger Type: NONE Trigger Binding: NULL Scope: "" Multi-valued: FALSE Comment: "The principal's DCE key encryption public key value; an X.509 SubjectPublicKeyInfo value in ASN.1 DER format." 7.5. DCEPKAuthentication ERA The `DCEPKAuthentication' ERA is a reserved ERA that may be attached to any user principal to hold the public key used in the DCE authentication protocol to verify a signature from that user. The `DCEPKAuthentication' ERA attached to the cell's `krbtgt' principal is the public key used by the client to verify a signature from the DCE KDC during DCE authentication. The `DCEPKAuthentication' ERA attached to the client principal is the public key used by the KDC to verify a signature from the client during DCE authentication. Anderson, Cuti Page 26 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 The format of the `DCEPKKeyEncipherment' ERA is an IDL-encoded byte- string of type `sec_passwd_rec_t' with key type `sec_passwd_pubkey'. Attribute Name: DCEPKAuthentication Attribute UUID: d44dc60e-6230-11cf-98ed-08000919ebb5 Attribute Encoding: sec_attr_enc_bytes ACL Manager Type: 06ab9320-0191-11ca-a9e8-08001e039d7d Query Permissions Set: sec_acl_perm_read Update Permissions Set: sec_acl_perm_mgmt_info Test Permissions Set: sec_acl_perm_read Delete Permissions Set: sec_acl_perm_mgmt_info Unique: TRUE Reserved: TRUE Intercell Action: ACCEPT Trigger Type: NONE Trigger Binding: NULL Scope: "" Multi-valued: FALSE Comment: "The principal's DCE authentication public key value; an X.509 SubjectPublicKeyInfo value in ASN.1 DER format." 7.6. DCEPKPrivateKeyStorage ERA The `DCEPKPrivateKeyStorage' ERA is a reserved ERA that may be attached to any user principal to identify the private key storage mechanism of that user. The format of the `DCEPKPrivateKeyStorage' ERA is a UUID. Attribute Name: DCEPKPrivateKeyStorage Attribute UUID: 1f79c78e-b026-11cf-b7c8-0800090a5254 Attribute Encoding: sec_attr_enc_uuid ACL Manager Type: 06ab9320-0191-11ca-a9e8-08001e039d7d Query Permissions Set: sec_acl_perm_mgmt_info Update Permissions Set: sec_acl_perm_mgmt_info Test Permissions Set: sec_acl_perm_mgmt_info Delete Permissions Set: sec_acl_perm_mgmt_info Unique: TRUE Reserved: TRUE Intercell Action: Reject Trigger Type: NONE Trigger Binding: NULL Scope: "" Multi-valued: FALSE Comment: "Values: sec_psm_pkss_mechanism, sec_psm_file_mechanism, sec_psm_kdc_pk_init_mechanism" Anderson, Cuti Page 27 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 8. USER INTERFACES 8.1. Login User interfaces to login utilities have not changed, except that additional new error conditions may be reported. Login utilities such as `dce_login' invoke the existing `sec_login' API, which changes only by the addition of new error status values that can be returned. Login utilities still need to prompt for a user name and a password. The "password" that the user supplies is first tried by `sec_login' as a passphrase to access the user's Personal Security Module. If there is no Personal Security Module, or if the passphrase fails to unlock the module, the "password" is then tried automatically as a DCE password (unless the user is identified as requiring public key). See "TGT Acquisition Protocol" under "FUNCTIONAL DEFINITION" for more information. 8.2. Key Storage and Retrieval The existing `dcecp' user interface for reading and writing ERA values may be used to read or write the `DCEPKKeyEncipherment', `DCEPKAuthentication', `DCEPKPrivateKeyStorage', or `pre_auth_req' ERAs. The `DCEPKAuthentication' and `DCEPKKeyEncipherment' attributes must be IDL-encoded byte-strings of type `sec_passwd_rec_t' with key type `sec_passwd_pubkey'. New options for manipulating public and private key values are defined for the `dcecp> account create' and `dcecp> account modify' commands. These allow setting a principal's private key value in the Personal Security Module, and setting the corresponding public key value in the DCE Registry. There is no user interface provided for reading the value of a principal's private key. 8.2.1. Existing dcecp operations for public key Examples of accessing public key information using existing operations: dcecp> principal show -xattr {DCEPKAuthentication {30 81 9f 30 0d 06 09 2a 86 48 86 f7 0d \ 01 01 01 05 00 03 81 \ 8d 00 30 81 89 02 81 81 00 b3 b2 02 84 85 ea cf 0e b8 3e c6 \ 7f c2 16 ff ea 30 79 cf a2 20 2f c5 ea 43 dc e5 39 f1 01 d2 \ 50 52 7c 54 a9 2e 02 c3 8c 57 0c b5 46 b4 4b 0c 20 1d c6 66 \ Anderson, Cuti Page 28 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 6d 70 16 c2 d3 f2 39 0f 1a 3a 44 f1 ee 35 dd fb 16 77 e6 a7 \ 6c c6 86 ba f5 e9 a2 54 54 60 43 7a 2e cd dd 36 0d 8e 0a 03 \ 4f 12 22 95 ff e1 da 3e 25 b1 fb 0a ce f7 9d 95 a2 89 0b bd \ a6 9a c9 ec d7 c4 e4 4b 89 26 29 30 67 8f 14 89 b5 02 03 01 \ 00 01}} {DCEPKKeyEncipherment {30 81 9f 30 0d 06 09 2a 86 48 86 f7 0d \ 01 01 01 05 00 03 81 \ 8d 00 30 81 89 02 81 81 00 b2 c4 c2 b9 cd c3 9b 3b 8f 54 35 \ 88 fc 22 8e 39 cd 3d 25 99 62 87 f0 0c 00 b9 55 cd f4 a4 b5 \ 39 25 94 ee 23 5a 35 c6 da 2f 6f 5a a5 9a a3 b4 22 91 43 bf \ 68 3d e8 51 63 43 d0 56 ba c0 86 a3 b2 10 1d e0 05 7e 34 b8 \ 90 4a ed 06 88 ce 3e 52 08 ad 5a 2a ae 7c 3f 0a ce 3b 40 8f \ 03 48 79 7d bd 6e c2 7e 3d 37 5e 8a 63 ff e8 09 5b 93 ad 04 \ 12 ca d9 f2 2f 74 14 c6 c9 79 c5 34 cb 93 71 f9 5d 02 03 01 \ 00 01}} {DCEPKPrivateKeyStorage 8687c5b8-b01a-11cf-b137-0800090a5254} {pre_auth_req 3} dcecp> principal show krbtgt/ -xattr {DCEPKAuthentication {30 81 9f 30 0d 06 09 2a 86 48 86 f7 0d \ 01 01 01 05 00 03 81 \ 8d 00 30 81 89 02 81 81 00 c3 6d 50 5f 28 da 55 e1 fb 94 ac \ 2a 29 16 44 bd 62 d0 61 c5 e1 cd f2 a1 3a f6 1c e7 40 11 0a \ 4d eb 80 38 5a b7 1b bf 25 ae 68 6b bc d7 ad 05 27 67 5b c3 \ bb f7 66 23 4b 59 a4 3f 9f 74 e1 a1 4a a5 9c 86 9c 23 58 b3 \ 3f a9 45 5d d5 e6 33 21 79 4d 86 dd 35 2f fb a2 f6 59 76 ec \ 06 b9 2d 5c 5c 75 61 c7 b4 ec 50 6d 30 02 6d d5 0a 45 ad 06 \ 54 4e 60 c4 f8 77 3b 6c da 58 5d 99 f6 37 cb cb 3d 02 03 01 \ 00 01}} {DCEPKPrivateKeyStorage adb48ed4-e94d-11cf-ab4b-08000919ebb5} dcecp> principal modify [ -add | -change ] \ {pre_auth_req 3} 8.2.2. New dcecp operations for public key New options have been added to `dcecp' to assist cell administrators in setting up accounts to use public key login. Syntax of new account create and modify options: Attribute name Value -------------- ----- -pkmechanism file | pkss -pksignatureusage {} -pkkeycipherusage {} pk_attributes Value ------------- ----- generatekey Integer: value "default" or desired modulus size privatekeyfile File system path to private key Anderson, Cuti Page 29 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 publickeyfile File system path to public key oldpassphrase Passphrase string newpassphrase Passphrase string The value of the `generatekey' option is the desired modulus size for the key. NOTE: In the reference implementation, the default value for generatekey, indicated by specifying the parameter value `default', is 1024. `{publickeyfile ...}' and `{privatekeyfile ...}' may not be used together with `{generatekey ...}'. `{publickeyfile ...}' and `{privatekeyfile ...}' must always be specified together: if you have one, you must have the other. The `{newpassphrase ...}' for the `-pksignatureusage' option must be the same as the `{newpassphrase ...}' for the `-pkkeycipherusage' option. Examples: 8.2.2.1. Setting up a public key account dcecp> account create pk_account -group none -organization none -password pk_pwd -mypwd -dce- -pkmechanism file -pksignatureusage { {generatekey default} {newpassphrase pk_pass} } -pkkeycipherusage { {generatekey 512} {newpassphrase pk_pass} } 8.2.2.2. Changing a key-pair obtained from an external source dcecp> account modify pk_account -pksignatureusage { {privatekeyfile /tmp/pk_account.sigkeypvt} {publickeyfile /tmp/pk_account.sigkeypub} {oldpassphrase pk_pass} } Anderson, Cuti Page 30 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 8.2.2.3. Changing passphrase on existing keys dcecp> account modify pk_account -pksignatureusage { {oldpassphrase pk_pass} {newpassphrase pk_pwd} } -pkkeycipherusage { {oldpassphrase pk_pass} {newpassphrase pk_pwd} } Key values obtained from an external source must be stored in a file with identifying header information. The `sec_pubkey_write_keyfile()' API may be used to write a key value to a file in the correct format. It is up to the user to ensure that public and private key values supplied to the user interfaces are consistent with each other and are valid public key key-pairs. 8.3. KDC Key Update In order to allow a cell administrator to update the public key pair of the DCE Security Server (KDC), a new `-pkgenprivkey' option to the `dcecp> account modify' command is provided. Example: dcecp -c account modify krbtgt/dc.cell.ch.hp.com -pkgenprivkey default This option is invalid except when used on the account of the `krbtgt' principal of the local cell. It is also invalid except when executed by a user having cell administrator privileges. The value of the `-pkgenprivkey' option is the desired modulus size of the key to be generated. It is recommended that KDC keys be at least 1024 bits long. NOTE: In the reference implementation, the default value for `-pkgenprivkey', indicated by specifying the parameter value `default', is 1024. 9. APIs and Interfaces Anderson, Cuti Page 31 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 9.1. DCE Personal Security Module Interface The interface to the DCE personal Security Module (`PSM') Interface is defined in a new file `security/idl/sec_psm.idl', listed here: /* * @OSF_COPYRIGHT@ * COPYRIGHT NOTICE * Copyright (c) 1996 Open Software Foundation, Inc. * ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE * in the src directory for the full copyright text. */ /* * Copyright (c) Hewlett-Packard Company 1996 * Unpublished work. All Rights Reserved. * * Personal Security Module (PSM) Interface * */ [ local ] interface sec_psm { import "dce/sec_pk_base.idl"; typedef void *sec_psm_handle_t; /* PSM API */ /* sec_psm_open * * Open the personal security mechanism using password. * * Return status * error_status_ok: Success. * other (non-zero): sec_pvtkey_privileged * sec_pvtkey_no_more_memory * sec_psm_no_more_memory * * Input * * name: Pointer to the user's canonical name within the * specified domain. * pwd: Pointer to the user's password. * domain_id: Pointer to the application domain the user * is operating on. Anderson, Cuti Page 32 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * * Output * * psm_handle: Pointer to an opaque handle to the personal * security context data. * */ error_status_t sec_psm_open( [in] void *name, [in] char *pwd, [in] sec_pk_domain_t *domain_id, [out] sec_psm_handle_t *psm_handle ); /* sec_psm_close * * Close the personal security mechanism and cleanup the * personal security context data. It also ensures any * confidential information such as passwords or private * key are zeroed. * * Return status * error_status_ok: Success. * other (non-zero): sec_psm_not_init * sec_psm_invalid_handle * sec_psm_internal_error * sec_pvtkey_invalid_handle * sec_pvtkey_mechanism_not_init * * Input * * psm_handle: Pointer to an opaque handle to the personal * security context data. This handle should be * obtained through sec_psm_open(). * */ error_status_t sec_psm_close( [in] sec_psm_handle_t psm_handle ); /* sec_psm_sign_data * * Compute the signature of the input data using the * signature algorithm specified in the arguments. * * The routine allocates memory for the data returned in * the signature parameter. Users should call * sec_pk_data_free() to deallocate that memory. Anderson, Cuti Page 33 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * * Return status * error_status_ok: Success. * other (non-zero): sec_psm_not_init * sec_psm_invalid_handle * sec_psm_unsupported_algorithm_id * sec_pvtkey_invalid_handle * sec_pvtkey_mechanism_not_init * sec_pvtkey_internal_error * sec_pvtkey_invalid_password * sec_pvtkey_multiple_key_usages * * Input * * psm_handle: Pointer to an opaque handle to the personal * security context data. This handle should be * obtained through sec_psm_open(). * signature_alg_id: The ASN.1 DER-encoded object ID of * the signature algorithm, such as * MD5WithRSAEncryption. * key_usage: The usage of the private key which should be * picked for this operation. * data: Pointer to the ASN.1 DER-encoded data to be signed. * * Output * * kvno: Key version number of the key used. * signature: Pointer to a signature buffer pointer. * */ error_status_t sec_psm_sign_data( [in] sec_psm_handle_t psm_handle, [in] sec_pk_algorithm_id_t *signature_alg_id, [in] sec_pk_usage_flags_t key_usage, [in] sec_pk_gen_data_t *data, [out] unsigned32 *kvno, [out] sec_pk_signed_t *signature ); /* sec_psm_verify_data * * Verify the data. Usually, you verify other people's signature. * * Return status * error_status_ok: Success. * other (non-zero): sec_psm_not_init * sec_psm_invalid_handle * sec_psm_unsupported_algorithm_id * sec_bsafe_decryption_failure Anderson, Cuti Page 34 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * sec_pk_e_domain_unsupported, * sec_pk_e_usage_unsupported, * sec_rgy_object_not_found, * sec_rgy_not_authorized, * sec_attr_unauthorized * * Input * * psm_handle: Pointer to an opaque handle to the personal * security context data. This handle should be * obtained through sec_psm_open(). * signer_domain: pointer to the application domain of the * principal; [see the sec_pubkey interface for more * details.] * signer_name: Pointer to the name of the principal which had * signedthe data. * kvno: Key version number of the key used. * signature_alg_id: The ASN.1 DER-encoded object ID of the * signature algorithm, such as MD5WithRSAEncryption. * key_usage: The usage of the ;public key which should be * picked for this operation. * data: Pointer to the data to be verified * signature: Pointer to the signature to be verified. * */ error_status_t sec_psm_verify_data( [in] sec_psm_handle_t psm_handle, [in] sec_pk_domain_t *signer_domain_id, [in] void *signer_name, [in] unsigned32 kvno, [in] sec_pk_algorithm_id_t *signature_alg_id, [in] sec_pk_usage_flags_t key_usage, [in] sec_pk_gen_data_t *data, [in] sec_pk_signed_t *signature ); /* sec_psm_encrypt_data * * Encrypt the data in the algorithm specified. The routine * allocates memory for the data returned in the cipher_data * parameter. Users should call sec_pk_data_free() to * deallocate that memory. * * For reference implementation, only keyEncipherment key_usage * will be implemented. * * Usually you encrypt the data with other's public key. * * Return status Anderson, Cuti Page 35 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * error_status_ok: Success. * other (non-zero): sec_psm_not_init * sec_psm_invalid_handle * sec_psm_unsupported_algorithm_id * sec_pk_e_domain_unsupported, * sec_pk_e_usage_unsupported, * sec_rgy_object_not_found, * sec_rgy_not_authorized, * sec_attr_unauthorized * * Input * * psm_handle: Pointer to an opaque handle to the personal * security context data. This handle should be * obtained through sec_psm_open(). * encryptee_domain: pointer to the application domain * of the principal; * [see the sec_pubkey interface for more details.] * encryptee_name: Pointer to the name of the principal this * data is encrypted for. * encryption_alg_id: The ASN.1 DER-encoded object ID of * encryption algorithm, such as RSA. * key_usage: The usage of the public key this key pair * belongs to. * clear_data: Pointer to the ASN.1 DER-encoded data to be * encrypted. * * Input, output * * kvno: Key version number of the key used. * * Output * * cipher_data: Pointer to the encrypted output buffer. */ error_status_t sec_psm_encrypt_data( [in] sec_psm_handle_t psm_handle, [in] sec_pk_domain_t *encryptee_domain, [in] void *encryptee_name, [in,out] unsigned32 *kvno, [in] sec_pk_algorithm_id_t *encryption_alg_id, [in] sec_pk_usage_flags_t key_usage, [in] sec_pk_gen_data_t *clear_data, [out] sec_pk_encrypted_t *cipher_data ); /* sec_psm_decrypt_data * * Decrypt the mechanism-specific encrypted data. The routine * allocates memory for the data returned in the clear_data Anderson, Cuti Page 36 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * parameter. Users should call sec_pk_data_free() to * deallocate that memory. * * For reference implementation, only keyEncipherment key_usage * will be implemented. * * Usually you decrypted the data with your own private key. * * Return status * error_status_ok: Success. * other (non-zero): sec_psm_not_init * sec_psm_invalid_handle * sec_psm_unsupported_algorithm_id * sec_bsafe_encryption_failure * sec_pvtkey_invalid_handle * sec_pvtkey_mechanism_not_init * sec_pvtkey_internal_error * sec_pvtkey_invalid_password * sec_pvtkey_multiple_key_usages * * Input * * psm_handle: Pointer to an opaque handle to the personal * security context data. This handle should be * obtained through sec_psm_open(). * kvno: Key version number of the key used. * encryption_alg_id: The ASN.1 DER-encoded object ID of * encryption algorithm, such as RSA. * key_usage: The usage of the private key which should be * picked for this operation. * cipher_data: Pointer to encrypted cipher buffer. * * Output * * clear_data: Pointer to decrypted clear text * buffer pointer. */ error_status_t sec_psm_decrypt_data( [in] sec_psm_handle_t psm_handle, [in] unsigned32 kvno, [in] sec_pk_algorithm_id_t *encryption_alg_id, [in] sec_pk_usage_flags_t key_usage, [in] sec_pk_encrypted_t *cipher_data, [out] sec_pk_gen_data_t *clear_data ); /* sec_psm_gen_pub_key * * Generate public key according to key type. The routine Anderson, Cuti Page 37 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * allocates memory for the data returned in the key * parameters. Users should call sec_pk_data_free() to * deallocate that memory. * * Currently it only supports RSADSI's public key. * * Return status * error_status_ok: Success. * other (non-zero): sec_psm_wrong_pub_key_type * sec_bsafe_alloc * * Input * * key_type: Only RSA_PKCS is supported. * * modulus_bit_size: Desired key-length. The length of the * desired key. Interpretation of this * parameter is algorithm-dependent; For RSA, * it shall be interpreted as the bit-length of * the key. * * Output * * private_key: Pointer to the encoded private key structure of * the newly-generated key. * public_key: Pointer to the encoded public key structure of the * newly-generated key. * */ error_status_t sec_psm_gen_pub_key( [in] sec_pk_algorithm_id_t *key_type, [in] unsigned32 modulus_bit_size, [in] sec_pk_gen_data_t *seed, [out] sec_pk_data_t *public_key, [out] sec_pk_data_t *private_key ); /* ADMINISTRATIVE INTERFACES */ /* sec_psm_put_pub_key * * Store the public key pair with associated data into the personal * security mechanism. * * Return status * error_status_ok: Success. * other (non-zero): sec_psm_not_init * sec_psm_invalid_handle * sec_pk_e_domain_unsupported, * sec_pk_e_usage_unsupported, Anderson, Cuti Page 38 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * sec_rgy_object_not_found, * sec_rgy_not_authorized, * sec_attr_unauthorized * sec_pvtkey_invalid_handle * sec_pvtkey_mechanism_not_init * sec_pvtkey_no_more_memory * sec_pvtkey_internal_error * sec_pvtkey_same_domain_and_usage_key_already_exists. * * Input * * psm_handle: Pointer to an opaque handle to the personal * security context data. This handle should be * obtained through sec_psm_open(). * pwd: Pointer to the user's password. * key_usage: The usage of the public key this key pair * belongs to. * pvtkey: Pointer to the ASN.1 DER-encoded private key buffer. * pubkey: Pointer to the ASN.1 DER-encoded public key buffer. * */ error_status_t sec_psm_put_pub_key( [in] sec_psm_handle_t psm_handle, [in] char *pwd, [in] sec_pk_usage_flags_t key_usage, [in] sec_pk_pubkey_t *public_key, [in] sec_pk_pvtkey_t *private_key ); /* sec_psm_update_pub_key * * Update the user's own public key pair or passphrase. The * oldpassphrase is specified to authenticate the user updating the * key. * * In the reference implementation, only a single version of a key * with a given key usage will be maintained. Any old key version * will be overwritten. * * Return status * error_status_ok: Success. * other (non-zero): sec_psm_not_init * sec_psm_invalid_handle * sec_pk_e_domain_unsupported, * sec_pk_e_usage_unsupported, * sec_rgy_object_not_found, * sec_rgy_not_authorized, * sec_attr_unauthorized * sec_pvtkey_invalid_handle * sec_pvtkey_mechanism_not_init Anderson, Cuti Page 39 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * sec_pvtkey_private_key_is_not_supplied * sec_pvtkey_new_password_required * sec_pvtkey_no_more_memory * sec_pvtkey_internal_error * sec_pvtkey_no_matched_private_key * sec_pvtkey_Invalid_password. * * Input * * psm_handle: Pointer to an opaque handle to the personal * security context data. This handle should be * obtained through sec_psm_open(). * oldpwd: Pointer to the user's current password. * newpwd: Pointer to the user's new password. * key_usage: The usage of the public key this key pair * belongs to. * pvtkey: Pointer to the ASN.1 DER-encoded private key buffer. * pubkey: Pointer to the ASN.1 DER-encoded public key buffer. * */ error_status_t sec_psm_update_pub_key( [in] sec_psm_handle_t psm_handle, [in] char *oldpwd, [in] char *newpwd, [in] sec_pk_usage_flags_t key_usage, [in] sec_pk_pubkey_t *public_key, [in] sec_pk_pvtkey_t *private_key ); } 9.2. DCE Public Key Module API The interface to the DCE Public Key Module API is defined in a new file `security/idl/sec_pubkey.idl', listed here: /* * @OSF_COPYRIGHT@ * COPYRIGHT NOTICE * Copyright (c) 1996 Open Software Foundation, Inc. * ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE * for the full copyright text. */ /* ** Copyright (c) Hewlett-Packard Company 1996 ** Unpublished work. All Rights Reserved. ** ** Public Key Storage and Retrieval Interface */ Anderson, Cuti Page 40 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 [ local ] interface sec_pubkey { import "dce/rgynbase.idl"; import "dce/sec_pk_base.idl"; typedef error_status_t (*sec_pk_key_retrieval_fn_t)( [in] void *principal, [in] sec_pk_domain_t *domain, [in] sec_pk_usage_flags_t usage, [in,out] unsigned32 *kvno, [out] sec_pk_pubkey_t *pubkey_p ); typedef error_status_t (*sec_pk_key_storage_fn_t)( [in] void *principal, [in] sec_pk_domain_t *domain, [in] sec_pk_usage_flags_t usage, [in,out] unsigned32 *kvno, [in] sec_pk_pubkey_t *pubkey_p ); typedef struct { sec_pk_domain_t domain; sec_pk_key_retrieval_fn_t r; sec_pk_key_storage_fn_t s; } sec_pk_domain_def; /* * s e c _ p u b k e y _ d e f i n e _ d o m a i n * * Define a public key storage domain. * * This extends the set of domains supported by the other * sec_pubkey functions within the current process. * * This is used to define "new" domains within the KDC * and within the pk-init client which fetch public keys directly * from known trusted sources. * * domain -- the new domain to define. * * retrieve -- pointer to a function which retrieves a public key, * or NULL if retrievals are not possible in this domain. * * store -- pointer to a function which stores a public key, * or NULL if storage is not possible in this domain. Anderson, Cuti Page 41 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 */ error_status_t sec_pubkey_define_domain ( sec_pk_domain_t *domain, sec_pk_key_retrieval_fn_t retrieve, sec_pk_key_retrieval_fn_t store ); /* * s e c _ p u b k e y _ f i n d _ d o m a i n * * find the functions implementing a public key storage domain. * * domain -- the domain to find. * * Returns NULL if domain is not implemented. */ sec_pk_domain_def *sec_pubkey_find_domain( sec_pk_domain_t *domain ); /* PUBLIC KEY STORAGE AND RETRIEVAL OPERATIONS * * These interfaces are used within the sec_psm interface, * and the sec_login interface, but may also be used * directly by user applications. * */ /* s e c _ p u b k e y _ s t o r e * * Function: * Store a public key value for a principal * * Stores an X.509 DER-encoded public key value of type * SubjectPublicKeyInfo in the public key storage * facility. This operation overwrites any * existing public key storage for , and * creates public key storage if none exists. * * In the reference implementation: * - only the sec_pk_domain_dce_pk_login domain * supports the sec_pubkey_store operation * - usage must be either sec_pk_usage_digitalSignature, * sec_pk_usage_keyEncipherment, or both. * - If usage is sec_pk_usage_digitalSignature the public * key is stored in the DCEPKAuthentication ERA attached * to the principal. * - If usage is sec_pk_usage_keyEncipherment, the public key is * stored in the DCEPKKeyEncipherment ERA. * * Default ACLs for the reference implementation on the Anderson, Cuti Page 42 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * underlying ERA storage locations will allow only a * principal with sec_admin privileges to perform * this operation. Sites may choose to modify the ACLs * on the underlying ERAs to allow the owner principal * to modify the public key as well, although sites * should be aware that ability to modify a principal's * public key equates to the ability to impersonate the * principal. * * In Parameters: * principal - the canonical name in the specified * domain of the principal whose public * key is being stored (sec_rgy_name_t * containing /.../cell/principal in * reference implementation) * domain - a UUID identifying the domain in which * the key is used * (sec_pk_domain_dce_pk_login in * reference implementation) * usage - usage(s) of the key being stored * (sec_pk_usage_digitalSignature, * sec_pk_usage_keyEncipherment, or both * in reference implementation) * kvno - key version; if 0, * retrieves newest version. * pubkey_p - pointer to an X.509 DER-encoded public key * value of type SubjectPublicKeyInfo * * Out Parameters: * None * * Errors: * error_status_ok * sec_pk_e_domain_unsupported, * sec_pk_e_usage_unsupported, * sec_pk_e_key_vers_unsupported * sec_pk_e_no_memory * * Errors passed through from: * uuid_equal * sec_rgy_attr_update */ error_status_t sec_pubkey_store ( [in] void *principal, [in] sec_pk_domain_t *domain, [in] sec_pk_usage_flags_t usage, [in,out] unsigned32 *kvno, [in] sec_pk_pubkey_t *pubkey_p ); /* s e c _ p u b k e y _ r e t r i e v e Anderson, Cuti Page 43 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * * Function: * Retrieves an X.509 DER-encoded public key value with * type SubjectPublicKeyInfo from the public key * storage facility for a given principal. * * In the reference implementation: * - usage must be either sec_pk_usage_digitalSignature or * sec_pk_usage_keyEncipherment * - If usage is sec_pk_usage_digitalSignature the * public key is retrieved from the * DCEPKAuthentication ERA attached to the * principal. * - If usage is sec_pk_usage_keyEncipherment, the * public key is retrieved from the * DCEPKKeyEncipherment ERA. * * Default ACLs for the reference implementation allow * any principal to perform this operation. * * In Parameters: * principal - the canonical name in the specified * domain of the principal whose public * key is being retrieved * (sec_rgy_name_t in reference * implementation) * domain - a UUID identifying the domain in which * the key is used * usage - usage of the key being retrieved * (sec_pk_usage_digitalSignature, or * sec_pk_usage_keyEncipherment, but not * both, in reference implementation) * kvno - key version to be retrieved; if 0, * retrieves newest version. * * Out Parameters: * pubkey_p - pointer to an X.509 DER-encoded * public key value of type * SubjectPublicKeyInfo; storage for this * structure must be freed using the * sec_pk_data_free() function. * * Errors: * error_status_ok * sec_pk_e_key_vers_unsupported * sec_pk_e_usage_unsupported * sec_pk_e_key_attr_read_failed * sec_pk_e_no_memory * * Errors passed through from: * sec_id_global_parse_name Anderson, Cuti Page 44 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * sec_rgy_cell_bind * sec_rgy_attr_cursor_alloc * sec_rgy_attr_lookup_by_id * uuid_equal */ error_status_t sec_pubkey_retrieve ( [in] void *principal, [in] sec_pk_domain_t *domain, [in] sec_pk_usage_flags_t usage, [in,out] unsigned32 *kvno, [out] sec_pk_pubkey_t *pubkey_p ); /* s e c _ p u b k e y _ r e a d _ k e y f i l e * * Function: * Read a key from a keyfile. Keyfile is assumed * to have format as follows: * unsigned32 'P' 'K' 'E' 'Y' * unsigned32 file format version# (must be 1 or 2) * unsigned32 key_version (file format version 2 only) * unsigned32 key_length * byte key[key_length] * * In Parameters: * keyfilepath -path to keyfile * key_version_p -NULL or pointer to key version number * desired; if 0, any key version accepted * * Out Parameters: * key_version_p -NULL or pointer to key version number * being returned * file_fmt_ver_p -address of file format version (NULL if * no output file format desired). This will * be returned if it can be read, even if * version does not match or key can't be read. * key_ret_p -address of sec_pk_data_t key; caller must * allocate the sec_pk_data_t before calling * this function. The caller must * deallocate key.data (and, if malloc'd, * key) when finished. In the case of a * private key, key.data should be zeroed * before being deallocated. * * Errors: * sec_pk_e_kf_param_not_alloc - A parameter other than * file_fmt_ver_p NULL * sec_pk_e_kf_open_err - error opening the keyfile * sec_pk_e_kf_read_err - error reading the keyfile * sec_pk_e_kf_format_err - keyfile did not start with * 'P''K''E''Y' Anderson, Cuti Page 45 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * sec_pk_e_kf_version_err - keyfile version not 1 or 2 * sec_pk_e_no_memory - unable to allocate memory for * key data */ error_status_t sec_pubkey_read_keyfile( [in] char *keyfilepath, [in] unsigned32 *file_fmt_ver_p, [in,out] unsigned32 *key_version_p, [out] sec_pk_data_t *key_ret_p ); /* s e c _ p u b k e y _ w r i t e _ k e y f i l e * * Function: * Write a key value to a keyfile. Keyfile * has following format: * unsigned32 'P' 'K' 'E' 'Y' * unsigned32 file format version# (2) * unsigned32 key_version * unsigned32 key_length * byte key[key_length] * * In Parameters: * keyfilepath -path to keyfile * key_version_p -pointer to key version to be written * key_p -address of sec_pk_data_t structure holding * the key to be written * * Out Parameters: * key_version_p -pointer to key version written * file_fmt_ver_p -address of file format version written * (NULL if you don't want this) * * Errors: * sec_pk_e_kf_param_not_alloc - parameter other than * file_fmt_ver_p NULL * sec_pk_e_kf_open_err - error opening the keyfile * for writing * sec_pk_e_kf_write_err - error writing the keyfile */ error_status_t sec_pubkey_write_keyfile( [in] char *keyfilepath, [in] sec_pk_data_t *key_p, [in,out] unsigned32 *key_version_p, [out] unsigned32 *file_fmt_ver_p ); } Anderson, Cuti Page 46 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 9.3. DCE Private Key Module Interface The interface to the DCE Private Key Module Interface is defined in two new files `security/idl/sec_pvtkey.idl' and `security/psm/domestic/sec_pvtkey_switch.h', listed here. `sec_pvtkey_switch.h' defines an interface for registering a private key storage mechanism. `sec_pvtkey.idl' defines the interface between the `sec_psm' layer and the `sec_pvtkey' layer. 9.3.1. security/idl/sec_pvtkey.idl /* * @OSF_COPYRIGHT@ * COPYRIGHT NOTICE * Copyright (c) 1996 Open Software Foundation, Inc. * ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE * in the src directory for the full copyright text. */ /* * Copyright (c) Hewlett-Packard Company 1996 * Unpublished work. All Rights Reserved. * * Private Key Storage Interface */ [ local ] interface sec_pvtkey { import "dce/rgybase.idl"; import "dce/sec_pk_base.idl"; typedef void *sec_pk_mechanism_handle_t; /* Capability should be uuid */ typedef uuid_t sec_pk_pvtkey_capability; /* sec_pvtkey_open * * Open (connect to) the private key storage service. For file-based * keystore implementation, it creates the file for the follow up key * store. It opens the file for the follow up key retrieval or key * update. It can involve a password check (please note, password * check is not applicable to sys admin's operation). For a * server-based implementation, it binds to the server. Anderson, Cuti Page 47 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * * Return status * error_status_ok: Success. * other (non-zero): * for PKSS: * Can't initialize keystore container. * Can't locate keystore. * Can't communicate with keystore. * Access-control failure. * for file base: * sec_pvtkey_privileged * sec_pvtkey_no_more_memory * * Input * * Name: Pointer to the user's canonical name within the * specified domain. * domain_id: The application domain this key belongs to. * * Output * handle: A pointer to an opaque handle to the private key * context data. The context data should contain the * domain_id of the operation. */ error_status_t sec_pvtkey_open( [in] char *name, [in] sec_pk_domain_t *domain_id, [out] sec_pk_mechanism_handle_t *handle ); /* sec_pvtkey_close * * Close the connection to the private key storage service. It also * frees the handle. If there are sensitive data, the data should * be zeroed first. * * Return status * error_status_ok: Success. * other (non-zero): Can't close keystore container. * Can't locate keystore. * Can't communicate with keystore. * Access-control failure. * for file base: * sec_pvtkey_invalid_handle * sec_pvtkey_mechanism_not_init * * Input * * handle: A pointer to an opaque handle to the private key * context data. The context data should contain the Anderson, Cuti Page 48 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * domain_id of the operation. The handle should be * obtained throught sec_pvtkey_open(). */ error_status_t sec_pvtkey_close( [in] sec_pk_mechanism_handle_t handle ); /* sec_pvtkey_capabilities * * Inquire about the capabilities of a key storage service. Multiple * storage services may be supported by a client system, selected * according to username and/or domain_id. If no keystore service * is defined for a given username and domain_id, all sec_pvtkey * operations for that name/domain will return the error * "Can't locate keystore". Some services may not * support all storage service operations, and the * sec_pvtkey_capabilities function allows the PSM module to * interrogate a particular storage service to determine whether a * given feature or operation is supported. * * Return status * error_status_ok: Success. * other (non-zero): Can't locate keystore. * Can't communicate with keystore. * for file base: * sec_pvtkey_capability_not_supported * * Input * Name: Pointer to the user's canonical name within the * specified domain. * capability_parameter: Pointer to the parameter specific to the * capability specified. In KEYGEN capability, it is * public-key algorithm. If specified as * NULL, the default public-key algorithm (RSA) * is implied. Many capability queries will * ignore this parameter. * Feature: Pointer to a uuid code identifying a service feature. * * The following features are currently defined: * Feature code Feature * ------------ ------- * SEC_PVTKEY_CAP_KEYGEN Service can generate keys for * the specified algorithm. * SEC_PVTKEY_CAP_ANYALG Service can store keys for * any algorithm. * SEC_PVTKEY_CAP_KEYALG Service can store keys for * the specified algorithm. * SEC_PVTKEY_CAP_KEYDEL Service can delete user's * key. * Anderson, Cuti Page 49 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * Output * Supported: true if the feature is available, false if not. * */ error_status_t sec_pvtkey_capabilities( [in] sec_pk_mechanism_handle_t handle, [in] void * capability_parameter, [in] sec_pk_pvtkey_capability *feature, [out] boolean32 *supported ); /* sec_pvtkey_store * * Store the user's keypair encrypted using the user's password in * the storage service. The encryption mechanism is determined by * the service provider. The public-key algorithm ID (such as * RSA, DSA) should be included in both the private_key and * public_key structures which are the final [in] parameters. The * keys will be indexed by name, domain_id, key_usage and * key_version in the private key storage service in order to * allow retrieval via the sec_pvtkey_get API. * * If the specified key already exists in the keystore, the * routine will leave it unchanged and return a failure status. * To replace a key in a keystore, either use sec_pvtkey_update or * sec_pvtkey_update_generate, or call sec_pvtkey_delete followed * by sec_pvtkey_store. * * A keystore may enforce its own access-control requirements, and * an access-control failure will be indicated by an appropriate * status code, with the contents of the keystore unchanged. For * example, a file-based keystore implementation may require that * the caller has write-access to the keystore file; a * server-based implementation may require that the caller has * appropriate ACL-based permission to create a new entry; a * memory-card implementation may require that the card be * write-enabled. * * Return status * error_status_ok: Success. * other (non-zero): Can't initialize keystore container. * Can't locate keystore. * Can't communicate with keystore. * Access-control failure. * Same domain and usage's key already exists. * for file base: * sec_pvtkey_invalid_handle * sec_pvtkey_mechanism_not_init * sec_pvtkey_no_more_memory * sec_pvtkey_internal_error Anderson, Cuti Page 50 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * sec_pvtkey_same_domain_and_usage_key_already_exists. * * Input * * handle: A pointer to an opaque handle to the private key * context data. The handle should be obtained through * sec_pvtkey_open() * pwd: Pointer to the user's password. * key_usage: The usage permitted of this keypair. One key_usage * at a time. * key_vno: The key version number. (0 may be specified to * indicate that the routine should select the next * appropriate or newest key version number). * (In the reference implementation, key_vno starts with * 1, then monotonically increases 1 for each update.) * private_key: Pointer to the encoded private key * structure. * public_key: Pointer to the encoded public key structure. * */ error_status_t sec_pvtkey_store( [in] sec_pk_mechanism_handle_t handle, [in] char *pwd, [in] sec_pk_usage_flags_t key_usage, [in] unsigned32 key_vno, [in] sec_pk_data_t *private_key, [in] sec_pk_data_t *public_key ); /* sec_pvtkey_delete * * Delete the user's keypair from the storage device. * * Return status * error_status_ok: Success. * other (non-zero): Can't initialize keystore container. * Can't locate keystore. * Can't communicate with keystore. * Access-control failure. * for file base: * sec_pvtkey_key_deletion_not_supported * * Input * * handle: A pointer to an opaque handle to the private key * context data. The handle should be obtained through * sec_pvtkey_open() * pwd: Pointer to the user's password. * key_usage: The usage of the key pair of the desired key. One Anderson, Cuti Page 51 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * key_usage at a time or NULL key usage. * NULL value means "delete all the key_usages * related to the user. * key_vno: The version number of the desired key. If 0 (zero) is * specified, the function will select the most recent * key version number. * */ error_status_t sec_pvtkey_delete( [in] sec_pk_mechanism_handle_t handle, [in] char *pwd, [in] sec_pk_usage_flags_t key_usage, [in] unsigned32 key_vno ); /* sec_pvtkey_generate * * Generate a new keypair and store it in the keystore encrypted * using the user's password in the storage service. The encryption * mechanism is determined by the service provider. The keys will * be indexed by name, domain_id, key_usage and key_version in the * private key storage service in order to allow retrieval via the * sec_pvtkey_get API. * * If the specified key already exists in the keystore, the routine * will leave it unchanged and return a failure status. To replace * a key in a keystore, either use sec_pvtkey_update or * sec_pvtkey_update_generate, or call sec_pvtkey_delete followed by * sec_pvtkey_store. * * A keystore may enforce its own access-control requirements, and * an access-control failure will be indicated by an appropriate * status code, with the contents of the keystore unchanged. For * example, a file-based keystore implementation may require that * the caller has write-access to the keystore file; a server-based * implementation may require that the caller has appropriate * ACL-based permission to create a new entry; a memory-card * implementation may require that the card be write-enabled. * * Return status * error_status_ok: Success. * other (non-zero): Can't initialize keystore container. * Can't locate keystore. * Can't communicate with keystore. * Access-control failure. * Same domain and usage's key already exits. * Key generation not supported. * for file base: * sec_pvtkey_key_generation_not_supported Anderson, Cuti Page 52 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * * Input * * handle: A pointer to an opaque handle to the private key * context data. The handle should be obtained through * sec_pvtkey_open() * pwd: Pointer to the user's password. * alg_id: Desired public-key algorithm. If specified as * NULL, the default public-key algorithm (RSA) * shall be used. * key_length: Desired key-length. The length of the desired * key. Interpretation of this parameter is * algorithm- dependent; For RSA, it shall be * interpreted as the bit-length of the key. For * any algorithm, a value of 0xffffffff shall mean * the algorithm-specific default. * key_usage: The usage of the public key this key pair * shall belongs to. * key_vno: The key version number. (0 may be specified to * indicate that the routine should select the next * appropriate or newest key version number). * (In the reference implementation, key_vno starts with * 1, then monotonically increases 1 for each update.) * * Output * * public_key: Pointer to the encoded public key structure of the * newly-generated key. * */ error_status_t sec_pvtkey_generate( [in] sec_pk_mechanism_handle_t handle, [in] char *pwd, [in] sec_pk_algorithm_id_t *alg_id, [in] unsigned32 key_length, [in] sec_pk_usage_flags_t key_usage, [in] unsigned32 key_vno, [out] sec_pk_data_t *public_key ); /* sec_pvtkey_get * * Retrieve the user's keypair from the storage device. * The routine allocates memory for the data returned in the * private key and public key parameters. Users should call * sec_pvtkey_free() to deallocate that memory. * * The keypair returned will be the first one found with a * stored key_usage value containing the input "key_usage" value. * i.e. the input value (which will typically have a single bit Anderson, Cuti Page 53 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * set) will be "AND"d with the stored value (which may have many * bits set), and the will be returned if the result is not 0. * * Return status * error_status_ok: Success. * other (non-zero): Access control failure. * Can't locate keystore. * Can't communicate with keystore. * Can't find specified key. * Invalid password. * for file base: * sec_pvtkey_invalid_handle * sec_pvtkey_mechanism_not_init * sec_pvtkey_internal_error * sec_pvtkey_invalid_password * sec_pvtkey_multiple_key_usages * * Input * * handle: A pointer to an opaque handle to the private key * context data. The handle should be obtained through * sec_pvtkey_open() * pwd: Pointer to the user's password. * domain_id: The application domain of the desired key. * key_usage: The usage of the public key of the desired key. One * key_usage at a time. * * Input/Output * * key_vno: The key version number. (0 may be specified to * indicate that the routine should select the * newest key version number). The return value is * the key version of the key returned. * * Output * * private_key: Pointer to the encoded private key * structure. * public_key Pointer to the encoded public key * structure. * */ error_status_t sec_pvtkey_get( [in] sec_pk_mechanism_handle_t handle, [in] char *pwd, [in] sec_pk_usage_flags_t key_usage, [in, out] unsigned32 *key_vno, [out] sec_pk_data_t *private_key, [out] sec_pk_data_t *public_key ); Anderson, Cuti Page 54 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 /* sec_pvtkey_update * * Update the user's keypair record in a keystore. This API may be * used to change either the password, or the keypair, or both. * It may be invoked either by the user to change her own * keypair record (in which case the current_pwd parameter must * be supplied), or by a system administrator to change another * user's keypair record (in which case the current_pwd parameter * should be specified as NULL. * * Keystore implementations may impose their own access-control * requirements. In particular, some keystore implementations * may not support administrative updates, or may require that * the caller have valid administrative DCE credentials. * * Return status * error_status_ok: Success. * other (non-zero): Access control failure. * Can't locate keystore. * Can't communicate with keystore. * Can't find specified record. * Invalid password. * for file base: * sec_pvtkey_invalid_handle * sec_pvtkey_mechanism_not_init * sec_pvtkey_private_key_is_not_supplied * sec_pvtkey_new_password_required * sec_pvtkey_no_more_memory * sec_pvtkey_internal_error * sec_pvtkey_no_matched_private_key * sec_pvtkey_Invalid_password. * * Input * * handle: A pointer to an opaque handle to the private key * context data. The handle should be obtained through * sec_pvtkey_open() * current_pwd: Pointer to the user's current password. Used to * authenticate the user when changing her own * password or keypair. If this parameter is NULL, * the keystore will assume that the update is an * administrative action, and will enforce * administrative access-control * new_pwd: Pointer to the user's new password. If the user * is changing her own key, and does not wish to change * the associated password, this argument may be NULL * (subject to any restrictions imposed by the keystore). * If this is an administrative action, a valid new_pwd * must be supplied. * key_usage: The allowed usage for this keypair. One * key_usage at a time. Anderson, Cuti Page 55 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * private_key: Pointer to the encoded private key structure. * public_key: Pointer to the encoded public key structure. * If the user is changing her own password, and does * not wish to change the corresponding keypair, this * parameter may be NULL (subject to any restrictions * imposed by the keystore). If this is an * administrative action, valid private and public * keys must be supplied. * * Output * key_vno: The key version number. (0 may be specified to * indicate that the routine should select the next * appropriate or newest key version number). * (In the reference implementation, key_vno starts with * 1, then monotonically increases 1 for each update.) * */ error_status_t sec_pvtkey_update( [in] sec_pk_mechanism_handle_t handle, [in] char *current_pwd, [in] char *new_pwd, [in] sec_pk_usage_flags_t key_usage, [out] unsigned32 *key_vno, [in] sec_pk_data_t *private_key, [in] sec_pk_data_t *public_key ); /* sec_pvtkey_update_generate * * Update the user's keypair record for a keystore that supports * key generation. This API may be used to change * either the keypair alone, or both the keypair and the password. * It may be invoked either by the user to change her own keypair * record (in which case the current_pwd parameter must be supplied), * or by a system administrator to change another user's keypair * record (in which case the current_pwd parameter should be * specified as NULL. * * Keystore implementations may impose their own access-control * requirements. In particular, some keystore implementations * may not support administrative updates, or may require that * the caller have valid administrative DCE credentials. * * * Return status * error_status_ok: Success. * other (non-zero): Access control failure. * Can't locate keystore. * Can't communicate with keystore. * Can't find specified record. Anderson, Cuti Page 56 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 * Key generation not supported. * Invalid password. * for file base: * sec_pvtkey_key_generation_not_supported * * Input * * handle: A pointer to an opaque handle to the private key * context data. The handle should be obtained through * sec_pvtkey_open() * current_pwd: Pointer to the user's current password. * Used to authenticate the user when changing her * own password or keypair. If this parameter is * NULL, the keystore will assume that the update is * an administrative action, and will enforce * administrative access-control * new_pwd: Pointer to the user's new password. If the user * is changing her own key, and does not wish to change * the associated password, this argument may be NULL * (subject to any restrictions imposed by the keystore). * If this is an administrative action, a valid new_pwd * must be supplied. * alg_id: Desired public-key algorithm. If specified as * NULL, the default public-key algorithm (RSA) * shall be used. * key_length: Desired key-length. The length of the desired * key. Interpretation of this parameter is * algorithm-dependent; For RSA, it shall be * interpreted as the bit-length of the key. For any * algorithm, a value of 0xffffffff shall mean the * algorithm-specific default. * key_usage: The allowed usage for this keypair. One at a time. * * * Output * * key_vno: The key version number. (0 may be specified to * indicate that the routine should select the next * appropriate or newest key version number). * (In the reference implementation, key_vno starts with * 1, then monotonically increases 1 for each update.) * public_key: The newly-generated public-key. * */ error_status_t sec_pvtkey_update_generate( [in] sec_pk_mechanism_handle_t handle, [in] char *current_pwd, [in] char *new_pwd, [in] sec_pk_algorithm_id_t *alg_id, Anderson, Cuti Page 57 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 [in] unsigned32 key_length, [in] sec_pk_usage_flags_t key_usages, [out] unsigned32 *key_vno, [out] sec_pk_data_t *public_key ); } 9.3.2. security/psm/domestic/sec_pvtkey_switch.h /* * @OSF_COPYRIGHT@ * COPYRIGHT NOTICE * Copyright (c) 1996 Open Software Foundation, Inc. * ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE * in the src directory for the full copyright text. */ /* * (c) Copyright 1996, * Digital Equipment Corporation, Maynard, Massachusetts, USA * All Rights Reserved */ /* * Copyright (c) Hewlett-Packard Company 1996 * Unpublished work. All Rights Reserved. */ #ifndef SEC_PVTKEY_SWITCH_H_ #define SEC_PVTKEY_SWITCH_H_ #ifdef __cplusplus extern "C" { #endif #include #include #include #define SEC_PVTKEY_SWITCH_FLAG_MATCHALL 1 #define SEC_PVTKEY_SWITCH_FLAG_TERMINATE 2 #define SEC_PVTKEY_SWITCH_FLAG_ENABLED 4 typedef struct { unsigned32 magic; unsigned32 flags; const uuid_t * keystore_uuid; Anderson, Cuti Page 58 OSF-RFC 68.3 DCE 1.2.2 Public Key Login January 1997 char keystore_name[32]; /* Name must be 32 characters or less, */ /* and NULL-terminated if less. */ error_status_t (* open)(idl_char *name, sec_pk_domain_t *domain_id, sec_pk_mechanism_handle_t *handle); error_status_t (* close)(sec_pk_mechanism_handle_t handle); error_status_t (* capabilities)(sec_pk_mechan