Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/sigstore_models/common/v1/__init__.py: 100%

1import enum 

2import typing as t 

3from datetime import datetime 

4 

5from sigstore_models._core import Base, ProtoBytes 

6 

7 

8class HashAlgorithm(str, enum.Enum): 

9 # NOTE: We don't include HASH_ALGORITHM_UNSPECIFIED 

10 # because it's a protobuf-level hack, and not a valid hash algorithm. 

11 SHA2_256 = "SHA2_256" 

12 SHA2_384 = "SHA2_384" 

13 SHA2_512 = "SHA2_512" 

14 SHA3_256 = "SHA3_256" 

15 SHA3_384 = "SHA3_384" 

16 

17 

18class PublicKeyDetails(str, enum.Enum): 

19 # TODO: Figure out a good way to encode deprecated variants. 

20 # RSA 

21 PKCS1_RSA_PKCS1V5 = "PKCS1_RSA_PKCS1V5" # deprecated 

22 PKCS1_RSA_PSS = "PKCS1_RSA_PSS" # deprecated 

23 PKIX_RSA_PKCS1V5 = "PKIX_RSA_PKCS1V5" # deprecated 

24 PKIX_RSA_PSS = "PKIX_RSA_PSS" # deprecated 

25 

26 # RSA public key in PKIX format, PKCS#1v1.5 signature 

27 PKIX_RSA_PKCS1V15_2048_SHA256 = "PKIX_RSA_PKCS1V15_2048_SHA256" 

28 PKIX_RSA_PKCS1V15_3072_SHA256 = "PKIX_RSA_PKCS1V15_3072_SHA256" 

29 PKIX_RSA_PKCS1V15_4096_SHA256 = "PKIX_RSA_PKCS1V15_4096_SHA256" 

30 

31 # RSA public key in PKIX format, RSASSA-PSS signature 

32 PKIX_RSA_PSS_2048_SHA256 = "PKIX_RSA_PSS_2048_SHA256" # See RFC4055 

33 PKIX_RSA_PSS_3072_SHA256 = "PKIX_RSA_PSS_3072_SHA256" 

34 PKIX_RSA_PSS_4096_SHA256 = "PKIX_RSA_PSS_4096_SHA256" 

35 

36 # ECDSA 

37 PKIX_ECDSA_P256_HMAC_SHA_256 = ( 

38 "PKIX_ECDSA_P256_HMAC_SHA_256" # deprecated - See RFC6979 

39 ) 

40 PKIX_ECDSA_P256_SHA_256 = "PKIX_ECDSA_P256_SHA_256" # See NIST FIPS 186-4 

41 PKIX_ECDSA_P384_SHA_384 = "PKIX_ECDSA_P384_SHA_384" 

42 PKIX_ECDSA_P521_SHA_512 = "PKIX_ECDSA_P521_SHA_512" 

43 

44 # Ed 25519 

45 PKIX_ED25519 = "PKIX_ED25519" # See RFC8032 

46 PKIX_ED25519_PH = "PKIX_ED25519_PH" 

47 

48 # These algorithms are deprecated and should not be used, but they 

49 # were/are being used by most Sigstore clients implementations. 

50 PKIX_ECDSA_P384_SHA_256 = "PKIX_ECDSA_P384_SHA_256" # deprecated 

51 PKIX_ECDSA_P521_SHA_256 = "PKIX_ECDSA_P521_SHA_256" # deprecated 

52 

53 # LMS and LM-OTS 

54 # 

55 # These algorithms are deprecated and should not be used. 

56 # Keys and signatures MAY be used by private Sigstore 

57 # deployments, but will not be supported by the public 

58 # good instance. 

59 # 

60 # USER WARNING: LMS and LM-OTS are both stateful signature schemes. 

61 # Using them correctly requires discretion and careful consideration 

62 # to ensure that individual secret keys are not used more than once. 

63 # In addition, LM-OTS is a single-use scheme, meaning that it 

64 # MUST NOT be used for more than one signature per LM-OTS key. 

65 # If you cannot maintain these invariants, you MUST NOT use these 

66 # schemes. 

67 LMS_SHA256 = "LMS_SHA256" # deprecated 

68 LMOTS_SHA256 = "LMOTS_SHA256" # deprecated 

69 

70 # ML-DSA 

71 # 

72 # These ML_DSA_65 and ML-DSA_87 algorithms are the pure variants that 

73 # take data to sign rather than the prehash variants (HashML-DSA), which 

74 # take digests. While considered quantum-resistant, their usage 

75 # involves tradeoffs in that signatures and keys are much larger, and 

76 # this makes deployments more costly. 

77 # 

78 # USER WARNING: ML_DSA_65 and ML_DSA_87 are experimental algorithms. 

79 # In the future they MAY be used by private Sigstore deployments, but 

80 # they are not yet fully functional. This warning will be removed when 

81 # these algorithms are widely supported by Sigstore clients and servers, 

82 # but care should still be taken for production environments. 

83 ML_DSA_65 = "ML_DSA_65" # See NIST FIPS 204 

84 ML_DSA_87 = "ML_DSA_87" 

85 

86 

87class HashOutput(Base): 

88 """HashOutput captures a digest of a 'message' (generic octet sequence) 

89 and the corresponding hash algorithm used.""" 

90 

91 algorithm: HashAlgorithm 

92 digest: ProtoBytes # Raw octets of the message digest 

93 

94 

95class MessageSignature(Base): 

96 """MessageSignature stores the computed signature over a message.""" 

97 

98 message_digest: t.Optional[HashOutput] = None # For artifact identification only 

99 signature: ProtoBytes # Raw signature bytes (required) 

100 

101 

102class LogId(Base): 

103 """LogId captures the identity of a transparency log.""" 

104 

105 key_id: ProtoBytes # Unique identity of the log (required) 

106 

107 

108class RFC3161SignedTimestamp(Base): 

109 """This message holds a RFC 3161 timestamp.""" 

110 

111 signed_timestamp: ProtoBytes # DER encoded TimeStampResponse (required) 

112 

113 

114class PublicKey(Base): 

115 """Public key with encoding details and optional validity period.""" 

116 

117 raw_bytes: t.Optional[ProtoBytes] = None # DER-encoded public key 

118 key_details: PublicKeyDetails # Key encoding and signature algorithm 

119 valid_for: t.Optional["TimeRange"] = None # Optional validity period 

120 

121 

122class PublicKeyIdentifier(Base): 

123 """PublicKeyIdentifier can be used to identify an (out of band) delivered 

124 key, to verify a signature.""" 

125 

126 hint: t.Optional[str] # Optional unauthenticated hint on which key to use 

127 

128 

129class ObjectIdentifier(Base): 

130 """An ASN.1 OBJECT IDENTIFIER""" 

131 

132 id: list[int] # Required list of integers 

133 

134 

135class ObjectIdentifierValuePair(Base): 

136 """An OID and the corresponding (byte) value.""" 

137 

138 oid: ObjectIdentifier 

139 value: ProtoBytes 

140 

141 

142class DistinguishedName(Base): 

143 """Distinguished name with organization and common name.""" 

144 

145 organization: str 

146 common_name: str 

147 

148 

149class X509Certificate(Base): 

150 """X.509 certificate container.""" 

151 

152 raw_bytes: ProtoBytes # DER-encoded X.509 certificate (required) 

153 

154 

155class SubjectAlternativeNameType(str, enum.Enum): 

156 EMAIL = "EMAIL" 

157 URI = "URI" 

158 OTHER_NAME = "OTHER_NAME" 

159 

160 

161class SubjectAlternativeName(Base): 

162 """Subject Alternative Name with type and identity.""" 

163 

164 type: SubjectAlternativeNameType 

165 # Using Union for the oneof identity field 

166 regexp: t.Optional[str] = None # Regular expression for expected value 

167 value: t.Optional[str] = None # Exact value to match against 

168 

169 

170class X509CertificateChain(Base): 

171 """A collection of X.509 certificates. 

172 

173 This "chain" can be used in multiple contexts, such as providing a root CA 

174 certificate within a TUF root of trust or multiple untrusted certificates for 

175 the purpose of chain building.""" 

176 

177 certificates: list[X509Certificate] # One or more DER-encoded certificates 

178 

179 

180class TimeRange(Base): 

181 """The time range is closed and includes both the start and end times, 

182 (i.e., [start, end]). End is optional to be able to capture a period 

183 that has started but has no known end.""" 

184 

185 start: datetime 

186 end: t.Optional[datetime] = None